Java Programming

You can write custom Java code to respond to any HSYCO event.

Java is precompiled, and offers the best performance and powerful programming features of a fully standard Java language.

The Java programming framework is very similar to the EVENTS language structure - a library of callback methods are asynchronously called on system and filed events. You are allowed to extend these methods with standard Java code and a comprehensive library of command and utility methods that already implement all common functions you may need to interact with field systems and with the user interface.

You are free to use any standard Java feature or external classes. This is a fully standard Java environment, not a sandboxed solution.

Custom Java code is always written as a plugin. A plugin is a directory under plugins in HSYCO’s root directory, containing a public class that extends the userBase class and declares the callback methods you need. The same plugin can also bundle EVENTS files and user interface projects. See Plugins Development for the directory structure, naming conventions and precedence rules.

You are also going to use Java to extend the core HSYCO system with custom I/O Servers, as well as to access other embedded HSYCO features, like the integrated SQL engine. These topics are discussed in the Advanced Development chapter.

The userBase Class

userBase is a skeleton class that provides methods to execute actions on the field devices, as well as internal functions. Your plugin’s callback class extends userBase, so that these methods can be called directly from your code.

The callback methods are the methods called by HSYCO after any event is detected. You only declare the callback methods you need; HSYCO finds them in your plugin’s class when it starts.

The Java Callback Methods API and Java Command and Utility Methods API chapters describe the callback methods and all the command and utility methods provided by userBase.

These methods are the only official HSYCO Java API methods.

You should avoid using other public methods provided by other classes within the HSYCO package. These methods could change without notice in any new HSYCO release, causing compatibility issues between your code and different versions of HSYCO.

Predefined Constants

The table below lists the predefined constants that you should use as parameters or are returned by the HSYCO Java API.

Name	Description
NOCHANGE	don’t change current status
OFF	off action and status
ON	on action and status
UNKNOWN	unknown status value

Compiling and Installing a Plugin

You can compile your plugin’s Java files with any standard Java compiler, with hsyco.jar in the classpath.
hsyco.jar also includes Apache POI and Apache PDFBox, for Office and PDF files: see Office and PDF Libraries.

However, we usually recommend installing and using Eclipse on your PC, since it simplifies the development workflow and integration with HSYCO.
See Eclipse Installation for detailed instructions.

Once HSYCO is running inside Eclipse, you can request a development license by contacting HSYCO at tech@hsyco.com.

After compilation, copy the resulting .class files into the plugin’s directory, plugins/<plugin name>/.

The HSYCO run-time environment should be restarted for plugin changes to become effective, unless the AutoKillFiles parameter in hsyco.ini lists the plugin’s class files.

Examples

Example of use of IOEvent and programTimerEvent, in a plugin named myLogic. The class file is plugins/myLogic/myLogic.class.

package plugins.myLogic;

import com.hsyco.*;

public class myLogic extends userBase {
	
	public static void IOEvent(String id, String value){

		//startup
		if (id.equals("knx.connection") && value.equals("online")) {
			messageLog("KNX - online");
		}

		//force dimmer to 100% when is on
		if ((id.equals("knx.light.1") || id.equals("knx.light.2") ) && (!value.equals("0"))) {
			ioSet(id,"100");
		}

		//if it's night and the light knx.light.4 is on turn on the light knx.light.5 and turn off both the lights after 120 seconds
		if (!isDaylight()) {
			if (id.equals("knx.light.4") && value.equals("1")) {
				ioSet("knx.light.5", "1");
				programTimerReset("lightsoff", 120);
			} 
		}
	}


	public static void programTimerEvent(String name){
		//called when a programTimer is triggered
		if (name.toLowerCase().equals("lightsoff")){	
			ioSet("knx.light.4", "0");
			ioSet("knx.light.5", "0");
		}
	}
}

Example of use of userCommand which is called whenever a button object in command mode is pressed.

package plugins.myLogic;

import com.hsyco.*;

public class myLogic extends userBase {
	
	public static String userCommand(String session, String userid, String name, String param) {
			 //when the button with name starting with modbuswritef10 is pressed writes a modbus register. The register to write is in the name of the button
			 if (name.startsWith("modbuswritef10")){
				
				try {
					 messageLog("Modbus write function 10");
					 String[] arr = name.split("\\.|,");
				     // Write with function 10
				     int value = Integer.parseInt(param);
				     // Prepare the register
	                 byte[] b = {(byte)((value >> 8) & 0xFF), (byte)(value & 0xFF)};
	                 byte[] r = modbusWriteMultipleRegisters("modbus", Integer.parseInt(arr[1]), Integer.parseInt(arr[2]), b);	
				} catch (Exception e) {
					// TODO: handle exception
				} 	
				
				return "ok";
			}  
			 
			return null;
		}
}