Operation manual

Functionality description of OpenCollar Edge trackers.

Turn ON / reboot

Upon providing power or rebooting Edge tracker, all subsystems will be initialised. Tracker will indicate turning on by fast blinking LED light 5-times. Tracker operation consist of several subsystems:

• BT communication

• BT scan

• LoRaWAN communication

• LR GPS module

• WiFi scan

• External flash

• GPS module

• Sensors

• Battery and charging

Functionality and predicted operation of each sub-sytem will be described in following sub-sections.

LED light

Visual LED light is added to most of the Edge trackers, RhinoPucks and RhinoCubes beeing an exception.

For HW versions < 1.4 of the RangerEdge boards (RangerEdge tracker, ElephantEdge tracker and WisentEdge tracker), only RED LED is present on the board. On the HW 1.4 RGB LED is available. Below are described visual aids for the tracker. In the case of HW <1.4 all colors are RED.

• Upon turning it on tracker blinks once with all three colors in the order RED-GREEN-BLUE

• When initialization process is completed, tracker will blink RED twice

• When connected via BT app, tracker is going to blink 5x BLUE

• When lora message is sent, tracker will blink 1x GREEN

• When magnet is either set or removed, tracker will blink 10x GREEN

• When tracker is charging, RED led will blink constantly

• When tracker is charging and battery gets full, GREEN led will turn on

BT communication

Upon turning on, device will initiate BT communication and BT advertising. BT communication will be active, unless BT module or whole device will go into the hibernation mode due to critical battery. More on power modes operation can be found in the section (Operation modes).

BT advertisement

By default BT advertisement is enabled. To disable, set setting "ble_adv" with id 0x08 to false. Interval of advertisement is governed by "ble_advertisement_interval" setting with id 0x18, with default value of 500 ms.

Device will advertise status in the following format:

• Type: manufacturer data (0xFF) of length 16 bytes:

  • byte 0-1: BT manufacturer data 0X0A61

  • byte 2-15: status message (see section ...)

• Type: data flags (0X01) of length 1

• Type: device name (0X09) of length 8 bytes

  • Device name consist of "SP" and last 3 MAC address bytes, all in ascii format.

BT security

Device can be protected with password that it set by "device_pin" setting with id 0x2A. It must be 4 bytes long. Only digits 0-9 are supported. If pin is set to: 0000 - default setting, pin is disabled. User can observe in the app if device is protected with pin, by looking for lock-key symbol, next to the device name.

Tracker needs to obtain pin 5 seconds after BT connection is established, otherwise it will disconnect. If pin is forgotten or unknown, user can unlock the device with 16 bytes long AppKey.

BT communication

User can communicate with the device via BT app. Se app manual on more information how to use the app.

pageMobile Application

If communication port is not active for more than a time period defined by setting "ble_auto_disconnect" with id 0X1F and default setting of 10 minutes, device will automatically disconnect to prevent battery drainage.

BT scan

Besides offering BT communication, device can perform BT scan to detect other BT devices, other Edge trackers in particular.

BT scan is governed by the following settings:

• "ble_scan_interval" with id 0x1C: period in seconds on which BT scan is performed - can be sett in the App. Depending on set flags for send to LoRa or store to flash, real time scan message can be send to LoRa or store to flash.

• "ble_scan_aggregated_interval" with id 0X1D: period in seconds on which aggregated BT scan data is send via LR/stored to flash - can be sett in the App. Depending on set flags for send to LoRa or store to flash, real time scan message can be send to LoRa or store to flash.

• "ble_scan_duration" with id 0X1B: single scan duration in ms. Keep in mind it needs to be as least as long as advertisement period, to catch other devices signal.

• "ble_scan_filter" with id 0X1E: filtering of scanned BT data can be implemented, before data is stored to flash or send via LR. In particular, the following values of this setting are applicable:

  • 0 - no filter is implemented

  • 1 - filter OpenCollar devices

  • 2 - filter smartphones

To disable BT scan, set both "ble_scan_interval" and "ble_scan_send_interval" to 0.

BT scan data

