User commands instructions

Instructions on how to send commands to EdgeTracker from app or via LoRaWAN communication.

Settings

List of settings, tracker supports, is specified in settings.json file, that can be found in latest FW release on GitHub. All available settings are located under "settings" cluster. Each setting is of the form: 

"settingname": {
            "id": "0x01",
            "enabled": true,
            "default": 0,
            "min": 0,
            "max": 1000000,
            "length": 4,
            "conversion": "uint32"
        }

where:

  • id - unique identifier

  • length - length in bytes

  • conversion - setting variable type

To change any setting, a custom command can be send via BT app or using LoRa communication.

Port 3 is used for commands handling.

Change settings via LoRa

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.

To set the above "settingname" example setting to value 1000, first convert 1000 to byte array: E8 03 00 00 and replace id with 01 and length with 04:

01 04 E8 03 00 00

Change settings via BT app

Use "Custom command" field to set settings that are not supported in the user interface. The main change when using the app for sending commands is that port needs to be specified as first value.

App supports commands in hex format with "0x" preamble or in decimal format. The above setting can be send either as:

0x03 0x01 0x04 0xE8 0x03 0x00 0x00

or as

3 1 4 232 3 0 0

Spaces need to be added!

Commands

Various commands are avaliable for user to interact with tracker. All commands are defined in settings.json file under "commands" cluster. Each command is of the form:

"cmd_name": {
          "id": "0xA1",
          "length": 1,
          "conversion": "uint8",
          "value": 0
        }

where:

  • id - unique command identifyer

  • length - length of additional data send in command

  • conversion - conversion of additional data send in command

Commands are send in similar way to settings via BT app or using LoRa communication.

Port 32 is used for sending commands.

Send command via LoRa

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 0

For example to send "cmd_name" test command with value 3, the following string is send to port 32:

A1 01 03

Send command via BT app

Same format as defined above is used. Again port needs to be added as first value in the array. The above command can be send in either of the formats:

0x20 0xA1 0x01 0x03

or

32 161 1 3

List of commands and their format

The following commands are supported at the moment. All need to be send to port 32. Below message formats for using LoRa communication are given. To adjust message format, follow the instructions above.

A1 - cmd_reset

Reboot tracker.

A1 00

A2 - cmd_send_all_val

Tracker will return all values, in stacked format, as described in the following command. Not recomended to use via LR, due to payload size limitations.

A2 00

A3 - cmd_send_single_val

Obtain value of a single value field, specified by its id. List of all values can be found in settings.json file under "values" cluster

A3 01 value_id

For example, to get value with id D1 send:

A3 01 D1

Tracker will respond on port 30 in the format:

value_id value_length [value in byte array format]

A4 - cmd_send_status

Status message will be send via LoRa/BT communication to status port 4. For status message structure, see TTN parser: ttn_decoder.js, addeed to lates release on GitHub or next chapter. 

A4 00

A5 - cmd_send_position

Obtain tracker latest GPS position (lat lon, alt). Send command:

A5 00

Tracker will respond with "msg_last_position" on port 31. For definition see next chapter.

A6 - cmd_reset_gps

Reboot Ublox GPS module.

A6 00

A7 - cmd_send_all_settings

Tracker will return all settings, in stacked format, as described in the following command. Not recommended to use via LR, due to payload size limitations.

A7 00

A8 - cmd_send_single_setting

Obtain value of a single setting field, specified by its id.

A8 01 setting_id

For example, to get "cmd_name" send:

A8 01 01

Tracker will respond on port 3 in the format:

setting_id setting_length [setting value in byte array format]

A9 - cmd_reset_initial_position

Reset initial reference position of the tracker to hardcoded position. (not recommended to use)

A9 00

AA - cmd_reset_initial_time

Reset initial reference time to hardcoded value. (not recommended to use)

AA 00

AB - cmd_clear_nvs

Clear internal storage. All set values are going to be deleted and set to default. Keep in mind that LR keys are going to be deleted as well!

AB 00

AC - cmd_reset_to_def_settings

Revert all setting to defoult values. Keep in mind that LR keys are going to be deleted as well!

AC 00

AD - cmd_send_status_lr

Status message will be send via LoRa communication to status port 4. For status message structure, see TTN parser: ttn_decoder.js, addeed to lates release on GitHub or next chapter. 

AD 00

AE - cmd_send_lr_fix

Obtain LR GNSS message and send it via LoRa communication.

AE 00

AF - cmd_set_location_and_time

Set reference location and time of the tracker. 

AF 0C [lon*10^7 int32 byte array] [lat*10^7 int32 byte array] [unix timestamp uint32 byte array]

B0 - cmd_get_rf_scan

Get rf scan - not supported at the moment!

