USB File Transfer (Update Mode)

Update Mode exposes the scooter as a USB drive on your computer. Copy files into the appropriate folder, safely eject the drive, and the scooter processes them automatically.

Entering Update Mode

You can enter Update Mode from the dashboard or the command line.

From the dashboard

  1. Double-tap the left brake to open the menu
  2. Go to Settings → System → Update Mode…

From the CLI

lsc usb ums

To switch back to normal (network) mode:

lsc usb normal

Leaving Update Mode

Hold the left brake for 3 seconds. The dashboard shows the hold as Cancel while Update Mode is still preparing, and as Exit once the drive is live.

  • While preparing: the entry is abandoned before the USB gadget switches over, so the network connection is never dropped.
  • Once active: the scooter switches the USB port back to network mode and processes whatever is on the drive, exactly as it does after an eject. Eject on your computer first so the files are fully written.

No other gesture leaves Update Mode. A right brake press or a seatbox tap is ignored on purpose, so a stray input can't interrupt a transfer. lsc usb normal works too.

Transferring files

  1. Open the footwell with a PH2 Phillips or H4 hex driver to reach the MDB. Its Mini-B port is normally occupied by the internal DBC USB cable.
  2. Undo the cable's retaining screw with a flat-head or PH1 screwdriver, then disconnect the internal DBC USB cable from the MDB.
  3. Connect your computer to that Mini-B port.
  4. A drive appears on your computer.
  5. Copy files into the appropriate folder (see below).
  6. Safely eject the drive. The scooter processes the files; a firmware update then triggers a reboot.
  7. Leave Update Mode, disconnect your computer, then reconnect and secure the internal DBC USB cable.
Open scooter footwell, showing the MDB in its installation position

The MDB sits in the open footwell.

Internal DBC USB cable unplugged from the MDB Mini-B port

Disconnect the internal DBC USB cable to free the Mini-B port.

After processing, the drive is wiped apart from ums_log.txt, so the next session starts clean.

What's on the drive

The scooter creates these folders when Update Mode starts.

PathWhat it's for
system-update/Firmware artifacts, .mender or .delta
maps/Map display tiles and Valhalla routing tiles

Map display tiles

Copy any .mbtiles file into the maps/ folder on the drive. The scooter installs it as the offline map source.

Download pre-built tiles from Librescoot OSM Tiles releases.

Valhalla routing tiles

Compressed routing tiles are supported.
Prefer a .tar.zst release: it reduces the download and USB transfer size, and the scooter unpacks it automatically.

Copy the downloaded archive into the maps/ folder as-is. The scooter accepts any file name ending in tiles.tar or tiles.tar.zst, including release files such as valhalla_tiles_<region>.tar.zst.

Download pre-built routing tiles from Librescoot Valhalla Tiles releases.

Firmware updates

Copy .mender or .delta artifacts into the system-update/ folder to install a firmware update without a SIM card. This is the only thing that triggers a reboot; everything else is applied by restarting the affected service.

Troubleshooting

  • Drive doesn't appear: make sure the scooter is in Update Mode (check dashboard or run lsc usb status). Try a different USB cable.
  • Files not applied after eject: check that you safely ejected (not just unplugged). The scooter needs the eject event to trigger processing.
  • Scooter doesn't reboot: reconnect USB and eject again, or reboot manually with lsc power reboot. A USB update can simply be retried from the start.
  • Wrong channel or map region installed: the scooter installs exactly the files you copied, and a firmware artifact from another release channel switches you to that channel. Download the artifact or tiles for the channel and region you want now and run another Update Mode session.

Configuration and diagnostics

Update Mode is managed by ums-service on the MDB. It switches the USB port from network mode (USB Ethernet) to USB Mass Storage mode, exposing a partition on the scooter's eMMC as a removable drive. When the drive is ejected, ums-service detects the eject event and works through the drive in a fixed order: settings, WireGuard, radio-gaga, uplink-service, onboot.sh, firmware updates, maps, scripts. Each step is independent, so one failing doesn't stop the rest, and ums_log.txt records what each one did.

In addition to the two rider-facing folders above, the drive contains:

PathDirectionWhat it's for
scripts/mdb.sh, scripts/dbc.shto scooterShell scripts run once on the named board
settings.tomlround-tripCurrent settings, exported for you to edit and read back
wireguard/round-tripWireGuard configs, exported and read back
radio-gaga/config.yamlround-tripradio-gaga telemetry config
uplink-service/config.yamlround-tripuplink-service config
onboot.shround-tripScript the scooter runs on every boot
diagnostics/mdb/, diagnostics/dbc/scooter writes itjournal.log and dmesg.log from each board, collected on entry
log-bundles/scooter writes itBundles previously captured with lsc, copied out for you
ums_log.txtscooter writes itWhat happened during processing. Written on the way out and kept when the drive is wiped