Single scan results in data of the format: "msg_ble_scan" with id: 0XFA. Data is stored to flash and/or send via LoRaWAN, based on store and send flags. More on messages structure and send/store flags can be found under Messages section.

BT aggregated scan data

Each individual scan result is added to aggregated data structure of the format: "msg_ble_scan_aggregated" with id: 0XF9. On specified interval, message is stored to flash and/or send via LoRaWAN, based on store and send flags. More on messages structure and send/store flags can be found under Messages section.

LoRa communication

Upon turning on the device of reboot, LR module will initialise. Modem-E FW is used on the lr1110 module. LR communication is active in all operation modes besides hibernation (more in Operation modes section).

Operation parameters

The following settings control LR operation:

• "lr_adr" with id 0X0E - set ADR profile. For correct setting refer to lora communication protocol manuals.

• "lr_region" with id 0X0F - set (1 - EU, 3 - US, look at lora communication protocol manuals for other values).

• "app_key" with id 0X10 - 16 bytes app key, set during the provisioning procedure or later on in app or via user command.

• "device_eui" with id 0X11 - 8 bytes device eui, read from lr1110 module on init.

• "app_eui" with id 0X12 - 8 bytes app eui, set during the provisioning procedure or later on in app or via user command.

• "lr_join_flag" with id 0X22 - uint32 value, where each bit represents flag for respective lora send port. If bit is set to 1, LR module will initiate join procedure when message is send to that port if device is not already joined. If set to 0, device will not attempt to join when sending on particular port.

• "lr_confirm_flag" with id 0X23 - uint32 value, where each bit represents flag for respective lora send port. If bit is set to 1, LR module will send message as confirmed. If set to 0, device will send unconfirmed message. NOT active in latest FW version (1.6)!

• "lr_max_confirm_fail" with id 0X24 - uint16 value, representing max nr. of times we device can send confirmed message without getting response, before re-initing LR module and re-attempting join process. NOT active in latest FW version (1.6)!

Join procedure

Upon successful initialisation of lr1110 module, join procedure will start at first attempt to send message or when sending messages the port with active lr_join_flag (see definition above), provided module is not joined yet. By default settings, only sending status message to port 4 will start joining procedure:

1. If lr module is successfully initialised and FW attempts to send LoRa message, module will check if joined. If not joining sequence will start.

2. If EU region is set, a single join attempt per sent message will be initiated.

3. Due to differences in supported channels, lr module will attempt to join on a randomly selected channel in the case of the selected US region. Therefore 10 automatic re-tries are enabled for US region, attempting to join on the correct channel. More on the joining procedure in the US band can be found here.

Defined by lr_confirm_flag, messages to some ports are send as "confirmed" - waiting for the server response. If message is sent as "confirmed", counter will count all attempts, where confirmation was not received. If counter reaches lr_max_confirm_fail, re-join procedure will start. NOT active in latest FW version (1.6)!

Sending and receiving messages

"lr_send_flag" with id 0X0C - uint32 value, where each bit represents flag for respective lora send port. If bit is set to 1, LR module will send generated message via LoRa. If set to 0, device will not send message. More about message and port specifications can be found in Messages subsection.

Each time message is send, lr module will wit for downlink messages and parse them. To learn more about device communication and user commands, refer to User commands instructions.

Message length

Maximum message length is defined by the ADR profile setting and chosen region. To see different ADR options refer to maximum data rate guide. In particular, for the EU region ADR setting 0 - 2 corresponds to maximum payload length of 51 bytes, while in the US region ADR setting 0 gives maximum payload of 11 bytes, ADR setting 1 corresponds to 53 bytes and ADR 2 to 125 bytes.

Standard procedure for changing ADR setting can be used, as described in the User commands instructions.

Region

Set region affect several region-based settings and operational differences. Difference in join procedure is described in the Join procedure section, while differences in max payload length are outlined in the Message length section. For all regional differences refer to guide.

To change region, set different value to the "lr_region" setting with id 0X0F - set (1 for EU and 3 for US). Keep in mind lr module needs to be rebooted, before new region will be set! To reboot lr module use "cmd_reset_lr" (send B9 00 to port 32).

LR1110 GPS

