Skip to content

Install to Internal Flash

Installing to internal flash replaces the installed kernel and root filesystem with libretouch. It keeps the stock bootloader and manufacturing data.

There are two supported routes:

  • Network installation is the convenient choice while the stock firmware and its update service are working.
  • USB installation from U-Boot does not depend on the installed operating system or its network. Keep this route available for reinstalling an image that does not boot or work as expected.

Hardware status: Network installation has been completed successfully on spotty_sm2 (SoundTouch 20 Series III). Images can contain other supported board targets, but treat installation on a board not marked as supported in the project status as experimental. Recovery is considerably harder on SCM hardware than on SM2 hardware.

Prerequisite: The device must be running stock firmware 15.00.20 or newer. libretouch keeps the stock bootloader and requires the device-tree-capable version introduced by 15.00.20. See Prerequisites.

What you need

  • For local-server or USB installation, the .stu file built for internal-flash installation. An external update service hosts its own index and package, so that mode needs the index URL instead of a local .stu.
  • Stable power for the complete erase, write, and reboot sequence.

If building the image yourself, create it with:

MACHINE=libretouch-nand bitbake libretouch-image-nand

The resulting .stu is in the build's image deployment directory. A release download may use a shorter filename, but it is the same package format.

The package contains the installer, kernel, and root filesystem. It does not contain MLO or U-Boot, and the installer does not write the bootloader, bootloader environment, or manufacturing-data partitions.

Before installing, it is worth preparing a FAT32 recovery stick as described in Install or recover from USB. It remains usable even if the newly installed userspace or networking does not start.

Install over the network

For this route you also need:

  • the upload_stu.py script distributed with libretouch, in tools/;
  • Python 3.10 or newer on a computer connected to the same network as the SoundTouch device—the script uses only the Python standard library;
  • the device's IP address, normally visible in the SoundTouch app or in the connected-device list of the network router.

Keep the device powered on and booted into the stock firmware. From the directory containing upload_stu.py, run:

python3 upload_stu.py DEVICE_IP IMAGE.stu

For example:

python3 upload_stu.py 192.168.1.42 libretouch-image-nand.stu

Before asking for confirmation, the script:

  1. validates the STU header and every section checksum;
  2. reads the board targets embedded in the package;
  3. builds an update index containing the matching device IDs and product names;
  4. checks that the stock update API answers on the device.

Review the displayed targets and answer y only if they include the device being installed. The script then starts a temporary HTTP server on the computer, asks the device to fetch the generated index, serves the .stu, and monitors update status.

The normal sequence is IDLE, DOWNLOADING, installation, and a reboot. The network connection can disappear while the device installs or reboots. This is expected after the script reports that the complete package was delivered.

Do not disconnect power after confirming the installation. Wait for the script to report completion or that the fully transferred device has gone offline for installation/reboot. The flash write continues on the device; closing the terminal does not abort it safely.

The installer writes the inactive kernel and root-filesystem slot first. It marks that slot bootable only after the complete package and both payloads pass their checksum checks. On the next reboot, the stock bootloader selects the new slot and starts libretouch.

Install or recover from USB

The stock bootloader can install the same .stu directly from a USB stick. It does not start Linux, so this remains available when libretouch fails during boot, has broken networking, or otherwise cannot run an updater itself. This route requires a serial console to reach the U-Boot prompt. Model-specific emergency button combinations are intended for complete stock packages and should not be used with a libretouch package, which deliberately contains no bootloader images.

Prepare the stick before relying on it:

  1. Format a USB drive as FAT32, using its first partition.
  2. Rename the libretouch package exactly Update.stu and copy it to the root of that partition. Leave other update images off the stick.
  3. Insert the stick in the device's USB setup port before applying power.

Small, plain USB 2.0 sticks are the most reliable with the old bootloader. If it stops at scanning bus for devices, try a different stick.

Connect the serial console and apply power. The stock bootloader offers a short window to stop autoboot, and it accepts exactly one key:

Autoboot in 5 seconds ('U' to stop):
U-Boot#

Press U — not any other key — and keep pressing it until the U-Boot# prompt appears. For a cautious first installation, update only Pong:

U-Boot# sweup

