Connected screens

Connected screens can be reached by tapping on a tracker on the Device List screen, which establishes the connection and displays the Tracker information screen. Connecting takes a few seconds, the application displays an overlay with a spinner to inform the user that it is in progress and he needs to wait. Other connected screens can be reached by pressing the buttons in bottom navigation bar with an exception for DFU, for which the button in located in the navigation header on the right.

These screens are:

• Tracker information

• Tracker configuration

  • Interval configuration

  • PIN configuration

  • GPS configuration

  • LoRA configuration

• WiFi and BLE scanning

• Download logs

• Firmware upgrade (DFU)

Tracker information

This screens give the user an insight to currently connected device's status and offers him to send various commands.

On the top is device status. It displays all the information that the tracker is also advertising, which is: battery state and voltage, hardware version, firmware version, accelerometer data, temperature and error information of main functions, such as LoRa, GPS or flash chips states. Besides that, it gives some additional data:

• uptime in hours (since boot)

• number of reboots

• number of LoRa GPS satellites that it sees

• number of fixes aquired with LoRa GPS

• if PIN is set or not

• if device is currently busy (searching for GPS fix) or idle

Second element is the last known position where location data from the last successful GPS fix is presented. Labels show latitude and longitude in degrees, altitude in meters and timestamp written in yyyy-mm-dd hh:mm:ss format. Below the labels is clickable text, offering the user to open Google Maps application and show the location as a marker on the map, which gives the user a simple way to visualise this position data.

Device status and last location are periodically refreshed, every 10 seconds. If user wants to get new data immediatelly, he can swipe down from the top of the screen and new data will be immediately fetched from the device.

Third element are device commands, buttons for performing various one time operations. User can click on a button and device will execute it immediately. Currently available commands are:

• Send status to LP1 (Device will send its status over LoRa network to the server)

• Send raw LP1 GPS data to LP1 (Device will send nonparsed GPS data containing all the details about the current LoRa GPS state over LoRa network to the server)

• Get Ublox GPS fix (Device will start to search for GPS fix using Ublox and a popup window will appear with results - described below)

• Initialize location and time (Use phone's data to set device's location and time, which helps the device to find GPS fix faster and gives actual time information to all data being saved or sent to the servers. The application will acquire the position and current time from the phone and send latitude, longitude together with a timestamp in UNIX format to the tracker, who will save it to flash)

• Reboot device (Popup will appear, in which the user needs to confirm that he actually wants to perform a reboot. This is to prevent accidental clicks which would trigger it and possibly disturb any ongoing operations)

Last element contains two text fields where user can write a custom command and rename this device.

Application supports getting and changing all settings that the user will require, but for developers and administrators it comes very handy to be able to send a command or write a value that is not yet supported by the application. This is what custom command field is for. Data that the developer is sending needs to be in raw format and follow the protocol PILV as any other data that is being transfered. This protocol is described in the next chapter. Raw format means, that data is written as a number of each byte, with spaces in between. Numbers can be in decimal or hexadecimal format (with a prefix 0x).

More information on writing manual commands can be found here:

pageUser commands instructions

Devices are preprogrammed with a default name: SPXXXXX. It consists of a prefix (SP), which means SmartParks, and six characters long serial number (XXXXXX), consisting of digits and letters. The name can be changed by using this rename field, the device supports all ASCII characters, excluding control characters. The name can be a maximum of 8 characters long and cannot be empty.

Get Ublox GPS fix popup

This popup is shown to the user on any connected screen. It appears after device finishes searching for a GPS fix using its Ublox chip and sends data. Here user can see all the details about the operation of the GPS, not just an actual position (latitude and longitude), which helps him to tune parameters in order to get better and faster fixes. Data has the following parameters:

• Latitude and longitude (Acquired position in degrees, if no fix was acquired these will be zero)

• Altitude (Acquired distance between sea level and the current position in meters, this will also be zero if no fix was acquired)

• Hot and cold retry (Number of retries to get a fix of both types of GPS start modes - hot and cold)

• Success (boolean value showing if device found a fix or not)

• Time to fix (Amount of seconds it took to find a fix or reached a timeout defined for when to stop searching for it)

• Type (type of the aquired fix, possible values are: No fix, 2D fix and 3D fix. This value is showing if fix acquisition was succesfull or not, if it was, then type of the fix is displayed. There are two types: horizontal - 2D where just horizontal position was found and vertical - 3D where also altitude information is available)

• Fix timestamp (exact time of the moment when fix was aquired, this is send from the tracker in UNIX format, but then shown as human readable date and time)

• SIV (abbrevation for satellites in view, which is the number of satelites that where seen by the device to be used in fix aqusition)

• pDOP (abbrevation for position dilution of precision, which is a description of the uncertainty in a fix. Value is related to the spacing of satellites in the sky above the device)

• Estimated horizontal accuracy (accuracy of the position from the acquired fix, shown in meters)

• Active tracking (shows if the GPS chip is constantly searching for a fix or only on specifed intervals)

