Chain PIR UART Control Protocol (Documentation V1)

1. Basic Information

2. Data Frame Format

All packets start with 0xAA 0x55 and end with 0x55 0xAA. Multi-byte length fields are entered low byte first.

2.1 Request Frame Format

Request Frame:
  AA 55 <Length_low> <Length_high> <Index> <Cmd> <Req Data...> <CRC> 55 AA

2.2 Response Frame Format

Response Frame:
  AA 55 <Length_low> <Length_high> <Index> <Cmd> <Resp Data...> <CRC> 55 AA

2.3 Response Data Convention

3. Checksum

CRC = (Index + Cmd + Data[0] + ... + Data[n]) & 0xFF

3.1 Checksum Example

#include <stddef.h>
#include <stdint.h>

uint8_t chain_calc_crc(uint8_t index, uint8_t cmd,
                       const uint8_t *data, size_t data_len)
{
    uint16_t sum = index + cmd;

    for (size_t i = 0; i < data_len; i++) {
        sum += data[i];
    }

    return (uint8_t)(sum & 0xFF);
}

4. Quick overview of commands

5. Command Details

5.1 Set RGB value - Cmd 0x20

Request data

Input parameters: Index_id (device index ID), Index (starting coordinates of the RGB lamp), Num (number of RGB to be set), RGB value

Request Frame:
  AA 55 | 0x05+Num*3 | 0x00 | Index_id | 0x20 | Index | Num | R | G | B | CRC | 55 AA

Response Data

Return parameters: Operation_Status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x20 | Operation_Status | CRC | 55 AA

Things to note

1. Operation_Status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Index is the starting coordinate of the RGB light, starting from 0. The Switch device has only one light, so Index = 0, Num = 1

5.2 Get RGB value - Cmd 0x21

Request data

Input parameters: Index_id (device index ID), Index (starting coordinates of RGB lights), Num (number of RGB lights to be read)

Request Frame:
  AA 55 | 0x05 | 0x00 | Index_id | 0x21 | Index | Num | CRC | 55 AA

Response Data

Return parameters: Operation_Status, RGB value

Response Frame:
  AA 55 | 0x04+Num*3 | 0x00 | Index_id | 0x21 | Operation_Status | R | G | B | ... | CRC | 55 AA

Things to note

1. Operation_Status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Index: The starting coordinates of the RGB light, starting from 0. The Switch device has only one light, so Index = 0, Num = 1

5.3 Set RGB light brightness - Cmd 0x22

Request data

Input parameters: Index_id (device index ID), Light (RGB brightness), Save_to_flash (whether to save to internal Flash)

Request Frame:
  AA 55 | 0x05 | 0x00 | Index_id | 0x22 | Light | Save_to_flash | CRC | 55 AA

Response Data

Return parameters: Operation_Status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x22 | Operation_Status | CRC | 55 AA

Things to note

1. Operation_Status operation status
   • 0: Operation failed
   • 1: Operation successful
2. Save_to_flash Whether to save internal Flash
   • 0: Do not save
   • 1：Save
3. Successful setting takes effect immediately
4. Saving to the internal Flash requires erasing the page, which is a time-consuming process. Frequent operations will affect the life of the device. If you need to adjust the brightness frequently, please avoid saving to the internal Flash every time.

5.4 Get RGB light brightness - Cmd 0x23

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x23 | CRC | 55 AA

Response Data

Return parameters: Light (RGB brightness)

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x23 | Light | CRC | 55 AA

Things to note

5.5 Get PIR infrared sensing results - Cmd 0x37

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0x37 | CRC | 55 AA

Response Data

Return parameters: PIR_Value value

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0x37 | PIR_Value | CRC | 55 AA

Things to note

1. PIR_Value (infrared sensing result)
   • 0：People leave
   • 1：People are coming

5.6 Chain PIR equipment automatically reports the current infrared sensing results when an infrared sensing event is triggered - Cmd 0xE0

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  Device-initiated report，No host request frame

Response Data

Return parameter: Status (infrared sensing result)

Response Frame:
  Device-initiated report，No response frame

Things to note

1. Status infrared sensing result
   • 0：People leave
   • 1：People are coming
2. Infrared sensing trigger condition, trigger once when the infrared sensing result of PIR changes.
3. This data packet is only reported when the "infrared sensing event" trigger switch is turned on. After the data packet is sent, the RGB light will superimpose the effect on the light effect set by the user, superimposing the G value or R value of RGB. When it senses the arrival of a person, the green light will turn on, which will last for 1 second and then turn off. off; when it senses that someone is leaving, the red light will turn on and last for 1 second and then go off. Example 1: The user sets the RGB lights to (R=128, G=0, B=128) and the brightness to 50%. After brightness compression, the actual display is: R=64, G=0, B=64. When the arrival of a person is sensed and the PIR sensing result changes, the G channel superimposes 255 and displays It becomes: R=64, G=255, B=64, then the G value gradually decays to 0 within 1 second, and finally returns to: R=64, G=0, B=64. Example 2: The user sets the RGB lights to (R=128, G=128, B=0) and the brightness to 50%. After brightness compression, the actual display is: R=64, G=64, B=0. When the arrival of a person is sensed and the PIR sensing result changes, the G channel is superimposed 255. due to The original G value is 64, and after superposition it is 319. When it exceeds 255, it is processed as the maximum value of 255, so the display becomes: R=64, G=255, B=0. Then the G value gradually decays to 0 within 1 second, and finally returns to: R=64, G=64, B=0.
4. 0x05 Chain PIR device automatically reports the type code. Set "infrared sensor event touch"

