API Reference Guide AIO

From OpenMotics
Jump to navigation Jump to search

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)

The DSPIC33E has 4 UART ports. 1 port is configured as CLI port, 1 port is configured as API port (for communication with BB), 1 for RS485 and 1 is optional for future use.

Versioning

This document describes the API instruction set applicable for the AIO design only.

Gateway Module FW version
1.0.x

Notation

Every API instruction must start with string characters STR always followed by 5 fixed bytes and a variable data payload 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
"STR" CID "B" "A" 0 6 Type Action Device_nr.msb Device_nr.lsb extra_parameter.msb extra_parameter.lsb "C" CSUM 13 10 13 10
  • Communication from Gateway to Master (DSPIC33E) always start with string "STR" and always ends with CR/LF/CR/LF (13/10/13/10), the payload is variable in length. Responses from Master to Gateway always start with string "RTR".
  • CID: Byte 0 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 byte0. 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 byte0 will be filled with a “null”. CID is set between 1 and 255. When CID is set to 0, it is not used.
  • Byte1 & 2 always contains the instruction to be executed, in this example "BA" or Basic Action.
  • Byte3 & 4 always contains the length of the payload (Byte3 the MSB, Byte4 the LSB). In this example, the length of the payload is 6 bytes.
  • After the payload, always "C" appears followed by the Check Sum.
  • M->G: Communication from Master Controller to Gateway Controller
  • G->M: Communication from Gateway Controller to Master Controller
  • CSUM: This is the Checksum of all bytes until character "C" is reached. The Checksum will never include the starting characters "STR" and "TRD" as well as the Character "C". In the above example, the checksum is equal to the sum of Bytes 0 to 10 and the result is an UINT8.

Instruction Set

BA -> Basic Action

Basic Action (BA) can be used to perform a multitude of actions like switching on/off outputs, set dimmer levels, execute group actions, program settings in Eeprom etc. This API call will allow to execute 1 BA. The details of each BA can be found in the Action Types AIO list.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
"STR" CID "B" "A" 0 6 Type Action Device_nr.msb Device_nr.lsb extra_parameter.msb extra_parameter.lsb "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"BA": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..10 -> Data payload: In these bytes, you'll find the data payload
  • Byte11 -> "C": Indicate that following byte is the CRC
  • Byte12 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
"RTR" CID "B" "A" 0 6 Type Action Device_nr.msb Device_nr.lsb extra_parameter.msb extra_parameter.lsb "C" CSUM 13 10
  • Byte5..10 -> Data payload: In the data payload, you'll find the 6 bytes of the BA that have been put in the queue to be executed
  • Byte11 -> "C": Indicate that following byte is the CRC
  • Byte12 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4

Note: When the Master responses with the above message means that the action is well received and is placed in the queue for immediate execution. Please note that other messages (M->G) can be triggered and sent as a result of an executed BA.

CD -> CAN Details

This instruction will request the detailed information of every Micro CAN slave connected.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "C" "D" 0 1 0 "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"CD": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • CID: Communication ID. 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, the Master did send information to the Gateway without being requested.
Response M->G
' 0 1 2 3 4 5 6 7 8 9-42 43 44 45 46 47
"RTR" CID "C" "D" 0 39 B0 B1 B2 B3 B4..B23 B38 "C" CSUM 13 10

This response will be sent by the Master to the BB when detailed information is received from every micro CAN (so the below response will be sent for every Micro CAN connected).

CID=0

Byte 0-38 (B0-B38) contains the payload of this message:

  • B0: ID2 of the micro CAN module
  • B1: ID1 of the micro CAN module
  • B2: ID0 of the micro CAN module
  • B3: MSB of the input link (which system input is linked to this physical input) of input0 of this uCAN module
  • B4: LSB of the input link (which system input is linked to this physical input) of input0 of this uCAN module
  • B5: MSB of the input link (which system input is linked to this physical input) of input1 of this uCAN module
  • B6: LSB of the input link (which system input is linked to this physical input) of input1 of this uCAN module
  • B7: MSB of the input link (which system input is linked to this physical input) of input2 of this uCAN module
  • B8: LSB of the input link (which system input is linked to this physical input) of input2 of this uCAN module
  • B9: MSB of the input link (which system input is linked to this physical input) of input3 of this uCAN module
  • B10: LSB of the input link (which system input is linked to this physical input) of input3 of this uCAN module
  • B11: MSB of the input link (which system input is linked to this physical input) of input4 of this uCAN module
  • B12: LSB of the input link (which system input is linked to this physical input) of input4 of this uCAN module
  • B13: MSB of the input link (which system input is linked to this physical input) of input5 of this uCAN module
  • B14: LSB of the input link (which system input is linked to this physical input) of input5 of this uCAN module
  • B15: Sensor link (which system sensor is linked to this physical sensor) of input0 of this uCAN module
  • B16: Sensor link (which system sensor is linked to this physical sensor) of input1 of this uCAN module
  • B17: Sensor Type:
    • 0: Sensor of the DS1820 family is connected on the first output
    • 1: Sensor of the DS1820 family is connected on the second output
    • 2: 2 sensors of the DS1820 family are connected (on both outputs)
    • 3: Honeywell Temp/humidity Sensor is connected
    • 4: TSL2561 LUX sensor is connected
    • 5: Honeywell Temp/humidity Sensor & TSL2561 LUX sensor are connected
    • 255: No sensors are currently connected
  • B18: Firmware Version (F1)
  • B19: Firmware Version (F2)
  • B20: Firmware Version (F3)
  • B21: Bootloader Byte: When tis byte=? then the micro CAN will remain in bootloader for 10 seconds after a reset, otherwise it will jump directly to the normal program
  • B22: ID_NE: This byte contains the information if the module is still new (byte="N") or the module is already added in the Master (byte="E")
  • B23: Minimum led brightness for this micro CAN module
  • B24: Maximum led brightness for this micro CAN module
  • B25: AD value MSB input 2
  • B26: AD value LSB input 2
  • B27: AD value MSB input 3
  • B28: AD value LSB input 3
  • B29: AD value MSB input 4
  • B30: AD value LSB input 4
  • B31: AD value MSB input 5
  • B32: AD value LSB input 5
  • B33: Modbus Address
  • B34: Modbus Type, see Modbus Parameters
  • B35: Modbus Model, see Modbus Parameters
  • B36: Modbus Speed, see Modbus Parameters
  • B37: Modbus Status, see Modbus Parameters
  • Byte44 -> "C": Indicate that following byte is the CRC
  • Byte45 -> CSUM: The Check Sum is calculated by taking the sum of Byte0..Byte43


