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.

You are also going to use Java to extend the core HSYCO system with plug-in applications and 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 Programming chapter.

user.java

The basic Java extension of HSYCO is based on a class called user, declared in a user.java file, contained in the hsyco/com/hsyco directory and compiled in a java.class file.

note

The user.class file must exist for the HSYCO to work correctly, even if there is no customized Java code.

HSYCO SERVER ships with an empty user.class file pre-installed.

The user class should extend the userBase class, a skeleton class that provides methods to execute actions on the field devices, as well as internal functions, and the callback framework methods, which are the methods called by HSYCO after any event is detected.

The dummy user.java file contains only the class declaration:

/*  HSYCO CONTROLLER, USER CODE
 *  (c) 2014-2025 HSYCO SpA
 *  For information, see the Home Systems Consulting web site:
 *  http://www.hsyco.com/
 */


package com.hsyco;
public class user extends userBase {
}

The HSYCO run-time environment should be restarted for user.class changes to become effective. The default setting of the AutoKillFiles parameter in hsyco.ini causes the automatic restart of HSYCO when user.class is changed.

The Java Callback Methods API and Java Command and Utility Methods API chapters describes 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
MERGED	DMX merged channel
NOCHANGE	don’t change current status
OFF	off action and status
ON	on action and status
PAUSE	pause status (only Squeezebox music player)
PLAY	play status (only Squeezebox music player)
UNKNOWN	unknown status value

Compiling and Installing user.java

You can compile the user.java file with any standard Java compiler.

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 user.class file into the com/hsyco/ directory, replacing the default user.class file.

Examples of user.java

Example of use of IoEvent and programTimerEvent.

package com.hsyco;

public class user 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 com.hsyco;

public class user extends userBase {
	
	public static String userCommand(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 = util.encodeInteger(value, 2);
	                 byte[] r = modbusWriteMultipleRegisters("modbus", Integer.parseInt(arr[1]), Integer.parseInt(arr[2]), b);	
				} catch (Exception e) {
					// TODO: handle exception
				} 	
				
				return "ok";
			}  
			 
			return null;
		}
}