5.7 Set the switch triggered by infrared sensing event - Cmd 0xE1

Request data

Input parameters: Index_id (device index ID), Mode (PIR mode)

Request Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xE1 | Mode | CRC | 55 AA

Response Data

Return parameters: Operation_Status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xE1 | Operation_Status | CRC | 55 AA

Things to note

1. Mode (turn on/off event trigger reporting function, default 1)
   • 0: trigger off
   • 1: Trigger on
2. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful Get "infrared sensor event touch"

5.8 Query the switch triggered by infrared sensing event - Cmd 0xE2

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xE2 | CRC | 55 AA

Response Data

Return parameter: Mode (turn on/off event trigger reporting function)

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xE2 | Mode | CRC | 55 AA

Things to note

1. Mode (sensing the arrival of a person/sensing the departure of a person triggering event reporting, default 1)
   • 0: trigger off
   • 1: Trigger on Set up the "Sensing arrival of people" event

5.9 Set the holding time of PIR infrared sensor "someone arriving" event trigger - Cmd 0xE3

Request data

Input parameters: Index_id (device index ID), Keep_Seconds (the number of seconds to keep the "sense someone arriving" event triggered), Save_to_flash (whether to save to internal Flash)

Request Frame:
  AA 55 | 0x05 | 0x00 | Index_id | 0xE3 | Keep_Seconds | Save_to_flash | CRC | 55 AA

Response Data

Return parameters: Operation_Status

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xE3 | Operation_Status | CRC | 55 AA

Things to note

1. Keep_Seconds ranges from 0 ~ 255 seconds, default is 5 seconds
2. Save_to_flash Whether to save internal Flash
   • 0: Do not save
   • 1：Save
3. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
4. Successful setting takes effect immediately
5. Saving to the internal Flash requires erasing the page, which is a time-consuming process. Frequent operations will affect the life of the device. Obtain the "sensing the arrival of people" event

5.10 Get the holding time triggered by the PIR infrared sensor "someone arriving" event - Cmd 0xE4

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xE4 | CRC | 55 AA

Response Data

Return parameter: Keep_Seconds (the number of seconds to keep the "sense someone arriving" event triggered)

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xE4 | Keep_Seconds | CRC | 55 AA

Things to note

1. Keep_Seconds ranges from 0 ~ 255 seconds, default is 5 seconds

5.11 Query the unique UID of the device - Cmd 0xF8

Request data

Input parameters: Index_id (device index ID), UID_Type

Request Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xF8 | UID_Type | CRC | 55 AA

Response Data

Return parameters: Operation_status, UID

Response Frame:
  AA 55 | 0x04+4/12 | 0x00 | Index_id | 0xF8 | Operation_status | UID (multi-byte) | CRC | 55 AA

Things to note

1. Operation_status operation status
   • 0: Operation failed
   • 1: Operation successful
2. UID_Type UID type
   • 0：4byte UID
   • 1：12byte UID

5.12 Query the upgrade program version number - Cmd 0xF9

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xF9 | CRC | 55 AA

Response Data

Return parameters: Bootloader_version

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xF9 | Bootloader_version | CRC | 55 AA

Things to note

5.13 Query the device software version number - Cmd 0xFA

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xFA | CRC | 55 AA

Response Data

Return parameters: Firmware_version

Response Frame:
  AA 55 | 0x04 | 0x00 | Index_id | 0xFA | Firmware_version | CRC | 55 AA

Things to note

5.14 Query device type - Cmd 0xFB

Request data

Input parameter: Index_id (device index ID)

Request Frame:
  AA 55 | 0x03 | 0x00 | Index_id | 0xFB | CRC | 55 AA

Response Data

Return parameters: Device_type

Response Frame:
  AA 55 | 0x05 | 0x00 | Index_id | 0xFB | Device_type_low | Device_type_high | CRC | 55 AA

Things to note

1. Device_type = (uint16_t)((Device_type_high << 8) | Device_type_low)

5.15 Enumeration request, sent by the end device of chain link change, and sent by the device when it is powered on, notifying the host to update the link device status - Cmd 0xFC

Request data

Input parameters: none

Request Frame:
  Device-initiated report，No host request frame

Response Data

Return parameters: none

Response Frame:
  Device-initiated report，No response frame

Things to note

None.

5.16 Heartbeat packets, regular communication between chain devices, can self-discover whether they are end devices, and the host can also use heartbeat packets to determine whether there is a chain device connection - Cmd 0xFD

Request data

Input parameters: none

Request Frame:
  AA 55 | 0x03 | 0x00 | 0xFF | 0xFD | CRC | 55 AA

Response Data

Return parameters: none

Response Frame:
  AA 55 | 0x03 | 0x00 | 0xFF | 0xFD | CRC | 55 AA

Things to note

5.17 Users can obtain the number of link devices through enumeration - Cmd 0xFE

Request data

Input parameter: Send_num (default 0, used to record the number of devices)

Request Frame:
  AA 55 | 0x04 | 0x00 | 0xFF | 0xFE | Send_num | CRC | 55 AA

Response Data

Return parameter: Receive_num (the value represents the number of devices)

Response Frame:
  AA 55 | 0x04 | 0x00 | 0xFF | 0xFE | Receive_num | CRC | 55 AA

Things to note

None.

6. Status code/enumeration value

6.1 Operating status

Other modes, ranges, and event enumeration values are defined in the "Notes" of the corresponding instructions.

7. Version records