TapHome system is able to integrate with other systems through simple ASCII integration protocol. This enables other systems to get information and control TapHome devices.
Supported communication layers
Protocol supports following commands:
HELP, LIST, GET, SET, ACTION, HEADER, AUTOSEND
Every command must be terminated with CRLF (0x0D 0x0A, \r\n) characters.
Command HELP<\r><\n> will display basic information about supported commands.
HEADER [ON/OFF] switch header information on or off.<\r><\n>
LIST display all exposed devices.<\r><\n>
GET [ID] get device with ID values.<\r><\n>
SET [ID ST VAL1 .. VALN] set device with ID status ST and values VAL1 to VALN.<\r><\n>
ACTION [ID NUM VAL] Perform on device with ID action number NUM with value VAL.<\r><\n>
PUSHALL [ON/OFF] switch push all devices change on or off.<\r><\n>
Command HEADER<\r><\n> switch between two possible data output. If header is ON there are send description information together with data. In case header is off it are send only data.
HEADER without parameters send information about actual switch state.
HEADER ON will switch on header information.
HEADER OFF will switch off header information.
Command LIST displays all exposed devices.
Displayed are following information:
Device ID is numerical device ID.
Device Type is text description of device type (Blind, Switch, ...).
Device Name as set in TapHome system.
Device Status as text information
LIST<\r><\n> command example output:
ID:2,Type:MultiValueSwitch,Name:Heating & Cooling,Status:OK<\r><\n>
Command GET need one parameter - device ID. It returns device status and values as numbers.
Example output of command GET 137<\r><\n>
Example when header is off:
Command SET need at least three parameters. First it is device ID, then new device status to be set and then at least one value to be set. For devices with more than one value all values should follow - for example blind require both parameters to be send - new level and new angle.
Example of output of command SET 137 0 35 80<\r><\n> with and then without header information:
Command action will execute action on device ID with send value. Actions are defined only for blinds. There are three actions number for blinds:
0 blind stop
1 adjust level from actual position +-value
2 adjust blind angle from actual position +-value
Example output of command ACTION 137 1 -20<\r><\n>:
Command PUSHALL will enable sending of all devices changes. Information are send in same format as response to command GET. Please note that when used on RS485 line there can be possible conflict on the bus which resolve to data mismatch. So we suggest to use this command only in full duplex lines / like RS232 or RS422. There is possible to switch it on also on RS485 line in systems where no SET command or ACTION commands will be used - this means only in monitoring systems. In RS485 lines where it is required SET and ACTION commands we suggest to use periodic pooling through command GET instead of automatic monitoring.
When unique interface ID is set, than it is possible to use all command in address mode. In this mode the address header proceeding the command itself. Address headers is sequence!InterfaceID: where InterfaceID is set in interface configuration. Each answer line is than also proceeded with the same header. Only interface with correct address will answer - incorrect addressing can not be recognized by answer.
Example of address mode request with command !2:LIST<\r>:
!2:ID:3,Type:MultiValueSwitch,Name:Heating & Cooling,Status:OK<\r><\n>
Exposed devices in Integration protocol
For exposing devices in Integration protocol first go to Expose devices and choose Add new interface. From offered interfaces choose one of Integration protocol RS485, Integration protocol TCP or Integration protocol UDP:
After adding interface according to type fill other parameters. Set unique Interface ID for each interface if you want to use address mode.
Choose terminal for communication and fill communication parameters for RS485. Set all serial line parameters as required by connected client.
Set TCP port of slave interface:
Set UDP port of slave interface:
Then use Add device to add your devices in the exposed devices:
Choose device from list of offered devices. Please note that already added devices are shadowed.
After adding device it is displayed in list of devices for Integration protocol interface:
Click on device to display information about it, change automatically generated device ID, or delete device from exposed devices.