LR1110 module supports GPS acquisition. Interval defining period when position data is obtained is governed by "lr_send_interval" with id 0X01. When set to 0, GPS feature is disabled.

On each pre-defined "lr_send_interval" or when sending command "cmd_send_lr_fix" with id 0XAE, device will perform assisted GNSS scan, using latest obtained position and time, either provided by successful Ublox GPS fix or user input. To enable optimal LR GPS operation, provide latest device position and time via app when first starting to use it on a new location.

After gnss scan is performed, NAV message, containing scan status and position data will be send via LoRa to server to be resolved. More on the message structure can be found in subsection LR GPS Messages.

If error code 0X07 is returned, device did not find any satellite during GNSS scan. Error code 0X08 indicates Almanac is to old.

Almanac update

To successfully perform assisted GNSS scan, recent enough Almanac data needs to be provided. The almanac data is valid for up to 90 days. Latest Almanac age can be obtained with command get value, requesting value with id 0XEC. Almanac age is represented as uint16 value, nr. of days since last GPS 0 time i.e. since 7th April 2019.

If GNSS scan results in error 0X08, Almanac needs to be updated.

Due to its length, full Almanac needs to be updated in several chunks. Total Almanac consists of 20 Bytes (Header) +128 (number of SV) * 20 Bytes =2580 Bytes. Using the command: "cmd_almanac_update" with ID 0XB6 user can provide parts of Almanac data to device either via LoRa or BT communication.

Each command must be send to port 32 and must be of the form:

• byte 0: cmdID 0XB6

• byte 1: length of the cmd

• byte 2-21: Almanac (id is obtained from first byte, as represents satellite id and 128 - header).

• ... stack as many as available

On received header with ID 128, FW will update Almanac. Update will take place only if provided date of the new Almanac is more recent than already stored one.

Satellite data

To get more insight in the LR GPS performance, satellite data from latest scan can be obtained. Message "msg_lr_satellites" sent to port "port_lr_sat_data" contains satellite data, signal strength and other parameters. More on the message structure is written in the LR satellite data message section.

LR1110 WiFi scan

LR1110 module can perform WiFi scan and store obtained data for analysis or send them as LoRa message.

WiFi scan is governed by the following settings:

• "wifi_scan_interval" with id 0x19: period in seconds on which WiFi scan is performed - can be sett in the App. Depending on set flags for send to LoRa or store to flash, real time scan message can be send to LoRa or store to flash.

• "wifi_scan_aggregated_interval" with id 0X1A: period in seconds on which aggregated wifi scan data is send via LR/stored to flash - can be sett in the App. Depending on set flags for send to LoRa or store to flash, real time scan message can be send to LoRa or store to flash.

• Currently scan type is not user configurable and is pre-set to LR1110_MODEM_WIFI_TYPE_SCAN_B_G_N.

To disable WiFi scan, set both "wifi_scan_interval" and "wifi_scan_aggregated_interval" to 0.

WiFi scan data

Single scan results in data of the format: "msg_wifi_scan" with id: 0XF8. Data is stored to flash and/or send via LoRaWAN, based on store and send flags. More on messages structure and send/store flags can be found under Messages section.

WiFi aggregated scan data

Each individual scan result is added to aggregated data structure of the format: "msg_wifi_scan_aggregated" with id: 0XF7. On specified interval, message is stored to flash and/or send via LoRaWAN, based on store and send flags. More on messages structure and send/store flags can be found under Messages section.

User messages

User messaging via LoRaWAN is supported. User can send message of length of up to 45 bytes via app.

Sending message from app

Message is send from app via command: C4 Cmd send lr message.

Send message to device to be send via LR on the command port.

C4 data_len data[data_len]

Up to 45 bytes are supported.

Tracker will send message on the next interval to LR.

Sending message from device to server

Up to 5 messages, stored in the local buffer, are sent to LoRa server. Single message can be send multiple times, to avoid data loss, defined by lr_messaging_retry_countsetting with id 0x32. Repeated send is separated by lr_messaging_retry_intervalsetting (id 0x31) in seconds.

Format of the message is msg_lr_messaging and is send to the lr messaging port.

Sending message from server to device

Message can be send to device from LR server. Device will store up to 5 messages to be red by the user from app. If device is rebooted all messages are lost.

