User Guide

User Guide

This guide walks you through the complete process of updating your BlueBuzzah device firmware on the Firmware page.

Home Screen

When you launch BlueBuzzah Updater, you'll see a sidebar with three sections:

• Firmware - Install new firmware on your devices (⌘1 on macOS, Ctrl+1 on Windows)
• Configure - Set up therapy profiles on your devices (⌘2 / Ctrl+2, see Therapy Profiles)
• Settings - Theme, high contrast, the app version and Check for Updates (⌘3 / Ctrl+3)

The app opens on Firmware, titled Update Firmware. ⌘R (Ctrl+R on Windows) looks for devices again.

Overview

A firmware update moves through four steps on one page:

graph LR
    A[Step 1:<br/>Choose Devices] --> B[Step 2:<br/>Choose a Version]
    B --> C[Step 3:<br/>Installation]
    C --> D[Step 4:<br/>Complete]
    style A fill:#35B6F2,stroke:#35B6F2,color:#0a0a0a
    style B fill:#35B6F2,stroke:#35B6F2,color:#0a0a0a
    style C fill:#35B6F2,stroke:#35B6F2,color:#0a0a0a
    style D fill:#35B6F2,stroke:#35B6F2,color:#0a0a0a

Loading

Steps 1 and 2 are two cards on the same page, so you can change either one until you select Update Firmware. While the installation runs, the other sections are locked until the flash finishes.

Before You Start

Make sure you have:

• BlueBuzzah Updater installed (Getting Started)
• Your BlueBuzzah device(s) connected via USB
• Device(s) detected as serial ports by your computer
• Internet connection (to download firmware)

Step 1: Choose Devices

In this step, you'll see all connected BlueBuzzah devices and assign roles.

What You'll See

• A card for each detected device, named by its hardware: BlueBuzzah v2 or BlueBuzzah v3
• The serial port and serial number of each device
• A Role control (Primary or Secondary) under each selected device

What To Do

1. Verify your device(s) are detected

   • Connected devices appear automatically
   • Each device shows its serial port (e.g., /dev/cu.usbmodem* on macOS or COM* on Windows)
   • Select Rescan if a device you just plugged in doesn't appear

2. Select up to 2 devices by clicking their cards

   • Both devices must be the same hardware version. You can't flash a v2 and a v3 device together; flash one kind at a time

3. Assign device role(s)

   For one device:

   • Choose Primary or Secondary in the Role control
   • Primary is recommended for single-device setups

   For two devices:

   • The updater sets the roles for you, one Primary and one Secondary
   • You can change them, but both roles must be different

Warning

Device Not Showing Up?

• Use a USB data cable. Some cables only charge
• Check that the device is turned on
• Try a different USB port
• Unplug the device, wait 5 seconds, then plug it back in

Note

Not sure which role to choose? See Understanding Device Roles for detailed guidance.

Step 2: Choose a Version

What You'll See

• The latest stable firmware release, chosen for you
• Its version number, release date and download size
• Badges such as Latest, Experimental and Downloaded

What To Do

1. Keep the latest version, or select Change Version to see every release
   • Most recent version appears at the top
   • Each release shows its version number and release date
   • Turn on Show experimental versions to list early builds for testing
2. Read release notes (optional)
   • Select Release Notes on a version to see what changed
3. Select Choose on the version you want to install
   • Recommended: Choose the latest version unless you have a specific reason to use an older version
   • Experimental versions show a warning: "This is an experimental version"
4. Select Update Firmware to start the installation
   • The button stays unavailable until you've chosen a device, a version and a role for each device

Tip

The updater automatically caches downloaded firmware. If you select the same version again later, it won't need to re-download. Select Delete Download in the version list to remove a cached copy.

Step 3: Installation

The updater will now install the firmware on your device(s). This step happens automatically.

What You'll See

• A reminder to keep the device(s) plugged in until this finishes
• Overall progress bar (0-100%) with the current stage:
  • Checking devices - A quick check of the selected devices
  • Downloading firmware - Downloading the firmware for your hardware (if not cached)
  • Getting the device ready - Switching the device into update mode
  • Writing firmware - Transferring firmware to the device
  • Setting the role - Sending the assigned role to the device
  • Finished - Device successfully updated
• A card for each device with its own progress bar and status: Waiting, Flashing, Done, Failed or Stopped
• Real-time log of installation steps (Show Log)

What Happens

The updater performs these steps automatically, using Nordic DFU for v2 devices and the ESP32-S3 bootloader for v3 devices:

1. Check devices
   • Runs a quick check of each selected device
2. Download firmware
   • Downloads the package for your hardware version from GitHub if not already cached
3. Prepare installation (per device)
   • Restarts the device into update mode
4. Write firmware (per device)
   • Transfers firmware to the device over USB
   • Shows progress as data is sent
   • Most time-consuming step
5. Set the role (per device)
   • Waits for the device to restart with the new firmware
   • Sends the assigned role (PRIMARY or SECONDARY) to the device
6. Complete
   • Devices are updated one after another
   • Automatically proceeds to the result when every device succeeds

During Installation

• Do NOT unplug devices while installation is in progress
• Do NOT close the application. If you try, the app asks you to confirm first
• Wait for all stages to complete
• Stop ends the flash after you confirm. A stopped device may not start until you flash it again

⏱️ How long does it take? Typical installation takes 2-5 minutes per device, depending on firmware size and USB connection speed.

If a device fails, the page shows what went wrong with steps to fix it. Select Try Again to retry only the devices that failed, Start Over to go back to the start, or Copy Details to copy the log for a bug report.

Step 4: Complete

Congratulations! Your device(s) have been updated successfully.

What You'll See

• A success message: "Firmware ... is on both devices" (or "is on your device")
• Each device with its role and a Done status
• The installation log (Show Log, Copy Log, Save Log)

What To Do

1. Review the summary
   • Confirm the correct firmware version was installed
   • Verify device roles are correct
2. Disconnect your device(s)
   • You can safely unplug your devices after the update completes
   • The firmware has been written and activated
3. Test your device(s)
   • Power on your device
   • Verify the new firmware is working correctly
   • Test PRIMARY/SECONDARY communication (if using two devices). Turned on, the two devices find each other on their own
4. Select Done to return to the start of the Firmware page
   • You can perform another update if needed
   • Or configure therapy profiles
   • Or close the application

Post-Installation

Your device now has:

• The firmware version you chose installed
• Role configured (PRIMARY or SECONDARY) and saved on the device
• Ready to use!

Tips and Best Practices

Tip

• Always use the latest firmware unless you have a specific reason to use an older version
• Keep devices plugged in throughout the entire update process
• Update both devices in a pair at the same time to ensure they're running the same firmware version
• Test after updating - Verify your device works correctly after each firmware update
• Note your roles - Remember which physical device is PRIMARY and which is SECONDARY
• Configure therapy profiles after firmware update if you want to customize stimulation patterns

Related Documentation

• Therapy Profiles - Configure stimulation profiles on your devices
• Understanding Device Roles - Learn about PRIMARY and SECONDARY roles
• Getting Started - Installation and first-time setup