Skip to main content
BlueBus firmware can be upgraded via USB using Python-based tools that communicate with the on-board bootloader. The bootloader runs at 115200 baud with odd parity and implements a simple protocol for flashing firmware.

​
Prerequisites

Before upgrading, ensure you have:
  • Python 3.x installed on your system
  • USB cable (Type A to Type B Mini)
  • BlueBus firmware file (.hex format)
  • Required Python packages: pyserial, intelhex, tk-tools
Install dependencies: 
pip3 install pyserial intelhex tk-tools

​
Upgrade methods

You can upgrade firmware using either a graphical tool or command-line interface.

​
GUI firmware tool

The graphical tool provides an easy-to-use interface for firmware upgrades.
1

Connect your BlueBus

Connect the BlueBus module to your computer using a USB cable. The device will appear as:
  • Linux: /dev/ttyUSB*
  • macOS: /dev/tty.usbserial*
  • Windows: COM*
2

Launch the GUI tool

Run the graphical firmware tool:
python3 gui_firmware_tool.py
3

Select your device

From the dropdown menu, select your BlueBus device. The tool will automatically:
  • Request the platform identifier (e.g., BLUEBUS_BOOTLOADER_2_4)
  • Display current firmware version
  • Show the unit serial number
4

Select firmware file

Click “Select firmware file…” and choose your .hex firmware file.
5

Flash firmware

Click “Flash Firmware” to begin the upgrade process. The tool will:
  • Erase the flash memory (starting at address 0x1800)
  • Write firmware in 164-byte blocks
  • Display progress percentage
  • Automatically start the application when complete
The bootloader will automatically enter bootloader mode if it doesn’t detect a valid application or if the recovery pin is pulled low.

​
Console firmware tool

For automated or scripted firmware upgrades, use the command-line tool.

​
Basic upgrade

python3 console_firmware_tool.py --port /dev/ttyUSB0 --firmware bluebus_firmware.hex
The tool will automatically detect the port if only one BlueBus is connected: 
python3 console_firmware_tool.py --firmware bluebus_firmware.hex

​
Additional commands

python3 console_firmware_tool.py --port /dev/ttyUSB0 --getfw

​
Entering bootloader mode

The bootloader has a 100ms timeout window to receive commands. There are several ways to enter bootloader mode:

​
Automatic entry

The bootloader automatically activates when:
  • No valid application firmware is detected
  • The recovery pin (RD5) is pulled low at startup
  • The EEPROM bootloader mode flag is set

​
Manual entry from application

If the application is running, send the bootloader command: 
python3 console_firmware_tool.py --port /dev/ttyUSB0
Within the timeout window, the tool will:
  1. Connect at 115200 baud (no parity)
  2. Send \r to get a prompt
  3. Send bootloader\r command
  4. Wait 500ms for mode switch
  5. Reconnect at 115200 baud with odd parity
  6. Begin bootloader communication

​
Memory layout

The firmware flashing process writes to specific memory regions:
RegionStart AddressEnd AddressDescription
Bootloader0x08000x17FFProtected bootloader code
Application Start0x1800-Firmware upload begins here
Application Vector0x2000-Application entry point
Application End-0xAB000Maximum application size
The bootloader protects addresses below 0x1800 to prevent overwriting itself. Attempts to write to protected memory are automatically skipped.

​
Firmware file format

BlueBus firmware uses Intel HEX format (.hex files). The tools parse this format and:
  • Extract 24-bit instruction words from the HEX file
  • Package data in 82-instruction blocks (164 bytes)
  • Prepend each block with a 3-byte address
  • Send blocks sequentially via the bootloader protocol

​
Troubleshooting

​
Device not detected

  • Verify USB cable is connected properly
  • Check that USB drivers are installed (especially on Windows)
  • Try a different USB port
  • On Linux, ensure you have permission to access /dev/ttyUSB* (add user to dialout group)

​
Timeout errors

If you see “Failed to get a response within X seconds”:
  1. Disconnect and reconnect the USB cable
  2. Ensure no other applications are using the serial port
  3. Try manually entering bootloader mode with the recovery pin
  4. Verify the baud rate and parity settings (115200 baud, odd parity)

​
Write failures

If firmware writes fail:
  • Verify the .hex file is not corrupted
  • Ensure sufficient power supply to the BlueBus
  • Try the upgrade process again (the bootloader erases all flash before writing)

​
Platform not recognized

The tool expects one of these platform identifiers:
  • BLUEBUS_BOOTLOADER_1_3
  • BLUEBUS_BOOTLOADER_1_4
  • BLUEBUS_BOOTLOADER_1_5
  • BLUEBUS_BOOTLOADER_2_0
  • BLUEBUS_BOOTLOADER_2_1
  • BLUEBUS_BOOTLOADER_2_2
  • BLUEBUS_BOOTLOADER_2_3
  • BLUEBUS_BOOTLOADER_2_4
If you see “Unsupported device”, your bootloader may need to be updated separately.

Build docs developers (and LLMs) love

Get started for freeTalk to us