Format of the message is msg_lr_messaging and must be send to the lr messaging port.

Message example

// sends ABCDE with retry and sequence set to 1
// Message format: port, id, len, msg_len, 5x ascii chars, seq, retry
// Payload in decimal (base 10)
28, 144, 8, 5, 65, 66, 67, 68, 69, 1, 1
// Payload in hexadecimal (base 16)
1C, 90, 08, 05, 41, 42, 43, 44, 45, 01, 01

If using TTN web console interface, to send the message ABCDE, do the following:

1. Go to End device and open the desired device

2. Click on tabs Messaging -> downlink

3. Set FPort: 28 and payload type to bytes

4. Write the command: 90 08 05 41 42 43 44 45 01 01

5. Press Schedule downlink

Reading messages from device via app

Incoming messages, stored on device, can be red by the user via app. Messages are send in the form of msg_lr_messaging_timestamp

UBLOX GPS

Ublox GPS module is present on all tracker HW types. Basic operation: tracker tries to obtain GPS fix on defined interval time and send in via LoRaWAN as message to port 2. If sending extra data is supported, governed by setting: "gps_sat_data" with id: 0x0A (turn this on: 0A 01 01 or turn this off: 0A 01 00 to port 3) also additional satellite data is send to port 9.

RF scanning

On some HW types, RangerEdge v1.4 in particular, RF scanning board can be attached and RF scans performed.

Messages

During operation, device will produce several messages in various modules. Each message type is associated with specific port. The following ports and message types are supported:

1. Port LR gps: 1

2. "port_ublox_gps": 2,

3. "port_settings": 3,

4. "port_status": 4,

5. Port LR satellite data: 5

6. "port_wifi_scan_aggregated": 6,

7. Port ble scan aggregated: 7,

8. "port_rf_scan": 8,

9. "port_ublox_sat_data": 9,

10. "port_wifi_scan": 10,

11. Port ble scan: 11

12. Port lr messagging: 28

13. "port_flash_log": 29,

14. "port_values": 30,

15. "port_messages": 31,

16. "port_commands": 32

Sending and storing messages

Messages associated with each individual port can be either stored to flash and/or send via LoRaWAN. This can be controlled with two individual settings:

"lr_send_flag" ID: 0x0C

32 bit integer, where each bit determines if messages associated with port on corresponding bit is or is not send via LoRaWAN, when generated.

"flash_store_flag ID: 0X0D

32 bit integer, where each bit determines if messages associated with port on corresponding bit is or is not stored to flash, when generated.

Port LR GPS: 1

Message of type "msg_gnss" with id 0XF1 contains NVS message, obtained when LR GNSS scan is performed. Message is of the form:

• byte 0: message ID - 0XF1

• byte 1: message length

• byte 2 - end: NAV payload

  • byte 2: destinationID

    • 0X00 - message to the host (errors, warnings)

    • 0X01 - message to the GNSS solver (valid nav message)

  • byte 3: if message to the host, error code:

    • 0X07 - no satellites detected in the scan

    • 0X08 - almanac to old

  • byte 3-end: if message to the solver, NAV payload

Port UBLOX GPS

Message of type

Port status: 4

Messages of type "msg_status" with id 0XF4 is send to port 4. Message contains various status data of the form below.

Status message has changed due to new requirements and has two versions. Starting with firmware v1.11 trackers will have status version 2. Mobile application supports both status versions.