• COG (abbrevation for course over ground, presented in degrees, giving the user course of the movement, where zero degress means moving to the North)

• SOG (abbrevation for speed over ground, presented in km/h, which is an actual speed of the device in movement, it is very close to zero if it's not moving)

Tracker configuration

This screen serves as a menu for all configuration subscreens. Application offers the user to change many tracker's settings, which means they could not be fitted on a single screen. They have been divided into 4 subscreens, grouped by their purpose. Timing related ones are displayed on Interval configuration screen, there is a separate screen for security (PIN) related settings and two for specific connection systems, GPS and LoRa.

Application loads settings when the user navigates to one of the configuration screens, which means only those that are on the selected screen are loaded. On each screen, there is a text informing the user about the current status of loading or saving values, when this is executing, a spinner appears, giving the user a visual element showing that something is in progress and he needs to wait. When the application loads values, it first sets all of them to unknown and when actual data for a value is received, it substitutes the unknown. This way the user knows if a value was not received from the device or parsed successfully and that received ones are actually the same as on the device.

Interval configuration

Here user can view and change settings that define how frequently some operation will happen. Configurable intervals are presented in the table below.

Setting name	Description	Dropdown values
LP1 send	send GPS data to LoRaWAN server	off, 1 min, 15 mins, 1 h, 2 h, 4 h
Status send	send status data to LoRaWAN server	1 min, 15 mins, 1 h, 2 h, 4 h
WiFi scan send	send results from device's WiFi scan to LoRaWAN server	off, 1, 3, 5, 7, 10 minutes
BLE scan send	send results from device's BLE scan to LoRaWAN server	off, 1, 3, 5, 7, 10 minutes
WiFi scan	execute WiFi scan	off, 1, 3, 5, 7, 10 minutes
BLE scan	execute BLE scan	off, 1, 3, 5, 7, 10 minutes

Screen consists of dropdown menus for each interval. When user select the desired value, it immediatelly gets sent to the device. This means that there is no save or send button required. There is however, reload intervals button, located below the dropdown menus, which will refresh data shown in the app with device's settings.

PIN configuration

Here user can see and edit the device's PIN. The code is hidden with symbols **** displayed instead and user needs to press a button to show it. By default, the device won't have a PIN set and the code displayed is going to be 0000, which means that security is disabled and the code will not be asked when connecting to it.

To change it, a user needs to write new numbers to the field and press the Update PIN button. The code needs to be exactly four digits long. If a user wants to disable authentication with the PIN code it should write 0000.

This feature was added to device's firmware in one of the later releases, which means it can't be used on a device which has an old firmware installed, specifically older than v1.6. Application detects this and doesn't render the fields for PIN configuration, but instead displays to the user a message saying that he needs to update device's firmware to a newer version.

GPS configuration

All GPS settings related to Ublox chip are presented here. They are grouped into two categories: fix intervals and fix settings. When user sets all settings to desired values, it needs to press Update configuration button. There is also a reload settings button, which will get all values from the device.

With fix intervals user sets how frequently device will search for a fix. This can be set by a dropdown menu, its available values are: off, 1 min, 15 mins, 1 hour, 2 hours and 4 hours. Application allows the user to use a single interval all the time or to have two different ones, each being used for 12 hours. Two interval configuration can be enabled by ticking a box. When this is enabled, dropdown menu for second interval (with the same values as above) becomes editable, together with a dropdown where user can set the starting time of the first interval (available options are all hours between midnight and noon). Since both intervals are used for equal amount of time (12 hours), setting the start of the second interval is not needed, it's calculated automatically from the first one.

With fix settings user configures other fix related settings. These include changing timeouts and number of retries for both types of fixes, choosing a backoff factor and enabling active tracking.

There are four text fields, two for cold and two for hot fix configuration. Fields provide an option to write number of retries and fix timeout in seconds. Application checks if written values are valid, lowest possible number for both types is 1, highest number for retry fields is 255 and for timeout fields is 600 seconds.

Next element is a dropdown menu for specifying backoff factor, with these options: disabled, 1.5 and 2. This setting specifies what should device do when it fails to get GPS cold fix in specified number of retries. If backoff is disabled, device will continue to search for a fix as specified by the interval value. If this is enabled, device will multiply the set interval by a factor and only search for a fix then.

Below is a check box for enabling or disabling active tracking. If it's enabled, it means that the device has permanently turned on Ublox chip and is constantly searching for a fix. If it's disabled it means that device will turn on Ublox chip only on specified intervals or when it's requested by the user with a command Get Ublox GPS fix.

LoRa configuration

This subscreen has a slightly different name in the app: LP1 configuration. One could also notice that LP1 is used instead of LoRa everywhere in the application. This is due to legal reasons, prohibiting us to use the name LoRa.

Application allows configuring the region and data rate of the LoRa chip. Region configuration is required due to differences in available radio frequencies that can be used by LoRa network, which varies from country to country. Changing data rate gives user an option to fine tune LoRa operations in regards to his specific needs for amount of data that is being trasfered and device's power consumption. Both settings have a dropdown menu, currently available options are:

• Region: EU and US

• Data rate: 0, 1, 2, 3, 4, 5 and 6

Below these settings are fields for getting and setting authentication keys, which the device needs in order to be able to communicate with a LoRa server. There are three fields:

• Device EUI (Has a length of 8 bytes, it's predefined and can only be read from the device. Next to it it's a button, that copies it to phone's clipboard, easing the process of copying it to other applications used for registration of the device)

• App EUI (Also has a length of 8 bytes, but it's writable. User needs to get it from a LoRa server and write it when activating the device)

• App Key (Has a length of 16 bytes, it's writable. This is device's unique authentication key, user also needs to get it from a server and write it to the device)

WiFi and BLE scanning

Devices also have an ability to scan for nearby WiFi and BLE devices. User can request both of these by tapping on one of the buttons and device will return the results, which can be seen here. Note that BLE scan can't be run when the phone has connection established, device will instead return results from the last scan performed before user connected to it.

Each result contains the following data:

• last three bytes of the MAC address

• human readable timestamp (showing when this device was last seen)

• counter for how many times this device was seen on scan

• RSSI value (signal strength of last time this device was scanned)

Download logs

Device saved various information to its storage, these messages are called logs. Logs can be downloaded to the phone using this screen. User can download all or specific logs and clear all of them from the device. The last element shows the status of this operation with a spinner to indicate when downloading is in progress. Information about the size of downloaded logs in bytes is also presented, which updates in real time.

Process of downloading logs is described here: https://github.com/IRNAS/smartparks-connect-app/tree/dev#download-device-logs

Below is an example of a few parsed logs from an actual device.

{
  "1": {
    "name": "msg_status",
    "data": {
      "reset": 0,
      "bat": 3300,
      "charging": false,
      "locked": true,
      "temp": 22.352941176470594,
      "uptime": 0,
      "acc_x": -1.17647058823529,
      "acc_y": 8.235294117647058,
      "acc_z": 4.313725490196077,
      "lr_sat": 0,
      "lr_fix": 0,
      "err_lr_join": false,
      "err_ble": false,
      "err_ublox": false,
      "err_acc": false,
      "err_bat": false,
      "err_ublox_fix": false,
      "err_flash": false,
      "ublox_busy": false,
      "ver_fw_major": 1,
      "ver_fw_minor": 5,
      "ver_hw_major": 1,
      "ver_hw_minor": 1,
      "ver_hw_type": 4
    },
    "port": 4,
    "timestamp": 1628042179,
    "timestamp_parsed": "2021-08-04 03:56:19"
  },
  "2": {
    "name": "msg_ble_scan",
    "data": {
      "1": {
        "rssi": -55,
        "mac": "25:18:e1"
      },
      "2": {
        "rssi": -63,
        "mac": "79:56:65"
      },
      "3": {
        "rssi": -81,
        "mac": "b3:e7:8d"
      },
      "N_BT_res": 3,
      "t": 1628041580
    },
    "port": 11,
    "timestamp": 1628041581,
    "timestamp_parsed": "2021-08-04 03:46:21"
  },
  "3": {
    "data": {
      "id": 0,
      "confirmed": true
    },
    "name": "msg_cmd_confirm",
    "port": 31,
    "timestamp": 1606314718,
    "timestamp_parsed": "2020-11-25 15:31:58"
   },
}

Firmware upgrade (DFU)

One of the core features of this application is to enable upgradability of device's firmware, which can be done on this screen. Application offers to get the payload from two different sources: phone storage (Upgrade from phone storage button) and Memfault service (Upgrade from Memfault server button).

• Selecting to load it from phone storage opens document picker where user can select a file containing the firmware upgrade payload. Popup then appears with display of selected file where user needs to confirm that he is sure to start the DFU process.

• Tapping on Memfault button downloads and start the DFU automatically. Application waits 15 seconds for server to return data, if it's not returned the process is stopped and fail message is presented to the user.

Below the buttons, current state is shown together with status of the upgrade and its progress percentage. State tells the user if the application is in idle, DFU is in progress, has completed succesfully or has failed. Progress is used to show how much of the payload has been uploaded to the device. Status shows in which step the DFU is, all possible values are described below:

• Upload - payload is being uploaded to the device

• Test - device is testing if the payload was succesfully uploaded and stored as an image

• Validate - device is validating the integrity of a stored image

• Reset - device is reseting and will boot using the new image

• Confirm - device confirmed that it managed to boot

• Success - DFU process has finished succesfully

• Error - DFU was canceled or it failed

When the upgrade is in progress, a user needs to wait on this screen. If he wants to go to any other screen by pressing the back button, DFU needs to be aborted, and a warning popup is presented to the user where he needs to confirm this. There is also a message informing the user not to leave the app because it could happen that the upgrade would fail to finish.

More information about the process of checking the loaded file, downloading the payload from memfault and actually performing the upgrade are available in the following chapter Upgrading tracker firmware.