Custom I/O Drivers

HSYCO offers a development framework to easily build your own I/O server, written in Java, so you can interface with external systems that are not part of the built-in library of supported systems.

A user-defined I/O server, called “driver” from now on, behaves in the exactly the same way as the standard servers.

The Directory Structure and Naming Convention

Each driver has a dedicated sub-directory under the “drivers” directory in HSYCO’s root directory. The name of that directory is the driver’s name, and should be all lowercase letters [a-z] and numbers [0-9] only.

You should define names carefully, so to avoid naming conflicts with other drivers you may wish to install on the same HSYCO server.

 All built-in I/O servers names are reserved and should not be used as names for custom drivers.

The driver’s directory must contain at least two files: the Driver.class containing the Java code, and settings.json, used to let the Manager’s Settings application know about your custom driver and its configuration options.

You can have other files as well, for other custom Java classes and additional resources.

Driver.java

A driver is created as a Driver class in package drivers.<driver name>.

It should be a public class that extends driverBase.

The following code is the skeleton for a driver called mydriver.

package drivers.mydriver;

import java.util.HashMap;

import com.hsyco.driverBase;

public class Driver extends driverBase {
	public static final int DEFAULTSOCKETPORT = 0;
	public static final int COMMANDSQUEUESIZE = 256;
	public static final boolean SHUTDOWNWHENSLAVE = true;
	
	private String name = null;

	// called once every time the driver is started.
	// Returning false will fail the initialization procedure, and the driver will not start
	public boolean init(String name, HashMap<String, String> config) {
		
		super.init(name); // do not remove
		this.name = name;
		return true;
	}
	
	// called repeatedly while the driver should be alive.
	// Returning false will not update the keep-alive timer, causing the driver to quit after a while.
	// This call should always return within about 30 seconds, to avoid the keep-alive watch-dog intervention
	public boolean loop() {
		
		return true;
	}
	
	// called once when the driver quits after it has started correctly.
	// Should always return true
	public boolean end() {
		
		return true;
	}
	
	// Optional - called on user keys, gui input objects, submit and user action in Events or Java
	public String user(String session, String user, String id, HashMap<String, String> fields) {
		
		return "";
	}
	
	// Optional - called for each command that should be processed by the driver
	public void command(String name, String value) {
		
	}
}

As you can see, the code structure is pretty simple. A handful of callback methods are called by the HSYCO core engine during initialization, exit, and for normal operations.

These methods, described in the Custom Drivers Callback Methods API documentation, are where you will write your custom interface code, also using a number of utility methods that are described in the Custom Drivers Command and Utility Methods API documentation.

settings.json

settings.json is a simple text file in JSON format, used to let the Manager’s Settings application know about your custom driver and its configuration options.

settings.json is not strictly needed for the driver to function, but without it you would not be able to use the Manager’s Settings application for HSYCO configuration.

This is an example of a simple settings.json file.

{
	"MYDRIVER": {
		"connection": "ip",
		"auth": "yes",
		"options": {
			"decimals": {
					"type": "select",
					"format": "0|1|2",
			},
			"startupevents": {
				"type": "select",
				"format": "true|false",
			}
		}
	}
}

The structure of this file is a single field with the same name of the driver, but in uppercase letters.

The main field’s value is an object with three fields, “connection”, “auth” and “options”.

The connection Field

“connection” is a string type with possible values “ip”, “comm” or an empty string.

“ip” is used for drivers that require IP host and port number parameters, “comm” for drivers using serial (Comm) ports, and the “” empty string for drivers that don’t need any communication parameters.

The auth Field

“auth” is a string type with possible values “yes” or “no”.

When set to yes, the Settings application will enable the user and password parameters in the driver’s configuration page.

The options Field

The “options” field contains a list of objects, each one corresponding to an optional parameter.

The name of the option will be shown in the options list for the driver, so it should be meaningful.

Each option has two mandatory fields, “type” and “format”, and an optional “key_format” field.

Creating a Driver Bundle

The most effective way to create a single file bundle for a driver is to simply zip the driver’s directory.

You will distribute the zip file, and simply install it using the file manager to upload it to the main drivers directory.

The file will manager automatically expand the file in place.

Please note that HSYCO will have to be manually restarted when you upload a new driver or update an existing one, unless the AutoKillFiles configuration parameter is set to explicitly list all relevant files of the driver.