Payload WSSFC-ULA | Firmware 2
1. Payload document is applied for the following products
| Item code | HW Version | Firmware Version | Remarks |
| WSSFC-ULA-01 | 2 | 2 | |
2. Changes information in this version v.s previous version
| Item | Changes | Changed by | Changed Date | Approved by | Approved Date |
| 1 | Initial version | D.Q.Tuan | 01-08-2022 | N.V.Loc | 24-08-2022 |
The approved date is also the release date of this document.
3. Payload for Uplink messages
START_UP message
| When? | Purpose | Wait for Downlink? | LED color |
| This message will be sent once after 60 seconds from power-up the device | To understand when was the device powered up | NO |
Blink WHITE |
| Payload | EVENT_ID | HW_VERSION | FW_VERSION | LATEST_SIGFOX_DOWNLINK |
| bits | 4 | 4 | 8 | 64 |
| value | 0b0000 = 0 | yes | yes | yes |
HEART_BEAT message
| When? | Purpose | Wait for Downlink? | LED color |
| This message will be sent in the pre-defined cycle, default is 24 hours | To check the health status, get the current configuration, and send the new configuration to the device via downlink | YES |
Blink GREEN |
| Payload | EVENT_ID | HW_VERSION | FW_VERSION | LATEST_SIGFOX_DOWNLINK |
| bits | 4 | 4 | 8 | 64 |
| value | 0b0001 = 1 | yes | yes | yes |
PARAMETER_UPDATE message
| When? | Purpose | Wait for Downlink? | LED color |
|
When the reed switch is activated by the magnet key. How? Move Magnet Key to the contact point of REED SWITCH. |
To send the new configuration to the device via downlink | YES |
Blink PURPLE |
| Payload | EVENT_ID | HW_VERSION | FW_VERSION | LATEST_SIGFOX_DOWNLINK |
| bits | 4 | 4 | 8 | 64 |
| value | 0b0010 = 2 | yes | yes | yes |
FORCE_DATA message
| When? | Purpose | Wait for Downlink? | LED color |
|
When the reed switch is activated by the magnet key. How? Move Magnet Key to the contact point of REED SWITCH.Led blink SKY BLUE, move Magnet Key away. |
To get the instant measured value from the device for calibration and validation. | NO |
Blink SKY BLUE |
| Payload | EVENT_ID | HW_ERROR | reserved | ALARM | BATTERY_LEVEL | reserved | LEVEL_THOUSANDTHS | LEVEL_MM |
| bits | 4 | 1 | 3 | 2 | 2 | 4 | 16 | 16 |
| value | 0b0011 = 3 | yes | zeros | yes | yes | zeros | yes | yes |
CYCLIC_DATA message
| When? | Purpose | Wait for Downlink? | LED color |
| This message will be sent in the pre-defined cycle. | To get the measured value from the device in the pre-defined cycle. | NO |
Blink SKY BLUE |
| Payload | EVENT_ID | HW_ERROR | reserved | ALARM | BATTERY_LEVEL | reserved | LEVEL_THOUSANDTHS | LEVEL_MM | Tentative |
| bits | 4 | 1 | 3 | 2 | 2 | 4 | 16 | 16 | 8 |
| value | 0b0100 = 4 | yes | zeros | yes | yes | zeros | yes | yes | yes |
ALARM message
| When? | Purpose | Wait for Downlink? | LED color |
| This message will be sent upon the alarm occurs. Sensor_sampling_rate will determine the processing delay of the alarm. | To get the instant measured value upon the measured value was passing a threshold. | NO |
Blink RED |
| Payload | EVENT_ID | HW_ERROR | reserved | ALARM | BATTERY_LEVEL | reserved | LEVEL_THOUSANDTHS | LEVEL_MM | Tentative |
| bits | 4 | 1 | 3 | 2 | 2 | 4 | 16 | 16 | 8 |
| value | 0b0101 = 5 | yes | zeros | yes | yes | zeros | yes | yes | yes |
4. Payload Fields of Uplink
Below is explanation about the payload fields in the uplink messages.
|
Data name |
Description |
Encoding or Possible values |
Length (in bits) |
|
EVENT_ID |
Unique ID identifying the device event |
4-bit unsigned integer 0 = START_UP 1 = HEARTBEAT 2 = PARAMETERS_UPDATE 3 = FORCE_DATA 4 = CYCLIC_DATA 5 = ALARM |
4 |
|
HW_VERSION |
Indicate HW version |
4-bit unsigned integer 1..15 |
4 |
|
FW_VERSION |
Indicate FW version |
8-bit unsigned integer 1..255 |
8 |
|
LATEST_SIGFOX_DOWNLINK |
Latest received and valid sigfox downlink frame = Current configuration |
64-bit encoded field See Sigfox Downlink tab |
64 |
|
HW_ERROR |
HW error |
0b0 = no error 0b1 = error |
1 |
|
ALARM |
Alarm |
0b00 = no alarm 0b01 = low alarm 0b10 = high alarm 0b11 = not used |
2 |
|
BATTERY_LEVEL |
Battery level |
2-bit unsigned integer 0 to 3 0: 10% 1: 30% 2: 60% 3: 99% |
2 |
| LEVEL_PPT |
|
16-bit unsigned integer Level value in part per thousand (scaled, used for alarm) |
16 |
|
DISTANCE_MM |
|
16-bit unsigned integer Distance value in mm |
16 |
|
TENTATIVE |
Tentative number |
8-bit unsigned integer Formula: (8-bit_Tentative +1)= real_tentative # Range: 1 to 256 Accuracy: 1 Example: 0b00000111 = 0x7=7=> 7+1 =>tentative # 8 |
8 |
5. Payload for Downlink messages
Users can use a downlink message to change the configuration of the device. There are 02 types of downlink messages:
- Downlink type = 0: to write the configuration for the specific type of Sigfox-ready sensor. The format is fixed for each type of sensor.
- Downlink type = 5: to write a value to any address of configuration parameter of any Sigfox-ready sensor. This method is generic and can be applied to any type of Sigfox-ready sensor, the user just needs to know the memory map of the sensor.
5.1 Downlink type = 0
|
Payload |
HIGH_ALARM_SETPOINT |
LOW_ALARM_SETPOINT_FACTOR |
ALARM_ENABLE |
ALARM_PERIOD |
LED_BUZZER_ENABLE |
HEARTBEAT_PERIOD |
MEASURE_PERIOD |
TX_REPEAT |
CYCLIC_DATA_PERIOD |
DEVICE_RESET |
DOWNLINK_TYPE |
|
bits |
32 |
8 |
1 |
3 |
1 |
3 |
4 |
1 |
3 |
4 |
4 |
|
Value |
yes |
yes |
yes |
yes |
yes |
yes |
yes |
yes |
yes |
yes |
0b0000 = 0 |
Below is the table to explain in detail the meaning of each configuration parameter and its default value.
|
Parameter |
Description |
Possible values |
Default value |
Length (in bits) |
|
HIGH_ALARM_SETPOINT |
High alarm setpoint for calculated value |
32-bit float value |
1000000000 |
32 |
|
LOW_ALARM_SETPOINT_FACTOR |
Low alarm setpoint for calculated value |
8-bit unsigned integer LOW_ALARM_SETPOINT = HIGH_ALARM_SETPOINT * LOW_ALARM_SETPOINT_FACTOR / 200 |
0 |
8 |
|
ALARM_ENABLE |
Enable/Disable ALARM event |
0b0 = ALARM event is OFF 0b1 = ALARM event is ON |
0b0 = ALARM event is OFF |
1 |
|
ALARM_PERIOD |
Period of time to send ALARM event |
0b000 = every 10min 0b001 = every 30min 0b010 = every 1h 0b011 = every 2h 0b100 = every 3h 0b101 = every 6h 0b110 = every 12h 0b111 = every 24h |
0b000 = every 10min |
3 |
|
LED_BUZZER_ENABLE |
Enable/Disable LEDs and Buzzers interactions for action not triggered by the reed switch |
0b0 = LEDs and Buzzers are OFF 0b1 = LEDs and Buzzers are ON |
0b1 = LEDs and Buzzers are ON |
1 |
|
HEARTBEAT_PERIOD |
Period of time to send HEARTBEAT event |
0b000 = every 1h 0b001 = every 6h 0b010 = every 12h 0b011 = every 24h (1 day) 0b100 = every 48h (2 days) 0b101 = every 72h (3 days) 0b110 = every 120h (5 days) 0b111 = every 240h (10 days) |
0b011 = every 24h (1 day) |
3 |
|
MEASURE_PERIOD |
Period of time to measure sensor |
0b0000 = every 1s 0b0001 = every 2s 0b0010 = every 5s 0b0011 = every 10s 0b0100 = every 20s 0b0101 = every 30s 0b0110 = every 1min 0b0111 = every 2min 0b1000 = every 5min 0b1001 = every 10min 0b1010 = every 20min 0b1011 = every 30min 0b1100 = every 1h 0b1101 = every 2h 0b1110 = every 3h 0b1111 = every 6h |
0b1011 = every 30min |
4 |
|
TX_REPEAT |
Sigfox TX repeat |
0b0 = Send RF 1 time 0b1 = Send RF 3 time |
0b1 = Send RF 3 time |
1 |
|
CYCLIC_DATA_PERIOD |
Period of time to send CYCLIC_DATA event |
0b000 = every 10min 0b001 = every 30min 0b010 = every 1h 0b011 = every 2h 0b100 = every 3h 0b101 = every 6h 0b110 = every 12h 0b111 = every 24h |
0b001 = every 30min |
3 |
|
DEVICE_RESET |
Once this parameter is set, the device shall restart once after having received the Downlink. |
0b1010 = 0xA = force device reset others = do nothing |
0b0000 = do nothing |
4 |
|
DOWNLINK_TYPE |
Downlink type |
4-bit unsigned integer See Sigfox Downlink tab |
0b0000 |
4 |
EXAMPLE FOR DOWNLINK TYPE = 0
If you plan to change the MEASURE_PERIOD = 30 minutes and CYCLIC_DATA_PERIOD = 1 hr then please enter your desired values, guided by the table below:
|
Parameter |
Setting value (in decimal) |
Setting Value (in binary) |
Length (in bits) |
|
HIGH_ALARM_SETPOINT |
1000000000 |
01001110011011100110101100101000 |
32 |
|
LOW_ALARM_SETPOINT_FACTOR |
0 |
00000000 |
8 |
|
ALARM_ENABLE |
|
0 |
1 |
|
ALARM_PERIOD |
|
000 |
3 |
|
LED_BUZZER_ENABLE |
|
1 |
1 |
|
HEARTBEAT_PERIOD |
|
011 |
3 |
|
MEASURE_PERIOD |
|
1011 |
4 |
|
TX_REPEAT |
|
1 |
1 |
|
CYCLIC_DATA_PERIOD |
010 |
3 |
|
|
DEVICE_RESET |
|
0000 |
4 |
|
DOWNLINK_TYPE |
|
0000 |
4 |
Then you will get the final configuration code as below:
0100 1110 0110 1110 0110 1011 0010 1000 0000 0000 0000 1011 1011 1010 0000 0000 = 4E6E6B28000BBA00
5.2 Downlink type = 5
With this downlink, the user can write the configuration to any address on the memory map of the device. Please refer to the memory map of the device to understand what parameters can be written.
The length of the configuration parameter can be 1, 2 bytes, or 4 bytes, but the total length of the Downlink payload must equal 64 bits (8 bytes). Please see below the downlink format for both types.
Downlink type 5 for the parameter of 2 bytes length:
|
Payload |
PRM_ADDRESS |
PRM_LENGTH |
PRM_VALUE |
reserved |
DOWNLINK_TYPE |
|
bits |
8 |
8 |
16 |
28 |
4 |
|
Value |
yes |
0x02 = 2 |
yes |
zeros |
0b0101 = 5 |
Downlink type 5 for the parameter of 4 bytes length:
|
Payload |
PRM_ADDRESS |
PRM_LENGTH |
PRM_VALUE |
reserved |
DOWNLINK_TYPE |
|
bits |
8 |
8 |
32 |
12 |
4 |
|
Value |
yes |
0x04 = 4 |
yes |
zeros |
0b0101 = 5 |
Where:
- PRM_ADDRESS: address of the configuration parameter in the memory map of the device;
- PRM_LENGTH: is the length of that parameter, in bytes;
- PRM_VALUE: is the value the user wants to write to that parameter;
- reserved: a series of bits of zero to fulfill the downlink so that it has the total length = 64 bits (8 bytes)
EXAMPLE FOR DOWNLINK TYPE = 5
Here is the list of parameters of WSSFC-ULA that can be configured via Downlink type = 5 and the examples of the downlink payload on the right-most side column. It is the example value, not the default value of the device. Please check the memory map of the device for more detail about the parameters.
Note: the total length of the downlink must be equal to 8 bytes
|
PARAMETER |
DATA TYPE OF PARAMETER |
PRM_ADDRESS |
PRM_LENGTH |
PRM_VALUE |
DOWNLINK_TYPE |
PAYLOAD OF DOWNLINK (IN HEXA) |
|
(bytes) |
|
1 |
1 |
4 |
2 |
8 |
|
CONSTANT_A |
Float |
0x16 |
0x04 = 4 |
0x3F8CCCCD = 1.1 |
0x0005 |
16043F8CCCCD0005 |
|
CONSTANT_B |
Float |
0x18 |
0x04 = 4 |
0x3E4CCCCD = 0.2 |
0x0005 |
18043E4CCCCD0005 |
|
HIGH_CUT |
Float |
0x1A |
0x04 = 4 |
0x447A0000 = 1000 |
0x0005 |
1A04447A00000005 |
|
LOW_CUT |
Float |
0x1C |
0x04 = 4 |
0x00000000 = 0 |
0x0005 |
1C04000000000005 |
|
SENSOR_BOOT_TIME |
Uint32 |
0x1E |
0x04 = 4 |
0x000000C8 = 200 |
0x0005 |
1E04000000C80005 |
| NUMBER OF SAMPLES |
Uint16 |
0x32 |
0x04 = 2 |
0x000A0000 = 10 |
0x0005 |
3202000A00000005 |
5.3 Free online data conversion tools
- To convert from Float to Hex and vice versa, users may use this free online tool: https://gregstoll.com/~gregstoll/floattohex/
- To convert a decimal number to Hex, the user may use this free online tool: https://www.binaryhexconverter.com/decimal-to-hex-converter
6. Reed switches
The Sigfox-ready sensor normally comes with at least one reed switch for user manipulation during commissioning or maintenance.
Some other versions come with 02 reed switches.
The WSSFC-ULA comes with one reed switch; please find below the functions of this switch.
|
EVENT |
PRE-CONDITION |
ACTION |
LED STATUS |
ACTIVITIES |
POST-CONDITION |
|
FORCE_DATA |
Any state |
Move Magnet Key to the contact point of REED SWITCH. Led blink SKY BLUE, move Magnet Key away. |
Blink SKY BLUE |
the device will send the uplink message FORCE_DATA |
Back to the previous state |
|
PARAMETERS_UPDATE |
Any state |
Move Magnet Key to the contact point of REED SWITCH. Led blink SKY BLUE, hold Magnet Key 5s. Led blink PURPLE, move Magnet Key away. |
Blink PURPLE |
the device will send the uplink message PARAMETER_UPDATE and wait for a new downlink to get the new configuration |
Back to the previous state |
No Comments