This keeps Ping as the previous-firmware fallback. To reinstall libretouch after a failed installation, or to make both slots contain the same known-good image while retaining persistent settings, use:

U-Boot# sweup preserve

sweup preserve rewrites both kernel/root-filesystem slot pairs. It does not rewrite the bootloader, but unlike plain sweup it also removes the old-system slot as a fallback. Use it when the goal is a complete repair rather than a cautious first trial.

The bootloader prints each section and verifies its CRC before erasing NAND. Wait for eUpdate DONE; do not reset or disconnect power while the command is running. Then remove the stick and reset the device:

U-Boot# reset

For the full command matrix, slot behavior, console output, and model-specific USB details, see the U-Boot update mechanism.

Network-server options

By default, the script listens on TCP port 8000 and automatically determines which address the device should use to reach the computer. Allow inbound TCP connections to that port in the computer's firewall for the duration of the installation.

If the automatic address is wrong, specify an address on the same reachable network as the device:

python3 upload_stu.py 192.168.1.42 IMAGE.stu \
    --advertise-address 192.168.1.10

If port 8000 is already in use, select another allowed port, or use 0 to let the operating system select one:

python3 upload_stu.py 192.168.1.42 IMAGE.stu --serve-port 8080

An existing update service can be used instead of the temporary server. Its index must already contain the correct device entries and refer to a .stu package hosted by that service:

python3 upload_stu.py 192.168.1.42 \
    --update-server https://updates.example.net/libretouch/index.xml

If the supplied URL ends in /, the script appends index.xml. In this mode, do not specify a local .stu argument. The script passes the index URL to the device and monitors the update; it does not upload anything, generate the index, or validate the externally hosted package. Both the index and package must already be available to the device, and the external service is responsible for their target metadata, lengths, and checksums.

To inspect the built-in device-ID table without starting an update:

python3 upload_stu.py --list-devices

--device-id is an expert override for a package whose revision does not name a known target. Do not use it merely to silence a target mismatch: an ID can make the stock updater accept an image that was not built for that hardware.

Troubleshooting

The update API cannot be reached

Confirm that the device is still running stock firmware, that its IP address has not changed, and that the computer can reach it. The update API is supplied by the stock system; it is not expected to answer after libretouch has booted.

The device never requests the package

The device must be able to open the index URL printed by the script. Check the computer's firewall, the selected --serve-port, and the address printed in the URL. Use --advertise-address if the computer has VPN, container, or multiple network interfaces and the script selected the wrong one.

The package target is unknown

Run upload_stu.py --list-devices and check the module and codename. A normal release package should select its entries automatically. Stop rather than guessing if the actual hardware is not one of the package's displayed targets.

The device reports that an update is already active

If a real update is running, let it finish. If no transfer or installation is active and the state remains stuck after several minutes, reboot the stock firmware normally and retry. Do not remove power while flash is being written.

Confirm the installed system

Allow the device to finish rebooting. With a serial console, confirm that libretouch reaches its login prompt and inspect the selected slot:

cat /proc/cmdline
cat /proc/mtd

The ubi.mtd= value identifies the running root-filesystem slot. In the standard partition map, NAND.File-System-Ping is MTD 8 and NAND.File-System-Pong is MTD 9.

An installed system stays on the network, so this is the point to deal with its open root access: it runs an SSH server and root logs in without a password. Set one now, or keep the device off untrusted networks — see the security note.

passwd

If boot stops at the initramfs emergency shell

Use the serial console to inspect the selected NAND root filesystem without changing it. First identify the selected slot with the two commands above. Attach that partition with its 2048-byte UBI header offset, then mount its rootfs volume read-only:

mkdir -p /mnt/root
ubiattach /dev/ubi_ctrl -m 8 -O 2048   # Ping; use -m 9 for Pong
ubinfo -a
mount -t ubifs -o ro ubi0:rootfs /mnt/root

If ubiattach reports that the device is already attached, do not attach it again. Use ubinfo -a to identify its UBI number and substitute that number for ubi0 in the mount command. The mounted tree is for inspection and copying only; do not remount it read-write or write to NAND from this shell without a separate recovery plan.

Other installation and recovery routes

Because the stock bootloader is retained, returning to stock firmware remains possible through Restore stock firmware. For an SM2 device that no longer boots from NAND, see Unbrick a device.