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 server 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;

	// if there are GUI objects that should be visible when this driver is used, uncomment the line and list all objects you need
	// public static final String[] WEBOBJECTS = {"button", "buttonicon", "buttonimage"};
	
	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"
			},
			"code": {
				"type": "input",
				"format": "\\d+",
				"key_format": "\\d"
			}
		}
	}
}

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

The driver field’s value is an object with the following fields:

"connection"

can have the following values:

• "comm": the driver communicates through a serial port, thus the I/O Server settings panel will enable the "Comm" field
• "ip": the driver communicates through an IP connection, thus the I/O Server settings panel will enable the "IP" field
• "comm,ip": the driver may communicate both via serial port or IP connection. Both fields will be enabled
• "": the driver does not require communication parameters to be set. The "Comm" and "IP" fields will be disabled
• "comm?" or "ip?": adding a '?' after "comm" or "ip" indicates that the communication parameters are optional.

"comm_type"

this field is required if the "connection" field specifies the use of a serial port. The allowed values are the following:

• "comm": the used port will be selected among one of the entries listed in the Comm Ports section of the Manager's Settings
• "comm2": it will be possible to select 2 Comm Ports
• "port": the used port will be manually entered. For instance one has to specify the name of the actual communication port (e.g. "tty0")
• "io:<driver_name>": the serial communication occurs through another I/O Server of type <driver_name>, e.g. "io:MODBUSTCP". Thus one will select among a list of defined I/O Servers.

"auth"

can have the following values:

• "no": the authentication paramenters are not required by the driver
• "yes": the driver requires the user and password parameters
• "password": the driver requires only the password parameter.

"is_commport"

this field is optional and defaults to "no". It can have the following values:

• "no": this driver cannot be used as a comm port
• "yes": this driver can be used as a comm port.

"options"

the value of this filed is an object whose fields represent additional parameters for the driver. For each option add a new field properly named and set the value to an object with the following fields and values:

"type"

can have the following values:

• "select": the Settings application will show a select field for the user to chose the value of the option from a list
• "input": the Settings application will show an input field for the user to type the value of the option

"format"

a regex string describing the format of allowed values for this option (e.g. a value of "[-|+]?\\d+" indicates that the value must be a relative integer number). If the type of this option is "select", then the value of this field must be set to the list of possible values, using the format "<val_1>|<val_2>| ... |<val_n>" (e.g. "1|2|3")

"key_format"

to be used for options of type "input". It defines the regex expression used to validate each character entered in the input field. For instance, if an option has a numeric value, the value shall be set to "\\d".

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 manager will 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.