Firmware Communication Protocol
On Smart Lighting Reference Design
6-United/iP3
Jan27, 2018
Revision 0.9
Contents
Firmware Communication Protocol
On Smart Lighting Reference Design
SMG/ISG & 6-United
Jan27, 2018
Revision 0.9
Revision History
1. Introduction
1.1 Purpose of this document
1.2 Smart Lighting Communication Overview
2. LoRa Frame Format
2.1 Frame Format
2.2 Command Type
3. Feature Description
3.1 Payload Format
3.2 Node Data Report Interface
3.3 Uploading Frame Inteval Set & Get
3.4 Node’s ID Notification & Get
3.5 Lighting Control Interface
3.6 Power Meter Data Interface
3.7 GPS Data Interface
3.8 G-Sensor Interface
3.9 Lighting Control Mode Interface
3.10 Lighting Schedule/Policy Interface
3.11 Firmware Update Interface
3.12 Light status switch upload
3.13 Get Local Time,Sunrise and Sunset
Revision History
Rev. No. / Description / Rev. Date0.1 / Initial Release / 2016/11/07
0.2 / Added multi-client support / 2016/11/08
0.3 / Added 801LP LoRa command / 2016/11/17
0.4 / Tune the protocol / 2016/12/26
0.5 / Update the policy and schedule section / 2017/02/04
0.6 / Update some the lighting control section / 2017/02/07
0.7 /
- Add download frame format;
- Update node data len;
- Update decription from Chinese to English
- Update ALS control policy setting
0.8 /
- Update Control Slots define
- Add uploading light status change in auto/adv. Mode
- Update auto mode
- Add get local time,sunset,sunrise
0.9 /
- Update auto mode script
- Add light control mode
- Delete timezone in adv. mode
1.Introduction
1.1Purpose of this document
This document describes the communication protocol in smart lighting solution, mainly focus on the protocol between Smart Lighting node device and control client. It will cover the data format, communication flow control and command definition.
1.2Smart Lighting Communication Overview
The smart lighting solution include the smart lighting node, wireless communication gateway, wireless communication server, application server and control client. In this document, we consider the wireless communication only pass the data between node and control client.
Smart lighting node collects the data and sends to control clients through wireless communication. At the same time, control clients send the command and control back to smart lighting node.
In our design, all the communication modules/gateways/servers only transfer the data between smart lighting node and control clients.
(To be update later, to support multi control clients connected to server at same time, requester information will be sent to node, and node will send this information back to server in response to indicate the command requester. One or more requester information may be integrated into one single command. )
All the data are transferred in predefined format. Node and client will parse the data frame by defined format as well. All the frame with wrong format will be ignored.
Since there may be some untrusted communication in the communication chain. We can’t make sure the data received is correct. Data may be modified, lost or duplicated during the communication.
2.LoRa Frame Format
2.1Frame Format
In this document, we use LoRaWAN as our wireless communication solution. All the format and command definition is based on UM801LPUserGuideV1.1_EN.
Below is upload frame format sending from MCU:
Preamble / Start ID / LoRa_CMD / Length / Port / Payload / CRC / End0xFF / 0xFFAA / 1 Byte / 1 Byte / 1 Byte / N Bytes / 2 Bytes / 0x40
Preamble: >0 Byte, additional bytes to wake up the UM801MP LoRa module.
Start ID: Start of one frame.
LoRa_CMD: Please ref UM801LP user guide for the details.
Length: Length of yellow marked fields, including Port and Payload.
Port: LoRa Port, use to indicate the Payload type. See below for details.
Payload: Data payload. See below for detail description.
CRC: 2 Bytes CRC value, HDLC type.
End: 0x40 as the end of the frame.
Below is download frame format received by MCU:
Preamble / Start ID / LoRa_CMD / Length / Status / Port / Payload / CRC / End0xFF / 0xFFAA / 1 Byte / 1 Byte / 1 Byte / 1 Byte / N Bytes / 2 Bytes / 0x40
Status:define as 7. Error Reason Table in UM801LPUserGuideV1.1_EN
2.2Command Type
For LoRa_CMD field, we will use part of the UM801LP definition in our protocol. In the one bit command, bit7-5 is the command type indicator. And bit4-0 is the command list.
The following table shows the meaning of bit 7-5.
BIT / Description / 0 / 17 / data direction / Lora ==》Node(MCU) / Node(MCU) ==》Lora，
6 / Read/Write / Node(MCU) Read from Lora / Node(MCU) Write to Lora
5 / Excute result / fail / success
4:0 / command / Command list.
The LoRa_CMD list is defined as follow:
Lora_CMD / Value / DescriptionCRO_FW / 0x01 / r/w the registers related tofirmware module
CRO_RD / 0x02 / r/w the registers related to radio
CIO_WM / 0x03 / Operate the working mode of module
CNO_DS / 0x04 / r/w the registers related to information of device
CCP_LJ / 0x05 / Join
CCP_JR / 0x06 / JoinReset
CCP_LTC / 0x07 / Data sent as an confirmed package
CCP_LTU / 0x08 / Data sent as an unconfirmed package
EV_LJ / 0x10 / Second response of Join
EV_LT / 0x11 / 2ndresponse of transmit or get data from server
EV_LINK / 0x12 / Notify the status of the link
In this document, we will use CCP_LTC and CCP_LTU for the uplink data, and node will parse the EV_LT package for the downlink data.
3.Feature Description
3.1Payload Format
We use following format for data payload structure.
CMD / LEN / Value1 Byte / 1 Byte / N Bytes
CMD: Data payload type.
LEN: Length of Value in Bytes. It will be 0 for Read command.
Value: Data value format is different for each data payload type. In the next section, we will describe the detail data format for each CMD type and scenario.
To support multiple clients to control one node at same time, we can add one Req. ID in downlink payload, this Req. ID is generated by server and client, to indicate the command requester. One byte Req. ID can be integrated into each downlink package right after the LEN as below. And the node will return the Req. ID in response package as well.
CMD / LEN / Req. ID / Value1 Byte / 1 Byte / 1 Byte / N Bytes
In the rest of this document, we consider all the node uplink information will be broadcasted to all connected client through server and no Req. ID implemented.
In the following sections, we will describe all the frame format and communication flow for smart lighting user scenarios.
3.2Node Data Report Interface
As a LoRa node, it will report the data to server periodically for data analysis purpose. This data package also be considered as the heart beaten package to indicate the activity of the node. The data package will contain the necessary information as customer required.
The port and payload format as below:
CMD / LEN / Data0x02(1 Byte) / 28(1 Byte) / See below detail.
The detail format of the data payload is defined as below:
Bytes / Type / Little / Signed / Description / Formula1 / INT / N/A / N / Light PWM (0-254) / L/254%
4 / INT / Y / N / Voltage (V) / V/1000
4 / INT / Y / N / Current (A) / C/1000
4 / INT / Y / N / Power (KW) / P/1000
4 / INT / Y / N / Energy (KWh) / E/1000
2 / INT / Y / Y / X-axis / X*0.00006G
2 / INT / Y / Y / Y-axis / Y*0.00006G
2 / INT / Y / Y / Z-axis / Z*0.00006G
2 / INT / Y / Y / Tiltangle / Tilt/10︒
2 / INT / Y / N / ALS Data(Lux) / A
1 / INT / N/A / N / Lighting Control Mode / M
Return: Indicate the operation execute result. 0 for success.
3.3Uploading Frame Inteval Set & Get
The following command will be used to get the current data report interval time.
CMD / LEN0x50 / 0x00
Scripts as below:
5000
And node will return the current interval with following package.
CMD / LEN / Interval0x51 / 0x02 / 2 Bytes
Interval: the interval time of 2 data report messages. Little Ending.
Also node can send the following command to set the interval time.
CMD / LEN / Interval0x50 / 0x02 / 2 Bytes
Scripts as below:
50020f00
Then node will save the data into NVRAM, and return the following package.
CMD / LEN / Return / Interval0x51 / 0x03 / 1 Byte / 2 Bytes
Return：0x00 Successful.
0x01 Fail.
3.4Node’s ID Notification & Get
When smart lighting node powers on and connects to communication, node will send ID Notification package to server. The package contains the Node ID to indicate the Node Type; hardware version and firmware version. The port and data payload frame is as below:
CMD / LEN / Node ID / HW Version / FW Version0x01 / 0x07 / 0x02 / 2 Byte Version / 4 Bytes Version
Current node type definition:
NodeID / Description0x02 / Smart Lighting
HW Version now is reserved for future usage. Node will return a fixed number.
Client can also query the node information by the following command.
CMD / LEN0x20 / 0x00
Scripts as below:
2000
The node responses this command by the following command.
CMD / LEN / Node ID / HW Version / FW Version0x21 / 0x07 / 0x02 / 2 Byte Version / 4 Bytes Version
3.5Lighting Control Interface
To control the Lighting ON/OFF or dimmingfunction.We implements the DALI interface for smart lighting control. DALI command normally has 2 bytes data from host to DALI controller, and 1 byte data as response if needed. For the client to node communication, node only transfers the DALI command to DALI controller directly. The data payload frame is as below:
CMD / LEN / Value0x22 / 2*L / L* 2 Bytes DALI CMD
2 Bytes DALI CMD, it can support up to 5 DALI command sent at once. (L<= 5)
For those DALI commands which have the return, node will get the 1 byte return value from DALI controller and combine it into the response frame.
CMD / LEN / Value / Value0x23 / 4*L / 2 Bytes DALI CMD / 2 Bytes DALI TRN
DALI command list we are using to set the Lamp:
- Get the current Lamp light Level:
FF 21 FF 98
Scripts as below:
2204ff21ff98
- Set the value XX to sense Y.
A3 XX FF 4Y
Scripts as below:
2204A388FF04
- Active the sense Y.
FF 1Y FF 4Y
Scripts as below:
2204FF01FF04
- Turn ON the light to 100%. (Y= 1-16)
A3 FE FF 4Y FF 1Y
Scripts as below:
2206A3FEFF01FF04
- Turn OFF the light (Y= 1-16)
A3 00 FF 4Y FF 1Y
Scripts as below:
2206A300FF01FF04
We also provide the command to control the Light to specific lighting percentage. The data payload as below:
CMD / LEN / Value0x24 / 0x01 / Request Lighting data
The Lighting data value from 0x00 to 0xFE as DALI interface described.
0x00: OFF.
0xFE: ON.
Scripts as below:
2401dd
The response will be as below:
CMD / LEN / Value0x25 / 0x01 / Read back Lighting data after setting
3.6Power Meter Data Interface
There is a power meter chip in the smart lighting node which connected to the light to collect the power related information like voltage, current, power and energy. Node will periodically report the power meter data to client for analysis, please see the details information in Section 3.2.
The power meter data transfer method is as below:
Volt = VV/ 1000 (V);
Current = AA / 1000 (A);
Power = PP / 1000 (KW);
Energy = EE / 1000 (KWH);
3.7GPS Data Interface
There is one GPS module in node, which will provide the location information of the lighting pole. Since the pole will not be moved after installed. Node will read the GPS location information and store it in NVRAM. When client queries the GPS data, node will read the information from NVRAM or GPS module (if there is no data stored) and response to client. The request port and data payload frame is as below:
CMD / LEN0x26 / 0x00
Scripts as below:
2600
The data returned will include the latitude and longitude data. Detail format to be updated.
CMD / LEN / Latitude / Longitude / Altitude / Latitude Valid / Longitude Valid / Altitude Valid0x27 / 15 / 4 Bytes / 4 Byte / 4 Bytes / 1 Byte / 1 Bytes / 1 Byte
The Latitude and Longitude format is dddmm.mmmm*10000.
The Valid byte indicate whether the data read from GPS interface is valid or not.
3.8G-Sensor Interface
G-Sensor is used to monitor the lighting pole tilt status. The node can real time report the tilt angle.
At the first time when the lighting pole is installed uprightly, the tilted angle needs to be calibrated to be 0. Client should send the calibration command (2800) to node.
CMD / LEN0x28 / 0x00
Scripts as below:
2800
Node will read the currentG-sensor data and store it into inside NVRam. Then it will send the response back to server with the status of calibration.
CMD / LEN / Status0x29 / 0x01 / 1 Byte Status
0x00: Calibration successful.
0x01: Calibration fail.
Node will periodically report the tilt angle data to client for analysis, please see the details information in Section 3.2. Note that the node will report “0xFFFF” when the calibration is not finished.
3.9Lighting Control Mode Interface
The smart lightingprovide couple of different control mode for lamp control.
- Automatic Mode: Lighting control base on the schedule and policy.
- Advanced Auto Mode: Schedule based on astrological calendar and ALS sensor.
- Manual Mode: Manually control the lighting.
- SensorMode:Lighting control onlybase on ALS sensor
In automatic mode, the lamp lighting controlled by schedule predefined and ALS data from sensor. In advanced auto mode, the light controlled by astrological data and ALS data from sensor. In manual mode, the lamp lighting controlled by client DALI command only, the schedule and other sensor control will be disabled. In Sensor Mode:Lighting control onlybase on ALS sensor.
The definition of the control mode is as below:
Control Mode / ValueAutomatic Mode / 0x01
Adv. Auto Mode / 0x02
Manual Mode / 0x03
Sensor Mode / 0x04
Client can send the command to node to set the lighting control mode.
CMD / LEN / Mode0x2A / 0x01 / 1 byte Mode
Scripts as below:
2a0102
The node will set the control mode, and response the current mode to client.
CMD / LEN / Return / Mode0x2B / 0x02 / 1 Byte / 1 byte Mode
Also Client can send the following command to node for the current control mode acquire.
CMD / LEN0x2A / 0x00
Scripts as below:
2a00
The node will return the current mode, and response the current mode to client.
CMD / LEN / Mode0x2B / 0x01 / 1 byte Mode
3.10Lighting Schedule/Policy Interface
- AUTO MODE:
As we describe above, the light is controlled by schedule in auto mode.
Auto Schedule defines the control action to be done in 1 day. The schedule data format will be as below:
Control Number / HH1 / MM1 / Dimm1 / HH2 / MM2 / Dimm2 / … / HHN / MMN / DimmN4 Byte / 1 Byte / 1 Byte / 1 Byte / 1 Byte / 1 Byte / 1 Byte / … / 1 Byte / 1 Byte / 1 Byte
HH: hour
MM: minute
In each schedule,one group of Hour, Min and Dimm indicates one light control action: when time is go to hour:min, set the lamp to Dimm%.
Control Number: Total number of the control action included in one schedule data. We can support up to 10 control actions in one schedule data.
(1)SET AUTO SCHEDULE
Client can send command to set the predefined schedule to node.
CMD / LEN / Schedule No. / Value0x2C（1 Byte） / Length（1 Byte） / 1 Byte / Schedule Data
Scripts as below:
2c1101040000000000610500910a00b10f00e1 //set auto schedule 1 to 4
2c1102040000000100620600920b00b21000e2 //set auto schedule 2 to 4
2c1103040000000200630700930c00b31100e3 //set auto schedule 3 to 4
2c1104040000000300640800940d00b41200e4 //set auto schedule 4 to 4
2c1105040000000400650900950c00b51300e5 //set auto schedule 5 to 4
2c1106040000000500660a00960d00b61400e6 //set auto schedule 6 to 4
Schedule No. : We support up to 16 different schedules stored in node NVRAM. The Schedule No. indicates which one will be set. Its value vary from 1-16.
Node will set the schedule data inside and return the data stored to client as below. :
CMD / LEN / Return / Schedule No. / Value0x2D / Length / 1 Byte / 1 Byte / Schedule Data
(2)GET AUTO SCHEDULE
Client can send the following command to node to get the specific schedule data.
CMD / LEN / Schedule No.0x2C / 0x01 / 1 Byte
Scripts as below:
2c0102
Node will read the schedule data and response to client.
CMD / LEN / Schedule No. / Value0x2D / Length / 1 Byte / Schedule Data
Return value:
ReturnValue / read / setsucceed / 0x00 / 0x10
failed / 0x01 / 0x11
(3)AUTO POLICY SET:
Base on those schedules stored in node, we can define one policy for auto control mode. The Policy data format is defined as below:
Time Zone / Control Number / MM1 / DD1 / SS1 / … / MMN / DDN / SSN1 Byte / 1
Byte / 1 Byte / 1 Byte / 1
Byte / … / 1 Byte / 1 Byte / 1
Byte
Time Zone: the delta time compare with UTC.
Control Number: the number of total control group,N<=12.
MM: Month
DD: Day
SS: schedule applied. Upper Nibble: Weekday schedule. Lower Nibble: Weekend schedule.
It will be combination of 2 schedules, indicate for weekday and weekend. For example, SS1=0x34 means schedule 3 for weekday and schedule 4 for weekend.
Same as schedule, client can send the below command to set the policy.
CMD / LEN / Value0x2E / Length / Policy Data
Scripts as below:
2e0e50040c01120c1a560c1b560c1c34
Node will save the Policy data into NVRAM and active the policy at once. And response with the following package.
CMD / LEN / Return / Value0x2F / Length / 1 Byte / Policy Data
(4)AUTO POLICY GET:
Also client can send the following command to get the current policy data.
CMD / LEN0x2E / 0x00
Scripts as below:
2e00
The response of the read command will be as below:
CMD / LEN / Value0x2F / Length / Policy Data
- ADVANCE AUTO MODE:
For advanced auto mode, GPS will provide the sunrise time and sunset time day by day. So the schedule will only include the delta time but not the exactly time. The schedule will be as below:
Expire date / Sunrise Slot No. / Sunset Slot No. / Control Slots4 Bytes / 1 Byte / 1 Byte / N*3 Bytes
Expire data: indicate this valid period of this schedule. Ordianally,it should be set 3408 0C 1F = 2100-Dec-31st.If year>2100 or month>12 or data>31st,firmware will set it 3408 0C 1F = 2100-Dec-31st.
Expire date format is:year:month:day2byte:1byte:1byte.3408 0C 1F =2100-Dec-31st Notes:3408: 34 is low byte,08 is high byte in 16bit integer,expire date is GTM 0
Sunrise slot No. Sunset Slot No. : The number of control slots base on sunrise and sunset.
Control Slots:N = Sunrise slot No.+ Sunset Slot No. Each slot will contain 3 bytes: 2bytes (signed) delta minites and 1byte (unsigned) dim(00-fe). All delta minites in Sunrise Slots is counted from local sunrise time(local GTM,forBeiing China GTM +8), as well as all delta minites in Sunset Slots is counted from local sunset time.
Notes:
1<=sunrise slot number<12;
1<=sunset slot number<12;
2 <=sunrise slot number+sunset slot number <=12
-24*60 < delta minites24*60
Example
Sunrise Slot No. / Sunset Slot No. / Sunrise 1 / Sunrise 2 / Sunset 12 / 1 / FFF1D2 / 0F0000
Two commands for sunrise:
- F1FFD2 => F1FF =15 min before sunrise; D2 is lightdimm,
- 0F0000 => 0F00 = 15 min after sunrise; 00 = OFF
Attention: Low Byte data is in low address
One command for sunset: