Gateway Software Update (UltraLite)

We recommend that the software image on your DevKit's microSD card be updated to the latest UrsaLeo Gateway Software Platform Release. This document describes this process.

If you are recording sensor data, it is highly recommended to download the latest readings to your computer before continuing.

As a prerequisite, you will need:

• A computer (Windows or macOS) with the latest version of Etcher installed - https://www.balena.io/etcher/
• A microSD card reader connected to your computer
• A valid registered account on the UrsaLeo Cloud platform
• A microUSB cable to connect the UltraLite unit to your computer
• UrsaLeo UltraLite DevKit with Silicon Labs Thunderboard 2 sensor

To perform the software update, you will need to gain terminal access to your DevKit. Please see this article: UltraLite DevKit Operation.

Update your DevKit software in 4 steps:

1. (Existing users only) Recover the DeviceID and Registration Code
2. Flash the new software image
3. Configure your network
4. Reboot your DevKit

1. Recover the DeviceID and Registration Code (existing users only)

You can recover your Device ID and Registration Code from the sticker on the box of your DevKit or by logging into your account in the UrsaLeo Cloud Platform.

To retrieve from your account:

• Log in to your UrsaLeo Cloud Console https://services.ursaleo.com
• Click the Devices tab to see a list of all devices registered to your account. Beside each device name is a device ID (an alphanumeric string starting with mo, rs, or a similar two letter combination, like rs123456) and registration code (4 groups of 4 characters, separated by spaces, like xWYZ-1234-YYhV-9079). Note that the registration code is case sensitive.

• If you’re unable to find and retrieve these two codes, please Submit a Request. You will need to enter these codes after you’ve updated your DevKit’s software.

2. Flash the new software image

a) Download the latest UrsaLeo UltraLite Gateway Software image file

• Log in to your UrsaLeo Cloud Console https://services.ursaleo.com
• Select the Images tab to download the latest UrsaLeo UltraLite Gateway Software file (with extension .wic.xz) to your PC.
  
  
  
  
  

b) Flash the new image using Etcher

• Start Etcher and select the downloaded Gateway Software image file. Note that if you are using a Mac running macOS Catalina, you will need to give Etcher full disk access in System Preferences/Privacy. Visit Etcher's support pages for more info.

• Select the microSD card.

• Select Flash. Allow changes to your device. Cancel any requests to insert or format drives.

3. Boot your DevKit

• Eject the microSD card and remove from the card reader then re-insert it into the DevKit microSD connector.
• Connect your DevKit to your computer using the microUSB port next to the power switch on the DevKit.
• Power on your DevKit. Note: The first boot after the software update may take 2-3 minutes. Subsequent boot times are faster - less than 1 minute.

4. Gain Terminal access to your UrsaLeo Gateway

• Download and install Silicon Labs VCP drivers on PC (Windows or macOS): Silicon Labs VCP drivers

For Windows PC:

• Download and install Putty serial comms software on PC:
• Start Putty and configure serial settings:
  • Baud rate: 115200
  • Data bits: 8
  • Stop bits: 1
  • Parity: None

Putty configuration

• Power on the DevKit and wait for the boot prompt to appear

For macOS:

• Launch Terminal.
• Connect to the USB serial port.

   # ls /dev/*tty*

• You will see /dev/tty.SLAB_USBtoUART. Connect to the port and set it to 115200 8n1 with no flow control.

# sudo screen /dev/tty.SLAB_USBtoUART 115200/8/1/n/Xoff

• Enter your admin password for the macOS user.
• Hit enter until you see prompt for a login.
• Login as “root” with no password
• The shell prompt appears ready to run commands

Note: If you are unable to connect after following the steps above, turn the UltraLite devkit off and back on. Connection should occur.

4. Perform configuration

• When the device has not been configured (as is the case immediately after flashing), the configuration menu will automatically be presented after login. Configuration can also be called from the shell, later, by executing
  

  # ul-config

Once the menu is displayed, proceed through the available options in order:

Option 1 - Configure WiFi (optional)

• If hard-wired Ethernet is not used, use this option to configure WiFi - the ISO 2-digit country code must be entered (GB for Great Britain; US for United States), along with the WiFi SSID and password. For countries other than US and GB, look up your country code here: https://www.nationsonline.org/oneworld/country_code_list.htm
• Once this information is set successfully, the network interface will be enabled and started – Option 1 will be marked with "OK" in the case of successful configuration, or a failure message will be issued. On failure, please recheck that your WiFi access point is active and the credentials are valid, then try again.

Option 2 - Register Device

• When selected, this option first tests the route to the UrsaLeo cloud MQTT bridge. On a connectivity failure, a message to check connectivity will be displayed. Address the connectivity issue by connecting an Ethernet cable or configuring WiFi as described above for Option 1, then retry Option 2.
• Once connectivity is established, you will be prompted to enter the Device ID, Registration Code, and your UrsaLeo Cloud platform username and password. Existing users should enter the Device ID and Registration Code as described above. New users can simply press enter when prompted to generate these codes.
• (New users only) On completion, a new key pair to identify your device will be generated and the public portion sent over https to register your device (the private portion is stored on your device). This process also checks that a valid device exists along with the validation code in the cloud. All being well, the device will then connect to the UrsaLeo cloud platform, storing the credentials locally.
• On failure, an error message will indicate specific authorisation and other issues. Check your credentials and try again. Note that the Registration Code is case sensitive and must be entered correctly, including the dashes.

Option 3 - Thunderboard Demo

• Use Option 3 to configure the Thunderboard demo and restore the BLE connection between your DevKit and the Thunderboard 2 sensor that came with your kit.
• Type 3 and press return. It is recommended to press the reset button on the Thunderboard and select the option that is returned at the prompt after a few seconds. This process can take 10 - 20 seconds to complete - be patient!
• It can also be used at a later stage to change or replace the Thunderboard 2 sensor. Note that your device will not send data until this step is completed.

Option 4 - BME280 Demo (Optional)

• Use Option 4 to configure the BME280 demo as an alternative to the Thunderboard demo. This uses the I2C bus to connect to BME280 modules. The modules I2C address can be changed in the config file /etc/ursaleo/bme280.ini
• Type 4 and press return.
• It can also be used at a later stage to change or replace the BME280 sensor. Note that your device will not send data until this step is completed.

Option 5 - System Info

• Displays key system configuration details on screen and generates a log file containing current configuration and system state that can be emailed to support. This can be run at any time.

Option 6 – Reboot

• You can now reboot your device by selecting Option 5. **Note that no previous changes will be saved to the device unless Option 5 is performed.**
• After the Devkit has completed rebooting, we recommend that you press the reset button near the centre of the Thunderboard. The green LED near the centre of the Thunderboard should flash one or two times then go off - indicating a connection.
• Your DevKit is now updated and will automatically start sending sensor data to your UrsaLeo Cloud account.

To view your sensor data in the dashboard, see Step 6: Monitor Your Sensor Data

The UltraLite DevKit includes the UrsaLeo debug LED module connected to the baseboard. As the DevKit is booting, LEDs 1, 2 and 3 will turn on as follows:

• LED 1: On (connection to Google IoT Core)
• LED 2: On (connection to Thunderboard Sense 2 / BME280)
• LED 3: On (authentication with Google Cloud Platform) after a few seconds
• LED 4, 5 and 6: will be off as they are reserved for future use.
• Note: If LED 2 is not "On", press the reset button located in the centre of the Thunderboard to establish a connection.