BloxOsLite (UbiSwitch, SwitchBlox Industrial)

<aside> ⚠️ You only need to flash UbiSwitch if:

You currently have an unflashed UbiSwitch -You are an ‘advanced’ customer with your own debug probe for flashing.
You are upgrading to the latest version V1.0.0, which requires an upgrade over the SWD interface.

If we have supplied you with a pre-flashed version, you do not need to run these steps.

</aside>

<aside> ⚠️ If we have supplied you with an unflashed version, you can run these steps yourself or RMA it back to our lab where we will flash it for you.

</aside>

At-a-glance

Download the latest release (or older releases) here

Software architecture

An overview of the architecture is shown below.***

Each firmware release is initially flashed (along with its bootloader) only once using the JTAG/SWD interface to the CPU on the BotBlox board. This should only be done during production. Over time as the feature set of BloxOsLite matures, we’ll

Following this, subsequent updates occur over UART using MCUmgr management subsystem.

graph TD
  Bootloader -- Boots --> BloxOsLite
  MCUMgr -. Update over UART .-> Bootloader
  Flashing -. Flash over SWD .-> Bootloader
  Flashing -. Flash over SWD .-> BloxOsLite

<aside> 🚨 ***Customers using UbiSwitch Rev B may be using a 64Kb MCU instead of 128Kb MCU due to a board upgrade, which we have now resolved for future boards. This only affects a few boards existing out there but please visit the below page to view different instructions on flashing.

</aside>

Flashing firmware

Requirements

By no means an exhaustive list of debuggers but to help get started.

JLink

SEGGER J-Link Base: ARM Debug SWD capable debugging probe that allows debugging software on host machine to program BotBlox board.
20 pin, 0.1” <> 6 pin, 0.05” cable: used to connect to SWD interface on BotBlox board to debugging probe.
J-Link Software package: Debug/flashing software used to write the bootloader and BloxOsLite application to flash memory. Contains J-Flash software used to program MCU.

STLINK

STLINK-V3 modular in-circuit debugger and programmer for STM32/STM8: ARM Debug SWD capable debugging probe that allows debugging software on host machine to program BotBlox board.
TC2030-IDC-NL: used to connect to SWD interface on BotBlox board to debugging probe.
ARM20-CTX-M 20-Pin Male to TC2030-IDC Adapter for Cortex: 20-pin to 6-pin IDC adapter to allow TC2030-IDC cables to be used for ARM JTAG and ARM SWD (Serial Wire Debug) applications.
STM32CubeProgrammer: Debug/flashing software used to write the bootloader and BloxOsLite application to flash memory.

Steps

Download and unzip the binaries on the release page. Please choose the latest release.
1. (SIMPLE) If there is a combined bootloader and app binary provided, then you can use this and only need to flash one file.
  1. app_with_bootloader_vX.X.X_YYYYMMDD.hex with the version number and date.
2. (ALTERNATIVE) 3 files: bootloader.hex , app.hex and app_dfu.bin are provided
  1. bootloader.hex = bootloader binary
  2. app.hex and app_dfu.bin = application binaries (in hex and bin file format, used for flashing and upgrades over serial respectively).
Connect the debug probe to your host machine. Confirm the debug probe is found by your system.
1. If using ST-Link probes: On STM32CubeProgrammer, refresh Serial number in STLINK configuration tab to find your probe. Ensure Port=SWD .
  
  Wire up your ST-Link probe to your TC2030 cable.
2. If using J-Link probes: Load SEGGER J-Link Configuration (or JLinkConfig) and confirm the appearance of your debug probe
  
  Connect the 6 pin TC2030 cable with 20 pin adapter directly into the J-Link debug probe.
Plug the 6 pin needle connector to the SWD interface on your BotBlox board.
1. On UbiSwitch, this is connector J9 . Please ensure you have mounted the UbiSwitch module to an UbiSwitch baseboard to power the device. The device will not be powered by the debug header alone. You will need to remove the heatsink in order to do this.
The J9 connector on UbiSwitch is highlighted.

b. SwitchBlox Industrial, this is connector J9 .
Power on the board.
1. For UbiSwitch, this will mean connecting the board to the baseboard and powering the UbiSwitch module through that.
2. For SwitchBlox Industrial, power the board as normal.
Flash the binaries.
1. Either flash the combined binary file or bootloader.hex and app.hex separately. See [Download and unzip the binaries on the release page. Please choose the latest release.](https://botblox.notion.site/Download-and-unzip-the-binaries-on-the-release-page-Please-choose-the-latest-release-d6380d4c12be4abbbebc271d6f94daf9)
2. ℹ️ If you only want to update the bootloader but leave the app version the same, please only use the bootloader.
3. Please ensure the 6 pin needle adapter is always making good contact with the J9 connector interface otherwise errors can occur.
4. If using ST-Link probes: On STM32CubeProgrammer, click Connect and verify the correct target information shown.
  
  In Erasing & Programming tab, select the first file. Ensure that Run after programming is deselected.
  
  After this, repeat with the second file, if necessary. Ensure that Skip flash erase before programming is selected if programming a second file.
5. If using J-Link probes: In JFlashLite , select the STM32G071KB device with SWD interface.
  
  Select first file, then click Program Device to program the bootloader.
  
  Repeat this step for second file, if necessary.
Power cycle the board and wait for the boot LED to turn off. You are then able to open a serial console into the CLI over UART.
1. Baudrate: 115200 bits per second
2. 8 data bits per character, no parity checking and 1 stop bit

Updates using MCUmgr

After flashing the firmware and using the device in the field, you will need to perform an update when we make new releases of BloxOsLite.

<aside> 🚨 You can ignore this step if you are already running the latest version.

</aside>

Requirements

USB-UART converter (3.3V TTL)
MCUmgr client manager
- Recommend using mcumgr-client
- Zephyr have great docs on the various options you can use for updating from a host system if you want an alternative.

Steps

Download the binaries on the release page
1. Unlike previously, you will only need the app_dfu.bin binary.
Connect the USB-UART converter from your host machine to the UART connector on the BotBlox board.
1. On UbiSwitch Baseboard, this is connector J18.
Clone and build the MCUmgr client.
Using mcumgr-client in ‣
1. Power on the board. Notice the LED will turn on to indicate that the device is in firmware loader mode but only for a set amount of time. You will need to make sure that any MCUmgr commands you run occur when the board is in this mode.
2. mcumgr-client -d /dev/ttyUSB0 list is useful for forcing the board to remain in serial recovery mode. You can use this command to view the current version installed too. Note that /dev/ttyUSB0 is the device name for the USB-UART converter, which may be different on your host machine. Below is a typical readout.
```
mcumgr-client 0.0.4, Copyright © 2024 Vouch.io LLC

00:06:54 [INFO] send image list request
00:06:55 [INFO] response: {
  "images": [
    {
      "hash": [
       ...
      ],
      "slot": 0,
      "version": "0.1.0"
    }
  ]
}
```
3. mcumgr-client -d /dev/ttyUSB0 upload app_dfu.bin to actually upload the latest app_dfu.bin to the primary slot. Note that this will erase the previous version permanently so once you reset, you will be booted to the new version.
4. mcumgr-client -d /dev/ttyUSB0 reset to trigger a reboot
If you notice bugs or missing features, please report them as issues on our GitHub or BotBlox forum. Note that the process to downgrade versions is the same as upgrade except that you can choose a particular version