API Reference Guide

From OpenMotics
Jump to: navigation, search

Contents

General

All communication between the Gateway (G) Controller and the Master (M) Controller will be based on standard TTL RS232 (baudrate 115200, 8 databits, no parity, 1 stopbit, no flow control).

2 modes of communication are possible:

  • Advanced communication protocol (Advanced Mode - API)
  • Simple communication protocol (Simple Mode - CLI)

Changing mode from API to CLI is done through the instruction CM (described in this document). Changing from CLI to API is done with the instruction <mode>exit</mode> (described in the CLI Reference Guide).

Depending how jumper J1 and J2 is set, internal or external TTL RS232 communication can be made (See RS232):

  • J1 and j2 set: The Master Controller is connected over RS232 with the Gateway controller
  • J1 and J2 removed: The Master controller TTL RS232 connection is available on the TTL CLI connector

Versioning

This document describes the API instruction available on the Gateway Module RS232 Master Controller interface.

Gateway Module FW version
3.140.x

Notation

Every API instruction must start with string characters STR always followed by 18 bytes (when not mentioned otherwise) as described in this document. In API mode, no characters will be echoed.

Example:

' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR B A CID AT AN 0 0 0 0 0 0 0 0 0 0 0 13 10
  • When this font is used, these are ascii characters to be directly sent, no interpretation needed
  • When this font is used, a variable will be used to represent the byte to be sent.
  • Byte 0 till 15 will contain data, followed by Byte 16 CR(DEC 13 - carriage return) and byte 17 LF (DEC 10 - line feed) as termination bytes. This is the case for most instructions, however, exceptions exist that send or receive more characters than 18.
  • Byte 0 and 1 will always contain the instruction or the response instruction (always 2 bytes)
  • CID: Byte 2 will always contain the Communication ID. When the Gateway Controller sends a request to the Master Controller, the Gateway Controller will add a communication ID (communication number) in byte2. The Master will always answer the request of the Gateway with the same communication ID. When the Gateway performs an automatic send, the communication ID will not be used and byte2 will be filled with a “null”. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • M->G: Communication from Master Controller to Gateway Controller
  • G->M: Communication from Gateway Controller to Master Controller
  • When Null or 0 is indicated as character, any character can be sent. Characters indicated as null as receiver can be ignored.

Instruction Set

AE -> Activate Eeprom

The Master Controller is equipped with an external memory (Eeprom 25LC512). When the Master starts up, Eeprom data is copied in RAM memory. When data in Eeprom is changed (by using API or CLI commands), RAM memory must be updated by performing a copy from Eeprom to RAM. This is done by the instruction “AE”.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR A E CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Communication ID (filled in by Gateway, copied in the response of the Master)
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
A E CID Res1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Res1-Res2: OK -> After data is successfully copied into RAM, instruction “OK” will be send back.
  • Res1-Res2: ER -> If the operation is not successful, Error instruction ”ER” will be send back.

Note1: This response will be received in normal circumstances, when an error occurs, an error message will be sent (see automatic sends: Error)

Note2: API instruction "ae" also exist but has a different function

AV -> Add Virtual Module

The Master Controller can also use Virtual Modules (available in Firmware version 3.142.1 and higher). For more explanation, see Virtual Inputs, Virtual Outputs and Virtual Sensors. This instruction will add a Virtual Module in the module list.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR A V CID VMT 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • VMT: Virtual Module type ("i", "o" or "d")

Note1: 3 different type of virtual modules can be created ("o" -> Virtual Output module, "d" -> Virtual Dimmer module, "i" -> Virtual input module)

Note2: Virtual sensors will not be added as a virtual sensor module. The system allows 32 sensors. Each sensor can be configured as normal or as virtual.

Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
A E CID Res1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Res1-Res2: OK -> when the virtual module has been added, instruction “OK” will be send back.

ae -> RTD-10 Airco Value refresh

When the Beagle Bone black is updating eeprom data for the RTD-10 function, this data (for example ventilator speed) must be updated immediately so after changing the eeprom value, please use this instruction to activate these eeprom changes. For more information about the RTD-10 function, please see the Heating/Cooling pages.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR a e CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
a e CID Res1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Res1-Res2: OK -> After data is successfully copied into RAM, instruction “OK” will be send back.
  • Res1-Res2: ER -> If the operation is not successful, Error instruction ”ER” will be send back.

Note1: This response will be received in normal circumstances, when an error occurs, an error message will be sent (see automatic sends: Error)

Note2: API instruction "AE" also exist but has a different function

AR -> RTD-10 Airco ON/OFF status bit Read

This function will read the 24 Airco Status Bits (ASB) in case the RTD-10 function is used. Please see the Heating/Cooling Pages for more details about the RTD-10 function.

Please Note that the Thermostat Mode is used to enable Cooling/Heating, the Airco ON/OFF bit will be used when RTD-10 function is activated (by using 240 as thermostat output). For more information about the RTD-10 function, please see the Heating/Cooling pages.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR A R CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5-26 27 28
A R CID ASB0 ASB1 ASB2-23 13 10
  • ASB0-23: Airco Status Bit (ASB), When ASBx=0 -> Airco x is OFF, When ASBx>0 -> Airco x is ON
  • Firmware version 3.143.18 and higher have the possibility to configure the "Maximum number of Thermostats". The "Maximum number of Thermostats" can be set between 24 and 32. When more then 24 thermostats are configured (See Memory Model Page0/Byte59), the above output data will be increased so instead of 24 bytes of data, 32 bytes will be thrown if Byte0/Page59=32 for example. The standard configuration for "maximum number of thermostats" is 24.

AW -> RTD-10 Airco ON/OFF status bit Write

This function will write one of the 24 (or 32 as of firmware version 3.143.18 and higher) Airco Status Bits (ASB) in case the RTD-10 function is used. Please see the Heating/Cooling Pages for more details about the RTD-10 function.

Please Note that the Thermostat Mode is used to enable Cooling/Heating, the Airco ON/OFF bit will be used when RTD-10 function is activated (by using 240 as thermostat output).

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR A R CID Thermostat Nr ASB 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Thermostat Nr: Thermostat Nr (0-23) for which the ASB must be changed
  • ASB: Airco Status Bit (ASB), When ASB=0 -> Airco is OFF, When ASB>0 -> Airco in ON
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5-26 27 28
A W CID ASB0 ASB1 ASB2-23 13 10
  • ASB0-23: Airco Status Bit (ASB), When ASBx=0 -> Airco x is OFF, When ASBx>0 -> Airco x is ON
  • Firmware version 3.143.18 and higher have the possibility to configure the "Maximum number of Thermostats". The "Maximum number of Thermostats" can be set between 24 and 32. When more then 24 thermostats are configured (See Memory Model Page0/Byte59), the above output data will be increased so instead of 24 bytes of data, 32 bytes will be thrown if Byte0/Page59=32 for example. The standard configuration for "maximum number of thermostats" is 24.

To switch ON/OFF the airco units with RTD-10 function, Basic Action 81 can be used as well.

BA -> Basic Action

This API call will perform a Basic Action to be put on the action queue for execution. Essentially, 95% of the different actions that can be done by the system can be performed by using basic actions. Basic actions will allow the programmer to execute a variety of actions with 1 instruction. Example of basic actions are: Switching a light ON, switching a light OFF, dimming lights, toggle lights, switching groups ON/OFF, perform group actions, make changes in the thermostat settings, perform IF THEN ELSE functions, delay actions etc. The different basic actions that exist can be found back in the Addenda of the CLI reference guide document.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR B A CID AT AN 0 0 0 0 0 0 0 0 0 0 0 13 10
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
B A CID Resp1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Res1-Res2: OK -> Instruction is put in the action queue.
  • Res1-Res2: ER -> Communication error.
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • AT: Action Type of the Basic Action to be executed (For more explanation: see Basic Action and Action Types)
  • AN: Action Number of the Basic Action to be executed (For more explanation: see Basic Action and Action Types)

Note: Every combination of 2 bytes can be put in action the queue. The “OK” response gives only an indication that the instruction is executed and put on the action queue. The “OK” doesn't mean that a valid instruction in the queue was executed. If non-acceptable values have been put in the queue, the Master will not execute those queue entries and remove them from the action queue.

bl -> Brightness List

