User Guide
v2.5.0
Table of contents
Booster Manager Mode
What is the Booster Manager Mode?
The Booster Manager Mode is a new feature introduced in the SidecarTridge Multi-device firmware version 2.0 . It allows users to manage microfirmware apps on the device through a web interface, making it easier to install, launch, and manage apps.
Thanks to the Booster Manager Mode, users can now easily manage microfirmware apps on the SidecarTridge Multi-device board. This mode is designed to simplify the process of installing and launching apps, providing a user-friendly web interface accessible from any device connected to the same WiFi network. As a side effect, it also helps developers to build their own microfirmware apps and test them on the device without needing to integrate with the main firmware.
In Manager mode, the Booster app will automatically connect to your configured WiFi network and will automatically connect to the public repository of microfirmware apps, displaying them in the web interface. The web interface is accessible from any computer or mobile device connected to the same WiFi network as the Booster app.
See the Booster Manager in action:
Starting with Booster v2.1.0, if Wi-Fi negotiations fail the Manager falls back to an offline-safe mode: the Atari ST terminal remains active so you can still boot the microfirmwares that are already downloaded. Press ESC on the terminal to enter the apps workflow, or hold any SHIFT key to keep booting from GEMDOS without touching the web UI.
If your network supports mDNS (.local domains), you can access the web interface at http://sidecart.local. Otherwise, use the IPv4 address shown on the Multi-device screen. See Network requirements in the Getting Started guide for details on how the device obtains its IP address (DHCP by default; static IPv4 is also supported).
The Atari ST Manager screen and the shared web status banner also show live Wi-Fi signal strength and the Pico W MAC address, and Booster replies to ICMP ping requests while connected so network troubleshooting is easier.
Note: The device needs a SDHC or SDXC microSD card formatted with exFAT or FAT32 file system to work properly. The app will warn the user if the microSD card is not present or not formatted correctly.
Web interface menu
The menu at the top of the web interface opens the Apps, Network and Config views. Its last three items open in a new tab: Help goes to this documentation, Report Issue to the page for reporting a problem, and, starting with Booster v2.5.0, News to the SidecarTridge news channel on Telegram.
Starting with Booster v2.5.0 the web interface also fits phones: the menu folds behind a Menu button and opens over the page.
The Firmware update page is not in the menu. It opens from the banner shown when a new firmware version is available.
Apps view
The Apps view is the default view when you open the web interface. It lists the apps of the catalog selected in the Config view (Stable by default) and shows which of them are already installed on the microSD card. While the catalog is being fetched, the page shows a loading indicator.
Starting with Booster v2.5.0, apps are shown as cartridges on shelves, one shelf per topic, so many apps fit on one screen. Apps with an update come first, then the other installed apps. Swipe a shelf or use its arrows to see the rest of it.
To find an app:
- Type in the Search apps box. It looks in the names, descriptions, tags and creators of the apps.
- Use the dropdowns to narrow the list by computer, by release type (Stable and beta, or only one of them) and by creator.
- Pick one of the chips under the search box to show only the apps with that tag. The number on each chip counts every app with the tag, so it can be higher than the number next to the shelf of the same name: each app sits on one shelf only.
While a filter is on, the shelves become a single list of the matching apps. Clear filters brings the shelves back.
The colour of a cartridge shows the state of the app:
- Grey: not installed.
- Putty, the colour of the Atari ST case: installed.
- Reddish, with an exclamation mark: installed, and a newer version is available.
Each cartridge has one main button: Install, or Launch when the app is installed. Select the cartridge, or its i button (the exclamation mark when there is an update), to open the app’s panel:
The panel shows:
- Name, version and creator of the app, with a link to the creator’s website when the catalog has one.
- Description: what the app does. Most descriptions end with a Learn more link to the app’s documentation.
- Features: the tags of the app, in grey.
- Computers: the computers supported by the app, in red.
When the catalog publishes more than one version of an app, the panel also shows a Version dropdown. The latest version is selected by default; the older versions still published are listed after it, and the installed version is marked “(current)” when it is not the latest. Pick an older version to roll back to it.
The panel buttons are:
- Install vX / Update to vX / Downgrade to vX: installs the version selected in the dropdown to the microSD card. The label says what will happen compared to the installed version, and the button is hidden when the selected version is the one already installed. A downgrade asks for confirmation.
- Launch: copies the installed app into the flash memory of the device, reboots the device and starts the app.
- Delete: removes the app from the microSD card. You can install it again at any time.
- Restore and launch and Restore config only: only on the DEV APP, for microfirmware developers. See Debugging in Visual Studio Code.
When you launch an app, the web page and the computer screen say that the app is being copied. Do not refresh or leave the page until the app is launched. Booster does its best to reset the computer at the end, but this is not always possible: if the app does not start, power-cycle the computer with the device connected.
From then on the app stays in the flash memory of the device and starts every time you power it on. To return to the Booster app, use the command menu of the app, or hold the SELECT button for more than 10 seconds and then power-cycle the device and the computer.
Starting with Booster v2.5.0, a launch that fails is reported instead of retried forever: the computer screen shows Launch failed and the device restarts into Booster, so you can launch the app again. If the power is cut while an app is being copied, the device starts Booster at the next power-on instead of a half-copied app.
Launching apps from the Atari keyboard
When the ST keyboard is handy, press ESC on the Booster screen to open the apps workflow, or hold any SHIFT key to continue booting from GEMDOS. This works even when WiFi is not available, so any app already on the microSD card can still be launched offline.
Starting with Booster v2.5.0, the apps workflow lists the apps on the card 18 to a page. Press N and P for the next and previous page, and type the number of any app to launch it from any page.
Settings of each app
Each app keeps its settings in one of 30 slots in the flash memory of the device. Starting with Booster v2.5.0, an app takes a slot the first time it is launched, not when it is installed, so apps you install but never run do not use one. When all 30 slots are in use, launching another app moves the settings of the app launched least recently to the microSD card, as <uuid>.cfg in the apps folder. That app gets them back the next time you launch it. You can install and use any number of apps, and each one keeps its settings.
On the Apps page, an app whose settings are on the card says so in small grey text under its name. The .cfg files travel with the microSD card, so keep the card with the device: another device that launches the same app restores those settings.
The apps folder also holds .lookup, a copy of the device’s list of slots. If the power is cut while that list is being saved, the device puts it back from the copy at the next start. Deleting an app also removes its .cfg file.
Network view
The Network view shows the list of available WiFi networks and permits some basic network configuration options:
- Country: The country code of the WiFi network. This is used to configure the WiFi module to use the correct channels and frequencies.
- Hostname: The hostname of the device. This is used to identify the device on the network. By default is
sidecart. - Wifi Power: The power of the WiFi module. From 0 to 4.
- Show RSSI: Show the RSSI value in dBm for visible WiFi networks. This helps estimate signal strength and connection stability.
- DHCP Enabled: Enable or disable DHCP on the device. Enabled by default, which works out of the box on any home or small-office network. Disable it only if your network has no DHCP server (industrial VLANs, isolated segments, captive portals): the TCP/IP settings view will then let you enter a static IPv4 address, netmask, gateway, and DNS servers. Starting with Booster v2.5.0, these values are checked when you click Save: if one is not valid, the page names it and nothing is saved.
When Show RSSI is enabled, the device can show the RSSI value of nearby WiFi networks. As a general reference, use the first matching threshold in the table below.
| RSSI Value (dBm) | Signal Strength | Probability of Good Connectivity |
|---|---|---|
>= -30 dBm | Excellent | Very high |
>= -40 dBm | Very good | High |
>= -50 dBm | Good | Good |
>= -60 dBm | OK | Usually good |
>= -67 dBm | Minimum for stable WiFi | Acceptable |
>= -70 dBm | Weak | Borderline |
>= -80 dBm | Very weak | Low |
< -80 dBm | Almost unusable | Very low |
Below -80 dBm, the signal strength is considered weak and can lead to connectivity issues. The board may fail to connect to the selected WiFi network, lose the connection intermittently, or take longer to obtain an IP address from DHCP. Monitoring RSSI values helps you identify networks with stronger signals and connect to more reliable WiFi networks.
Don’t forget to click the Save button to save the changes!
While a .wificonf file is on the microSD card (Booster v2.4.2 and later), a banner at the top of this view says so, and the TCP/IP configuration and the Network list are grayed out and read-only. The file applies those settings again at every boot, so a change made here would be lost at the next reboot. The WiFi settings (country, hostname, power and RSSI) stay editable. To change the network from this view, delete or rename the file and power-cycle the device. See Auto setup and headless factory configuration.
It’s also possible to change the WiFi network. To do this, click on the new WiFi network from the list. A new window will open with the WiFi network details. Enter the password and click the Connect button.
The Booster app will save the WiFi credentials to flash memory and reboot. It will then connect to your WiFi network and show a message on the computer screen.
Note: If the Booster app is not able to connect to the WiFi network, Starting with Booster v2.1.0 the Manager will stay in offline mode so you can still launch already-downloaded apps from the keyboard. Only press the SELECT button for ten seconds (to return to Factory mode) if you actually need to reconfigure Wi-Fi from scratch.
Config view
The Config view shows the device information and some basic configuration options. Before Booster v2.5.0 this page was called the Device view.
- Apps folder: The folder where the apps are stored. By default is
/apps. This folder is created on the microSD card when the Booster app is launched for the first time if it does not exist. - Apps catalog URL: The catalog the Apps view loads. Choose Stable - Tested release (the default), Testing - unstable releases, Development - Local development only, or Custom catalog URL to type your own. A custom catalog’s
apps.jsonfile must be reachable over HTTP. Microfirmware developers need Development: it lists the DEV APP. - Boot feature: The UUID of the microfirmware app to load at boot time, or the Booster factory path. If the app cannot find the configured UUID in flash memory, it will load the Booster app in Manager mode.
- SD card baud rate (KB): The speed of the microSD card, chosen from a list between
1000and24000. The default is12500. Lower it if your card gives read errors.
Don’t forget to click the Save button to save the changes!
It also provides two buttons to reboot the device:
- Reboot the device: Reboot the device and load the microfirmware app in flash memory. This is the normal way to reboot the device.
- Restore to the default fabric settings: Reboot the device and load the Booster app in Factory mode. This is useful to reset the WiFi configuration or return the device to its default setup.
Firmware update
Starting in version v2.0.6 Beta you don’t need to download the newer firmware version manually. Instead, the Booster app reports available updates and guides you through the installation process.
When a new firmware version is available, the Booster app shows a Firmware update available banner at the top of the Apps, Network and Config views, with the target version, a link to the changelog so you can review the release notes, and an Upgrade button.
The upgrade has two steps. Keep the page open and do not refresh it until it finishes.
Download. Click Continue upgrading. The device downloads the new firmware and its checksum to the apps folder of the microSD card and checks one against the other. This can take up to two minutes, depending on your network. The screen of the Atari 16/32 computer displays the progress.
Install. Click Confirm firmware upgrade. The device restarts into the installer, which checks the whole file on the microSD card, writes the new firmware to flash, reads it back and starts it. This takes about a minute, and the computer screen turns black while it happens.
If the download fails or does not match its checksum, the upgrade is refused before anything is written to flash. The page says why and the current firmware keeps running, so you can try again later.
After the upgrade, the WiFi, network and Config view settings and the settings saved by each app are kept. The app that was in the device is replaced by the placeholder that ships with the firmware: it is still on the microSD card, so launch it again from the Apps view.
Do not power off the device while the new firmware is being installed. Starting with Booster v2.5.0, if the power is cut anyway or the microSD card cannot be read, power the device on again with the same card in and the installer starts over. With older versions an interrupted update could leave the device unable to start; in that case, perform a fresh installation of the firmware.