B1 - cmd_get_wifi_scan

Get aggregated data in wifi scan. Tracker will response with "msg_wifi_scan_aggregated" (see next chapter).

B1 00

B2 - cmd_get_ble_scan

Get aggregated data of BT scan. Tracker will response with "msg_ble_scan_aggregated" (see next chapter).

B2 00

B3 - cmd_get_almanac_age

Get almanac age - not supported at the moment!

B4 - cmd_get_lr_satellite_data

Perform LR GPS scanning and return both GNSS message as well as satellite data message, used in the fix. See next chapter for message definitions. 

B4 00

B5 - cmd_get_ublox_satellite_data

Perform Ublox position fix and return both position message, as well as satellite data message, used in the fix. See next chapter for message definitions. 

B5 00

B6 - cmd_almanac_update

Not yet supported

B7 - cmd_get_mac

Get BT MAC addres from the device.

B7 00

Device responds with "msg_mac_id" (see next chapter).

B8 - cmd_get_ublox_fix

Perform Ublox position fix and returnposition message.

B8 00

B9 - cmd_reset_lr

Reset LR module.

B9 00

BA - cmd_flash_clear

Clear all data from external flash.

BA 00

BB - cmd_flash_get_all

Get all messages stored on specific port. Use port=0 to get messages from all ports. 

BB 01 port_nr

Tracker will start to return all available messages from head to tail on port 29 via BT/LoRa. When all messages are send, confirmation message, "msg_cmd_confirm", will be received.

BC - cmd_flash_get_from_head

Read specific number of messages, starting from specified message on defined port.

BC 0C [port_nr encoded as 4 bytes array] [start msg  nr. (from head) - 4 bytes] [nr. of messages - 4 bytes]

To read 10 messages on port 4, starting from 50th message, send:

BC 0C 04 00 00 00 32 00 00 00 0A 00 00 00

Tracker will start to return all available messages from head to tail on port 29 via BT/LoRa. When all messages are send, confirmation message, "msg_cmd_confirm", will be received.

C4 - cmd_send_lr_message

Send message to device to be send via LR. 

C4 data_len data[data_len]

Up to 45 bytes are supported.

Message formats

Tracker send various message types via LoRa/BT communication and/or store them to flash. All message types are defined in settings.json fil, under cluster "messages".

Each is of the form:

"msg_name": {
            "port": "port_lr_gps",
            "id": "0xF1",
            "length": 250,
            "conversion": "byte_array"
        },

where:

  • port - specified port on which message is send. Port names are defined in settings.json file, under the cluster "ports"

  • id - msg id

  • length - max length of the message

All messages are following same basic format:

msg_id msg_len [msg specific data byte array]

If message is send via BT, port is added as first byte:

msg_port msg_id msg_len [msg specific data byte array]

Total received message length is tehrefore 2 + length on LoRa communication and 3 + length on BT, due to added port before other values.

F1 - msg_gnss

Send on port 1. GNSS data message. See ttn-decoder for format.

F2 - msg_ublox_location

Send on port 2. Message containing Ublox GPS fix and additional fix data. See ttn-decoder for format.

F3 - msg_cmd_confirm

Confirmation message, send on defoult message port 31. This message is returned after any command that does not evoke any other message send or has failed. Format:

F3 02 cmd_id success/fail

F4 - msg_status

Status message, send on port 4. See ttn-decoder for format.

F5 - msg_lr_satellites

Message, containing satellite data, used in GNSS LR position fix. Send on port 5. See ttn-decoder for format.

F6 - msg_ublox_satellites

Message, containing satellite data, used in Ublox position fix. Send on port 9. See ttn-decoder for format.

F7 - msg_wifi_scan_aggregated

Message containing top-3 scanned wifi results. Send on port 6. See ttn-decoder for format.

F8 - msg_wifi_scan

Message containing scanned wifi results from single scan. Send on port 10. See ttn-decoder for format.

F9 - msg_ble_scan_aggregated

Message containing top-3 scanned BT results. Send on port 7. See ttn-decoder for format.

FA - msg_bt_scan

Message containing all results from single BT scan. Send on port 11. See ttn-decoder for format.

FB - msg_rf_scan

Not supported.

FC - almanac_age

Almanac age of the format:

FC 04 [almanac age, uint32 as 4 bytes]

FD - msg_mac_id

Message contating MAC id of the form:

FD 06 [MAC - 6 bytes]

FE - msg_last_position

Message containing last obtained position in the form:

FE 0C [lon*10^7 int32 byte array] [lat*10^7 int32 byte array] [alt*10^4 uint32 byte array]

FF - msg_read_flash

Message format for sending flash logs to port 29. See ttn-decoder for format.

PreviousTTN v3 instructions

Last updated