This function will read the list of brightness values of the 32 (0-31) sensors

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR b l CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3-34 35 36 37 38 39
b l CID Bri 0-31 C CRC.Byte1 CRC.Byte0 13 10
  • Response is 40 bytes long
  • Bri 0-31: Brightness of sensor 0 - 31 (represented as System Value)
  • CRC is the sum of all decimal values of all characters except for the 2 start characters “hl”, CID, “C” character at the end together with the CRC itself and the double LF/CR. The sum of the CRC is stored in a word (2 bytes: CRC.Byte1 and CRC.Byte0) variable. Each CRC starts with character “C” followed by 2 bytes.

Note: All brightness values are in System Value format

CC -> CAN Communication

This instruction will transparently sent a CAN message on the CAN bus. This instruction is mainly used for bootloader purposes.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR C C CID NrOfBytes SID Byte0 Byte1 Byte2 Byte3 Byte4 Byte5 Byte6 Byte7 C CRC.Byte1 CRC.Byte0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • CRC is the sum of all decimal values of all characters except for the 2 start characters “CC”, CID, “C” character at the end together with the CRC itself and the double LF/CR. The sum of the CRC is stored in a word (2 bytes: CRC.byte1 and CRC.Byte0) variable. Each CRC starts with character “C” followed by 2 bytes.

Response M->G:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
C C CID NrOfBytes SID Byte0 Byte1 Byte2 Byte3 Byte4 Byte5 Byte6 Byte7 C CRC.Byte1 CRC.Byte0 13 10
  • Hw: Hardware version type
  • F1, F2 and F3: Major firmware version, minor and built of the active code section
  • Stat: status of the application firmware code and the Total CRC. (0 if match, 1 if some mismatch) (only updated if the FE command is send)
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

cl -> Temperature List

This function will read the list of temperature values of the 32 (0-31) sensors

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR c l CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3-34 35 36 37 38 39
c l CID Temp 0-31 C CRC.Byte1 CRC.Byte0 13 10
  • Temp 0-31: Temperature of sensor 0 -31 (represented as System Value)
  • CRC is the sum of all decimal values of all characters except for the 2 start characters “cl”, CID, “C” character at the end together with the CRC itself and the double LF/CR. The sum of the CRC is stored in a word (2 bytes: CRC.byte1 and CRC.Byte0) variable. Each CRC starts with character “C” followed by 2 bytes.

Note: All temperature values are in System Value format

cm -> Change Communication length

This instruction will change the communication protocol between 18 or 77 characters and will enable/disable silent mode of the bus.

The instruction “cm” is used when larger amounts of data must be downloaded to the remote modules when they are in bootloader mode. This instruction must be done before actually starting the download. In normal circumstances, the communication between Master en Gateway is based on a 18 (0-17) character communication protocol. This instruction will set the receiving protocol of the Master to 77 characters instead of 18 or bring it back to 18 characters.

Additionally, this instruction can enable the bus to be in silent mode. When the bus is in silent mode, normal operation of input and output modules is not possible. This mode will only be enabled when new firmware must be loaded.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 ... 16 or 76 17 or 77
STR c m CID Max Char BL mode 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Max Char (18 or 77): This will indicate if the next message (after executing this one) to the master is 77 characters wide or the normal 18 character message. The value for Max Char can only be 18 or 77.
  • BL mode: When BL mode=0 -> Normal operation, When BL mode=1 -> Bootloader (silent) mode
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
c m CID Max Char BL Mode 0 0 0 0 0 0 0 0 0 0 0 13 10

CM -> Change Mode

When changing from Advanced (API) Mode to Simple (CLI) Mode, the command “CM” must be used.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR C M Mode 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Mode: ascii character “0” -> CLI mode, ascii character “1” API mode
Response M->G

Ok

  • Every character send from Gateway to Master will now be echoed as expected in CLI mode.
  • To change from Simple mode (CLI) to Advanced mode(API) again, following instruction must be given: “exit” followed by CR
  • This instruction has no CID since CLI mode doesn't use the CID parameter.

Note: This command can be used in API mode as well in CLI mode. This is useful, when connecting, to put the system immediately in the right mode (without knowing in which mode the system is). In this particular case, start sending CR (DEC 13) followed by “STRCM0” or “STRCM1” followed by 13 characters (spaces for example), followed by CR and LF.

DA -> Discover Module Start

With this instruction, the system will be placed in discovery mode so new modules can be added. This instruction has the same behavior as the CLI instruction “module discover start”. After this instruction is executed, the bus will be in init mode. When the init button on a module is pressed, the module will sent an init message to the master and the Master will sent a “MI” message to the Gateway (for further information, see API instruction “MI”). Please note when the system is in discovery (or init) mode, the system will not work normally (switches will not work normally, basic action will not be executed, time based actions will not work etc), discovery mode is only meant to add new modules.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR D A CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
D A CID Resp1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Res1-Res2: OK -> Instruction successful.
  • Res1-Res2: ER -> Instruction failed.

DO -> Discover Module Stop

With this instruction, the system will be placed in normal mode after it has been in discovery mode. This instruction has the same behavior as the CLI instruction “module discover stop”. After this instruction is executed, the bus is in Live mode and the system will work normally again.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR D O CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Request M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
D O CID Resp1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Res1-Res2: OK -> Instruction successful.
  • Res1-Res2: ER -> Instruction failed.

ec -> Error Clear

With this instruction, the error counters of the initialized input/output modules in the Master can be cleared.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR e c CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Request M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
e c CID Resp1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Res1-Res2: OK -> Instruction successful.
  • Res1-Res2: ER -> Instruction failed.

el -> Error List

This instruction will list all error counters for input as well as output modules. The Master will communicate with each module individually and when it encounters an error, it will add this error to the error counter of that individual module.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR e l CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 ... y y+1 y+2 y+3 y+4 y+5 y+6
e l CID Nr Modules Type x Module Nr x Counter MSB x Counter LSB x Type x+1 Module Nr X+1 Counter MSB x+1 Counter LSB x+1 ... C CRC.byte1 CRC.byte0 13 10 13 10
  • The Response will have a variable length depending on the number of modules initialized
  • Nr Modules: Will indicate the number of input and Output modules that are initialized (of which the error information will follow in this message)
  • Type x: Will indicate the type of input/output module (“I” for Input, “T” for sensor, “O” for output, “D” for Dimmer, “R” for Restricted Output etc) of Module x
  • Module Nr x: Will indicate the input/output number of Module x
  • Counter MSB x: Will indicate the most significant byte of the error counter of module x
  • Counter LSB x: Will indicate the Least significant byte of the error counter of module x
  • CRC: Fixed character “C” followed by CRC MSB and CRC LSB. CRC is the sum of all decimal values of all characters except for the 2 start characters “el”, CID and the double CR/LF
  • Starting at Byte 4, first the error information of all input modules will be sent followed by the error information of all outputs. Of no input modules are initialized, then the Master will start will all output modules (if any).
  • The error counter for each module is 2 byes long (0-65535). When a error counter reaches his maximum, the error counter will remain at 65535 even when additional errors are detected.
  • After a power outage or a reset of the master, the error counters are automatically cleared.

EL -> Eeprom List

The Master has an eeprom with 256 (0-255) banks of 256 bytes. With this instruction, you can read 1 full bank (256 bytes).

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR E L CID Bank 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Bank: Bank to be read, bank must be between 0 and 255.
  • CID: Byte 2 will always contain the Communication ID. When the Gateway (Linux board) sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 ... 257 258 259 260 261
E L CID Bank Byte0 Byte1 Byte2 Byte3 Byte4 Byte5 Byte6 Byte7 Byte8 Byte9 ... Byte253 Byte254 Byte255 13 10
  • The Master will always respond with 262 bytes instead of the normal 18 bytes even when a bank is empty (all bytes=255).

ER -> Error

Automatic send

When the Bus is in Live mode and an error occurs, an automatic message will be sent to the Gateway.

Automatic sent M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
E R 0 Error Code ID0 ID1 ID2 ID3 0 0 0 0 0 0 0 0 13 10
  • ID0..ID3: address ID of the module with an error
  • Error Code: This represents the error number which can be found back in the list of Error Codes
  • CID is not used.

EV -> Event

Automatic send

When Basic Action 60 is executed, an event will be generated and be sent to the Beagle Bone black by API instruction EV and to the RS232 port of the Master when RTI is enabled. An example: When a "lights all off function" is programmed with a long press on a switch, we also want hifi and TV to switch off so we need a Basic Action that can be added to the all off to trigger the Beagle Bone black to execute actions (by using the Openmotics plug-in system for example).

