Interaction with the tracker

Communicating with the device

Establishing the connection consists of the following steps:

• Application sends the request to connect to the device, which responds with connection response.

• Negotiation of MTU (maximum transmission unit) happens next. Both entities need to agree on it, application requests it to be 250 bytes and device should accept it.

• Connection has been established and application proceeds to discover available services and characteristics.

• Exchange of connection ("keep alive") data is started. Phone and device will send it periodically to each other. Application is monitoring this and triggers an event if device disconnects in order to perform needed actions.

• PIN (or LoRa App key) is sent, if device requires it. It needs to be done in 5 seconds after the connection is established, in order to not get disconnected from the device. Device will not send any data until the correct key is provided.

• Application subscribes to receiving notifications from device. This is the only way to receive data from the device. Data cannot be directly read, because the service used by device implements only notification characteristic.

• Periodical polling of status data is started. Application sends two commands to request status and last location and device responds with messages containing latest information.

Application terminates pending connection after 5 seconds and retries 4 times. If it's still unable to connect, it will stop, display an error message to the user and restart BLE scan.

In order to disconnect from the device, the application does the following:

• It checks and stops any timeout timers that are still running. These timers are used through the app to stop waiting for specific data after a defined amout of time has passed. Some of them may be running and need to be cleared.

• It stops monitoring for the connection state changes. Connection data will stop and the event to handle this data disruption should not be triggered anymore, since disconnection was triggered intentionally.

• It proceeds to unsubscribe from receiving notifications, data should not be received from the device anymore.

• It then cancels the connection by sending the disconnect command to the device. Application and device then handle disconnecting independently.

• Periodic pooling of status data is stopped and message is displayed to the user, telling him that disconnecting process has finished.

Data transfer

Data types

Application can send to the device a command or a setting.

Commands are used to trigger a specific operation that should run once and immediatelly. From the application only some of them could be triggered, since some of them are not meant to be used by the user. Application implements commands such as requesting status or last position, triggering a reboot, setting initial position and time (this data is added to the request) and getting a current value of a specific setting (specified also in the request).

Sending a setting is used to directly update it on the device. This is a separate data type, because it doesn't trigger any operation on the device, but it just substitutes the existing value. Device will then use the new value next time it performs an operation that uses it.

Device sends to the application a message, value or a setting.

Message is received as a response to the command and will provide the requested data that can be then parsed to an object. Messages are: status data, last position, Ublox GPS data, etc. There is also a special message named confirm, which is returned to the application after those commands that don't trigger any message or other type of a reply being sent.

Value is a data type, that provides device's certain data information, such as current MCU temperature, number of messages in flash, timestamp of the last succesfull GPS fix, etc. Any available value can be requested by sending a Send single value command with a provided value identifier.

Setting is received by the application after it was requested by Send single setting command. This is used to get settings that need to be displayed in the currently active screen in order for the user to inspect them.

Data transfer protocol

This is described here: https://github.com/IRNAS/smartparks-connect-app/tree/dev#communication-protocol

Protocol was designed in a way, that it supports transferring the same data over two different network types: BLE and LoRa. This way we can have the same encoding and decoding procedures in all parts of the system, which consists of the device, LoRaWAN server and this application. There are however some implementation differences between the server and application, but from the device's perspective, data received from or sent to either of those looks exactly the same.

Data validation checks

Data parsing using PILV protocol implements various checks in the application for validation. This is done by putting received data through a series of checks. Additional checks are also done on the device.

These checks use a specific file (settings.json) that contains definitions for all settings, commands, values and messages that device uses. This file is aquired from the firmware release, meaning that a release of the application will match it with a specific release of the firmware. This file also includes this version information, for reference. For each parameter (which is any of the defined data types), the following is defined (note that some parameters are defined only for specific parameters):

• ID of the parameter

• if is enabled (defined only for values)

• default value (defined only for settings and values)

• minimum and maximum valid values (if applicable, the same as default otherwise)

• length of the value (excluding headers)

• conversion (data type of the data)

• value (defined only for commands)

When data is received, application first checks if headers are valid, these are port, ID and length bytes. Then it attempts to decode it acording to the conversion defined in settings file for this parameter ID. If data is of numeric conversion type, it is also checked if it's between minimum and maximum valid values.

When data is being sent, application checks if provided command name actually exists in the settings file, then it checks the defined length, which determines if there need to be any values appended, which are then also checked.

Handling data transfer failures

Application implements timeouts for all features that require waiting for data, which was requested automatically, by the application itself or manually, by the user. This is used to avoid waiting for messages that will never arrive due to connection or communication disruptions. But also to inform the user that data did not arrive in defined time frame and to give him an option to retry getting it again or some other option to handle it.