Note1: The master will request life information of every Micro CAN connected thus the above response will be received once for every Micro CAN connected.

Note2: When Firmware version 255.255.255 is received means that the module didn't respond and thus all other data received can be ignored

CS -> CAN ID Search

This instruction will search the CAN ID of a given input or sensor nr. Every Micro CAN can have several inputs and sensors linked to 1 Micro CAN (and his ID) and this instruction will return the 3 ID bytes for an input nr or sensor nr. These ID's are needed to execute certain BA's.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13
"STR" CID "C" "S" 0 3 is_nr.MSB is_nr.LSB Type "C" CSUM 13 10 13 10
  • Type: If Type=1 -> is_nr represents the input_nr, if Type=2 -> is_nr represents the sensor_nr
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"CS": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..7 -> Data payload: In these bytes, you'll find the data payload
  • Byte8 -> "C": Indicate that following byte is the CRC
  • Byte9 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..7
  • CID: Communication ID. 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, the Master did send information to the Gateway without being requested.
Response M->G (instruction=1)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
"RTR" CID "C" "S" 0 6 is_nr.MSB is_nr.LSB Type CAN_ID2 CAN_ID1 CAN_ID0 "C" CSUM 13 10
  • CAN_ID2..0: These are the CAN ID's of the Micro CAN. If the CAN ID's return 255 means that the search didn't return any match.

DL -> Device information List

This instruction will request the status list of all inputs or outputs that are configured.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "D" "L" 0 1 Type "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"DL": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Type: If Type=0 then send the Output status list, if Type=1 then send the Input list
  • CID: Communication ID. 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, the Master did send information to the Gateway without being requested.
Response M->G
' 0 1 2 3 4 5 5+x ... 5+y 6+y 7+y 8+y 9+y
"RTR" CID "D" "L" 0 1+NrOfModules Type Data_1 ... Data_y "C" CSUM 13 10
  • Byte5..5+y -> Data payload: In the data payload, you'll find the necessary bytes of the DL response instruction.
  • Byte6+y -> "C": Indicate that following byte is the CRC
  • Byte7+y -> CSUM: The Check Sum is calculated by taking the sum of the data payload + byte0..4
  • data_1..y: These are the data bytes containing the requested information:
    • When Type=0 then the response will contain the status of the output modules. NrOfModules are the Number of Output Modules that are configured in the system, if this is 5, 5 bytes of Output status will be send, each byte containing the status of 8 outputs (1=Output ON, 0=Output OFF, Most significant bit=8th output, Least significant bit=1st output). When the NrOfModules>0 then x=1 and y=NrOfModules+1. Data_1 contains the status of the first 8 outputs, data_y contains the status of the last 8 outputs.
    • When Type=1 then the response will contain the status of the input modules. NrOfModules are the Number of Inputs Modules that are configured in the system, if this is 5, 5 bytes of Input status will be send, each byte containing the status of 8 inputs (1=Input ON, 0=Input OFF, Most significant bit=8th input, Least significant bit=1st input). When the NrOfModules>0 then x=1 and y=NrOfModules+1. Data_1 contains the status of the first 8 inputs, data_y contains the status of the last 8 inputs.

ER -> Error information

This message will be send when an error occurred for example wrong parameters have been sent or parameters out of limits.

Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
"RTR" CID "E" "R" 0 6 Type ParameterA ParameterB.msb ParameterB.lsb ParameterC.msb ParameterC.lsb "C" CSUM 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"ER": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..10 -> Data payload: In these bytes, you'll find the data payload
  • Byte11 -> "C": Indicate that following byte is the CRC
  • Byte12 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Type: This is the type of Error, see Error List AIO
  • ParameterA..C is the error data, see Error List AIO
  • Note: The CID will always be 0 for error messages sent to the BB

ES -> Execute Series of Basic Actions

This API call will allow to execute a series of Basic Actions. A Basic Action consist of following elements:

  • Type (byte): Type of action, for example all output actions have Type 0
  • Action (byte): This is the action itself, for example switch Output On or OFF
  • Device Nr (word): This is the parameter that indicates on which asset (for example output nr) the action must be executed
  • Extra parameter (word): This is an extra parameter that is used on some Basic Actions to set for example the timer of dimmer value

The API call "ES" will allow the same instruction (Type, Action & extra parameter) to be executed on a series (minimum 2, maximum 40) of device numbers.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 ... 7+(2*x) 8+(2*x) 9+(2*x) 10+(2*x) 11+(2*x) 12+(2*x) 13+(2*x) 14+(2*x)
"STR" CID "E" "S" 0 4+(2*x) Type Action extra_parameter.msb extra_parameter.lsb Device_nr_1.msb Device_nr_1.lsb ... Device_nr_x.msb Device_nr_x.lsb "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"ES": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..8+(2*x) -> Data payload: In these bytes, you'll find the data payload
  • Byte9+(2*x) -> "C": Indicate that following byte is the CRC
  • Byte10+(2*x) -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • x -> number of devices (minimum 2, maximum 40)
Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12
"RTR" CID "E" "S" 0 4 Type Action extra_parameter.msb extra_parameter.lsb "C" CSUM 13 10
  • Byte5..8 -> Data payload: In the data payload, you'll find the 6 bytes of the BA that have been put in the queue to be executed
  • Byte9 -> "C": Indicate that following byte is the CRC
  • Byte10 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4

Note: When the Master responses with the above message means that the actions are well received and are placed in the queue for immediate execution.

EV -> Event information

This message will be send when an event occurred for example an output has been changed or a temperature sensor has a new value.

Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 '14 15 16'
"RTR" CID "E" "V" 0 8 Type Action DeviceNr.MSB DeviceNr.LSB Data0 Data1 Data2 Data3 "C" CSUM 13 10
  • Byte0 -> CID: Communication ID, always 0 since Master initiates message without Gateway sending any request
  • Byte1&2 ->"EV": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..12 -> Data payload: In these bytes, you'll find the data payload
  • Byte13 -> "C": Indicate that following byte is the CRC
  • Byte14 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Type/Action are the type of Action, see AIO API Event Codes
  • Data0..3 is the event data, see AIO API Event Codes

