2 stable releases
1.1.0 | Jul 30, 2022 |
---|---|
1.0.0 | Mar 21, 2022 |
#1689 in Command line utilities
49KB
898 lines
For users
bose-dfu is an open-source, command-line firmware update tool for certain Bose speakers and headphones. Unlike Bose's official updater, bose-dfu
- runs on Windows, macOS, Linux, and any other OS supported by Rust and HIDAPI
- can downgrade firmware as well as upgrade it
- doesn't rely on a web service to run
Using this tool, you can enter and leave firmware update ("DFU") mode on compatible devices connected via USB. After putting a device in DFU mode, you can write new firmware to it.
See the next section for a list of devices known to be compatible and the one after that for instructions on how to find firmware images for your device (which can also help you determine compatibility).
Tested devices
Use this tool at your own risk. I will not take responsibility for damage bose-dfu does to your device, even if that device is on the following list:
- SoundLink Color II (used for initial development)
It's likely that most Bose devices that take updates in .dfu
format work with
this tool, but I can't guarantee that. If your device isn't on the list above
and you use this tool, you are volunteering to potentially brick your
device. bose-dfu will warn you before it operates on an untested device. If
you successfully use bose-dfu with such a device, please open a pull request to
add it to the list.
Incompatible devices
The following devices are known not to work with bose-dfu because they use a substantially different update protocol:
- Noise Cancelling Headphones 700 (tchebb/bose-dfu#1)
Obtaining firmware
No firmware images are included with this tool, so you'll have to obtain those
yourself. Firmware images end in the extension .dfu
, and this tool does some
basic verification of images you attempt to write to ensure they are for the
right device and have not mistakenly become corrupt. There are two ways to get
official firmware images that I'm aware of: directly from Bose, and via the
unofficial archive linked above.
Directly from Bose
Bose hosts the latest firmware (and possibly earlier ones, too) for each device at https://downloads.bose.com/. Although directory listings aren't enabled, https://downloads.bose.com/lookup.xml lists all devices.
Each <PRODUCT>
element in lookup.xml
holds both the USB product ID of that
device when in DFU mode and the URL of an index.xml
file for the device.
index.xml
lives in a directory named for the device's codename and holds the
filename(s) of its latest firmware image in one or more <IMAGE>
elements.
Firmware files live alongside the index.xml
file that refers to them.
To find firmware for your device, you can run bose-dfu info
and match the
"Device model" field against directory names on Bose's server. Alternatively,
you can put your device in DFU mode using bose-dfu enter-dfu
, get its USB ID
using bose-dfu list
, and match its USB PID (the part of the ID after the
colon) against a <PRODUCT>
element in lookup.xml
.
Via unofficial archive
The bosefirmware GitHub user maintains repositories
archiving old firmwares for various lines of Bose devices. Several of these
repositories, most notably ced, contain .dfu
files.
I am not affiliated with this user and do not guarantee the authenticity or accuracy of the files their repositories contain.
Installation
If you already have a Rust toolchain installed on your computer, installing
bose-dfu is as simple as running cargo install bose-dfu
. To get a Rust
toolchain, you can use rustup or install rust
using
your system's package manager.
Alternatively, you can find prebuilt binaries for Linux, Windows, and macOS on the releases page.
If you use Linux and encounter permission errors or see INVALID
in the output
of bose-dfu list
, you likely need to give your user permission to access Bose
HID devices. You can do this by copying 70-bose-dfu.rules
into
/etc/udev/rules.d/
and reconnecting the device (no reboot needed). If your
device is untested, it won't have an entry in that file so you'll need to add
one yourself.
Usage
bose-dfu has several subcommands, which are summarized in its help text:
bose-dfu 1.0.0
Firmware updater for various Bose devices
USAGE:
bose-dfu <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
-V, --version Print version information
SUBCOMMANDS:
list List all connected Bose HID devices (vendor ID 0x05a7)
info Get information about a specific device not in DFU mode
enter-dfu Put a device into DFU mode
leave-dfu Take a device out of DFU mode
download Write firmware to a device in DFU mode
file-info Print metadata about a firmware file, no device needed
help Print this message or the help of the given subcommand(s)
To update a device, you'll need to run at least bose-dfu enter-dfu
, bose-dfu download
, and bose-dfu leave-dfu
, in that order. The other subcommands help
you inspect the current state of devices and firmware files. Notable is info
,
which tells you the current firmware version a device is running.
Subcommands that perform an operation on a device support arguments for
selecting which device to talk to. You can use -p
to select by USB product
ID, -s
to select by USB serial number, or both together. Additionally, the
same subcommands support the -f
/--force
flag, which has no effect for
tested devices but is required to perform operations on untested ones.
FAQ
Can updating my device's firmware brick it?
Quite possibly; there have been reports online of even the official Bose updater bricking headphones. That being said, my SoundLink Color II falls back to DFU mode when its firmware is corrupt, allowing for easy recovery. I have not yet managed to brick it while developing this tool, and my attempts have included intentionally disconnecting its USB cable in the middle of a firmware download.
Can bose-dfu read firmware as well as writing it?
Not out of the box. Although USB DFU supports an upload operation, which is
supposed to read back the exact firmware that was last downloaded, Bose's
implementation of it returns an image that's not identical and which can't be
successfully re-downloaded. As such, I've intentionally omitted an upload
subcommand to prevent confusion. There is an upload()
function in
src/protocol.rs
, though: if you want to use it, adding a corresponding
subcommand is up to you.
For developers
Protocol
The USB protocol implemented herein was derived entirely from USB captures of Bose's official firmware updater. No binary reversing techniques were used to ascertain or implement the protocol.
Bose's DFU protocol is nearly identical to the USB DFU protocol, except it communicates via USB HID reports instead of raw USB transfers. This one main change, presumably made because communicating with an HID device doesn't require custom drivers on any major OS, seems to imply all the other notable changes (e.g. an added header for uploads and downloads to hold fields that would otherwise be part of the Setup Packet).
As such, I have not written a formal protocol description for Bose DFU. The USB DFU specification, in combination with this tool's source code and comments therein, should sufficiently document the protocol.
Prior work
I am not aware of any other third-party implementations of this protocol. However, Bose appears to have at least two first-party implementations: the first is the "Bose Updater" website and associated native application available at https://btu.bose.com/, which is what I took USB captures from in order to develop bose-dfu. I did not inspect it in any further detail.
The second is the Electron-based "Bose USB Link Updater",
which bundles and invokes a patched version of dfu-util that
implements this protocol (which Bose seems to call "USB-DFU" based on strings
in the Electron code). It also includes a custom utility called "dfuhid" that
puts a device into DFU mode, serving the same purpose as bose-dfu enter-dfu
.
Notably, I have been unable to find source code for this modified dfu-util. dfu-util is a GPL application, so Bose is obligated to provide source upon request. However, based on their license text, I expect they will honor this obligation only if you mail them a physical letter and pay for them to ship you the source on physical media. This is more work than I want to do, but I will happily review the source if someone else goes to the trouble of getting it. It may well contain useful information that can be used to increase bose-dfu's reliability or device compatibility.
Dependencies
~6–16MB
~191K SLoC