SimpleBinary Binding - jfederico/openhab GitHub Wiki

SimpleBinary is openHAB binding that lest you easily connect small devices like Arduino via serial port. Binding uses own binary protocol which is easy to implement. The protocol is described below. Implementation example for Arduino is part of my repository: https://github.com/docbender/openHAB-SimpleBinary. Latest release can be found also there in release section: https://github.com/docbender/openHAB-SimpleBinary/releases.

It is possible to configure several ports not only one. At one line it is possible to connect several devices (ready for RS422/RS485).

Each port has separated configuration (speed, mode). Communication can operate in 2 data read modes - OnScan and OnChange.

Communication can operate it 2 modes reading data from connected devices - OnScan and OnChange. In OnScan mode all data are reading cyclically. In OnChange mode only new data are sent to openHAB. Each device is polled whether has new data and then sends new data to openHAB.

Binding support openHAB data types listed in the table. Individual item type are converted to simple data types such as byte, word, double word, float, array, rgb. For same types may be converted type defined, others has it strictly defined. Supported data types

In openhab.cfg is binding configured this way:

################################### SimpleBinary Binding ######################################
#
# Select port (ex.: COM1:115000;onscan;forceRTSInv or /dev/ttyUSB1:9600). It is possible defined 
# more ports ex. port1, port2,port145,... Behind semicolon you can specify data pool control (optional).    
# Options for reach slave data are onchange(ask configured devices for new data - default) 
# or onscan(read all data every scan). Option forceRTS or forceRTSInv are for trigger RTS signal
# during data send (useful for RS485 converter). 
# 
simplebinary:port=COM4:9600;onchange
#refresh - check for new data interval - default 10000ms 
simplebinary:refresh=2000

Binding specify item configuration is located as usual in the brackets at the end of the configuration line. It consists of three compulsory and two optional parameters.

Configuration format:

simplebinary="port name:device address:item address:[used data type]:[direction]"

Example of binding configuration:

Dimmer    Item01    "Value[%d]"    { simplebinary="port:1:1" }
Number    Item02    "Value[%d]"    { simplebinary="port:1:3:dword:IO" }
Number    Item03    "Value[%f]"    { simplebinary="port:1:4:float:O" }
Number    Item04    "Value[%f]"    { simplebinary="port:1:14:float:I" }
String    Item05    "Value[%s]"    { simplebinary="port:2:1:array[32]:O" }
Color     TestColor01              { simplebinary="port:2:2:rgb:O" }

Binding itself offers some diagnostic states. There are available statuses for communication port itself and also statuses for connected devices. These statuses can be provided into openHAB if they are properly configured (by use configuration parameter info behind port name or device address).

Port diagnostic info configuration format:

simplebinary="port name:info:port status"

Port statuses:

Device diagnostic info configuration format:

simplebinary="port name:device address:info:device status"

Device statuses:

Example of diagnostic item configuration:

Number    PortState            "Port state [%s]"                 { simplebinary="port:info:state" }
Number    PortPreviouState     "Port previous state [%s]"        { simplebinary="port:info:previous_state" }
DateTime  PortStateChangeTime  "Port changed [%1$tA, %1$td.%1$tm.%1$tY %1$tT]"    { simplebinary="port:info:state_change_time" }

Number    Dev01State           "Device 1 state [%s]"             { simplebinary="port:1:info:state" }
Number    Dev01PreviouState    "Device 1 previous state [%s]"    { simplebinary="port:1:info:previous_state" }
DateTime  Dev01StateChangeTime "Device 1 changed [%1$tA, %1$td.%1$tm.%1$tY %1$tT]" { simplebinary="port:1:info:state_change_time" }
Number    Dev01PacketLost      "Device 1 packet lost rate [%s]"  { simplebinary="port:1:info:packet_lost" }

Number    Dev02State           "Device 2 state [%s]"             { simplebinary="port:2:info:state" }
Number    Dev02PreviouState    "Device 2 previous state [%s]"    { simplebinary="port:2:info:previous_state" }
DateTime  Dev02StateChangeTime "Device 2 changed [%1$tA, %1$td.%1$tm.%1$tY %1$tT]" { simplebinary="port:2:info:state_change_time" }
Number    Dev02PacketLost      "Device 2 packet lost rate [%s]"  { simplebinary="port:2:info:packet_lost" }

Binding sets the serial port speed according to user configuration. Other parameters are set as follows: 8 data bits, 1 stop bit, without parity and without flow control.

Flow control (especially for RS-485 converters) can be provided through RTS pin. This can be turned on by adding forceRTS parameter in binding port configuration. If it is required inverted function of RTS pin, forceRTSInv parameter should be added in configuration instead forceRTS.

Binding implements master/slave communication model. OpenHAB binding is master and connected devices are slaves. Master sends command and waits for response from slave. Answer should arrived in order tens of milliseconds. However bindings has 2000ms timeout to receive answer.

Communication protocol itself depends on requested operating mode of the device (OnScan / OnChange). Of course device can support both operating modes.

Every packet start with slave address and is followed by message type. Minimum packet length is 4 bytes. Packets are secured with CRC8 which should be enough for short packets.

###Master query for new data - OnChange mode On this packet master expecting as answer "data" packet or "no data" packet (message type 0xE2).

###Master query for data with specified address - OnScan mode On this packet master expecting as answer "data" packet or "invalid address" packet (message type 0xE4).

###Data packet for data type byte This "data" packet could be send by master to write data into slave or by slave as answer for data request. Answer from slave should "done" when everything was right.

###Data packet for data type word This "data" packet could be send by master to write data into slave or by slave as answer for data request. Answer from slave should "done" when everything was right.

###Data packet for data type dword This "data" packet could be send by master to write data into slave or by slave as answer for data request. Answer from slave should "done" when everything was right.

###Data packet for type HSB, RGB, RGBW This "data" packet could be send by master to write data into slave or by slave as answer for data request. Answer from slave should "done" when everything was right.

###Data packet for type array This "data" packet could be send by master to write data into slave or by slave as answer for data request. Answer from slave should "done" when everything was right.

###Acknowledge packet - Done Answer from slave that data write from master was accepted.

###Error packet - Repeat Answer that received packet had wrong CRC. On this packet master react by sending last packet again (max. 3 time).

###Acknowledge packet - No new data Slave react with this packet on query for new data in OnChange mode in case that there's no data to send.

###Error packet - Unknown data Slave react with this packet if received message had unknown/unsupported type.

###Error packet - Unknown address Slave react with this packet if received message had unknown data item address.

###Error packet - Error while saving data Slave send this packet when he could not save received data from master.

##Implementation The extent of implementation depends on the required features and data types (see chapter Protocol).

At first device should check if message is correctly received (CRC check). Secondly device should check if message is for him by compare message address and his own assigned address. If the address is different device must not respond! Otherwise device must response in corresponding way (see chapter Protocol).

##Implementation example Implementation example for Arduino can be found in repo folder arduino/SimpleBinaryExample.

It consists of two main classes. Class simpleBinary which contains protocol implementation itself and class itemData which provides item data storage and handling with item.

###CRC8 calculation implementation

char CRC8::evalCRC(char *data, int length)
{
   int crc = 0;
   int i, j;

   for(j=0; j < length; j++)
   {
      crc ^= (data[j] << 8);
	
      for(i=0;i<8;i++)
      {
         if((crc & 0x8000) != 0)
            crc ^= (0x1070 << 3);
	
         crc <<= 1;
      }
   }	
   return (char)(crc >> 8);
}