FS -> Information uCAN

This instruction will request information from the AIO or CAN control like the number of Micro CAN's are connected directly or 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
"STR" CID "F" "S" 0 6 ID3 ID2 ID1 ID0 Instr can_nr "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"FS": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..10 -> Data payload: In the data payload, you'll find the 6 bytes needed for a BA
  • Byte11 -> "C": Indicate that following byte is the CRC
  • Byte12 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • ID0..3 =ID of the CAN Control Module. If ID0..3=0 then the Mico CAN's directly connected to the AIO will be addressed.
  • 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.
  • CID: Byte 0 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 byte0. 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
"RTR" CID "F" "S" 0 9 ID3 ID2 ID1 ID0 Instr can_nr data0 data1 data2 "C" CSUM 13 10
  • Byte5..13 -> Data payload: In the data payload, you'll find the 9 bytes of the FS response instruction.
  • Byte14 -> "C": Indicate that following byte is the CRC
  • Byte15 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • 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 and data1/data2 can be ignored.
    • Instr=1: data0 contains ID2 of the requested Micro CAN, data1 contains ID1, data2 contains ID0

FM -> Put Message on the CAN bus

This instruction will forward messages on the CAN bus of the AIO (when ID0..3=0) or on the CAN bus of a CAN Control (when ID0..3!=0).

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

  • 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 UART API without any interpretation of the DSPIC. Messages with SID 0 are used to transfer pallets.
  • SID=1: 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 UART API without any interpretation of the DSPIC. Messages with SID 1 are used to communicate with the bootloader.
  • SID=5: This SID is used to prepare the Micro CAN for bootloading. All messages with SID=5 will be sent to the Micro CAN and their response will be tunnelled over the DSPIC (=Master controller in AIO) directly to the UART API (see API Reference Guide AIO). In other words, when using SID=5 in communication towards a Micro CAN (using API instruction FM), the response of the Micro CAN will be sent directly to the UART API (FM) of the AIO without any interpretation nor any actions of the DSPIC.
  • SID=6: All normal communication uses this SID so all messages generated by the AIO will be using this SID. These messages will be interpreted by the DSPIC and will not be tunnelled to the UART API.

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 18 19 20 21 22 23 24
"STR" CID "F" "M" 0 14 ID3 ID2 ID1 ID0 nr_can_bytes SID C_Byte0 C_Byte1 C_Byte2 C_Byte3 C_Byte4 C_Byte5 C_Byte6 C_Byte7 "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"FM": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..18 -> Data payload
  • Byte19 -> "C": Indicate that following byte is the CSUM
  • Byte20 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • ID0..3 =ID of the CAN Control Module.
    • If ID0..3=0 then the Mico CAN's directly connected to the AIO will be addressed.
  • 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.
  • CID: Byte 0 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 byte0. 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.
  • 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
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
"RTR" CID "F" "M" 0 14 ID3 ID2 ID1 ID0 nr_can_bytes SID C_Byte0 C_Byte1 C_Byte2 C_Byte3 C_Byte4 C_Byte5 C_Byte6 C_Byte7 "C" CSUM 13 10
  • Byte5..18 -> Data payload
  • Byte19 -> "C": Indicate that following byte is the CSUM
  • Byte20 -> CSUM: The Check Sum is calculated by taking the sum of Byte0..Byte18
  • You can receive 2 kind of answers:
    • Every FM instruction will always be answered by the master indicating that the instruction is well executed, the master will respond with FM including the original message. The answered CID will be equal to the received CID so please do not use CID 0 and CID 1.
    • An FM instruction (from Master to BB) can also be triggered by a message that the uCAN send's to the Master and the Master sends this over to the BB. For these kind of messages, the SID will always be 1.
  • The answer on a CAN message can contain multiple "FM" responses

FW -> Firmware Version Slave Modules

This message will be send (multiple times when multiple external modules are available) after instruction "ST" has been sent to request the Slave Firmware Version.

Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
"RTR" CID "F" "W" 0 7 ID3 ID2 ID1 ID0 Major Minor Built "C" CSUM 13 10
  • Byte0 -> CID: Communication ID, always 0 since Master initiates message without Gateway sending any request
  • Byte1&2 ->"FW": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..11 -> Data payload: In these bytes, you'll find the data payload
  • Byte12 -> "C": Indicate that following byte is the CRC
  • Byte13 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • CID=0
  • ID3..ID0: ID of the slave module
  • Major, Minor & Built: Firmware version
  • When Major=0 & Minor=0 & Built=0 -> Module didn't respond on Firmware version request

GC -> General Configuration

This instruction will provide general information of this All In One Module.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "G" "C" 0 1 Info_type "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"GC": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Info_type: Represents the requested information
    • Info_type=0 -> Number of configured modules
    • Info_type=1 -> Max of configured modules allowed
