Skip to content

libretouch User Documentation

libretouch is an alternative firmware for Bose SoundTouch hardware. It is a board-support system: the hardware works — audio, Wi-Fi, Bluetooth, display, buttons, the IR receiver — but there is no player application on top of it. What you get is a "blank" Linux system on the device, reachable over the network and over a serial console.

These pages cover building an image, getting it onto a device, getting back off it again, and recovering a device that no longer boots.

Does this work on my device?

Yes. Every SoundTouch device is built around the same TI AM3356 SoC on one of two processor modules, and libretouch supports both. What differs from product to product is how completely the board around that module is described.

Device Support
SoundTouch 20 Series III (spotty_sm2) Full. Audio, Wi-Fi, Bluetooth, display, keypad, IR, USB and NAND all work, and it can be installed to internal flash.
Every other SoundTouch device Limited. Boots to a shell on the generic module device tree, which describes the SoC, memory, NAND, USB and the serial console. The front panel and audio routing need a board description of their own.

This table will grow. The SoundTouch adapter (lisa_scm) is the board currently being worked on, and "limited" is where every product starts — Add support for a new device is the path from one row to the other.

Hardware overview lists every known model with its board and status. Look up the board rather than the product name: one board is often sold under several names, and lisa_scm alone answers to seven of them depending on which host system it is cabled to. If you are not sure what you have, Identify the board shows how to read the name off the device itself.

Not every device has a USB-A socket. All of them have the micro-USB service port, so USB RNDIS network boot works everywhere; booting from a USB drive needs a socket to plug the drive into. USB ports says which models have one.

Security of the shipped images

The images are development images. They run an SSH server, and root can log in over the network without a password. Anyone who can reach the device can take full control of it. This is deliberate — the system is still being brought up, and a device whose userspace fails to start has to stay reachable — but it means a libretouch device does not belong on an untrusted network, and must never be exposed to the internet.

On a shared network, use a serial console instead, or set a root password with passwd after first boot. The same caveat applies to the recovery paths: USB RNDIS network boot puts an unauthenticated shell on the link between your computer and the device.

Before you start

Stock firmware 15.00.20 or newer has to be installed, on any device and for every procedure here. libretouch keeps the stock bootloader and boots through it, and only that version onwards can boot with a device tree. Prerequisites explains how to check, what to do about an older device, and why lisa_scm prefers a specific version.

Getting libretouch onto a device

Start by building an image. From there the route depends on the socket the device has:

Neither touches the internal flash. Development setups covers running libretouch this way day to day, and installing to internal flash is the permanent step once a device is proven.

Installation and recovery

Using the device

Extending libretouch