Automatic sent M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
E V 0 Event Code 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Event Code: This represents the event code which is used in Basic Action 60.
  • CID is not used.

FB -> Button pressed in bootloader mode

When the module is in Bootloader mode and the init button is pressed, the below message is sent.

Automatic sent M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F B CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FC -> Write CRC of new loaded firmware

This instruction will write the full CRC of the new firmware version to be loaded. This instruction will only work when the remote module is in Bootloader mode.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F C CID ID0 ID1 ID2 ID3 CRC3C CRC2C CRC1C CRC0C C CRC.Byte1 CRC.Byte0 0 0 13 10
  • ID0..2 = ID of the Slave module addressed
  • CRC3C, CRC2C, CRC1C and CRC0C: 4 bytes CRC of the new firmware to be written
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • CRC.Byte1 and CRC.Byte0: CRC of the message itself (sum of all bytes except "C", CRC.byte1, CRC.Byte0 and CR/LF)
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F C CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FD -> Write 1 block of firmware

This instruction will upload 1 block (64 bytes) of new RS485 slave firmware to 1 RS485 slave. This instruction will only work when the remote module is in boot loader mode and when the communication protocol is put on 77 bytes (“cm”).

The goal of this instruction is to sent 1 block (64 bytes) of new firmware to 1 module.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 ... 72 73 74 75 76 77
STR F D CID ID0 ID1 ID2 ID3 Addr1 Addr0 Data0 Data1 ... Data63 C CRC.Byte1 CRC.Byte0 13 10
  • Addr1-0: Address of block to be written
  • Data0-63: This contains 1 block (64 bytes) of firmware.
  • CRC1-0: CRC check = sum of all bytes except CID , “C”, CRC.Byte1, CRC.Byte0, CR and LF
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F D CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • This instruction can only be used when first the instruction “cm” is used to set the receiving Master protocol at 77 characters.
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FE -> Ends the firmware operations loading

This instruction will end the firmware download operation of the RS485 slave module and will trigger the integrity check of the downloaded firmware. The variable ‘Err’ will indicate the result of the downloaded firmware. This instruction must be executed after full firmware download.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F E CID ID0 ID1 ID2 ID3 C CRC.Byte1 CRC.Byte0 0 0 0 0 0 0 13 10
  • ID0..3 =ID of the module that needs to be brought in bootload mode
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response G->M
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F E CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FG -> Goto App Mode

This instruction will put the slave module back in normal (App) mode (leave bootloader mode)

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F G CID ID0 ID1 ID2 ID3 C CRC.Byte1 CRC.Byte0 0 0 0 0 0 0 13 10
  • ID0..2 = ID of the Slave module addressed
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response G->M
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F G CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FH -> Check Bootloader Version

This instruction will request bootloader version information from any RS485 slave device active on the RS485 bus.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F H CID ID0 ID1 ID2 ID3 C CRC.Byte1 CRC.Byte0 0 0 0 0 0 0 13 10
  • ID0..ID3: Unique address ID of the slave module, ID0 is always the module type
  • ID0 =“I” for Input module, “R” for Restricted (Shutter) Output, “O” for output, “D” for Dim control, “T” for Temperature module, “L” for Oled etc
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.

Response M->G:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
F H CID ID0 ID1 ID2 ID3 Err F1 F2 C CRC.Byte1 CRC.Byte0 13 10
  • F1, F2: Major and minor bootloader version
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FN -> Prepare RS485 slave module to receive new firmware

This instruction will prepare the RS485 slave modules to receive new firmware. This instruction will only work when the remote module is in boot loader mode.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F N CID ID0 ID1 ID2 ID3 F1N F2N F3N C CRC.Byte1 CRC.Byte0 0 0 0 13 10
  • ID0..2 = ID of the Slave module addressed
  • F1N, F2N and F3N: Major firmware version, minor and built of the new code section that will be loaded
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F N CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FR -> Reset RS485 slave modules

This instruction will reset the addressed RS485 slave module and put them in bootloader mode for x seconds.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F R CID ID0 ID1 ID2 ID3 x C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • ID0..3 =ID of the module that needs to be brought in bootload mode
  • x= number of seconds the module will remain in bootloader mode.
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F R CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works


FV -> Check Firmware Version of a RS485 slave module

This instruction will request version information from any RS485 slave device active on the RS485 bus.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F V CID ID0 ID1 ID2 ID3 C CRC.Byte1 CRC.Byte0 0 0 0 0 0 0 13 10
  • ID0..ID3: Unique address ID of the slave module, ID0 is always the module type
  • ID0 =“I” for Input module, “R” for Restricted (Shutter) Output, “O” for output, “D” for Dim control, “T” for Temperature module, “L” for Oled etc
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.

Response M->G:

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F V CID ID0 ID1 ID2 ID3 Err Hw F1 F2 F3 Stat C CRC.Byte1 CRC.Byte0 13 10
  • Hw: Hardware version type
  • F1, F2 and F3: Major firmware version, minor and built of the active code section
  • Stat: status of the application firmware code and the Total CRC. (0 if match, 1 if some mismatch) (only updated if the FE command is send)
  • Err: Error code received from module in Bootloader, see Bootloader Error Codes
  • See Bootloader for more information how the Bootloader of the Remote Modules works

FX -> Erase external Eeprom slave modules and perform factory reset

