The Edge firmware responds to messages to change settings and it responds to message with commands to execute specific tasks. Settings and Command messages are send on different ports. To illustrate the difference: settings messages are used to change settings and command messages are used to get the current settings.
A list of all settings that the Edge firmware support is specified in the settings.json file. The latest version of this file can be found in latest FW release on GitHub. All available settings are located under the "settings" cluster. Each setting is of the form:
"settingname": {
"id": "0x01",
"enabled": true,
"default": 0,
"min": 0,
"max": 1000000,
"length": 4,
"conversion": "uint32"
}where:
To change any setting, a custom command can be send via the Smart Parks Connect App using short range Bluetooth or using the LoRaWAN server to send Downlinks. The Smart Parks Connect App sends various commands and settings using predefined forms and buttons, so we will not further discuss this method here. We will focus here on explaining how to compose the correct payload to be send with a downlink message to the Edge units using the LoRaWAN server.
Port 3 is used for sending settings:
| id_dec | id_hex | name |
|---|---|---|
| 1 | 0x1 | lr_gps_interval |
| 2 | 0x2 | ublox_send_interval |
| 3 | 0x3 | status_send_interval |
| 4 | 0x4 | satellite_send_interval |
| 5 | 0x5 | gps_init_lon |
| 6 | 0x6 | gps_init_lat |
| 7 | 0x7 | init_time |
| 8 | 0x8 | ble_adv |
| 9 | 0x9 | lr_sat_data |
| 10 | 0xA | gps_sat_data |
| 11 | 0xB | data_log |
| 12 | 0xC | lr_send_flag |
| 13 | 0xD | flash_store_flag |
| 14 | 0xE | lr_adr |
| 15 | 0xF | lr_region |
| 16 | 0x10 | app_key |
| 17 | 0x11 | device_eui |
| 18 | 0x12 | app_eui |
| 19 | 0x13 | horizontal_accuracy |
| 20 | 0x14 | cold_fix_retry |
| 21 | 0x15 | hot_fix_retry |
| 22 | 0x16 | cold_fix_timeout |
| 23 | 0x17 | hot_fix_timeout |
| 24 | 0x18 | ble_advertisement_interval |
| 25 | 0x19 | wifi_scan_interval |
| 26 | 0x1A | wifi_scan_aggregated_interval |
| 27 | 0x1B | ble_scan_duration |
| 28 | 0x1C | ble_scan_interval |
| 29 | 0x1D | ble_scan_aggregated_interval |
| 30 | 0x1E | ble_scan_filter |
| 31 | 0x1F | ble_auto_disconnect |
| 33 | 0x21 | device_name |
| 34 | 0x22 | lr_join_flag |
| 35 | 0x23 | lr_confirm_flag |
| 36 | 0x24 | lr_max_confirm_fail |
| 37 | 0x25 | gps_backoff_factor |
| 38 | 0x26 | ublox_send_interval_2 |
| 39 | 0x27 | ublox_switch_interval |
| 40 | 0x28 | ublox_min_fix_time |
| 41 | 0x29 | ublox_multiple_intervals |
| 42 | 0x2A | device_pin |
| 43 | 0x2B | ublox_active_tracking |
| 44 | 0x2C | led_enabled |
| 45 | 0x2D | motion_ths |
| 46 | 0x2E | enable_motion_trig_gps |
| 47 | 0x2F | gps_triggered_interval |
| 48 | 0x30 | gps_skipped_triggered_interval |
| 49 | 0x31 | lr_messaging_retry_interval |
| 50 | 0x32 | lr_messaging_retry_count |
| 51 | 0x33 | ublox_leave_on |
| 52 | 0x34 | memfault_send_interval |
| 53 | 0x35 | rejoin_interval |
| 54 | 0x36 | check_error_interval |
| 55 | 0x37 | gnss_constellation_to_use |
| 56 | 0x38 | rf_scan_enabled |
| 57 | 0x39 | sat_send_flag |
| 58 | 0x3A | satellite_enabled |
| 59 | 0x3B | satellite_retry |
| 60 | 0x3C | rf_scan_interval1 |
| 61 | 0x3D | rf_scan_duration |
| 62 | 0x3E | rf_scan_config |
| 63 | 0x3F | fence_enabled |
| 64 | 0x40 | fence_interval |
| 65 | 0x41 | fence_sampling_length |
| 66 | 0x42 | fence_mv_scaling_factor |
| 67 | 0x43 | flash_status_interval |
| 68 | 0x44 | s_band_app_key |
| 69 | 0x45 | s_band_network_key |
| 70 | 0x46 | s_band_dev_adr |
| 71 | 0x47 | ble_scan_report_zero_connections_found |
| 72 | 0x48 | wifi_scan_report_zero_connections_found |
| 73 | 0x49 | cmdq_enabled |
| 74 | 0x4A | cmdq_scan_duration |
| 75 | 0x4B | cmdq_search_interval |
| 76 | 0x4C | cmdq_on_no_detection_wait_duration |
| 77 | 0x4D | cmdq_searched_mac_address |
| 78 | 0x4E | cmdq_reporting_interval |
| 79 | 0x4F | s_band_rf_frequency_hz |
| 80 | 0x50 | cmdq_report_zero_messages_to_be_sent |
| 81 | 0x51 | satellite_max_messages_per_interval |
| 82 | 0x52 | ublox_interval2_start |
| 83 | 0x53 | rf_scan_multiple_intervals |
| 84 | 0x54 | rf_scan_interval1_start |
| 85 | 0x55 | rf_scan_interval2_start |
| 86 | 0x56 | rf_scan_interval2 |
| 87 | 0x57 | lr_adr_profile |
Send downlink message to port 3 of the form:
id length [data in byte array format]where data in byte array format needs to be little-endian encoded.
For example to change the GPS interval1 to 60 minutes, the following downlink payload needs to be send to port 3:
02 04 10 0E 00 00To change the status interval1 to 30 minutes, the following downlink payload needs to be send to port 3:
03 04 08 07 00 00The following downlink messages are frequently used and will help you to better understand the format. The downlink is presented both in HEX and in BASE64 format.
0E 01 00 / DgEA0E 01 01 / DgEB0E 01 02 / DgEC0E 01 03 / DgED0E 01 04 / DgEE0E 01 05 / DgEF03 04 3C 00 00 00 / AwQ8AAAA03 04 84 03 00 00 / AwSEAwAA03 04 08 07 00 00 / AwQIBwAA03 04 10 0E 00 00 / AwQQDgAA02 04 84 03 00 00 / AgSEAwAA02 04 10 0E 00 00 / AgQQDgAA02 04 10 1c 00 00 / AgQgHAAA02 04 c0 a8 00 00 / AgTAqAAA26 04 84 03 00 00 / JgSEAwAA02 04 00 00 00 00 / AgQAAAAA16 02 C8 00 / FgLIAA==14 01 14 / FAEU17 02 2D 00 / FwItAA==15 01 04 / FQEE25 01 0E / JQEO27 01 0B / JwEL29 01 01 / KQEB13 04 32 00 00 00 / EwQyAAAA13 04 19 00 00 00 / EwQZAAAAEach message type has its own port assigned. For each message type we can control if it is send over LoRaWAN or not. This is not related to the specific interval of a feature that is producing the message. For example, if the ublox_send_interval is set to 60 seconds, the Ublox GPS proces will try to produce a port 2 (msg_ublox_location) and a port 9 (msg_ublox_satellites) message. However, the lr_send_flag setting will define if these messages are actually send over LoRaWAN.
The lr_send_flag setting has id: 0x0C and always is of length: 0x04.
Therefore the downlink always looks like this: 0c 04 <flag bytes>.
The structure of this setting is different from the other settings, therefore we will explain it here and provide the most used settings values. We can only explain this value by looking at it in binary format.
FC00066F422786007911111100000000000000011001101111Each bit in the binary format represents a port id of a specific message. However, as with all other settings values, the order is written in little-endian. This means, the order is backwards. Therefore, the last bit represents port 1. We can see this value has 28 bits, and therefore represents the state of 28 message types (28 ports). Some port numbers are currently not in use and therefore are always 0.
Presenting the binary value backwards we can more easily decode the value by hand:
11110110011000000000000000111111Without the inversion we can also use the following table:
note: computers start counting positions with the number 0.
| bit | 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 | 27 |
| value | 1 | 1 | 1 | 1 | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 1 | 0 | 1 | 1 | 1 | 1 |
| meaning | ON | ON | ON | ON | ON | ON | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | ON | ON | OFF | OFF | ON | ON | OFF | ON | ON | ON | ON |
| port | 28 | 27 | 26 | 25 | 24 | 23 | 22 | 21 | 20 | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
In most cases using the standard settings are good as the most functions are controlled with setting the actual interval. For example: if you do not set the interval of ublox_send_interval the device will not send any message on port 2.
A situation where we do want to use this is in base of BLE and WiFi scanning, where we only want to send LoRaWAN messages containing the aggregate of the scans and not the real-time scanning results. This will allow the device to save energy. For this we can turn OFF the specific ports for the real-time scan results:
FC00046F422785956711111100000000000000010001101111FC00026F422785905511111100000000000000001001101111This setting defines when a specific message type is stored in the on-board flash storage using the flash_store_flag. This setting works the same way as the lr_send_flag setting described in the section above.
The flash_store_flag setting has id: 0x0D and always is of length: 0x04.
Therefore the downlink always looks like this: 0d 04 <flag bytes>.
The structure of this setting is different from the other settings, therefore we will explain it here and provide the most used settings values. We can only explain this value by looking at it in binary format.
400066F67110511100000000000000011001101111Each bit in the binary format represents a port id of a specific message. However, as with all other settings values, the order is written in little-endian. This means, the order is backwards. Therefore, the last bit represents port 1. We can see this value has 28 bits, and therefore represents the state of 28 message types (28 ports). Some port numbers are currently not in use and therefore are always 0.
Presenting the binary value backwards we can more easily decode the value by hand:
11110110011000000000000000000001Without the inversion we can also use the following table:
note: computers start counting positions with the number 0.
| bit | 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 | 27 |
| value | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 1 | 0 | 1 | 1 | 1 | 1 |
| meaning | ON | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | ON | ON | OFF | OFF | ON | ON | OFF | ON | ON | ON | ON |
| port | 28 | 27 | 26 | 25 | 24 | 23 | 22 | 21 | 20 | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
In most cases using the standard settings are good as the most functions are controlled with setting the actual interval. For example: if you do not set the interval of ublox_send_interval the device will not store any message on port 2.
The sat_send_flag setting has id: 0x39 and always is of length: 0x04.
Therefore the downlink always looks like this: 39 04 <flag bytes>.
Each message type has its own port assigned. For each message type we can control if it is send over Iridium satellite or not. This is not related to the specific interval of a feature that is producing the message. For example, if the ublox_send_interval is set to 60 seconds, the Ublox GPS proces will try to produce a port 2 (msg_ublox_location) and a port 9 (msg_ublox_satellites) message. However, the sat_send_flag setting will define if these messages are actually send over the Iridium satellite connection.
The structure of this setting is different from the other settings, therefore we will explain it here and provide the most used settings values. We can only explain this value by looking at it in binary format.
FC00066F422786007911111100000000000000011001101111Each bit in the binary format represents a port id of a specific message. However, as with all other settings values, the order is written in little-endian. This means, the order is backwards. Therefore, the last bit represents port 1. We can see this value has 28 bits, and therefore represents the state of 28 message types (28 ports). Some port numbers are currently not in use and therefore are always 0.
Presenting the binary value backwards we can more easily decode the value by hand:
11110110011000000000000000111111note: computers start counting positions with the number 0.
| bit | 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 | 27 |
| value | 1 | 1 | 1 | 1 | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 1 | 0 | 1 | 1 | 1 | 1 |
| meaning | ON | ON | ON | ON | ON | ON | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | OFF | ON | ON | OFF | OFF | ON | ON | OFF | ON | ON | ON | ON |
| port | 28 | 27 | 26 | 25 | 24 | 23 | 22 | 21 | 20 | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
The lrd_adr_profile setting controls how the device is responding to ADR request from a LoRaWAN network server. These are following options:
0x00 → Network Server controlled for static devices0x01→ Long range distribution for mobile devices0x02 → Low power distribution for mobile devices0x03 → User defined distributionBy default the device is using 0x03. This works fine for Chirpstack and TTN deployments. For use on the KPN LoRaWAN Network (based on Actility) in the Netherlands we advice to use the 0x00 setting. This may also we needed for other Actility/Thingpark deployments. This will ensure the device does not get into a loop of ADR requests and ADR responses.
57 01 00 / VwEAA list of all settings that the Edge firmware support is specified in the settings.json file. The latest version of this file can be found in latest FW release on GitHub. All available settings are located under the "commands" cluster. Each setting is of the form:
"cmd_name": {
"id": "0xA1",
"length": 1,
"conversion": "uint8",
"value": 0
}where:
To change any setting, a custom command can be send via the Smart Parks Connect App using short range Bluetooth or using the LoRaWAN server to send Downlinks. The Smart Parks Connect App sends various commands and settings using predefined forms and buttons, so we will not further discuss this method here. We will focus here on explaining how to compose the correct payload to be send with a downlink message to the Edge units using the LoRaWAN server.
Port 32 is used for sending commands.
Send command in the following form to port 32:
id length [value in byte array format]Keep in mind that additional value is always litlle-endian encoded. If command length is 0, no additional value needs to be send, hence:
id 0For example to execute a command to get the current GPS interval1 setting, the following downlink payload needs to be send to port 32:
A8 01 02The following downlink messages are frequently used and will help you to better understand the format. The downlink is presented both in HEX and in BASE64 format.
A1 00 / oQA=A6 00 / pgA=B9 00 / uQA=B8 00 / uAA=Currently the GPS position is only returned to the BLE channel, meaning the App. A future firmware update will ensure the position is also returned to all selected communication channels.
A5 00 / pQA=It could look something like:
function decodeReturnCommand(bytes) {
if (bytes[0] == 0xfe) {
var value = bytes[5] << 24 | bytes[4] << 16 | bytes[3] << 8 | bytes[2];
var latitude = value / 10000000; // gps latitude,units: °
value = bytes[9] << 24 | bytes[8] << 16 | bytes[7] << 8 | bytes[6];
var longitude = value / 10000000; // gps longitude,units: °
value = bytes[13] << 24 | bytes[12] << 16 | bytes[11] << 8 | bytes[10];
var altitude = value / 1000;
var fix_time = bytes[17] << 24 | bytes[16] << 16 | bytes[15] << 8 | bytes[14];
var decoded = {
latitude: latitude,
longitude: longitude,
altitude: altitude,
fix_time: fix_time,
};
};
return decoded;
}
And adding this to the bottom:
else if (fPort == 31) {
decoded = decodeReturnCommand(bytes);
} BC 0C [port_nr encoded as 4 bytes array] [start msg nr. (from head) - 4 bytes] [nr. of messages - 4 bytes]Get ALL messages on specific port → BB 01 <PORT ID>
BB 01 02 / uwECBB 01 04 / uwEEBB 01 0D / uwENBB 01 0F / uwEPUblox GPS positions:
BC 0C 02 00 00 00 00 00 00 00 64 00 00 00 / vAwCAAAAAAAAAGQAAAA=BC 0C 0D 00 00 00 00 00 00 00 03 E8 00 00 / vAwNAAAAAAAAAAPoAAA=BC 0C 0D 00 00 00 00 00 00 00 05 DC 00 00 / vAwNAAAAAAAAAAXcAAA=BC 0C 0D 00 00 00 00 00 00 00 07 D0 00 00 / vAwNAAAAAAAAAAfQAAA=BLE Scan:
BC 0C 0B 00 00 00 00 00 00 00 64 00 00 00 / vAwLAAAAAAAAAGQAAAA=BC 0C 0B 00 00 00 00 00 00 00 03 E8 00 00 / vAwLAAAAAAAAAAPoAAA=CMDQ:
BC 0C 0F 00 00 00 00 00 00 00 64 00 00 00 / vAwPAAAAAAAAAGQAAAA=BC 0C 0F 00 00 00 00 00 00 00 03 E8 00 00 / vAwPAAAAAAAAAAPoAAA=BA 00 / ugA=A7 00 / pwA=A8 01 <setting_id>A8 01 01 / qAEBA8 01 02 /A8 01 03 /A8 01 04 /A8 01 05 /A8 01 06 /A8 01 07 /A8 01 08 /A8 01 09 /A8 01 0A /A8 01 0B /A8 01 0C /A8 01 0D /A8 01 0E /A8 01 0F /A8 01 10 /A8 01 11 /A8 01 12 /A8 01 13 /A8 01 14 /A8 01 15 /A8 01 16 /A8 01 17 /A8 01 18 /A8 01 19 /A8 01 1A /A8 01 1B /A8 01 1C /A8 01 1D /A8 01 1E /A8 01 1F /A8 01 21 /A8 01 22 /A8 01 23 /A8 01 24 /A8 01 25 /A8 01 26 /A8 01 27 /A8 01 28 /A8 01 29 /A8 01 2A /A8 01 2B /A8 01 2C /A8 01 2D /A8 01 2E /A8 01 2F /A8 01 30 /A8 01 31 /A8 01 32 /A8 01 33 /A8 01 34 /A8 01 35 /A8 01 36 /A8 01 37 /New settings are added with the release of new features. This means the list is longer / different for new firmware features. It is adviced always to check the latest settings.json file for a particular firmware version.