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.
Contents
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;
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 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:
- "com": 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
- "com,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
- "com?" or "ip?": adding a '?' after "com" 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
- "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
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 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.