Round-trip means the scooter writes its current file to the drive when Update Mode starts and reads it back when you leave. Edit exported files in place, keeping unrelated settings and credentials. If a file is absent because the feature has not been configured, you can create it at the exact path shown above. Use a plain-text editor, UTF-8 and Unix (LF) line endings, and check that your editor has not added .txt to the filename.

Keep a secure backup before editing: WireGuard and service configurations can contain private keys or tokens. Missing settings.toml, service YAML files or onboot.sh leave the installed versions unchanged. WireGuard has different removal rules, described below.

Configuration

Changing settings.toml or anything under wireguard/ restarts librescoot-settings. Changing radio-gaga/config.yaml restarts radio-gaga, and uplink-service/config.yaml restarts librescoot-uplink. Nothing is restarted if the file came back unchanged.

settings.toml

Settings use TOML sections, with keys and values below each section heading. For example, these entries correspond to dashboard.language and dashboard.theme:

[dashboard]
language = "en"
theme = "auto"

Edit the values under the existing [dashboard] heading. Quote strings; write booleans as true/false and numbers without quotes. Keep the rest of the exported file: the import replaces the on-disk TOML file rather than merging a small fragment. Invalid TOML is skipped. See the Settings Reference for supported keys, types and values.

wireguard/*.conf

Put one standard WireGuard INI configuration per tunnel directly in wireguard/, for example wireguard/wg-scooter.conf. It needs an [Interface] section containing the scooter's private key and tunnel address, plus a [Peer] section with the server's public key, endpoint and allowed networks. The WireGuard setup guide includes a complete example, server-side peer settings and connection checks.

The folder is authoritative: deleting an exported .conf removes that tunnel, and leaving wireguard/ empty removes all managed tunnels. Removing the folder itself leaves the installed files unchanged. Other extensions and subfolders are not imported. UMS copies the files; NetworkManager validates their contents when settings-service imports them.

Service configuration files

radio-gaga/config.yaml and uplink-service/config.yaml configure the two optional online services. Use spaces for YAML indentation and keep your existing connection details. The following excerpts show the connection fields; keep the other sections of your exported file.

For radio-gaga, the endpoint is an MQTT broker and the scooter identifier/token authenticate to it:

mqtt:
  broker_url: "ssl://mqtt.example.net:8883"
scooter:
  identifier: "YOUR_SCOOTER_IDENTIFIER"
  token: "YOUR_AUTH_TOKEN"

Keep any existing mqtt.ca_cert path or mqtt.ca_cert_embedded certificate data. Certificate paths resolve on the MDB. For a new installation, start with the radio-gaga example and fill in the endpoint, credentials and CA certificate for your backend.

For uplink-service, use its WebSocket endpoint and its own credentials:

uplink:
  server_url: "wss://uplink.example.net/ws"
scooter:
  identifier: "YOUR_SCOOTER_IDENTIFIER"
  token: "YOUR_AUTH_TOKEN"

See the uplink-service example for the full structure. Fill in your WebSocket server's endpoint and credentials. Copy the configuration to the exact USB path above even if the upstream example has another filename. Check the service's journal for configuration errors if it fails to start after import.

One-time scripts and onboot.sh

scripts/mdb.sh and scripts/dbc.sh run once, under Bash, on the named board. The DBC script is skipped if the DBC cannot be reached. Use a plain-text shell script, for example:

#!/bin/bash
set -eu
logger -t ums-script "USB maintenance script ran"

onboot.sh at the drive root is different: it installs /data/onboot.sh on the MDB for future boots, and is not run immediately on import. It must start with a shebang such as #!/bin/sh and pass a shell syntax check. A minimal example is:

#!/bin/sh
logger -t onboot "Custom MDB boot script ran"

UMS sets executable permissions on installed scripts. Make boot scripts safe to run repeatedly; deleting onboot.sh from the USB drive does not uninstall it. To disable it through USB, replace its contents with #!/bin/sh followed by exit 0.

Exported logs

diagnostics/mdb/journal.log, diagnostics/mdb/dmesg.log and their DBC equivalents contain plain-text diagnostic output. DBC output depends on the board being reachable. Copy these files and any log-bundles/ you need to your computer before leaving Update Mode. Check ums_log.txt for import results; the other files are cleared after processing.

Scripts run as root

Review scripts before importing them: they have full access to the board on which they run.

← Navigation Setup lsc CLI Reference →