Response M->G (Info_type=0)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
"RTR" CID "G" "C" 0 7 Info_type Nr_Output_M Nr_Input_M Nr_Sensor_M Nr_Can_M Nr_Can_Inputs Nr_Can_Sensors Power_RS485 Power_CAN "C" CSUM 13 10
  • Info_type=0
  • Byte5..13 -> Data payload
  • Byte14 -> "C": Indicate that following byte is the CRC
  • Byte15 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Nr_Output_M: This value represents the number of Output modules that are configured in the system.
  • Nr_Input_M: This value represents the number of Input modules that are configured in the system.
  • Nr_Sensor_M: This value represents the number of Sensor modules that are configured in the system.
  • Nr_Can_M: This value represents the number of Can modules (=Nr of Micro CAN's) that are configured in the system.
  • Nr_Can_Inputs: This value represents the number of Can inputs that are configured in the system.
  • Nr_Can_Sensors: This value represents the number of Can sensors that are configured in the system.
  • Power_RS485: When =1 then the Power of the RS485 Bus is ON, When =0 then the Power of the RS485 Bus is OFF.
  • Power_CAN: When =1 then the Power of the CAN Bus is ON, When =0 then the Power of the CAN Bus is OFF.
  • Note: The above numbers are data stored in memory, after a BA that execute an "eeprom activate" instruction, the above represented data can change
Response M->G (Info_type=1)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
"RTR" CID "G" "C" 0 9 Info_type Max_Output_M Max_Input_M Max_Sensor_M Max_Can_M Max_groups.msb Max_groups.lsb Max_bas.msb Max_bas.lsb Max_shutters Max_shutter_groups "C" CSUM 13 10
  • Info_type=1
  • Byte5..13 -> Data payload
  • Byte14 -> "C": Indicate that following byte is the CRC
  • Byte15 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Max_Output_M: This value represents the maximum possible output modules the system will accept
  • Max_Input_M: This value represents the maximum possible input modules the system will accept
  • Max_Can_M: This value represents the maximum possible Micro Can modules the system will accept on his direct CAN bus (excluding the Micro CAN connected via CAN Control)
  • Max_Sensor_M: This value represents the maximum possible sensor modules the system will accept
  • Max_groups: This value represents the maximum number of groups that can be created
  • Max_bas: This value represents the maximum number of Basic Actions that can be used in the different groups
  • Max_shutters: This value represents the maximum number of shutters that can be used
  • Max_shutter_groups: This value represents the maximum number of shutter groups that can be used
  • .msb: Most Significant Byte
  • .lsb: Least Significant Byte

IC -> Input Configuration

This instruction will provide all the details of 1 individual input module (8 inputs).

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "I" "C" 0 1 Module_nr "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"IC": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Module_nr: Represents the Input Module Number
Response M->G
' 0 1 2 3 4 5 6 7 8 9 ... 22 23 23 ... 31 32 33 34 35 36
"RTR" CID "I" "C" 0 28 Module_nr Input_status Input_invert Input_link1.msb Input_link1.lsb ... Input_link8.msb Input_link8.lsb Dali_link1 ... Dali_link8 Input_lock "C" CSUM 13 10
  • Byte5..32 -> Data payload
  • Byte33 -> "C": Indicate that following byte is the CRC
  • Byte34 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Module_nr: This is the Number of the Input Module
  • Input_status: This byte represents the status (1=Pressed, 0=released) of the 8 inputs of the module. BIT0=first input of this module, BIT7=last input of this module.
  • Input_invert: A typical switch is NO (Normally Open in other words, contact when pressed). An input can also be configured as NC (Normally Closed). The Invert_status byte represents the switch configuration of the 8 inputs. BIT0=first input of this module, BIT7=last input of this module. When BIT=0 -> Normally Open, BIT=1 -> Normally closed.
  • Input_linkx: In this word, you'll find the Output_nr that needs to be triggered when the input is activated. x=1 to 8 for the 8 inputs of this module. If input_linkx=65535 -> Nothing configured, if input_linkx>1023 & input_linkx<65535 -> Basic Action are configured, if input_linkx<640 (Max outputs) -> Output is linked to input.
  • Dali_linkx: These bytes represents the Dali link if used. Dali inputs can be used and which Dali ID is linked to which input can be found in theses bytes (values above 128 in Dali_linkx means that no Dali input is linked).
  • Input_lock: Represents the 8 bits for the 8 Inputs, BIT7 (MSB) -> Input 7 of this module, ..., BIT0 (LSB) -> Input 0 of this module. BITx=0 -> Input is unlocked, BITx=1 -> Input is locked.
  • .msb: Most Significant Byte
  • .lsb: Least Significant Byte

MC -> Module Configuration

This instruction will provide all the general information of a set of modules (All input modules or all output modules or all sensor modules).

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12
"STR" CID "M" "C" 0 2 Module_nr Type "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"MC": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..5 -> Data payload: In these bytes, you'll find the data payload
  • Byte7 -> "C": Indicate that following byte is the CRC
  • Byte8 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Module_nr: Represents the Module Number of the specific requested Module_type
  • Type: Represents the Module Type
    • Type=0 -> All type of output modules (Output/Dimmer/Roller-Shutter/virtual etc)
    • Type=1 -> All type of input modules (Input/button/virtual etc)
    • Type=2 -> All type of sensor modules (Sensor/virtual etc)
Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
"RTR" CID "M" "C" 0 10 Module_nr Type Module_Type ID0 ID1 ID2 ID3 Errors.msb Errors.lsb Module_status "C" CSUM 13 10
  • Byte5..13 -> Data payload
  • Byte14 -> "C": Indicate that following byte is the CRC
  • Byte15 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Module_Type: This will indicate which kind of module is used
    • Module_Type="I" -> This is an internal module (Onboard Inputs and Outputs for example)
    • Module_Type="E" -> This is an external RS485 module
    • Module_Type="C" -> This is a module generated for inputs or sensors directly connected on the AIO CAN bus
    • Module_Type="c" -> This is a module generated for inputs or sensors connected on the CAN Control
    • Module_Type="V" -> This is a Virtual module created
  • ID0..ID3: These are the 4 module ID's of each module.
  • Errors: These are the number of bus errors this module had since the last reset or error clear instruction.
  • Module_status: This represents the status of the requested module
    • BIT0..3: Module status
      • 0: OK
      • 1: Degraded1
      • 2: Degraded2
      • 3: Degraded3
      • 4: Offline
      • 5: Forced Offline
    • BIT4: Scan Module status
      • 0: Don't scan
      • 1: Scan
    • BIT5:Write FRAM
      • 1: Write
      • 0: Do Nothing
    • BIT6: Module responded
      • 1: Responded
      • 0: Didn't respond
    • BIT7: Report Error
      • 1: Report Error
      • 0: Do Nothing
  • .msb: Most Significant Byte
  • .lsb: Least Significant Byte

MR -> Memory Read

This instruction will read bytes from Eeprom or Fram.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
"STR" CID "M" "R" 0 5 Type Page.MSB Page.LSB StartByte NrOfBytes "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"MR": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of data payload
  • Byte5..9 -> Data payload: In these bytes, you'll find the data payload
  • Byte10 -> "C": Indicate that following byte is the CRC
  • Byte11 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • CID: Communication ID. 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, the Master did send information to the Gateway without being requested.
  • Page: The eeprom consist of 512 pages (0-511), the FRAM of 128 pages (0-127). This value indicates which page to start reading
  • StartByte: Each Page has 256 Bytes (0-255). This value indicates which byte (in Page) to start reading.
  • NrOfBytes: This value indicates how many bytes to read (Min 1, Max 32)
  • Type: This indicates the Memory type ("F"-> FRAM, "E"->EEPROM)
Response M->G
' 0 1 2 3 4 5 6 7 8 9 ... 8+y 9+y 10+y 11+y 12+y
"RTR" CID "M" "R" 0 4+NrOfBytes Type Page.MSB Page.LSB StartByte Data_1 ... Data_y "C" CSUM 13 10
  • Byte5..8+y -> Data payload: In the data payload, you'll find the necessary bytes of the MR response instruction.
  • Byte9+y -> "C": Indicate that following byte is the CRC
  • Byte10+y -> CSUM: The Check Sum is calculated by taking the sum of the data payload + byte0..4
  • data_1..y: These are the data bytes containing the requested eeprom information
  • y=NrOfBytes

mR -> modbus Read

This instruction will return the setpoint and sensor values of a given sensor_nr.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "m" "R" 0 1 sensor_nr "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"CR": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..5
  • CID: Communication ID. 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, the Master did send information to the Gateway without being requested.
Response M->G (instruction=1)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
"RTR" CID "m" "R" 0 7 sensor_nr Setpoint Mode Temperature Humidity CO2.MSB CO2.LSB "C" CSUM 13 10

MW -> Memory Write

This instruction will write bytes to Eeprom or Fram.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 ... 8+y 9+y 10+y 11+y 12+y 13+y 14+y
"STR" CID "M" "W" 0 4+NrOfBytes Type Page.MSB Page.LSB StartByte Data_1 ... Data_y "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"MW": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..8+y -> Data payload: In these bytes, you'll find the data payload
  • Byte9+y -> "C": Indicate that following byte is the CRC
  • Byte10+y -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • CID: Communication ID. 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, the Master did send information to the Gateway without being requested.
  • Page: The eeprom consist of 512 pages (0-511), the Fram of 128 pages (0-127). This value indicates which page to start writing
  • StartByte: Each Page has 256 Bytes (0-255). This value indicates which byte (in Page) to start writing.
  • NrOfBytes: This value indicates how many bytes to write (Min 1, Max 32)
  • y=NrOfBytes
  • Type: This indicates the Memory type ("F"-> FRAM, "E"->EEPROM)
Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
"RTR" CID "M" "W" 0 6 Type Page.MSB Page.LSB StartByte NrOfBytes Result "C" CSUM 13 10
  • Byte5..10 -> Data payload: In the data payload, you'll find the necessary bytes of the MW response instruction.
  • Byte11 -> "C": Indicate that following byte is the CRC
  • Byte12 -> CSUM: The Check Sum is calculated by taking the sum of the data payload + byte0..4
  • Result: "O"->OK, "E"->Error

OC -> Output Configuration

This instruction will provide the details of 1 individual output module (8 outputs).

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "O" "C" 0 1 Module_nr "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"OC": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Module_nr: Represents the Output Module Number
Response M->G
' 0 1 2 3 4 5 6 7 8 9 10 11 ... 36 37 38 39 40 41 42 43
"RTR" CID "O" "C" 0 35 Module_nr Output_status Output_lock Output_timer_1.msb Output_timer_1.lsb Output_timer_type_1 Output_dimmer_1 ... Output_timer_8.msb Output_timer_8.lsb Output_timer_type_8 Output_dimmer_8 "C" CSUM 13 10
  • Byte5..32 -> Data payload
  • Byte33 -> "C": Indicate that following byte is the CRC
  • Byte34 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Module_nr: This is the Number of the Input Module
  • Output_status: This byte represents the status (1=ON, 0=OFF) of the 8 outputs of this module. BIT0=first input of this module, BIT7=last input of this module.
  • Output_lock: Represents the 8 bits for the 8 Outputss, BIT7 (MSB) -> Output 7 of this module, ..., BIT0 (LSB) -> Output 0 of this module. BITx=0 -> Output is unlocked, BITx=1 -> Output is locked.
  • Output_timer_x.lsb and .msb: Current timer value of output x
  • Output_timer_type_x: Indicates the timer type (=0->No timer, =1->100ms timer, =2->1s timer, =3->1min timer) of output x
  • Output_dimmer_x: Dimmer value of Output x
  • .msb: Most Significant Byte
  • .lsb: Least Significant Byte

OD -> Output Detail

This instruction will provide all the details of 1 individual output like Dimmer, timer values, configuration values etc

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12
"STR" CID "O" "D" 0 2 Device_nr.msb Device_nr.lsb "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"OD": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..6 -> Data payload: In these bytes, you'll find the data payload
  • Byte7 -> "C": Indicate that following byte is the CRC
  • Byte8 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Device_nr: Represents the Output Number
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
"RTR" CID "O" "D" 0 16 Device_nr.msb Device_nr.lsb Output_status Dimmer Dimmer_Min Dimmer_Max Timer_Type Timer_Type_std Timer.msb Timer.lsb Timer_std.msb Timer_std.lsb Group_follow.msb Group_follow.lsb Dali_link Output_lock "C" CSUM 13 10
  • Byte5..20 -> Data payload
  • Byte21 -> "C": Indicate that following byte is the CRC
  • Byte22 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Device_nr: This is the Output Nr
  • Output_status: if 1 -> Output ON, if 0 -> Output OFF
  • Dimmer: Current dimmer value
  • Dimmer_Min: Lowest level the dimmer value can go for this output
  • Dimmer_Max: Highest level the dimmer value can go for this output
  • Timer_Type: This is the Timer_Type that is in use for this output now. In normal circumstance, the Timer_Type_std is used but Basic Action can trigger timers that overrule the std timer setting. The different Timer Types are the following:
    • 0 -> no timer
    • 1 -> 100ms timer
    • 2 -> 1s timer
    • 3 -> 1m timer
  • Timer_Type_std: This is the Timer_Type that will be used in normal circumstance and when not overruled by a Basic Action. The different Timer Types are the following:
    • 0 -> no timer
    • 1 -> 100ms timer
    • 2 -> 1s timer
    • 3 -> 1m timer
  • Timer: This is the current timer setting. If an output is on with an active timer, this value will decrease over time until timer=0 and the output will go off.
  • Timer_std: This is the Standard timer value that will be copied in Timer when the output goes off. The value used in Timer can be overruled by using Basic Actions.
  • Group_follow: This is the Group Nr (0-254) that will be triggered when an output is activated to change state.
  • Dali_link: An output can be coupled with a Dali Output. In this byte, you'll find the Dali ID (only valid when below 80, otherwise no Dali device is linked to this output)
  • Output_lock: =0 -> Output is unlocked, =1 -> Output is locked
  • .msb: Most Significant Byte
  • .lsb: Least Significant Byte

PC -> Pulse Counter Information

This instruction will provide the Pulse Counter Information of 1 input or the full 8 inputs of a module.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13
"STR" CID "P" "C" 0 3 Input_nr.msb Input_nr.lsb Type "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"PC": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..7 -> Data payload: In these bytes, you'll find the data payload
  • Byte8 -> "C": Indicate that following byte is the CRC
  • Byte9 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Input_nr: Represents the Input Number of an Input module
  • Type:
    • If Type=0 -> Request the Pulse Counter information of Input_nr
    • If Type=1 -> Request the 8 pulse counters of the module that is part of Input_nr
Response M->G (Type=0)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
"RTR" CID "P" "C" 0 9 Input_nr.msb Input_nr.lsb Type pc.byte3 pc.byte2 pc.byte1 pc.byte0 CRC16.msb CRC16.lsb "C" CSUM 13 10
  • Byte5..13 -> Data payload: In the data payload, you'll find the 9 bytes of the SI response instruction.
  • Byte14 -> "C": Indicate that following byte is the CRC
  • Byte15 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • pc: Pulse Counter information of input_nr
    • Pulse Counter information of input_nr is spread over 4 bytes, byte3->MSB, byte0->LSB
    • CRC16 is calculated over these 4 bytes
Response M->G (Type=1)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 ... 50 51 52 53 54 55 56 57 58 59
"RTR" CID "P" "C" 0 51 Input_nr.msb Input_nr.lsb Type pc0.byte3 pc0.byte2 pc0.byte1 pc0.byte0 CRC16_0.msb CRC16_0.lsb ... pc7.byte3 pc7.byte2 pc7.byte1 pc7.byte0 CRC16_7.msb CRC16_7.lsb "C" CSUM 13 10
  • Byte5..55 -> Data payload
  • Byte56 -> "C": Indicate that following byte is the CRC
  • Byte57 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • pc_x: Pulse Counter information of input_nr x
    • Pulse Counter information of input_nr x is spread over 4 bytes, byte3->MSB, byte0->LSB
    • CRC16 is calculated over these 4 bytes
  • Input_nr is determined which input module will be taken, for that input module, the 8 pulse counters will be sent over

SI -> Sensor information

This instruction will request sensor information (temperature, humidity, brightness) from a sensor module.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12
"STR" CID "S" "I" 0 2 Module_nr Instr "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"SI": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..6 -> Data payload: In the data payload, you'll find the 6 bytes needed for a BA
  • Byte7 -> "C": Indicate that following byte is the CRC
  • Byte8 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Instr: This parameter will indicate which values are requested
  • Module_nr: Each Module has a module nr (from 0 to ?). Each module can have 8 connected sensors. If you request the information of module nr 0, you will get as return the information of sensor 0 till 7, If you request the information of module nr 1, you will get as return the information of sensor 8 till 15 etc
    • If Instr=0 -> Request Temperature Values
    • If Instr=1 -> Request Humidity Values
    • If Instr=2 -> Request Brightness Values
    • If Instr=3 -> Request CO2 Values
    • If Instr=4 -> Request VOC Values
    • If Instr=5 -> Request extra sensor Values
    • If Instr=6 -> Request Temperature Offset Values (return value in Two's complement)
    • If Instr=10 -> Request sensor Configuration
    • If Instr=11 -> Request additional sensor Configuration
  • CID: Byte 0 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 byte0. 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 (instr=0, 1 or 6)

-> for sensors having a byte value

' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
"RTR" CID "S" "I" 0 10 Module_nr Instr data0 data1 data2 data3 data4 data5 data6 data7 "C" CSUM 13 10
  • Byte5..14 -> Data payload: In the data payload, you'll find the 9 bytes of the SI response instruction.
  • Byte15 -> "C": Indicate that following byte is the CRC
  • Byte16 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • data0..7: These are the 8 data bytes containing the requested sensor information. Data0 contains the first sensor value of that module, data7 contains the last sensor value.
Response M->G (instr=2,3,4 and 5)

-> for sensors having a word value

' 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
"RTR" CID "S" "I" 0 18 Module_nr Instr data0.msb data0.lsb data1.msb data1.lsb data2.msb data2.lsb data3.msb data3.lsb data4.msb data4.lsb data5.msb data5.lsb data6.msb data6.lsb data7.msb data7.lsb "C" CSUM 13 10
  • Byte5..22 -> Data payload: In the data payload, you'll find the 9 bytes of the FS response instruction.
  • Byte23 -> "C": Indicate that following byte is the CRC
  • Byte24 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • data0..7: These are the 8 data words containing the requested sensor information. Data0 (msb & lsb) contains the first sensor value of that module, data7 contains the last sensor value (msb & lsb).
Response M->G (instr=10)

-> Returns the sensor configuration of Module_nr

' 0 1 2 3 4 5 6 7..12 13..18 19..24 25..30 31..36 37..42 43..48 49..54 55 56 57 58
"RTR" CID "S" "I" 0 10 Module_nr Instr data_block0 data_block1 data_block2 data_block3 data_block4 data_block5 data_block6 data_block7 "C" CSUM 13 10
  • Byte5..54 -> Data payload: In the data payload, you'll find the 9 bytes of the SI response instruction.
  • Byte55 -> "C": Indicate that following byte is the CRC
  • Byte56 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • The 8 data_blocks contains the data of the 8 outputs of Module_nr: data_block0 contains the data (data0..data5) of sensor_nr0 (sensor_nr0=Module_nr*8), data_block1 contains the data (data0..data5) of sensor_nr1 (sensor_nr1=(Module_nr*8)+1), data_block2 contains the data (data0..data5) of sensor_nr2 (sensor_nr2=(Module_nr*8)+2),
  • Each data_block contains 6 bytes: data0..data5, etc
  • data0..5: These are the 5 data bytes containing the requested sensor information for each sensor_nrx:
    • data0: Sensor_type:
    • data1: temperature_follow: Indicates which group action to trigger when the temperature of that sensor changes
    • data2: humidity_follow: Indicates which group action to trigger when the humidity of that sensor changes
    • data3: brightness_follow: Indicates which group action to trigger when the brightness of that sensor changes
    • data4: airquality_follow: Indicates which group action to trigger when the airquality of that sensor changes
    • data5: sensor_dali_link: Indicates which Dali ID is linked to which sensor


Response M->G (instr=11)

-> Returns the sensor configuration of the extra sensors. Up to 64 extra sensors (word value) or 8 module_nr's can be used for additional sensors like wind speed, additional temperature sensors and others

' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
"RTR" CID "S" "I" 0 10 Module_nr Instr data0 data1 data2 data3 data4 data5 data6 data7 "C" CSUM 13 10
  • Byte5..14 -> Data payload: In the data payload, you'll find the 9 bytes of the SI response instruction.
  • Byte15 -> "C": Indicate that following byte is the CRC
  • Byte16 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • data0..7: These are the 8 data bytes containing the requested sensor extra configuration. Data0 contains which group to trigger when extra sensor0 of that module changes, Data1 contains which group to trigger when extra sensor1 of that module changes ...

sD -> shutter Detail

This instruction will provide all the details of 1 individual shutter or 1 individual shutter group.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12
"STR" CID "s" "D" 0 2 device_nr Instruction "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"OD": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..6 -> Data payload: In these bytes, you'll find the data payload
  • Byte7 -> "C": Indicate that following byte is the CRC
  • Byte8 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Instruction:
    • Instruction=0: Request detail of 1 shutter
    • Instruction=1: Request detail of 1 shutter group
  • device_nr: Represents the shutter_nr (when instruction=0) or shutter_group_nr (when instruction=1)
Response M->G (instruction=0)
' 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
"RTR" CID "s" "D" 0 17 shutter_nr 0 shutter_status output_up.msb output_up.lsb timer_up.msb timer_up.lsb output_down.msb output_down.lsb timer_down.msb timer_down.lsb shutter_position.msb shutter_position.lsb shutter_r_position.msb shutter_r_position.lsb shutter_group.msb shutter_group.lsb "C" CSUM 13 10
  • Byte5..21 -> Data payload
  • Byte22 -> "C": Indicate that following byte is the CRC
  • Byte23 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • shutter_nr: Response will contain information of this shutter_nr
  • shutter_status:
    • BIT0=1->Shutter is in UP direction, BIT0=0->Shutter is in DOWN direction
    • BIT1=1->Shutter is in LOCK status, BIT1=0->Shutter is in UNLOCK status
  • output_up: This is the output that is linked to the UP direction
  • timer_up: This is the timer value (value*100ms) that is used for the UP direction
  • output_down: This is the output that is linked to the DOWN direction
  • timer_down: This is the timer value (value*100ms) that is used for the DOWN direction
  • shutter_position: This is the current shutter position (0-> fully open, 65535-> fully closed) -> Value not yet used
  • shutter_r_position: This is the requested shutter position (0-> fully open, 65535-> fully closed) -> Value not yet used
  • shutter_group: 16 shutter groups exist in the system, every shutter can be linked to any of the 16 shutter groups.
Response M->G (instruction=1)
' 0 1 2 3 4 5 6 7 8 9 10 11
"RTR" CID "s" "D" 0 3 group_nr 1 shutter_group_status "C" CSUM 13 10
  • shutter_group_status:
    • BIT0=1->Shutter group is in UP direction, BIT0=0->Shutter group is in DOWN direction
    • BIT1=1->Shutter group is in LOCK status, BIT1=0->Shutter group is in UNLOCK status

SM -> Set RS485 Mode

This instruction will Set the RS485 Mode.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "S" "M" 0 1 RS485_mode "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"SM": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • RS485_mode:
    • RS485_mode=0: RS485 Bus is in LIVE mode and controlled by the Master (DSPIC)
    • RS485_mode=1: RS485 Bus is in INIT mode and Slaves can send messages without the Master asking for it, slaves are controlling the Bus
    • RS485_mode=2: RS485 bus is in TRANSPARENT mode and all incoming messages from slaves will be forwarded to the BB without any interpretation of the Master, the BB is controlling the Bus.
  • Notes:
    • Changing the RS485 mode will change the behaviour of the bus and change who is the Master of the Bus.
    • This instruction is mainly used to put the bus in Transparent mode to allow boot loading
    • When putting the Bus in Init mode, the necessary instructions to put the modules in discovery mode are not send. Please use other instructions or BA to accomplish this.
Response M->G
' 0 1 2 3 4 5 6 7 8 9
"RTR" CID "S" "M" 0 1 RS485_mode "C" CSUM 13 10
  • Byte5 -> Data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Note:

ST -> Status Read

This instruction will read the Status of the Master.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "S" "T" 0 1 Info_type "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"ST": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Info_type: Represents the requested information
    • Info_type=0 -> Request the current RS485 mode
    • Info_type=1 -> Request the current Master Firmware version
    • Info_type=2 -> Request the current Slave Firmware version
Response M->G (Info_type=0)
' 0 1 2 3 4 5 6 7 8 9 10
"RTR" CID "S" "T" 0 2 Info_type RS485_mode "C" CSUM 13 10
  • Info_type=0
  • Byte5..6 -> Data payload
  • Byte7 -> "C": Indicate that following byte is the CRC
  • Byte8 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • RS485_mode:
    • RS485_mode=0: RS485 Bus is in LIVE mode and controlled by the Master (DSPIC)
    • RS485_mode=1: RS485 Bus is in INIT mode and Slaves can send messages without the Master asking for it, slaves are controlling the Bus
    • RS485_mode=2: RS485 bus is in TRANSPARENT mode and all incoming messages from slaves will be forwarded to the BB without any interpretation of the Master, the BB is controlling the Bus.
  • See AIO Bootloading Slave modules
Response M->G (Info_type=1)
' 0 1 2 3 4 5 6 7 8 9 10 11 12
"RTR" CID "S" "T" 0 4 Info_type Fw_Major Fw_Minor Fw_Built "C" CSUM 13 10
  • Info_type=1
  • Byte5..8 -> Data payload
  • Byte9 -> "C": Indicate that following byte is the CRC
  • Byte10 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • RS485_mode:
  • Fw_Major, Fw_minor, Fw_Built: This is the current Firmware version of the Master (DSPIC33E)
Response M->G (Info_type=2)
' 0 1 2 3 4 5 6 7 8 9 10
"RTR" CID "S" "T" 0 2 Info_type RS485_mode "C" CSUM 13 10
  • Info_type=2
  • Byte5..6 -> Data payload
  • Byte7 -> "C": Indicate that following byte is the CRC
  • Byte8 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • The above response only indicates that the instruction has been received. The Master will now start to request the Firmware version of each individual external module and will respond with instruction "FW" for each external module. Modules that are not external (virtual or CAN generated modules for example) will not be contacted and will not give an API "FW" respond.
  • RS485_mode:
    • RS485_mode=0: RS485 Bus is in LIVE mode and controlled by the Master (DSPIC)
    • RS485_mode=1: RS485 Bus is in INIT mode and Slaves can send messages without the Master asking for it, slaves are controlling the Bus
    • RS485_mode=2: RS485 bus is in TRANSPARENT mode and all incoming messages from slaves will be forwarded to the BB without any interpretation of the Master, the BB is controlling the Bus.

TC -> Transparent Communication (RS485 Tunnel)

This instruction will allow the BB to send any bytes on the RS485 bus. This instruction can only be used when the RS485 bus is set in Transparent mode (API Instruction "SM")

Request G->M
' 0 1 2 3 4 5 6 4+x 5+x 6+x 7+x 8+x 9+x 10+x
"STR" CID "T" "C" 0 x Message_1 ... Message_x "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"TC": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..4+x -> Data payload: In these bytes, you'll find the data payload
  • Byte5+x -> "C": Indicate that following byte is the CRC
  • Byte6+x -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • x: Message length of the RS485 message to be put on the RS485 bus
Response M->G
' 0 1 2 3 4 5 6 7 8 9
"RTR" CID "T" "C" 0 1 x "C" CSUM 13 10
  • Byte5 -> Data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Notes:
    • This response means that the message was successfully sent to the Master (DSPIC), this is not the answer of the slave module. The answer of the RS485 slave module can be found in the API message "TM"
    • This message type can only be used when the RS485 bus is in Transparent mode (See API Instruction "SM"). When this instruction however is used when the RS485 bus is not in Transparent mode, a Check sum error will occur
    • See AIO Bootloading Slave modules

TM -> Transparent Message (from RS485 slave)

This message will be received from the RS485 slave after sending API message "TC"

Automatic Response M->G
' 0 1 2 3 4 5 6 4+x 5+x 6+x 7+x 8+x 9+x 10+x
"RTR" CID "T" "M" 0 x Message_1 ... Message_x "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"TC": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..4+x -> Data payload: In these bytes, you'll find the data payload
  • Byte5+x -> "C": Indicate that following byte is the CRC
  • Byte6+x -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • x: Message length of the RS485 message to be put on the RS485 bus
  • Notes:
    • Messages received in Transparent mode will not be interpreted by the Master.
    • The CID of these Transparent messages will always be 2 (SID 0, 1 and 2 are reserved and cannot be used by the BB)
    • See AIO Bootloading Slave modules

TR -> Time/Date Read

This instruction will Read Time and Date or other time related functions.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11
"STR" CID "T" "R" 0 1 Info_type "C" CSUM 13 10 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"TR": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5 -> Data payload: In these bytes, you'll find the data payload
  • Byte6 -> "C": Indicate that following byte is the CRC
  • Byte7 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Info_type: Represents the requested information
    • Info_type=0 -> Request the current time and date
Response M->G (Info_type=0)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
"RTR" CID "T" "R" 0 8 Info_type Hour Minute second day date Month Year "C" CSUM 13 10
  • Info_type=0
  • Byte5..12 -> Data payload
  • Byte13 -> "C": Indicate that following byte is the CRC
  • Byte14 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Hour: Current hour (0-23)
  • Minute: Current minute (0-59)
  • Second: Current second (0-59)
  • Day: Current day (1-7)
  • Date: Current day of the month (1-31)
  • Month: Current month (1-12)
  • Year: Current year (0-99)

TW -> Time/Date Write

This instruction will Write Time and Date or other related time functions.

Request G->M
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
"STR" CID "T" "W" 0 8 Info_type Hour Minute second day date Month Year "C" CSUM 13 10
  • Byte0 -> CID: Communication ID (filled in by Gateway, copied in the response of the Master)
  • Byte1&2 ->"TW": Represent the instruction
  • Byte3&4 -> Length: Represents the length (Byte3=Length.MSB, Byte4=Length.LSB) of the data payload
  • Byte5..12 -> Data payload: In these bytes, you'll find the data payload
  • Byte13 -> "C": Indicate that following byte is the CRC
  • Byte14 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Info_type: Represents the written information
    • Info_type=0 -> Write the current time and date
  • Hour: Current hour (0-23)
  • Minute: Current minute (0-59)
  • Second: Current second (0-59)
  • Day: Current day (1-7)
  • Date: Current day of the month (1-31)
  • Month: Current month (1-12)
  • Year: Current year (0-99)
Response M->G (Info_type=0)
' 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
"RTR" CID "T" "W" 0 8 Info_type Hour Minute second day date Month Year "C" CSUM 13 10
  • Info_type=0
  • Byte5..12 -> Data payload
  • Byte13 -> "C": Indicate that following byte is the CRC
  • Byte14 -> CSUM: The Check Sum is calculated by taking the sum of the Payload bytes + byte0..4
  • Hour: Current hour (0-23)
  • Minute: Current minute (0-59)
  • Second: Current second (0-59)
  • Day: Current day (1-7)
  • Date: Current day of the month (1-31)
  • Month: Current month (1-12)
  • Year: Current year (0-99)
  • Note: The above response is the current time/date being read after the write procedure is done so it should contain the new time/date.