MultiConnNet Module Instruction Set #
The MultiConnNet is Inplay’s proprietary Multi-Connection Private Network system. It is a 2.4GHz wireless communication network based on a private SDR (Software Defined Radio) protocol, utilizing a one-to-many star connection topology.
The system is comprised of two primary components: the Gateway module and the Node module. The module is connected to the HOST via UART interface, and this instruction set defines the data packet format between the module and the HOST.
The data packet originally issued by HOST is called Command and the module will return Response to HOST accordingly. The data packet originally issued by the module is called Event.
Command and Response #
Command and corresponding Response are data packets consist of a sequence of bytes. The format of the data packet is as follows.
| Sync Word | ID | Owner | Body Len | Body |
|---|---|---|---|---|
| (1 byte) | (1 byte) | (2 bytes) | (2 bytes) | (variable) |
Figure 1: Command and response data packet format
Sync Word: Fixed 0x4A for command and corresponding response.
ID: unique command id.
Owner: Represents who will actually excute the command or who send it for response. 0 represents local module, otherwise remote module’s device address.
Body Len: is the length of variable body that follows.
Command can be executed by local module or remote module. If command is executed locally (Owner in command data packet is 0), the receiver module will send back a response data packet to the HOST immediately, indicating the result of execution. This response is referred to as Local Response (Owner is 0 in response data packet). If command is executed remotely (Owner in command data packet is non-zero), the receiver module will send back local response immediately, indicating whether the command is accepted or not. If accepted, a subsequent Transmission Done Event is then received by HOST indicates the command is actually passed-through to the remote module. If the result of transmission is success, additional response data packet from the remote module will then be forwarded back to the HOST. Since Owner field is actual device address (non-zero) in this response, it is referred to as Remote Response.
Commands that execute remotely are only issued to gateway module. For node module, all commands are local command so that Owner field is ignored.
Configuration commands are those that must be sent at least once by HOST prior to other commands. Parameters by configuration command can be stored in flash so that system can automatically start running each time power on reset, without configuration command being issue again. Configuration command are local command only.
Data Transmission command is the only remote command that Remote Response is not generated since data is totally passed-through to HOST and completely user dependent.
Here are details of MultiConnNet commands and corresponding responses:
Serial Port Configuration (ID=1) #
This command changes parameters of the serial port that interacts with HOST. It is for local only. It is optional, meaning that if not configured, the module will use following default UART configurations:
- GPIO_2_1 as UART TX and GPIO_2_7 as UART RX
- 921,600 bps
- 8 bits
- No Parity
- 1 Stop bit
- Hardware flow control disabled
The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 4 | TX GPIO | 1 | Specify which GPIO is multiplexed for UART TX function. The upper 4 bits represent the Port, and the lower 4 bits represent the Pin. For example, for GPIO_0_2, TX GPIO=0x02. |
| 5 | RX GPIO | 1 | Same as TX GPIO |
| 6 | RTS GPIO | 1 | Same as TX GPIO. If 0xFF, RTS signal is not used. |
| 7 | CTS GPIO | 1 | Same as TX GPIO. If 0xFF, CTS signal is not used |
| 8 | baud rate | 4 | Support 921600, 460800, 230400, 115200, 57600, 38400, 19200 |
| 12 | data bit | 1 | Data bit length. 5 - 8 |
| 13 | polarity | 1 | 0: None 1: Odd 2: Even |
| 14 | stop bit | 1 | Stop bit number |
| 15 | receive buffer size | 4 | Receive buffer size, Maximum 2048 |
| 19 | reserved | 1 | 0x00 |
Example:
→ 4A 01 00 00 10 00 21 27 FF FF 00 C2 01 00 08 00 01 2C 01 00 00 00 ;GPIO_2_1, GPIO_2_7, 115200bps
← 4A 01 00 00 02 00 00 00 ;Local response
Network Parameter Configuration (ID=2) #
This command configure module’s network parameters. It is for local only. If network parameters are stored afterwords by Reset command, module can be run automatically without sending it again.
For gateway module, the command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | gateway module device address | 2 | A 16-bit value that can only be taken from 0x1000 to 0xF000, where the lower 12 bits are all zeros. |
| 8 | access address on connection | 4 | Access Address when data communication after connection |
| 12 | access address on pairing | 4 | Access Address when pairing procedure |
| 16 | channel on pairing | 1 | Channel on which pairing procedure is. |
Example:
;Device address (Gateway) is 0x1000, Access Addresses are 0x67453201 and 0xABABABAB, Channel on pairing is 37
→ 4A 02 00 00 0B 00 00 10 01 23 45 67 AB AB AB AB 25
← 4A 02 00 00 02 00 00 00
For node module, the command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | node module device address | 2 | A 16-bit value that can only be taken from 0x0000 to 0x0FFF, where the upper 4 bits are all zeros. |
| 8 | gateway device address | 2 | A 16-bit value that can only be taken from 0x1000 to 0xF000, where the lower 12 bits are all zeros. |
| 10 | access address on pairing | 4 | Access Address when pairing procedure |
| 14 | channel on pairing | 1 | Channel on which pairing procedure is. |
| 15 | connection interval | 2 | Node's connection interval. |
| 17 | supervision timeout | 4 | Time in millisecond, that allowed for a device to receive data or signals from another device. If no data is received within this timeframe, the connection may be considered lost or disconnected. |
| 21 | pair interval | 2 | Time interval in millisecond for sending pairing interaction information. The smaller the interval, the faster the pairing will be successful, but power consumption will increase. |
| 23 | pairing duration | 4 | Duration of pairing procedure in millisecond. 0 if non stop. |
Example:
;Node's device address is 0x0100, access address on pairing is 0x67453201, connection interval is 800ms, supervision timeout is 20000ms, pair interval is 50ms and pairing is not stopped.
→ 4A 02 00 00 15 00 00 01 00 10 AB AB AB AB 25 20 03 20 4E 00 00 32 00 00 00 00 00
← 4A 02 00 00 02 00 00 00
External Power Amplifier Control Configuration (ID=3) #
This command sets up module’s external Power Amplifier (PA) Control function. It is for local only. This command is optional, meaning that if not configured, the module will use following default GPIOs:
- TX enable: GPIO_3_3
- RX enable: GPIO_2_5
- BIAS: unused
The TX enable GPIO will automatically output high to open electronic circuits of power amplifier when RF is opened for transmission. RX enable GPIO and BIAS GPIO share similar working principles.
The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | TX GPIO | 1 | GPIO which is used to control Tx_En of expernal PA. The upper 4 bits represent the Port, and the lower 4 bits represent the Pin. For example, for GPIO_3_3, it is 0x33. |
| 7 | RX GPIO | 1 | GPIO which is used to control Rx_En of expernal PA. The upper 4 bits represent the Port, and the lower 4 bits represent the Pin. For example, for GPIO_2_5, it is 0x25. |
| 8 | BIAS GPIO | 1 | GPIO which is used to control bias of expernal PA. The upper 4 bits represent the Port, and the lower 4 bits represent the Pin. If no bias control, set it to 0xFF. |
Example:
→ 4A 03 00 00 03 00 33 25 FF ;TX GPIO is GPIO_3_3, RX GPIO is GPIO_2_5, no BIAS
← 4A 03 00 00 02 00 00 00 ;Local response
Get State (ID=10) #
This command retrieves the module status. It is for local only.
The length of this command is 0. The response is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | state | 1 | Current module state. 0: Not running, module may not be fully configured yet 1: Running |
Example:
→ 4A 0A 00 00 00 00 ;Try retrieving module status
← 4A 0A 00 00 01 00 01 ;Module is running normally
Get Connection (ID=11) #
This command retrieves the number of connected modules and corresponding device addresses. For nodes, a return value of 0 of number indicates not connected. It is for local only.
The length of this command is 0. The response is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | count | 1 | Number of connected devices |
| 7 | device address | count*2 | Device addresses of connected modules. |
Example:
→ 4A 0B 00 00 00 00 ;Try retrieving the connection status of gateway
← 4A 0B 00 00 07 00 03 00 01 01 01 02 01 ;Gateway has connected with 3 nodes 0x0100, 0x0101 and 0x0102
→ 4A 0B 00 00 00 00 ;Try retrieving the connection status of node
← 4A 0B 00 00 03 00 01 00 10 ;Node returns connection with gateway with device address 0x1000
Module Reset (ID=0x20) #
This command resets the module. For node module, this command is local only (*Owner field is ignored. For gateway module it can be locally or remotely executed. The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | option | 1 | 0: Reset 1: Reset module with previous configuration cleared 2: Reset module with previous configuration stored |
Example:
→ 4A 20 00 00 01 00 02 ;Save configuration before reset for local module
← 4A 20 00 00 02 00 00 00 ;Local response
→ 4A 20 00 01 01 00 00 ;Reset remote module 0x0100 from gateway
← 4A 20 00 00 02 00 00 00 ;Local module accepts command
← A4 A2 04 00 00 01 00 00 ;Transmission done event
← 4A 20 00 01 02 00 00 00 ;Remote response from node 0x0100
Modue Run (ID=0x21) #
This command start or stop running of module. For node module, this command is local only. For gateway module it can be locally or remotely execution. If Network Parameter Configuration is not stored, it is necessary to send this command to start the module, otherwise module will automatically start running after power on reset.
The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | running | 1 | 0: Stop 1: Start |
Example:
→ 4A 21 00 00 01 00 01 ;Start running of local module (either gateway or node)
← 4A 21 00 00 02 00 00 00 ;Local response
→ 4A 21 00 01 01 00 00 ;Stop running of remote node 0x0100 (from gateway)
← 4A 21 00 00 02 00 00 00 ;Local response
← A4 A2 04 00 00 01 00 00 ;Transmission done event
← 4A 21 00 01 02 00 00 00 ;Remote response from node with device address 0x0100
Module GPIO Output (ID=0x22) #
The command allows the module’s specified GPIO pin outputs to a designated level. For node, this command is local only. For gateway it can be called locally or remotely.
The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | GPIO | 1 | GPIO which is configured as output functionality. The upper 4 bits represent the Port, and the lower 4 bits represent the Pin. For example, for GPIO_0_4, it is 0x04. |
| 7 | level | 1 | Output level. 0 : Low level other : High level |
Example:
→ 4A 22 00 00 04 00 01 01 ;Node module's GPIO_0_1 outputs high
← 4A 22 00 00 02 00 00 00 ;Local response
→ 4A 22 01 01 04 00 01 01 ;Remote control node 0x0101 module's GPIO_0_1 to output high from gateway
← 4A 22 00 00 02 00 00 00 ;Local response
← A4 66 04 00 01 01 00 00 ;Transmission to node 0x0101 done
← 4A 22 01 01 02 00 00 00 ;Remote response received from node 0x0101
Module GPIO Input Trigger (ID=0x23) #
This command allows module to trigger a GPIO input event when GPIO is in a specified state. For node module, this command is local only, but the event can be either sent to its HOST via UART or remote connected device over the air depending on target field in command. For gateway module, if the command is local and then the event can only be sent to HOST via UART regarding of target field in command. If the command is remote execution, the event can be either sent to remote HOST via its UART or remotely to connected device over the air. To short, target field defines whether the event will be sent to the remote connected device corresponding to the executor of this command, with the condition that this remote device MUST only be a gateway module.
The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | GPIO | 1 | GPIO which is configured as input functionality. The upper 4 bits represent the Port, and the lower 4 bits represent the Pin. For example, for GPIO_0_4, it is 0x04. |
| 7 | internal pull up/down | 1 | 0: no pull up/down 1: internal pull up 2: internal pull down |
| 8 | edge-triggered condition | 1 | 0x00: falling edge 0x01: rising edge 0x02: both edge 0xFF: none |
| 9 | target | 1 | 0: local HOST 1: remote connected device |
Example:
→ 4A 23 00 00 04 00 04 01 00 01 ;node module GPIO_0_4 falling edge trigger with internal pull up enabled, event will be remotely sent to gateway.
← 4A 23 00 00 02 00 00 00 ;Local response
→ 4A 23 01 01 04 00 04 01 00 01 ;gateway remotely set node module (0x0101) GPIO_0_4 falling edge trigger with internal pull up enabled, event will be remotely sent to gateway.
← 4A 23 00 00 02 00 00 00 ;Local response
← A4 A2 04 00 00 10 00 00 ;Transmission done event
← 4A 23 01 01 02 00 00 00 ;Remote response
...
← A4 A4 04 00 01 01 04 00 ;GPIO Input trigger event
Data Transmission (ID=0x30) #
This command initiates user data transmission either from Gateway to Node or Node to Gateway. Module will return local response first like any other commands and then Transmission Done Event indicating actual wireless transmission is finished or not.
The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | data | variable length | Banary byte data array |
Example:
→ 4A 30 01 01 03 00 0A 0B 0C ;Send 3 bytes (0A 0B 0C) from gateway to node 0x0101
← 4A 30 00 00 02 00 00 00 ;Local response
← A4 A2 04 00 01 01 00 00 ;Transmission done event
→ 4A 30 00 10 03 00 0A 0B 0C ;Send 3 bytes from node to gateway 0x1000
← 4A 30 00 00 02 00 00 00 ;Local response
← A4 A2 04 00 00 10 00 00 ;Transmission done event
Firmware Update command (ID=0x40) #
This command initiates Firmware Update to module. For node, this command is local only, while for gateway it can be called locally or remotely. If remotely, node’s firmware is updated over the air. Firmware Update consists of 3 processes, Prepare, Write, Cancel. Each process is composed of different data packet.
Prepare #
The first process is to tell Node the firmware update over the air is going to begin, along with information including new firmware size, CRC verification, AES encryption etc.
The command is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | process | 1 | 0 |
| 7 | firmware size | 4 | firmware size |
| 11 | flag | 1 | Each bit set to 1 indicates that the corresponding function is enabled. bit 0: AES encryption bit 4: CRC check other: N/A |
| 12 | CRC | 4 | CRC value of part of firmware binary excluding the first 16K bytes. If CRC check in flag is not set, it's ignored. |
Example:
→ 4A 40 01 01 0A 00 00 20 1B 01 00 00 00 00 00 00 ;OTA prepare to node 0x0101, firmware size is 72,480 bytes, no CRC check and AES encryption
← 4A 40 00 00 02 00 00 00 ;Local response
← A4 A2 00 00 04 00 01 01 00 00 ;Transmission done event
← 4A 40 01 01 02 00 00 00 ;Remote response received from node 0x0101
Write #
This process is called several times to do actual firmware data transmission until finished.
The data packet is as follows:
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | process | 1 | 1 |
| 7 | offset | 4 | firmware offset |
| 11 | data | Len-7 | data length that follows |
Example:
→ 4A 40 01 01 <len> 01 00 00 00 00 ... ;OTA write firmware data to node 0x0101, offset is 0, size is <len> bytes
← 4A 40 00 00 02 00 00 00 ;Local response
← A4 A2 00 00 04 00 01 01 00 00 ;Transmission done event
← 4A 40 01 01 02 00 00 00 ;Remote response (4A 0B 02 00 00 00) received from node 0x0101
Cancel #
This command cancel any on-going OTA firmware update process.
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 6 | process | 1 | 0xFF |
Example:
→ 4A 40 01 01 01 00 FF ;OTA cancel firmware update to node 0x0101
← 4A 40 00 00 02 00 00 00 ;Local response
← A4 A2 04 00 01 01 00 00 ;Transmission done event
← 4A 40 01 01 02 00 00 00 ;Remote response (4A 0B 02 00 00 00) received from node 0x0101
Response #
A Response is the data packet returned by the module, indicates whether the command has been accepted or not. The body of Response is a fixed length of two bytes called Result, following the same header as the corresponding command. The Response can be local response sent by local module, or remote response sent by remote module, which is included in the data of the Data Reception Event. Both local response and remote response share the same data structure.
The available Result values are as follows:
0| NAME | VALUE | MEANING |
|---|---|---|
| WL_ERR_NO_ERROR | 0 | Success |
| WL_ERR_CMD | 0x1001 | Sync Word in data head error |
| WL_ERR_CMD_ID | 0x1002 | ID in data head error |
| WL_ERR_CMD_PARAM | 0x1003 | Parameter error |
| WL_ERR_TIMEOUT | 0x1004 | Command executing timeout |
| WL_ERR_BUSY | 0x1005 | Command is not acceptable due to system busy |
| WL_ERR_NOT_READY | 0x1006 | System is not ready of well configured |
Event Description #
An Event is the data packet actively sent by the module to the HOST. Events have Sync Word 0xA4 in their data packet and unique event identifier follows. The format of the data packet is as follows.
| Sync Word | ID | Body Len | Body |
|---|---|---|---|
| (1 byte) | (1 byte) | (2 bytes) | (variable) |
Figure 1: Event data packet format
Sync Word: Fixed 0xA4.
ID: unique event id.
Body Len: is the length of variable body that follows.
Here are details of MultiConnNet events:
Module Ready Event (ID=0xA0) #
This event indicates system is ready to accept command from HOST. It has no body so the body len field is 0.
Example:
← A4 A0 00 00
Connection Event (ID=0xA1) #
This event indicates Gateway/Node has successfully connected or disconnected to each other.
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 4 | connection | 1 | 0: disconnect 1: connect |
| 5 | device address | 2 | Remote device address |
Example:
← A4 A1 03 00 01 00 01 ;Gateway has connected with node 0x0100
Transmission Done Event (ID=0xA2) #
This event indicates data has been actually transmitted over the air.
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 4 | device address | 2 | Remove device address |
| 5 | result | 2 | Transmission result. 0 : success other : protocol-level errors |
Example:
← A4 A2 04 00 00 01 00 00 ;Gateway has transmitted data to node with device address 0x0100
Data Reception Event (ID=0xA3) #
This event indicates data has been received from remote connected devices.
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 4 | device address | 2 | Remote device address |
| 6 | data | Len-2 | Banary byte data array |
Example:
← A4 A3 05 00 00 01 00 01 02 ;Gateway has received 3 bytes data from node 0x0100
GPIO Input Trigger Event (ID=0xA4) #
This event indicates GPIO’s input status is triggered, which is configured by GPIO Input Configuration command. This event can be sent to local HOST or remote devices, depending on device address parameter in event data body.
| OFFSET | NAME | LENGTH | VALUE |
|---|---|---|---|
| 4 | device address | 2 | Remote device address, or local if 0. |
| 6 | GPIO | 1 | GPIO which input status is triggered. The upper 4 bits represent the Port, and the lower 4 bits represent the Pin. For example, for GPIO_0_4, it is 0x04. |
| 7 | level | 1 | Current GPIO level |
Example:
← A4 A4 04 00 01 01 04 00 ;Node 0x0101 GPIO_0_4 falling edge trigger