Byte number	V1 (fw < v1.11)	V2 (fw >= v1.11)
0	message ID - 0xF4	message ID - 0xF4
1	message length	message length
2	reset byte	reset byte
3	error flags bit 0: LR error bit 1: BT error bit 2: Ublox error bit 3: Ublox busy bit 4: sensors error (acc) bit 5: baterry error bit 6: Ublox fix error bit 7: Flash error	error flags bit 0: LR error bit 1: BT error bit 2: Ublox error bit 3: Ublox busy bit 4: sensors error (acc) bit 5: baterry error bit 6: Ublox fix error bit 7: Flash error
4	battery level	battery level
5	operation flags bit 0: charging status bit 1: implemented pin security bit 2: LR join status bit 3-7: free	operation flags bit 0: unread user message(s) bit 1: implemented pin security bit 2: LR join status bit 3: free bit 4-7: nr of LR satellites
6	temperature	temperature
7	uptime	uptime
8	accelerometer X	accelerometer X
9	accelerometer Y	accelerometer Y
10	accelerometer Z	accelerometer Z
11	version HW bit 0-3: HW minor bit 4-7: HW major	version HW bit 0-3: HW minor bit 4-7: HW major
12	version FW bit 0-3: FW minor bit 4-7: FW major	version FW bit 0-3: FW minor bit 4-7: FW major
13	HW type bit 0-3: HW type bit 4-7: free	type bit 0-3: HW type bit 4-7: FW type
14	number of LR satellites	charging voltage
15	last LR fix	bit 0: satellite com enabled bit 1: rf scan enabled bit 4-7: number of satellite send retries

Port LR satellite data: 5

Messages of type "msg_lr_satellites" with id 0XF5 are sent to port 5. Message contains satellite data for satellites used in the latest GNSS scan. Message is of the form:

• byte 0: message ID - 0XF5

• byte 1: message length

• byte 2: nr. of satellites

• byte 3 - end:

  • id

  • cnr

Port ble scan aggregated: 7

Messages of type "msg_ble_scan_aggregated" with ID 0XF9 are send to port 7. Message contains aggregated ble scan data. Only top 5 contacts, sorted by RSSI are send via LR and/or stored to flash. Message is of the form:

• byte 0: message ID - 0XF9

• byte 1: message length

• byte 2: nr. of unique BT scan results during this period (can included number of results in the message!)

• repeated for each included contact, total length of 9bytes per contact:

  • byte 0 - 2: last 3 bytes of MAC address

  • byte 3: RSSI (best value measured in interval for specific contact)

  • byte 4: count - nr. of times contact was observed on BT scan in interval

  • byte 5-8: timestamp when best rssi value was scanned

Port WiFi scan: 10

Messages of type "msg_wifi_scan" with id 0XF8 are sent to port 10. Message contains data of single wifi scan. When we have more results then can be fitted in single message length, multiple messages are formed. Only first message is send via LR, but multiple can be stored in flash. Ressults are orderd by rssi. Message is of the form:

• byte 0: message ID - 0XF8

• byte 1: message length

• byte 2-5: timestamp when latest scan was performed

• byte 6: nr. of unique BT scan results during latest ble scan contained in this message

• repeated for each included contact, total length of 4 bytes per contact:

  • byte 0 - 2: last 3 bytes of MAC address

  • byte 3: RSSI (best value measured in interval for specific contact)

Port ble scan: 11

Messages of type "msg_ble_scan" with id 0XFA are sent to port 11. Message contains data of single ble scan. When we have more results then can be fitted in single message length, multiple messages are formed. Only first message is send via LR, but multiple can be stored in flash. Ressults are orderd by rssi. Message is of the form:

• byte 0: message ID - 0XFA

• byte 1: message length

• byte 2-5: timestamp when latest scan was performed

• byte 6: nr. of unique BT scan results during latest ble scan contained in this message

• repeated for each included contact, total length of 4 bytes per contact:

  • byte 0 - 2: last 3 bytes of MAC address

  • byte 3: RSSI (best value measured in interval for specific contact)

Port LR messaging: 28

Messages of type "msg_lr_messaging_timestamp" with id 0xF0 are sent to and from port 28. Message is of the form:

• byte 0: message ID - 0XF0

• byte 1: message length

• byte 2: data length

• byte 3 - 3+data_len: message data

• byte 3+data_len+1: message sequence nr.

• byte 3+data_len+2: message retry send count.

• byte 3+data_len+3 - +4: timestamp of msg recieved.

Also messages of type "msg_lr_messaging" with id 0x90 are sent to and from port 28. Message is of the same format as the one above, iting the timestamp:

• byte 0: message ID - 0X90

• byte 1: message length

• byte 2: data length

• byte 3 - 3+data_len: message data

• byte 3+data_len+1: message sequence nr.

• byte 3+data_len+2: message retry send count.