Wiki
Clone wikideveloper-guide / Driver
This page describes the steps for developing a driver for integration with CoSSMic. It also lists the drivers currently available.
1. Developing a driver for integration with CoSSMic
A driver is responsible for the communication between the Device Manager module of EmonCMS and the household devices. For example, currently, there are drivers for integrating ModBus, MBus and IEC62056 meters (via RS485, driver "serial") and VHF-controlled smart plugs (driver "CUL") available. However, due to the design of the Device Manager, almost any device type can be integrated by developing a new driver.
A driver has a unique name, e.g. "serial" or "CUL", in the following #DRIVER#. The number of devices handled by a driver is not limited, however, each device needs to be identified by a unique address, in the following #ADDRESS#. The format of the address is arbitrary, so it can be identical to the hardware address of the device.
A driver has to implement the REST/JSON interface provided by the Device Manager. In the following, the available methods are described.
1.1 Connecting a new device
The connection of a new device has to be recognized by the driver. The driver needs to assign a device address. Also, the device needs to recognize, what data fields (e.g. energyIn, temperature) are provided by the new device. #FIELDS# is a comma-separated list of data fields. Finally, the new device is assigned to a EmonCMS node by calling
emoncms/devices/node/register.json?driverid=#DRIVER#&address=#ADDRESS#&type={#FIELDS#}
1.2 Posting device data
If a new value #VALUE# for a data field #FIELD# is available, the driver posts the data to the Device Manager. If the data belongs to a certain timestamp, the timestamp can be posted to the Device Manager. Otherwise, the current timestamp will be used.
emoncms/devices/post.json?driverid=#DRIVER#&address=#ADDRESS#&type=#FIELD#&value=#VALUE# emoncms/devices/post.json?driverid=#DRIVER#&address=#ADDRESS#&type=#FIELD#&value=#VALUE#&time=#TIME#
1.3 Controlling the driver
A driver can be controlled by EmonCMS, e.g. in order to start/stop it or to send commands to the connected devices (e.g. "switch on"). Thus, the driver needs to offer an interface, which can be accessed via PHP. Possible options for this interface are a socket or a FIFO pipe.
Once a command has to be send to the driver, EmonCMS calls the file /emoncms/Modules/devices/#DRIVER#/cmd.php. The cmd.php file has to be provided by the driver and implements its interface.
In cmd.php, the variables $cmd['command'], $cmd['address'] and $cmd['status'] are available. They contain the command, a device address and a status, respectively. E.g., for sending a "switch on" command, $cmd['command'] = 'set', $cmd['status'] = 1 and $cmd['address'] is the address of the device, which is to be switched on.
2. Available drivers
Currently, the following drivers are available for CoSSMic. Programming language can be java or Python.
Updated