This instruction will erase the internal and external (if installed) Eeprom of the slave module and bring it back to factory reset. This instruction is only applicable for the CAN Control since this is the only module with an external eeprom built-in.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F X CID ID0 ID1 ID2 ID3 Instr C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • ID0..3 =ID of the module that needs a factory reset
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Instr: Instruction will indicate which type of erase is requested. If Instr=0 then full erase is performed (=ID of the CAN modules will be erased, Eeprom of the CAN module will be erased, connected uCAN's will be erased), if instr=1 then only the Number of Inputs of the CAN control will be erased (the connected uCAN's inputs will be set to factory reset), if instr=2 then only the Number of sensors of the CAN control will be erased (the connected uCAN's sensors will be set to factory reset)
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F X CID ID0 ID1 ID2 ID3 Err C CRC.Byte1 CRC.Byte0 0 0 0 0 0 13 10
  • Err: Error code received from module
  • The response will be sent before the process of erasing starts so the response is not an indication of a successful erase. The erase for devices with external eeprom (example CAN Control) typically takes multiple minutes and during the erase, the status led will flash until the process is done. Once done, the module internal and external eeprom will be erased including the module ID (the master can only communicate again with this module after the discovery process is executed).

FS -> Request information from a CAN control to prepare boot loading of a Micro CAN

This instruction will request information from the CAN control like the number of Micro CAN's are connected to a certain CAN control as well as the ID's of the Micro CAN.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F S CID ID0 ID1 ID2 ID3 Instr can_nr 0 0 0 0 C CRC.Byte1 CRC.Byte0 13 10
  • ID0..3 =ID of the CAN Control Module
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Instr: If Instr=0 -> Request number of connected Micro CAN's (can_nr is ignored), If instr=1 -> Request ID of Micro CAN with can_nr
  • If for example the received number of connected Micro CAN's is 7, the software should request the ID of can_nr 0 to 6.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F S CID ID0 ID1 ID2 ID3 Instr can_nr data0 data1 data2 0 C CRC.Byte1 CRC.Byte0 13 10
  • data0..2: These are the 3 data bytes containing the requested information:
    • Instr=0: data0 contains the number of Micro CAN's connected to the CAN Control with ID0..3. data1 and data2 can be ignored.
    • Instr=1: data0 contains ID0 of the requested Micro CAN, data1 contains ID1, data2 contains ID2
  • See Micro CAN Bootloader for more information how the Bootloader of the Micro CAN Remote Modules works and for a detailed list of different CAN messages

Fm -> Set the ID of the CAN Control module

To be able to use instruction "FM", first the instruction "Fm" must be used to set the ID of the CAN Control.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F m CID ID0 ID1 ID2 ID3 0 0 0 0 0 0 C CRC.Byte1 CRC.Byte0 13 10
  • ID0..3 =ID of the CAN Control Module
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Instr: If Instr=0 -> Request number of connected Micro CAN's (can_nr is ignored), If instr=1 -> Request ID of Micro CAN with can_nr
  • If for example the received number of connected Micro CAN's is 7, the software should request the ID of can_nr 0 to 6.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F m CID ID0 ID1 ID2 ID3 Instr can_nr data0 data1 data2 C CRC.Byte1 CRC.Byte0 0 13 10
  • data0..2: These are the 3 data bytes containing the requested information:
    • Instr=0: data0 contains the number of Micro CAN's connected to the CAN Control with ID0..3. data1 and data2 can be ignored.
    • Instr=1: data0 contains ID0 of the requested Micro CAN, data1 contains ID1, data2 contains ID2
  • See Micro CAN Bootloader for more information how the Bootloader of the Micro CAN Remote Modules works and for a detailed list of different CAN messages

FM -> Put messages on the CAN bus

This instruction will forward messages through the CAN control directly on the connected CAN bus. The response will return through the CAN control towards the Master.

SID is a message identifier used for message on the CAN bus. In the Openmotics environment, 3 different SID values are used:

  • SID=6: All normal communication uses this SID so all messages generated by the CAN control will be with this SID. These message will not be tunnelled to the Master.
  • SID=0: This SID will only be used in bootloader mode of the Micro CAN. When the Micro CAN is in normal mode, those message will be ignored by the Micro CAN. All messages with SID 0 will be tunnelled towards the Master without any interpretation of the CAN Control.
  • SID=5: This SID is used to prepare the Micro CAN for bootloading. All messages with SID=5 will be tunnelled to the Master without any interpretation of the CAN Control.

The SID used in this instruction should be the following:

  • When sending instruction from the CAN Communication Protocol, always use SID=5
  • When sending pallets (when the Micro CAN is in Bootloading mode), always use SID=0
Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR F M CID nr_of_bytes SID C_Byte0 C_Byte1 C_Byte2 C_Byte3 C_Byte4 C_Byte5 C_Byte6 C_Byte7 C CRC.Byte1 CRC.Byte0 13 10
  • Nr Of Bytes: These are the number of bytes that will be sent on the CAN Bus (Min 2, Max 8)
  • C_Byte0..C_Byte7: These are the bytes that will be put on the CAN bus
  • Before using this instruction, instruction "fm" must be used to set the CAN Control ID's so the Master knows with which CAN control the communication must be done
  • CRC=sum of Byte0 to Byte12
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
F M CID nr_of_bytes SID C_Byte0 C_Byte1 C_Byte2 C_Byte3 C_Byte4 C_Byte5 C_Byte6 C_Byte7 C CRC.Byte1 CRC.Byte0 13 10
  • Nr Of Bytes: These are the number of bytes that the Micro CAN responded (Min 2, Max 8)
  • C_Byte0..C_Byte7: These are the bytes that the Micro CAN has been sending back
  • See Micro CAN Bootloader for more information how the Bootloader of the Micro CAN Remote Modules works and for a detailed list of different CAN messages

hl -> Humidity List

This function will read the list of humidity values of the 32 (0-31) sensors

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR h l CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3-34 35 36 37 38 39
h l CID Hum 0-31 C CRC.Byte1 CRC.Byte0 13 10
  • Hum 0-31: Humidity of sensor 0 -31 (represented as System Value)
  • CRC is the sum of all decimal values of all characters except for the 2 start characters “hl”, CID, “C” character at the end together with the CRC itself and the double LF/CR. The sum of the CRC is stored in a word (2 bytes: CRC.byte1 and CRC.Byte0) variable. Each CRC starts with character “C” followed by 2 bytes.

Note: All temperature values are in System Value format

GI -> Gateway information

Not yet implemented.

The Gateway has additional information which is not available in the Master. An example is the power information: The Openmotics system can be equipped with power meters to know all the detailed power and energy information. This instruction will allow the user to retrieve detailed power information of a power port.

Please note that this information is added by the gateway and not available in the master processor in other words this information can be available on the UART1 or UART2 port of the gateway and not on the master CLI port (when the 2 jumpers are removed), see RS232.

This instruction will allow the RTI driver or other RS232 equipment to retrieve the additional Gateway information.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR G I CID GI Type GI Action 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • GI Type: Indicates which instruction must be executed
    • GI Type="P": Request Power information
  • GI Number: Indicates which action number must be executed
    • Power Port (GI Type="P"): Indicates from which port (0-255) the power information is requested.
Response M->G
GI Type="P"
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 16 17 18
G I CID P Power Port Power1 Power0 Voltage1 Voltage0 Current1 Current0 Frequency1 Frequency0 C CRC.Byte1 CRC.Byte0 13 10
  • P: Instruction type "P" has been selected to retrieve the Power information
  • Power Port: Indicates for which power port (0-255) the power information is presented
  • Power1: Most significant byte of the power information (16 bits information, 0-65535W)
  • Power0: Least significant byte of the power information (16 bits information, 0-65535W)
  • Voltage1: Most significant byte of the Voltage information (16 bits information, 0-655,35V)
  • Voltage0: Least significant byte of the Voltage information (16 bits information, 0-655,35V)
  • Current1: Most significant byte of the Current information (16 bits information, 0-655,35A)
  • Current0: Least significant byte of the Current information (16 bits information, 0-655,35A)
  • Frequency1: Most significant byte of the Frequency information (16 bits information, 0-655,35Hz)
  • Frequency0: Least significant byte of the Frequency information (16 bits information, 0-655,35Hz)
  • CRC: Fixed character “C” followed by CRC MSB (CRC.byte1) and CRC LSB (CRC.byte0). CRC is the sum of all decimal values of all characters except for the 2 start characters “PO”, CID and the LF/CR

IL -> Input ON

This instruction will automatically be sent when an input goes to the ON state and when the automatic response byte IL (page0 byte 20 of eeprom, see Memory Model) is <>255.

Request G->M

Not applicable

Automatic Response M->G
0 1 2 3 4 5 6 7 8
I L CID Input Output 13 10 13 10

Byte Byte Byte Byte Byte Byte Byte Byte Byte 0 1 2 3 4 5 6 7 8 "I" "L" CID Input Output CR LF CR LF

  • CID: Byte 2 will always contain the Communication ID. When the Gateway (Linux board) sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used. Because “IL” is an automatic sent, CID can be ignored.
  • Input: Input number that is pressed
  • Output: this will indicate which output (=input link byte) is linked to the pressed input.
  • If 2 inputs are pressed for example, 2x “IL” will be received
  • If output =255, no function is linked to this input. If output=240, the input action list will be executed.
  • Activating and deactivating of this automatic response can be done by changing page 0 byte 20 followed by an eeprom activation action (see Memory Model.

IN -> Led Indicate Input/Output/Sensor

All input/output/sensor modules have leds. When a user wants to find back a certain input/output/sensor, led flashing can be activated by using this instruction.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR I N CID IT IA 0 0 0 0 0 0 0 0 0 0 0 13 10
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
I N CID Resp1 Resp2 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • IT: Indicate Type: This parameter will set which type of module must be addressed. When IT=0 -> Output/dimmer module, IT=1 -> Input module, IT=2 -> Temperature/sensor module
  • IA: Indicate Action: This parameter will set the input/output/sensor number that must flash.
  • Res1-Res2: OK -> Instruction successful.
  • Res1-Res2: ER -> Instruction failed.

MI -> Module initialize message

Automatic send

When the Bus is in discovery mode (see API instruction “DA”), a new module can be added or an existing can be detected. By pushing the init button on an input/output/dim control/temperature etc module, the module will sent an init message to the master and the Master will sent the “MI” instruction to the Gateway. “MI” messages are never requested by the Gateway and will be automatically sent but only when the system is in discovery mode (or init mode). When a new module is found, 2 “MI” messages will be sent, the first one that a new module is found, the second “MI” message that the module has become an existing module in the list.

Automatic sent M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
M I 0 ID0 ID1 ID2 ID3 Instruction Module Nr Data IO Type 0 0 0 0 0 13 10
  • ID0..ID3: address ID of the module detected, ID0 is always the module type
    • ID0 =“I” for Input module, “R” for Restricted/shutter Output, “O” for output, “D” for Dim control, “T” for Temperature module, “L” for Oled etc
  • Instruction: “N” -> New module found (byte 8 to 15 can be ignored), “E” -> Module exists in database (Module Nr and Data are used) of the Master Controller, “D” -> Duplicate address is found (the user needs to re-push the init button).
  • Module Nr: This is the Module ranking number in the system of the individual module (between 0-29).
    • 2 module lists exists:
      • input modules (ID0: “I”,”T”,”L”,"i" etc)
      • output modules (ID0: “O”,”D”,“R”,"o","d" etc).
  • IO Type: This indicates which type of IO is received
    • IO Type=0: Roller/Shutter module in Large Installation mode
    • IO Type=1: Any Output module except Roller/Shutter module when Large Installation mode is enabled.
    • IO Type=2: Any Input module
  • Data: data (byte) that will be read out of the selected module (input that’s being pressed for example).
  • CID is not used.

OL -> Output (that are on) List

This instruction will list all outputs (and their dimmer values) that are ON.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR O L CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • This message can also be sent automatically without any request, see explanation below.
Response M->G
0 1 2 3 4 5 6 7 ... y y+1 y+2 y+3
O L CID Nr Of Outputs ON Light 1 ON Dimmer 1 Light 2 ON Dimmer 2 ... 13 10 13 10
  • Nr of Outputs ON: Total number of outputs/lights that are ON
  • Light x ON: For every light/output that is ON, the Output nr is sent
  • Dimmer x: For every light/output that is ON, the Dimmer value is sent
  • The number of bytes in the response depends on the number of lights that are switched on. For example, when 3 lights are on, “OL” will be sent + CID + Nr of Outputs ON followed with 6 bytes for output data followed by 2 times CR + LF.
  • The “OL” response can also be automatically sent when an output has changed state (and thus without sending the “OL” instruction first). To enable this, byte 18 on page 0 of the eeprom must be below 255 (See Memory Model). This can be easily checked by following CLI instruction: eeprom read 0 18. If the result is 255, then the automatic OL response is not enabled. To enable the automatic “OL” sent, please use following 2 CLI instructions: eeprom write 0 18 0 and eeprom activate.
  • When an automatic “OL” response is sent (and thus without sending the “OL” instruction first), the CID of that instruction will be 0.
  • A second automatic response byte (page 0 byte 11 in eeprom, see Memory Model) exist that will sent the “RO” API message when an output changes state. To avoid receiving double messages, this can be disabled by using following 2 CLI instructions: eeprom write 0 11 255 and eeprom activate.
  • The automatic responses will only be sent in API mode

PL -> Pulse Counter list

The Master is equipped with 24 Pulse counters (Firmware version F3.141.19 or higher) which allows the connection of Power meters, water meters and gas meters etc equipped with a pulse output. Each input module keeps track of the number of input changes and will send those pulse counters to the Master processor of the Gateway. The Gateway can be configured to link certain inputs to certain Pulse counters (see Memory Model Page 0 Byte 160).

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR P L CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3-4 5-6 7-8 9-10 11-12 13-14 15-16 17-18 19-20 21-22 23-24 25-26 27-28 29-30 31-32 33-34 35-36 37-38 39-40 41-42 43-44 45-46 47-48 49-50 51 52 53 54 55
P L CID Pv0 Pv1 Pv2 Pv3 Pv4 Pv5 Pv6 Pv7 Pv8 Pv9 Pv10 Pv11 Pv12 Pv13 Pv14 Pv15 Pv16 Pv17 Pv18 Pv19 Pv20 Pv21 Pv22 Pv23 C CRC.Byte1 CRC.Byte0 13 10
  • Pvx: Pulse Counter Variable (2 bytes (MSB+LSB) -> word): in this variable, the pulse counter value will is stored.
  • CRC: Fixed character “C” followed by CRC MSB (CRC.byte1) and CRC LSB (CRC.byte0). CRC is the sum of all decimal values of all characters except for the 2 start characters “PL”, CID, "C", CRC.Byte1, CRC.Byte0 and the LF/CR

Note: When the system restarts due to power failure for example, all pulse counter variables will be reset.

pL -> Permanent Manual Thermostat List

This function is available as of Firmware Version V3.142.2 and higher and will read the thermostat list to see which thermostats are in Permanent Manual mode and which are not. See Virtual Sensors for more information.

To configure the Permanent Manual thermostats, please write the appropriate values in the Eeprom of the master (page 195), see Memory Model.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR p L CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 ... 26 27 28 29 30 31 32 33 34
p L CID TM PMT-0 PMT-1 PMT-2 PMT-3 ... PMT-22 PMT-23 C CRC.Byte1 CRC.Byte0 13 10 13 10
  • TM: Thermostat mode BIT4: =0 -> Heating mode, =1 -> Cooling mode (See Thermostat Mode)
  • PMT-X: Permanent Manual Thermostat setting for thermostat x, result is 0 (Thermostat will follow all setpoints settings of Openmotics configuration) or 1 (Thermostat is in permanent manual mode and won't follow any of the Openmotics automatic setpoints setting).
  • CRC: Fixed character “C” followed by CRC MSB (CRC.byte1) and CRC LSB (CRC.byte0). CRC is the sum of all decimal values of all characters except for the 2 start characters “pL”, CID, "C", CRC.Byte1, CRC.Byte0 and the LF/CR
  • Firmware version 3.143.18 and higher have the possibility to configure the "Maximum number of Thermostats". The "Maximum number of Thermostats" can be set between 24 and 32. When more then 24 thermostats are configured (See Memory Model Page0/Byte59), the above output data will be increased so instead of 24 bytes of data, 32 bytes will be thrown if Byte0/Page59=32 for example. The standard configuration for "maximum number of thermostats" is 24.


Note 1: You have 24 PMT bits for Heating and 24 bits for Cooling. When the system is in Heating (Thermostat mode.BIT4=0), the API command will send the Heating PMT bits, when the system is in Cooling (Thermostat mode.BIT4=1), the API command will send the Cooling PMT bits.

Note 2: The change in Permanent Manual mode is done by using Basic Action 82 (set) and 83 (Clear). When BA 82 or 83 is performed, the API instruction "pL" is automatically sent (CID=0). The "pL" will always sent the list of it's currently active mode (cooling or heating) in other words, when your system for example is in Heating mode and you make a change of a Permanent Manual setting of a Cooling thermostat, the "pL" instruction will contain the Heating parameters.

re -> Reset Master

This instruction is used to reset the Master Controller. This is useful when for example the new firmware must be loaded by using the bootloader.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR r e CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Request M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
r e CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • When the instruction “re” is sent to the Master, first the response will be sent followed by the reset.
  • After a reset, the Master will start-up with the settings retrieved from the eeprom. When the Master is programmed to start-up in CLI mode, than it will start-up in CLI mode.

RE -> Read Eeprom

The Master Controller is equipped with an Eeprom of 256x256 bytes (256 banks, each bank has 256 bytes). Instruction “R” will read max 10 bytes data from the eeprom.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR R E CID Bank Addr Nmbr 0 0 0 0 0 0 0 0 0 0 13 10
  • Bank: Bank number in Eeprom (0 to 255)
  • Addr: Start address (0 to 255) in selected bank
  • Nmbr: Number of bytes to read (1 to 255) in the same bank. When Nmbr=0 then the full page (256 bytes) will be sent starting at Address Addr.
  • When the end of a bank is reached, the Master continues to read in the beginning of the same bank. For example: read 9 bytes in bank 15 and start at address 250. The Master will start reading at address 250, then go to address 251, 252, 253, 254, 255 and the continues at address 0 of the same bank (15).
  • CID: Communication ID (filled in by Gateway, copied in the response of the Master)
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
R E CID Bank Addr Nmbr Data0 Data1 Data2 Data3 Data4 Data5 Data6 Data7 Data8 Data9 13 10
  • Bank: Bank (page) in Eeprom (0 to 255)
  • Addr: Start address in Bank (page) (0 to 255)
  • Nmbr: Number of bytes to read (1 to 10).
  • Data0..9: These are the data (bytes) read from the Eeprom. In the case of more than 1 byte (#>1) , additional bytes will be read from the same page.
  • Maximum 10 bytes can be read.

ri -> Read detail information of 1 input

This instruction will read all relevant programmed data of 1 input.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR r i CID input nr 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • input nr: 0-239
Response M->G
0 1 2 3 4 5-34 35-42 43 44 45 46 47 48 49
r i CID input nr Output Action Action Type+Action number 0..14 Input Name C CRC.Byte1 CRC.byte0 13 10 13 10
  • Input nr: Input Number (0-239)
  • Output Action: Every Input has an output action. When the output action is <240, then the output specified in the output action will be toggled when the input has been triggered. When the output action is =240, then the actions of the input action list (up to 15 actions per input) will be activated when the input is triggered.
  • Action Type+Action Byte 0..14: These 30 bytes will display the 15 Basic Actions (action type+ action byte) of the input action list
  • Input name: Ascii name of input (8 characters)
  • CRC: Fixed character “C” followed by CRC MSB (CRC.byte1) and CRC LSB (CRC.byte0). CRC is the sum of all decimal values of all characters except for the 2 start characters “ro”, CID and the double LF/CR

rn -> Read Number of input and output modules

This instruction will read the number of initialized input and output modules.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR r n CID input nr 0 0 0 0 0 0 0 0 0 0 0 0 13 10
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
r n CID Nr of Input Modules Nr of Output Modules Nr of Roller/Shutters 0 0 0 0 0 0 0 0 0 0 13 10
  • Nr of Input Modules: This value will indicate the number of initialized input modules. If the received value is for example 2, then 2 input modules are installed and initialized.
  • Nr of Output Modules: This value will indicate the number of initialized output modules (including Roller/Shutters when not in Large Installation mode. If the received value is for example 2, then 2 output modules are installed and initialized.
  • Nr of Roller/Shutter modules: This value will indicate the number of Roller/shutter that are in Large Installation mode. When the system is not in Large Installation mode, the roller/shutters will be found in the Nr of output modules.

RO -> Read Output

This function will read all Outputs of the Master controller, multiple RO instructions will be sent back depending in the number of output modules installed.

Please note that this instruction will not sent back the status of the Roller/Shutter modules that are added in Large Installation mode. To know the status of those modules, please use instruction SO.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR R O CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • This message can also be sent automatically without any request, see explanation below.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
R O CID Module Nr 0 0 0 Output Status Dimmer Value0 Dimmer Value1 Dimmer Value2 Dimmer Value3 Dimmer Value4 Dimmer Value5 Dimmer Value6 Dimmer Value7 13 10
  • Module Nr: Indicates the Module Nr (0-29) for which the data is being sent out
  • Output Status: Gives the Output status (1 bit per output) of Module Nr
  • Dimmer Value0-7: Gives the dimmer value (0-63) of every output of Module Nr. When the Module is not a dim control module, these values can be ignored.
  • The “RO” response can also be automatically sent when an output has changed state (and thus without sending the “RO” instruction first). To enable this, byte 11 on page 0 of the eeprom must be below 255 (See Memory Model). This can be easily checked by following CLI instruction: eeprom read 0 11. If the result is 255, then the automatic RO response is not enabled. To enable the automatic “RO” sent, please use following 2 CLI instructions: eeprom write 0 11 0 and eeprom activate.
  • When an automatic “RO” response is sent (and thus without sending the “RO” instruction first), the CID of that instruction will be 0.
  • A second automatic response byte (page 0 byte 18 in eeprom, see Memory Model) exist that will sent the “OL” API message when an output changes state. To avoid receiving double messages, this can be disabled by using following 2 CLI instructions: eeprom write 0 18 0 and eeprom activate.
  • The automatic responses will only be sent in API mode

ro -> Read detail information of 1 output

This instruction will read all relevant output programmed data of 1 output.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR r 0 CID Output Nr 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Output nr: 0-239
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18-33 34 35 36 37 38 39 40
r o CID Output Nr Type Light Timer MSB Timer LSB C Timer MSB C Timer LSB Status Dimmer Value Controller Out Max Power Floor Level Input Pressed Link out Menu position Data0..15 C CRC.Byte1 CRC.Byte0 13 10 13 10
  • Output nr: Output Number (0-239)
  • Type: D for Dimmer, O for output and R for Roller/Shutter
  • Light: 1->Light, 0->Output
  • Timer: Programmed Timer Value (MSB+LSB)
  • C Timer: Current timer Value (MSB+LSB)
  • Status: 0-> output or light off, 1->output or light on
  • Dimmer Value: Current dimmer value (light can be on or off), dimmer value from 0 to 63
  • Controller Out: Number of output modules for the total system
  • Max Power: Max power value (x10)
  • Floor Level: Indicates on which floor the light or output is present (give the ability to switch of all lights for example of the second floor)
  • Menu Position: Value indicates on which position of the menu (of the pronto for example) this output will appear
  • Data0..15: Ascii name of output or light (16 characters)
  • CRC: Fixed character “C” followed by CRC MSB and CRC LSB. CRC is the sum of all decimal values of all characters except for the 2 start characters “ro”, CID , "C", CRC.Byte1, CRC.Byte0 and the double LF/CR

rs -> Read thermostat Setpoint (and other thermostat related parameters)

The Master is has 24 (or 32 as of firmware version 3.143.18 and higher) built-in PID controllers to manage the temperature of a room. With the instruction “RS”, the system will provide the current setpoint, the current temperature the programmed setpoints etc of a certain room.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR r s CID Thermostat Nr 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Thermostat Nr: Requested Thermostat (0-23)
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19-34 35-94 95 96 97 98
r s CID Thermostat Nr Act T C Setp P Setp0 P Setp1 P Setp2 P Setp3 P Setp4 P Setp5 Sensor Nr Output Nr 0 Output Nr 1 Output0 Output1 Outside Temp TM Data0..15 Vars 13 10 13 10
  • Thermostat Nr: Thermostat Number (0-23)
  • Act T: Actual Temperature of the selected (Nmbr) thermostat
  • C Setp: Current setpoint temperature of the selected thermostat
  • P Setp0..5: Programmed setpoint of selected thermostat. Each thermostat has 6 (0..5) preprogrammed setpoint that can be used for day1/night/day2/away/vacation/party temperature setpoint. The preprogrammed setpoint can be used in special actions to change the current setpoint of a thermostat or a serie of thermostats.
  • Sensor Nr: Each thermostat has a temperature sensor (0-31). This variable will indicate which sensor is linked to the selected thermostat.
  • Output Nr 0,1: Each thermostat can be linked to 2 outputs (0-239, relay or 0-10V output) on which for example an electric valve can be connected. First output is the primary output, if the room can’t be heated by the first output, the second output (if used) will be switched on to provide additional heating (depending on the PID paranmeters.
  • Output0+1: This is the output value (0-63) of Output0 Nr and Output1 Nr
  • Outside Temp: This is the actual outside temperature.
  • TM: TM is the thermostat Mode. Thermostat mode will indicate in which mode the thermostat is in. For more information about the Thermostat Mode, please refer to Thermostat Mode.
  • Data0..15: This datafield contains the ascii characters of the thermostat name.
  • Vars: This contains all the additional thermostat information
    • P (34): P Parameter of PID
    • I (35): I Parameter of PID
    • D (36): D Parameter of PID
    • Int Thresh (37): : Int Thresh Parameter of PID
    • Thresh temp (38): This is the threshold temperature, if the outside temperature is below this threshold temperature, the thermostat function will be activated.
    • Days (39)
    • hours (40)
    • minutes (41)
    • Monday Start time Day1 (42): Time in System Value
    • Monday Stop time Day1 (43): Time in System Value
    • Monday Start Time Day2 (44): Time in System Value
    • Monday Stop Time Day2 (45): Time in System Value
    • Tuesday Start Time Day1 (46): Time in System Value
    • ...
    • Sunday Stop Time Day2 (69): Time in System Value
    • Fixed character T(70)
    • Temperature Day1 Mon (71): Temperature in System Value
    • Temperature Day1 Tue (72): Temperature in System Value
    • Temperature Day1 Wed (73): Temperature in System Value
    • Temperature Day1 Thu (74): Temperature in System Value
    • Temperature Day1 Fri (75): Temperature in System Value
    • Temperature Day1 Sat (76): Temperature in System Value
    • Temperature Day1 Sun (77): Temperature in System Value
    • Temperature Day2 Mon (78): Temperature in System Value
    • Temperature Day2 Tue (79): Temperature in System Value
    • Temperature Day2 Wed (80): Temperature in System Value
    • Temperature Day2 Thu (81): Temperature in System Value
    • Temperature Day2 Fri (82): Temperature in System Value
    • Temperature Day2 Sat (83): Temperature in System Value
    • Temperature Day2 Sun (84): Temperature in System Value
    • Temperature Night Mon (85): Temperature in System Value
    • Temperature Night Tue (86): Temperature in System Value
    • Temperature Night Wed (87): Temperature in System Value
    • Temperature Night Thu (88): Temperature in System Value
    • Temperature Night Fri (89): Temperature in System Value
    • Temperature Night Sat (90): Temperature in System Value,
    • Temperature Night Sun (91): Temperature in System Value
    • Fixed character C for CRC (92), CRC MSB (93), CRC LSB (94)
  • CRC is the sum of all decimal values of all characters except for the 2 start characters “rs”, CID, “C” character at the end together with the CRC itself and the double LF/CR. The sum of the CRC is stored in a word (2 bytes) variable. Each CRC starts with character “C” followed by 2 bytes.
  • All temperatures and timings are in System Value format

SL -> Setpoint (temperature) List

This function will read the current temperature setpoint of a series of 12 consecutive thermostats. Maximum 24 thermostats (0-23) can be used.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR S L CID Ser 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Ser: Ser=0 will return the current Setpoint temperature of thermostat 0 to 11, Ser=1 for thermostat 12 to 23.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
S L CID Ser Tmp0 Tmp1 Tmp2 Tmp3 Tmp4 Tmp5 Tmp6 Tmp7 Tmp8 Tmp9 Tmp10 Tmp11 13 10
  • TmpX: Setpoint Temperature will be returned in System Value format.
  • When Ser=0 then X=0 to 11 (current setpoint temperature of thermostat 0 to 11), when Ser=1 then X=12 to 23, when Ser=2 then X=24 to 32 (the rest of the bytes will contain 255). Ser=2 can be used in Firmware 3.143.18 and higher.

SO -> Read Output Roller/Shutter in Large Installation mode

This function will read the output status of an output module that is configured as Shutter/Roller in Large Installation mode.

Please note that this instruction will not sent back the status of the Output modules that are not added in Large Installation mode. To know the status of those modules, please use instruction RO.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR S O CID Module Nr 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Module Nr: Indicates the Module Nr (0-29) of the Roller/Shutter for which the data is requested
  • This message can also be sent automatically without any request, see explanation below.
Response M->G
0 1 2 3 4 5 6 7 8 9
S O CID Module Nr 0 0 0 Output Status 13 10
  • Module Nr: Indicates the Module Nr (0-29) of the Roller/Shutter for which the data is being sent out
  • Output Status: Gives the Output status (1 bit per output) of the Roller/Shutter of Module Nr
  • The “SO” response can also be automatically sent when an output has changed state (and thus without sending the “SO” instruction first). To enable this, byte 28 on page 0 of the eeprom must be below 255 (See Memory Model). This can be easily checked by following CLI instruction: eeprom read 0 28. If the result is 255, then the automatic SO response is not enabled. To enable the automatic “SO” sent, please use following 2 CLI instructions: eeprom write 0 28 0 and eeprom activate.
  • When an automatic “SO” response is sent (and thus without sending the “SO” instruction first), the CID of that instruction will be 0.
  • The automatic responses will only be sent in API mode

st -> Set Time

Write Time and date to the OpenMotics Master

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR s t CID Sec Min Hours Day Date Month Year 0 0 0 0 0 0 13 10

G->M: Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 "s" "t" CID Sec Min Hours Day Date Month Year Null Null Null Null Null Null CR LF

  • Sec: Seconds -> 0 to 59
  • Min: Minutes -> 0 to 59
  • Hours: Hours -> 0 to 23
  • Day: Day of the week -> 1 to 7 (1=Monday, …, 7=Sunday)
  • Date: Day of the Month -> 1 to 31 (Not implemented yet)
  • Month: Month -> 1 to 12 (Not implemented yet)
  • Year: Year -> 0 to 99 (Not implemented yet)
  • CID: Communication ID
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
s t CID Sec Min Hours Day Date Month Year 0 0 0 0 0 0 13 10

Note: The time can be read by using instruction “ST” -> Status

ST -> Status

Ask Status (can also be used as heartbeat)

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR S T CID instr data 0 0 0 0 0 0 0 0 0 0 0 13 10
  • Instr: This field will contains the Status instruction:
    • 0: No instruction
    • "R": Read the synchronisation eeprom page and byte which is happening for the moment between the Master and the CAN control(s)
    • "W": Write the Page the be synchronised now. The page will be written in the field data.
  • Data: page to be synchronised (0-255)
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
S T CID Sec Min Hours Day Code Page Byte 0 mode F1 F2 F3 Hw 13 10
  • Mode: “I” (initialisation mode) or “L” (live mode)
  • F1,F2 and F3: Firmware version: F1 is major release number, F2 is minor and F3 is built number
  • H: Hardware platform identification number
    • 1: Master with 18F2620 (20Mhz) and serial buffer 18F1220
    • 2: Master with 18F67J11 (20Mhz) and serial buffer 18F1220
    • 3: Master with 18F67J11 (10Mhz - 40Mhz PLL) and integrated serial buffer
    • 4: Master with 18F67J11 (10Mhz - 40Mhz PLL) including BeagleBone integration, remote modules power switch and integrated serial buffer
  • Sec: Seconds -> 0 to 59
  • Min: Minutes -> 0 to 59
  • Hours: Hours -> 0 to 23
  • Day: Day of the week -> 1 to 7 (1=Monday, …, 7=Sunday)
  • Code:
    • If instr=0 the Code=0, Page=0 and Byte=0 (no data feedback).
    • If instr="R" or instr="W" then Code="S" and Page and Byte will contain current synchronisation data
  • Page: The current eeprom page the Master is synchronising with the CAN Control
  • Byte: The current eeprom byte the Master is synchronising with the CAN Control

ml -> Thermostat Multi-Tenant Configuration byte List

This function will read the list of all programmed Thermostat Multi-Tenant Configuration bytes. For more information, please see Thermostat Multi Tenant page.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR m l CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 ... 26 27 28 29 30 31 32 33
m l CID MTC 0 MTC 1 ... MTC 23 C CRC.Byte1 CRC.Byte0 13 10 13 10
  • MTC x: Multi-Tenant configuration byte, see Thermostat Multi Tenant
  • CRC (CRC.Byte1 and CRC.byte0) is the sum of all decimal values of all characters except for the 2 start characters “ml”, CID, “C” character at the end together with the CRC itself and the double LF/CR. The sum of the CRC is stored in a word (2 bytes) variable. Each CRC starts with character “C” followed by 2 bytes.
  • Firmware version 3.143.18 and higher have the possibility to configure the "Maximum number of Thermostats". The "Maximum number of Thermostats" can be set between 24 and 32. When more then 24 thermostats are configured (See Memory Model Page0/Byte59), the above output data will be increased so instead of 24 bytes of data, 32 bytes will be thrown if Byte0/Page59=32 for example. The standard configuration for "maximum number of thermostats" is 24.

tl -> Thermostat List

This function will read the thermostat mode, the outside temperature, the temperature of each thermostat as well as the setpoint.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR t l CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5-36 37-68 69 70 71 72 73 74 75
t l CID Therm mode out temp Tmp Th0-31 Setp Th0-31 C CRC.Byte1 CRC.Byte0 13 10 13 10
  • Therm Mode: Thermostat Mode byte
  • Out Temp: Outside temperature (represented as System Value)
  • Tmp Th0-31: Temperature of thermostat 0-31 (represented as System Value)
  • Setp Th0-31: Setpoint of thermostat 0-31 (represented as System Value)
  • Firmware version 3.143.18 and higher have the possibility to configure the "Maximum number of Thermostats". The "Maximum number of Thermostats" can be set between 24 and 32. When more then 24 thermostats are configured (See Memory Model Page0/Byte59), the above output data (Tmp and Setp) will be increased so instead of 24 bytes of data, 32 bytes will be thrown if Byte0/Page59=32 for example. The standard configuration for "maximum number of thermostats" is 24.
  • CRC (CRC.Byte1 and CRC.byte0) is the sum of all decimal values of all characters except for the 2 start characters “tl”, CID, “C” character at the end together with the CRC itself and the double LF/CR. The sum of the CRC is stored in a word (2 bytes) variable. Each CRC starts with character “C” followed by 2 bytes.
  • Temperature is updated once every 30 seconds. When the system is started up, wait a few minutes before start reading temperatures (otherwise, the system will indicate that the temperature probe is not connected -> System Value = 255).

TL -> Temperature thermostat Sensor List

This function will read the current temperature of a series of 12 consecutive thermostats. Maximum 24 (or 32 as of Firmware version 3.134.18 or higher) thermostats (0-23) can be used. This instruction will read the temperature of the sensors linked to those particular thermostats. If sensor 27 is linked to thermostat 0, then the temperature of sensor 27 will be sent for thermostat 0.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR T L CID Ser 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Ser: Ser=0 will return the current temperature of thermostat 0 to 11, Ser=1 for thermostat 12 to 23.
  • As of Firmware version 3.143.18 and higher, up to 32 thermostats can be configured. In this case, Ser=2 will be used for thermostat 24 to 32.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
T L CID Ser Tmp0 Tmp1 Tmp2 Tmp3 Tmp4 Tmp5 Tmp6 Tmp7 Tmp8 Tmp9 Tmp10 Tmp11 13 10
  • TmpX: Temperature will be returned in System Value format.
  • When Ser=0 then X=0 to 11 (current temperature of thermostat 0 to 11), when Ser=1 then X=12 to 23, Ser=2 then X=24 to 32 (the rest of the bytes data bytes will contain 255)

TM -> Read Thermostat Mode

With this instruction, the Thermostat Mode can be read.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR T M CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
T M CID Tm 0 0 0 0 0 0 0 0 0 0 0 0 13 10

VL -> Virtual Sensor List

This function is available as of Firmware Version V3.142.1 and higher and will read the list of Virtual Sensor settings to see which sensors are configured as virtual. See Virtual Sensors for more information.

To write the sensor values to a virtual sensor, please use API instruction VS.

To configure the virtual sensors (virtual or non-virtual), please write the appropriate values in the Eeprom of the master (page 195), see Memory Model.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR V L CID 0 0 0 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
Response M->G
0 1 2 3 4 5 6 7 ... 33 34 35 36 37 38 39 40 41
V L CID VSC-0 VSC-1 VSC-2 VSC-3 VSC-4 ... VSC-30 VSC-31 C CRC.Byte1 CRC.Byte0 13 10 13 10
  • VSC-X: Virtual sensor configuration for sensor x, result is 0 (virtual sensor disabled) or 1 (virtual sensor enabled).

VS -> Write Virtual Sensor

This function is available as of Firmware Version V3.142.1 and write the values (temperature, humidity and brightness) of 1 sensor. See Virtual Sensors for more information. Please note that you can write to all sensors (virtual and non-virtual), however, when a sensor is configured as non-virtual, the values won't be accepted and the return values will be the values of the non-virtual sensor. With the API instruction VL, you can check which sensors are virtual and which are non virtual.

To configure the virtual sensors (virtual or non-virtual), please write the appropriate values in the Eeprom of the master (page 195), see Memory Model.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR V S CID Sensor Nr V-Temperature V-Humidity V-Brightness 0 0 0 0 0 0 0 0 0 13 10
  • Sensor Nr: Sensor number (0-31) for which virtual data has to be written.
  • V-temperature: Virtual Temperature to be written. This temperature is written in System Value format.
  • V-Humidity: Virtual Humidity to be written. This humidity is written in System Value format.
  • V-Brightness: Virtual Brightness to be written. This Brightness is written in System Value format.
  • CID: Communication ID (filled in by Gateway, copied in the response of the Master)


Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
V S CID Sensor Nr Temperature Humidity Brightness 0 0 0 0 0 0 0 0 0 13 10
  • Sensor Nr: Return sensor Nr (0-31)
  • Temperature: Temperature (in System Value) of Sensor Nr (Virtual or Non-virtual)
  • Humidity: Humidity (in System Value) of Sensor Nr (Virtual or Non-virtual)
  • Brightness: Brightness (in System Value) of Sensor Nr (Virtual or Non-virtual)

Note 1: The return value is the value currently present in the system for that sensor. When you try to write a value to a non-virtual sensor, the return value will be the value of the non-virtual sensor.

Note 2: When you configured a virtual sensor but you only have a temperature value for example, the unused values for humidity and brightness must be 255 (sensor not present).

WE -> Write Eeprom

The Master is equipped with external Eeprom memory. Instruction “W” will write data into this Eeprom.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR W E CID Bank Addr Nmbr Data0 Data1 Data2 Data3 Data4 Data5 Data6 Data7 Data8 Data9 13 10
  • Bank: The used eeprom has 256 (0 to 255) banks. Each bank contains 256 (0-255) Bytes.
  • Addr: Start address in page (0 to 255)
  • Nmbr: Number of bytes to write (1 to 10) in the same bank.
  • Data1..9: data (bytes) that will be written in eeprom. In the case of more than 1 byte (#>1) , additional bytes will be written in the same Bank.
    • When the end of a bank is reached, the Master continues to write in the beginning of the same bank. For example: write 9 bytes in bank 15 and start at address 250. The Master will start writing at address 250, then go to address 251, 252, 253, 254, 255 and the continues at address 0 of bank 15.
  • CID: Communication ID (filled in by Gateway, copied in the response of the Master)


Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
R E CID Bank Addr Nmbr Data0 Data1 Data2 Data3 Data4 Data5 Data6 Data7 Data8 Data9 13 10
  • The response is the data that’s being read from the Eeprom

ws -> Write Thermostat data (like setpoint and other thermostat related parameters)

The Master has 24 (or 32 as of firmware version 3.143.18 and higher) built-in PID controllers to manage the temperature of a room. This instruction allows the gateway to program the different thermostat parameters.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR w s CID Nmbr Config Data 0 0 0 0 0 0 0 0 0 0 13 10
  • CID: Byte 2 will always contain the Communication ID. When the Gateway sends a request to the Master, the Gateway will add the communication ID (communication sequence) in byte2. The Master will always answer the request of the Gateway with the same communication ID. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Nmbr: Thermostat number (0-23)
  • Config: This config parameter will tell the Master which parameter to write
    • Config=0->current setpoint
    • Config=1->programmed setpoint 0
    • Config=2->programmed setpoint 1
    • Config=3->programmed setpoint 2
    • Config=4->programmed setpoint 3
    • Config=5->programmed setpoint 4
    • Config=6->programmed setpoint 5
    • Config=7-> P parameter (PiD)
    • Config=8-> I parameter (PID)
    • Config=9-> Int threshold (PID)
    • Config=10-> D parameter (PID)
    • Config=11-> Temperature threshold (if outside temp < temp threshold -> activate thermostat)
    • Config=12-> Set Day (Time)
    • Config=13-> Set Hours (Time)
    • Config=14-> Set Minutes (Time)
    • Config=15-> Set Room Sensor Nr
    • Config=16-> Set thermostat Output 1
    • Config=17-> Set Thermostat Output 2
    • Config=18-45 -> programmed Hours for every day of the week
    • Config=46-52 -> Programmed Temperature Day1 (Mon-Sun)
    • Config=53-59 -> Programmed Temperature Day2 (Mon-Sun)
    • Config=60-66 -> Programmed Temperature Night (Mon-Sun)
    • Config=67 -> Multi-tenant Configuration byte: value to be written, see Thermostat Multi Tenant
    • Config=68 -> Set Thermostat Number to AUTO, only when Thermostat Multi Tenant has been enabled
    • Config=69 -> Set Thermostat Number to AWAY, only when Thermostat Multi Tenant has been enabled
    • Config=70 -> Set Thermostat Number to VACATION, only when Thermostat Multi Tenant has been enabled
    • Config=71 -> Set Thermostat Number to PARTY, only when Thermostat Multi Tenant has been enabled
  • temperature and time values must all be written in System Value format.
Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
w s CID Nmbr Config Data 0 0 0 0 0 0 0 0 0 0 13 10
  • All temperatures and timings are in System Value format
  • The feedback received from the Master contains the data after the “ws” function is executed and thus with the new data.
  • As of Version 3.143.18 and higher, 32 thermostat are supported (instead of 24)

WT -> Write Timer

This instruction will write the timer value of 1 output and store it in Eeprom.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
STR W T CID Output Timer.Byte1 Timer.Byte0 0 0 0 0 0 0 0 0 0 0 13 10
  • Output: Output Nr (0-239)
  • Timer.Byte1: MSB of the timer
  • Timer.Byte0: LSB of the timer
  • CID: Communication ID (filled in by Gateway, copied in the response of the Master)


Response M->G
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
R T CID Output Timer.Byte1 Timer.Byte0 0 0 0 0 0 0 0 0 0 0 13 10
  • The response is the new timer value that's being used for that output.