bananarchy/MANUAL.md

# Bananarchy Linux — user, flashing, and customization manual

![Bananarchy Banner](artwork/banner-800x240.png)

This manual covers flashing, operating, and customizing **Bananarchy Linux** (`240x320` native edition) on **Qualcomm MSM8905 and MSM8909** Nokia feature phones:
- **Nokia 8110 4G (`nokia-argon`)**
- **Nokia 2720 Flip (`nokia-beatles`)**
- **Nokia 800 Tough (`nokia-tough` / `nokia-coconut`)**
- **Nokia 8000 4G (`nokia-sparkler`)** and **Nokia 6300 4G (`nokia-leo`)**

---

## 1. System overview and workspace contents

### 1.1 System images (`images/`)
- `images/bananarchy-nokia-argon.img`: partitioned MBR image (`256 MiB` `ext2` `pmOS_boot` + `ext4` `pmOS_root`) ready for EDL flashing to `userdata`, `fastboot flash userdata`, or raw `dd` to a microSD card.
- Additional device images (`bananarchy-nokia-beatles.img`, `bananarchy-nokia-tough.img`, `bananarchy-nokia-sparkler.img`) can be generated at any time via `./rebuild-image.sh <device> --mkinitfs`.

### 1.2 Bootloader and EDL programmer (`bootloader/`)
- `bootloader/lk2nd-msm8909.img`: secondary bootloader (`lk2nd`) providing Fastboot and `extlinux` boot discovery for MSM8905 and MSM8909 devices.
- `bootloader/loaders/8110.mbn`: signed Qualcomm Sahara/Firehose programmer (`05c6:9008`).

### 1.3 Core architecture highlights
1. **Pure X11 (`Xlibre` + `sxmo-de-dwm`) for `240x320` QVGA displays**:
   - Uses a lightweight cross-compiled **Xlibre** server with `modesetting` KMS, partial-rectangle `ShadowFB` SPI updates, and zero Wayland overhead.
   - **Patched `dwm`** provides a `240x320` vertical bottom-stack (`bstack`) layout, a 24px top status bar, a transparent `"Menu"` / `"Names"` desktop softkey bar, a Conky desktop clock and status widget (which refreshes automatically when changing time, timezone, or wallpaper, or when logging out), and `< 2 ms` handling of physical slider (`SW_LID`) and wake keys.
2. **Preloaded resident DWM plugins (`< 2 ms` wakeup)**:
   - Core phone applications (`dmenu`, `xdrawer`, `dialer`, `calllog`, `callscreen`, `contacts`, `sms`, `files`, `camera`, `themes`, `modem`, `networks`, `ringtones`, `wallpapers`, `music`) run as preloaded resident daemons (`dwm-plugin <name> --preload`) that sleep at 0% CPU and open instantaneously over FIFO/socket IPC.
   - All UI elements share a single **XRDB theming engine** (`~/.xthemes/*.xth` -> `~/.Xresources`) with 20 preinstalled color schemes, proportional font sizing (`theme.baseFontSize`), and live reload without restarting X11.
3. **First-class terminal (`st`) and 6-mode `fcitx5-t9` keypad input**:
   - `st` is patched with HarfBuzz OpenType ligature shaping (`Fira Code` default) and live `.Xresources` reload.
   - `fcitx5-t9` provides 6 keypad input modes (`abc`, `Abc`, `ABC`, `Sym`, `Ctl`, `123` + `*` long-press `Ctrl+` latch) in a fixed bottom candidate bar (`Y = 290, H = 30`).
4. **Mainline Linux 6.12 hardware drivers**:
   - **QDSP6 / Q6Voice audio and Dual-SIM modem**: loudspeaker, boosted (+6 dB) earpiece, internal MEMS and headset microphones, `ModemManager` + `q6voiced` call audio routing, and direct Qualcomm QMI UIM Dual-SIM slot switching, PIN/PUK management, and SIM phonebook access.
   - **Rear 2MP camera and torch LED**: `msm8905-cam` V4L2 driver (`/dev/video0` `800x600` `RGB3` for GalaxyCore `GC2395`) and `leds-msm8905-torch` (`white:torch` + PM8909 clean poweroff).
5. **Preinstalled developer and utility stack**:
   - `gcc`/`g++`, `make`, `git`, GNU `coreutils`, `nano`, `ed`, `less`, `rlwrap`, `janet` + `jpm`, `bantam` coding agent, `perl` (`IO::Socket::SSL`), `tcl` (`tcllib`, `tcl-tls`, `sqlite-tcl`), `sqlite3`, `frotz`, `ffmpeg`, `mpv`, `imv`, and standalone `snake` and `tetris` X11 games.

---

## 2. Flashing instructions

### Method A: automated USB EDL flasher (recommended)

Run the automated EDL flasher from the repository root on your host machine:
```bash
sudo ./flash-edl.sh
```
*(To flash another target device image, pass its codename, e.g. `sudo ./flash-edl.sh nokia-sparkler`.)*

The script performs the following steps automatically:
1. Temporarily pauses host `ModemManager` so it does not interfere with `05c6:9008`.
2. Waits for the phone to appear in Qualcomm EDL mode (`05c6:9008`):
   - **From Bananarchy Linux**: open the **Power** menu (`End / Power` key or `System menu -> Power`), select **Reboot to loader** (`sxmo_power.sh loader`) to enter the `lk2nd` Fastboot menu, and select **EDL** (or let `flash-edl.sh` automatically send `fastboot oem reboot-edl`).
   - **Button combo**: power off the phone, hold **D-Pad up + D-Pad down**, and plug in the USB cable.
   - **EDL cable**: hold the EDL cable button while plugging in USB.
   - **From ADB or Fastboot**: the script automatically sends `adb reboot edl` or `fastboot oem reboot-edl` if detected.
3. Uploads `bootloader/loaders/8110.mbn` via Sahara and connects to eMMC via Firehose.
4. Backs up `gpt.bin`, `fsc`, `fsg`, `modemst1`, `modemst2`, `persist`, and `boot` into `./backup/` if not already backed up.
5. Flashes `lk2nd-msm8909.img` to `boot`, flashes `images/bananarchy-<device>.img` to `userdata`, clears the stock `system` superblock, and reboots into Bananarchy Linux.

---

### Method B: Fastboot flashing (once `lk2nd` is installed)

1. Enter the `lk2nd` Fastboot menu either by selecting **Reboot to loader** from the **Power** menu (`sxmo_power.sh loader`) or by holding **D-Pad down** while powering on the phone.
2. Flash the system image to `userdata`:
   ```bash
   fastboot flash userdata ./images/bananarchy-nokia-argon.img
   fastboot erase system
   fastboot reboot
   ```

---

### Method C: booting from a microSD card

`lk2nd` automatically checks the microSD card for a `pmOS_boot` partition before internal eMMC:
```bash
sudo dd if=./images/bananarchy-nokia-argon.img of=/dev/sdX bs=4M status=progress conv=fsync
```

---

## 3. Keypad controls and native applications

### 3.1 Global keypad controls (`240x320`)

| Physical key | Linux keysym / event | Action |
| :--- | :--- | :--- |
| **Left softkey (`Menu`)** | `XF86KbdLcdMenu1` (`KEY_MENU`) | Open **System menu**, close open menu, or wake and unlock when locked |
| **Right softkey (`Names` / `Back`)** | `XF86KbdLcdMenu2` / `BackSpace` (`KEY_BACK`) | On empty desktop: open **Contacts (`Names`)**; inside apps: open **App context menu** (or close menu if open); in T9 preedit: `BackSpace` |
| **Both softkeys together** | `KEY_MENU` + `KEY_BACK` | Toggle **XDrawer** (`xdrawer`) global phone controls overlay from anywhere |
| **Digits `0`–`9`, `*`, `#` (on idle desktop)** | `0`–`9`, `asterisk`, `numbersign` | Open **Dialer** (`xdialer`) and immediately insert the pressed digit, `*`, or `#` |
| **Call (green)** | `XF86PickupPhone` / `XF86Phone` (`KEY_SEND`) | Answer incoming call when ringing; on empty desktop: open **Call Log** (`xcalllog`); when locked: wake and unlock; in menus: confirm (`Return`); in apps: **2x** focus next window, **3x** cycle tiling layout |
| **End / Power (red)** | `XF86PowerOff` | Wake and unlock when locked, close open plugin/menu, or: **1x** open **Power menu**, **2x** cycle screen state, **3x** (or hold `400ms`) launch a new terminal |
| **D-Pad up / down** | `Up` / `Down` | Navigate menus and apps; in `st`: `Shift+Up`/`Shift+Down` (or `ScrlUp`/`ScrlDn` in `Ctl` mode) scrolls terminal history; in T9 preedit: toggle letter case (`a` <-> `A`) or jump `+4` / `-4` candidates |
| **D-Pad left / right** | `Left` / `Right` | On empty desktop: switch workspace tags (`-1` / `+1`); in T9 preedit: step back 1 candidate (`Left`) or commit candidate (`Right`); in idle `Ctl` mode: `Home` / `End` |
| **Center OK** | `Return` (`KEY_OK`) | Confirm / Enter, or commit active T9 preedit candidate immediately |
| **Slider close / open** | `SW_LID` (`lid:on` / `lid:off`) | **Close**: close open menu, turn off keypad backlight, and lock/turn screen off; **Open**: restore keypad backlight, unlock, and turn screen on |

> **Screen blanking, locking, and waking**:
> X11 screensaver/DPMS blanking is disabled so screen state is controlled cleanly by Sxmo. Automatic idle locking is disabled so the phone only locks when you explicitly ask it to (`Power -> Lock`, `XDrawer -> Lock`, `2x End / Power`, or closing the physical slider). To save battery, the display blanks after inactivity (`SXMO_UNLOCK_IDLE_TIME`, default 30s; `SXMO_LOCK_IDLE_TIME`, default 8s once locked) without locking. When the screen is off, wake and unlock in a single action by opening the slider or pressing **End / Power**, **Left softkey**, **Right softkey**, or **Call (green)**.

#### 3.1.1 Window tiling modes and switching combos
By default, `dwm` uses the **vertical bottom-stack (`bstack`, `TTT`)** layout so multiple `st` terminals stack **vertically (one under another)** to preserve full line width on the `240x320` portrait screen.

You can switch layouts and focus using either physical keypad multi-presses or an external keyboard (`Mod4` / `Super`):
- **Triple-press Call (green) (`3x Call`)**: cycle the active layout (`TTT` -> `[]=` -> `[D]` -> `[M]` -> `TTT`).
- **Double-press Call (green) (`2x Call`)**: move focus to the next open window (`Super+j`).
- **Triple-press End / Power (red) (`3x End`)**: launch a new `st` terminal in the active workspace.
- **External keyboard shortcuts (`Mod4`)**:
  - `Mod4+space`: cycle layout (`TTT` -> `[]=` -> `[D]` -> `[M]`).
  - `Mod4+Shift+slash`: vertical stack layout (`bstack`, `TTT`).
  - `Mod4+slash`: horizontal tile layout (`tile`, `[]=`).
  - `Mod4+m`: fullscreen monocle layout (`monocle`, `[M]`).
  - `Mod4+Up` / `Mod4+Down` (or `Mod4+k` / `Mod4+j`): move focus between tiled windows.
  - `Mod4+Shift+k` / `Mod4+Shift+j`: move the focused window up or down in the stack.
  - `Mod4+1`..`4`: switch to workspace tag `1`..`4`.
  - `Mod4+Shift+q`: close the focused window.

#### 3.1.2 Preloaded native DWM applications
All fifteen phone applications are compiled as shared-object plugins (`/usr/lib/dwm/plugins/*.so`), preloaded at `dwm` startup, and awakened over `/tmp/dwm_plugin_<name>.fifo` in `< 2 ms`:

1. **System and context menus (`dmenu.so` / `dmenu` / `xdmenu`)**:
   - **Open / close**: press **Left softkey (`Menu`)** for the **System menu** or **Right softkey (`Back`)** inside an application for its **Context menu**; press the same softkey or `Escape` to close.
   - **Built-in submenus and instant toggles**: renders `sys`, `applications`, `scripts`, `modem`, `config`, `power` (including **Logout**, **Reboot**, **Reboot to loader**, **Reboot to EDL**, and **Poweroff**), `audio`, `notifications`, `wm`, `timezone`, `games`, `st`, and `nano` menus in place in `< 0.5 ms` without spawning external processes.
   - **Script compatibility**: any script piping items into `/usr/bin/dmenu` or `sxmo_dmenu.sh` communicates with the resident daemon over `/tmp/dwm_plugin_dmenu.sock`.

2. **Global phone controls (`xdrawer.so` / `xdrawer`)**:
   - **Open / close**: press **both softkeys simultaneously** (`KEY_MENU` + `KEY_BACK`) from anywhere, or select **XDrawer** from the System menu.
   - **Controls**: use `Up`/`Down` (or `1`–`9`) to select **Speaker**, **Earpiece**, **Ring Vol**, **Ringer** (`Ring+Vib` / `Vibrate` / `Silent` / `DND`), **Flashlight**, **Sound**, **Microphone**, **Screen**, or **Keypad**; use `Left`/`Right` or `Return` to adjust or toggle.

3. **Phone dialer (`dialer.so` / `xdialer`)**:
   - **Open**: press any **`0`–`9`, `*`, or `#` key** on the empty desktop, or open **Dialer** from the System menu or Call Log.
   - **Dialing and T9 search**: typing digits filters saved contacts and recent numbers by phone number and T9 name in real time. Hold **`0`** (`>= 420 ms`) or press `Right` / **Left softkey (`+Sign`)** to insert `+`.
   - **USSD codes and `*#06#` Dual-SIM IMEI display**:
     - Typing **`*#06#`** immediately opens the **Device IMEI (`*#06#`)** dialog showing `IMEI 1`, `IMEI 2`, and `IMEI SV`.
     - Typing any USSD code (`*...#` or `#...#`, such as `*100#`) switches the center softkey to **`SEND`**. Pressing **Call (green)** or **Center `OK`** runs the USSD session inside an interactive in-dialer modal with scrollable carrier output and multi-step reply support.

4. **Call history (`calllog.so` / `xcalllog`)**:
   - **Open**: press **Call (green)** on the empty desktop, or select **Call Log** from the System menu or Dialer.
   - **Controls**: `Left`/`Right` switches between **`All`**, **`Missed`**, **`In`**, and **`Out`** tabs; `Up`/`Down` scrolls; **Call (green)** or **Center `OK`** dials the selected entry; **Left softkey (`Dialer`)** loads the number into the Dialer.

5. **Incoming and active call screen (`callscreen.so` / `xcallscreen`)**:
   - **Automatic activation**: wakes the screen and opens automatically on incoming and outgoing calls. Pressing **Call (green)** during an active call reopens `xcallscreen` from anywhere.
   - **Incoming call actions**: press **Call (green)**, **Left softkey (`Accept`)**, **`1`**, or **Center `OK`** to answer; press **`*`** or **`0`** to silence the ringer; press **End (red)**, **Right softkey (`Reject`)**, or **`#`** to decline.
   - **In-call controls and recording**:
     - **`[1]` / `*` — microphone mute**: toggles hardware QDSP6 and PipeWire microphone mute (`ON` / `MUTED`).
     - **`[2]` / `#` — call recording**: starts or stops recording call audio (`16 kHz` mono WAV) to `~/Recordings/call_<caller>_YYYYMMDD_HHMMSS.wav` with a live `REC MM:SS` badge.
     - **`[3]` — audio route**: switches between **`EARPIECE`** and **`SPEAKER`**.
     - **`Left` / `Right` — call volume**: adjusts in-call volume in `5%` steps.
     - **`[0]` / Left softkey (`DTMF`)**: toggles DTMF tone keypad mode.
     - **End (red)** or **Right softkey (`Hangup`)**: hangs up the call.

6. **Contacts phonebook (`contacts.so` / `xcontacts`)**:
   - **Open**: press the **Right softkey (`Names`)** on the empty desktop, or select **Contacts** from the System menu.
   - **Search and actions**: type `0`–`9` for live T9/number filtering; press **Call (green)** to dial immediately; press **Center `OK`** for the contact details card (**Call Contact**, **Send SMS**, **Read Messages**, **Open in Dialer**, **Copy to SIM**, **Edit Contact**, **Delete Contact**); or press **Left softkey (`Options`)** for phonebook-wide actions.
   - **Direct Dual-SIM QMI phonebook import and export**: select **Import from SIM** or **Export to SIM** in the **Options** menu (or **Copy to SIM** on an individual contact) to read or write `EF_ADN` SIM phonebook records directly over Qualcomm QMI UIM (`qrtr://0`) on either **SIM 1** or **SIM 2** — even on the inactive SIM slot.
   - **Built-in contact editor**: create or edit contacts directly on the keypad (`#` cycles input mode, `*` inserts space, hold `0` or press `Right` for `+`, or pick from recent unknown callers).

7. **SMS manager and composer (`sms.so` / `xsms`)**:
   - **Open**: select **Texts** from the System menu, or choose **Send SMS** / **Read Messages** from Contacts.
   - **Conversations and thread view**: browse SMS threads and drafts with contact name resolution, unread indicators, and message bubbles (`Recv` and `Sent`).
   - **Multi-tap composer**: pick a recipient from Contacts/Recents or type a number (hold `0` for `+`), compose messages with multi-tap keypad entry (`#` cycles input mode), monitor live character/segment counts (`0/160`), save drafts automatically, and send via **Call (green)**, **Center `OK`**, or **Left softkey**.

8. **File manager (`files.so` / `xfiles`)**:
   - **Open**: select **Files** from the System menu or press `Mod4+d`.
   - **Controls and viewers**: navigate directories with `Up`/`Down`/`Left`/`Right`/`Return`, filter with `0`–`9`, toggle dotfiles with `*`, and cycle sort order (**Name** / **Date** / **Size**) with `#`.
   - **Image preview and wallpaper installation**: pressing `Return` on any image file (`.jpg`, `.png`, `.bmp`, `.gif`, `.webp`, `.ppm`, `.tif`, `.ico`, `.svg`) opens the built-in image viewer (`*` toggles full-screen preview; **Left softkey (`Set Wall`)** installs the image into `~/Pictures/Wallpapers/`, applies it via `feh`, and refreshes Conky). You can also select **Preview Image** or **Set as Wallpaper** directly from the **Left softkey (`Actions`)** menu.
   - **Audio playback and ringtone installation**: pressing `Return` on any audio or tracker module file opens it immediately in **Music (`xmusic`)**. From the **Left softkey (`Actions`)** menu on any audio/tracker file, select **Play in Music Player** to play it in `xmusic`, or **Set as Ringtone** to copy it to `~/Ringtones/` and set it as the active phone ringtone.
   - **File management actions**: the **Left softkey (`Actions`)** menu also provides **View Text**, **Edit in Nano**, **New Folder**, **New File**, **Rename**, **Copy**, **Cut / Move**, **Paste Here**, **Properties**, **Open Terminal Here**, and **Delete**.

9. **Camera (`camera.so` / `xcamera`)**:
   - **Open**: select **Camera** from the System menu or run `xcamera`.
   - **Viewfinder and gallery**: streams live `800x600` frames from `/dev/video0` (`GC2395`) into a `240x180` 4:3 viewfinder. Press **Center `OK`**, **`5`**, or **Call (green)** to capture a JPEG to `~/Pictures/photo-YYYYMMDD-HHMMSS.jpg`; `*` or `1` toggles **Auto-Flash**; `0` or `2` toggles continuous **Torch**; `Up`/`Down` adjusts **Digital Zoom** (`1.0x` / `2.0x` / `4.0x`); `#` or `3` toggles the **3-second Self-Timer**; **Left softkey (`Gallery`)** opens the built-in photo gallery.

10. **Theme manager (`themes.so` / `xthemes`)**:
    - **Open**: select **Themes** from the System, Apps, or Config menu, or run `xthemes`.
    - **Live theme switching and customizer**: browse 20 preinstalled `.xth` schemes (`~/.xthemes/*.xth`) with live color swatches and press **Center `OK`** or **Call (green)** to apply across `dwm`, `dmenu`, `st`, and all plugins with zero restart. Press **`*`** or **Left softkey** to customize individual colors and font sizes, save a custom theme (`#`), or edit the `.xth` file in Nano.

11. **Modem, Dual-SIM, and PIN/PUK manager (`modem.so` / `xmodem`)**:
    - **Open**: select **Modem** from the System menu, or run `xmodem`. Also opens automatically when a SIM card requires PIN or PUK unlock.
    - **Four control tabs (`Left`/`Right` or `1`–`4`)**:
      - **`1:SIMs`**: inspects both physical SIM slots via QMI UIM (`PRESENT`/`EMPTY`, `[ACTIVE]`, `READY`/`PIN-LOCK`/`PUK-LOCK`, remaining retries, operator, and ICCID). Press `Return` on a slot to **Activate SIM Slot 1 / 2**, **Unlock SIM PIN**, **Unblock SIM with PUK**, **Enable / Disable PIN Lock**, or **Change SIM PIN** (with automatic `ModemManager` reprobe after unlock).
      - **`2:Radio`**: shows signal bar, registration status, access technology (`LTE`/`UMTS`/`GSM`), operator, both IMEIs, and phone number, with actions to switch **Network Mode** (`4G/3G/2G`, `3G/2G`, `4G Only`, `3G Only`, `2G Only`), **Send USSD Code**, toggle **Modem Power**, or **Restart ModemManager**.
      - **`3:AT`**: interactive AT command console with presets (`AT`, `ATI`, `AT+CSQ`, `AT+CPIN?`, `AT+COPS?`, etc.) and custom keypad entry.
      - **`4:Log`**: scrollable history of calls, SMS events, and USSD responses.

12. **Networks and Bluetooth manager (`networks.so` / `xnetworks` / `xbluetooth`)**:
    - **Open**: select **Networks** or **Bluetooth** from the System menu, or run `xnetworks` / `xbluetooth`.
    - **Three connectivity tabs (`Left`/`Right` or `1`–`3`)**:
      - **`1:Wi-Fi`**: toggle Wi-Fi radio, rescan (`*`), toggle **Wi-Fi Hotspot**, and connect to WPA2/open networks with a multi-tap password dialog (`*` toggles password visibility).
      - **`2:Cell/APN`**: toggle **Mobile Data**, inspect `wwan0` IPv4 status, edit **APN Configuration**, and toggle **USB Tethering**.
      - **`3:Bluetooth`**: toggle Bluetooth power, scan nearby devices (`*`), and pair, connect, disconnect, or remove devices.

13. **Ringtones and ringer manager (`ringtones.so` / `xringtones`)**:
    - **Open**: select **Ringtones** from the System, Config, or Audio menu, or run `xringtones`.
    - **Controls**: preview built-in, tracker module (`.mod`, `.xm`, `.it`, `.s3m`, etc.), and user ringtones (`~/Ringtones/`, `~/Music/`, `/usr/share/sxmo/ringtones/`, `/usr/share/sxmo/music/`) at the configured ringtone volume with `*` or **Left softkey (`Play` / `Stop`)**, press `Return` to set the active ringtone, and switch to **`2:Settings`** to configure **Ringer Mode**, **Ring Volume** (`0%`–`100%`, also adjustable in **XDrawer**), **Ring Duration**, **Ring Loop Count**, and 3-level hardware **Vibrate Strength** (`Level 1` gentle `1400 mV`, `Level 2` medium `2100 mV`, `Level 3` strong `3100 mV`).

14. **Desktop wallpaper manager (`wallpapers.so` / `xwallpapers` / `xbackground`)**:
    - **Open**: select **Wallpapers** from the System, Config, or Apps menu, or run `xwallpapers`.
    - **Controls**: browse system and user wallpapers with a live portrait thumbnail, cycle scaling mode (`Fill`, `Scale`, `Fit`, `Center`, `Tile`) with `Left`/`Right` or `#`, toggle full-screen preview with `*`, and press `Return` to apply the wallpaper and immediately refresh the Conky desktop overlay.

15. **Music and tracker module player (`music.so` / `xmusic` / `xplayer`)**:
    - **Open**: select **Music** from the System, Applications, or Audio menu, open any audio/tracker file from **Files (`xfiles`)**, or run `xmusic [file_or_dir]`.
    - **Supported formats**: plays standard audio (`.wav`, `.mp3`, `.ogg`, `.flac`, `.opus`, `.m4a`, `.aac`) as well as classic chiptune/tracker modules (`.mod`, `.xm`, `.it`, `.s3m`, `.mptm`, `.stm`, `.med`, `.okt`, `.669`, `.ult`, `.far`, `.mtm`, `.ptm`, `.amf`, `.dsm`, `.imf`, `.gdm`, `.stx`, `.umx`, `.mo3`) via an embedded `mpv` + `FFmpeg` + `libopenmpt` backend that automatically pauses on incoming calls.
    - **Three tabs (`1:Player`, `2:Queue`, `3:Files` — switch with `1`–`3` or `Left`/`Right` in Queue/Files)**:
      - **`1:Player`**: displays format badge (`MOD`, `XM`, `MP3`, etc.), scrolling track title, artist/metadata, animated equalizer bars, elapsed/total progress bar, repeat mode (`Off`, `All`, `One`), shuffle state, and volume. Press `Return` or `5` to **Play/Pause**, `Left`/`Right` (`4`/`6`) to **Seek `-5s`/`+5s`**, `Up`/`Down` (`2`/`8`) to adjust **Volume**, `7`/`9` for **Prev/Next track**, `*` to cycle **Repeat**, `#` to toggle **Shuffle**, `0` to **Stop**, or **Left softkey (`Options`)** to install the current track as the phone ringtone.
      - **`2:Queue`**: browse the active playlist queue, filter with `0`–`9`, press `Return` to jump to a track, `*` to remove a track, `#` to shuffle, or **Left softkey (`Actions`)** to set the selected track as ringtone or clear the queue.
      - **`3:Files`**: browse the filesystem (`~/Music`, `/usr/share/sxmo/music`, `/usr/share/sxmo/ringtones`, or any folder), press `Return` to play a file and load its folder into the queue, `*` to append a file or folder to the queue, or `#` to play the entire current folder.

#### 3.1.3 Standalone keypad games (`Snake` and `Tetris`)
Two classic X11 games (`/usr/bin/snake` and `/usr/bin/tetris`) are accessible from **System menu -> Games**:
- **Snake (`snake`)**: steer with `2`/`8`/`4`/`6` or D-Pad; pause or restart with `5`/`Return`/`#`/`*`; quit with `Right softkey`/`BackSpace`/`Escape`.
- **Tetris (`tetris`)**: move with `4`/`6` (`Left`/`Right`), rotate with `2` (`Up`), soft drop with `8` (`Down`), hard drop with `0`/`5`/`Return`, pause with `#`/`*`, and quit with `Right softkey`/`BackSpace`/`Escape`.

### 3.2 Multi-mode `fcitx5-t9` keypad reference

- **Short-press `#`** *(when no character is in preedit)*: cycles through the 6 input modes (`abc` -> `Abc` -> `ABC` -> `Sym` -> `Ctl` -> `123` -> `abc`), showing a `1500ms` mode banner at the bottom of the screen.
- **Auto-commit timeout**: `1500ms` for keys with `<= 10` candidates, or `1800ms` for keys with `> 10` candidates. Pressing a different key immediately commits the active candidate.
- **While a candidate is highlighted (`[item]`) in preedit**:
  - Press **`#`** or **D-Pad `Up`**: toggles letter case (`a` <-> `A`) on the fly, or jumps forward **`+4` candidates** for non-alphabetic items.
  - Press **D-Pad `Down`**: toggles letter case (`a` <-> `A`) for alphabetic items, or jumps backward **`-4` candidates** for non-alphabetic items.
  - Press **D-Pad `Left`**: steps backward **1 candidate** on the same key.
  - Press **D-Pad `Right`** or **Center `OK` (`Return`)**: commits the highlighted candidate immediately.
  - Press **`BackSpace`**: cancels the uncommitted preedit candidate without deleting already committed text.
- **Long-press (`>= 550ms`)**:
  - **Hold `0`–`9`**: commits the digit (`0`–`9`) immediately in any mode.
  - **Hold `*`**: in `123` mode, commits `.` (decimal point); in all other modes, toggles a one-shot **`Ctrl+` modifier latch** (`+^`) so the next key is sent as `Ctrl+<key>`.
  - **Hold `#`**: commits a literal `#` character immediately in any mode.

#### Modes 1–3: `abc` (lowercase), `Abc` (one-shot Shift), and `ABC` (Caps Lock)
*(In `Abc` and `ABC` modes, uppercase letters precede the digit and lowercase letters on keys `2`–`9`. In `Abc` mode, committing an alphabetic character automatically reverts to `abc`.)*

| Key | Tap sequence (`abc` mode) |
| :--- | :--- |
| **`1`** | `.` `,` `-` `_` `!` `?` `/` `@` `:` `;` `'` `"` `+` `=` `*` `#` `$` `%` `^` `&` `(` `)` `[` `]` `{` `}` `<` `>` `\|` `\` `~` `` ` `` `1` |
| **`2`** | `a` `b` `c` `2` `A` `B` `C` |
| **`3`** | `d` `e` `f` `3` `D` `E` `F` |
| **`4`** | `g` `h` `i` `4` `G` `H` `I` |
| **`5`** | `j` `k` `l` `5` `J` `K` `L` |
| **`6`** | `m` `n` `o` `6` `M` `N` `O` |
| **`7`** | `p` `q` `r` `s` `7` `P` `Q` `R` `S` |
| **`8`** | `t` `u` `v` `8` `T` `U` `V` |
| **`9`** | `w` `x` `y` `z` `9` `W` `X` `Y` `Z` |
| **`0`** | `Space` (`SPC`) `0` `Ent` (`Return`) `Tab` |
| **`*`** | `*` `#` `+` `-` `=` `_` `/` `\` `\|` `~` `` ` `` `@` `$` `%` `^` `&` `(` `)` `[` `]` `{` `}` `<` `>` `'` `"` `.` `,` `!` `?` `:` `;` `Tab` `Esc` `^C` `^D` `^Z` *(hold 450ms for `Ctrl+` latch)* |

#### Mode 4: `Sym` (grouped ASCII punctuation, symbols, and special keys)
| Key | Symbols / keys |
| :--- | :--- |
| **`1`** | `.` `,` `!` `?` `:` `;` `-` `_` `1` |
| **`2`** | `@` `#` `$` `%` `^` `&` `2` |
| **`3`** | `(` `)` `[` `]` `{` `}` `<` `>` `3` |
| **`4`** | `+` `-` `*` `/` `=` `_` `4` |
| **`5`** | `\|` `\` `~` `` ` `` `'` `"` `5` |
| **`6`** | `'` `"` `` ` `` `~` `^` `6` |
| **`7`** | `/` `\` `\|` `_` `-` `+` `7` |
| **`8`** | `<` `>` `!` `=` `?` `&` `8` |
| **`9`** | `$` `%` `^` `&` `*` `#` `@` `9` |
| **`0`** | `Space` (`SPC`) `0` `Tab` `Ent` (`Return`) `Esc` |
| **`*`** | `*` `#` `+` `-` `=` `_` `/` `\` `\|` `~` `` ` `` `@` `$` `%` `^` `&` `(` `)` `[` `]` `{` `}` `<` `>` `'` `"` `.` `,` `!` `?` `:` `;` |

#### Mode 5: `Ctl` (terminal control characters, navigation, and function keys)
- **Direct D-Pad navigation** *(when no preedit candidate is active in `Ctl` mode)*:
  - **D-Pad `Up` / `Down`**: sends `Page_Up` (`PgUp`) / `Page_Down` (`PgDn`) immediately.
  - **D-Pad `Left` / `Right`**: sends `Home` / `End` immediately.
- **Keypad multi-tap**:

| Key | Control sequences / special keys |
| :--- | :--- |
| **`1`** | `Esc` `Tab` `Del` `Ins` `Bksp` |
| **`2`** | `^C` `^D` `^Z` `^X` `^\` |
| **`3`** | `^A` `^E` `^U` `^K` `^W` |
| **`4`** | `^R` `^L` `^P` `^N` `^G` |
| **`5`** | `^S` `^Q` `^O` `^T` `^Y` |
| **`6`** | `^B` `^F` `^V` `^H` `^[` `^]` `^^` `^_` |
| **`7`** | `PgUp` `PgDn` `Home` `End` `ScrlUp` `ScrlDn` |
| **`8`** | `Up` `Down` `Left` `Right` |
| **`9`** | `F1` `F2` `F3` `F4` `F5` `F6` `F7` `F8` `F9` `F10` `F11` `F12` |
| **`0`** | `Space` (`SPC`) `Tab` `Ent` (`Return`) `Esc` |
| **`*`** | `Esc` `Tab` `^C` `^D` `^Z` `^X` `^L` `^R` `^W` |

#### Mode 6: `123` (instant numeric entry)
| Key | Action |
| :--- | :--- |
| **`0`–`9`** | Commits digit `0`–`9` immediately on single tap |
| **`*`** | Commits `*` immediately on single tap; **hold `450ms`** to commit `.` (decimal point) |
| **`#`** | **Short-press**: cycle back to `abc` mode; **hold `450ms`**: commit `#` |

---

## 4. Default credentials, USB SSH, and Bantam AI agent

- **Username**: `user`
- **Password**: `147147` (`doas` and `sudo` enabled, with passwordless `doas` configured for `wheel` in `/etc/doas.d/50-sxmo.conf`)
- **USB networking SSH**:
  ```bash
  ssh user@172.16.42.1
  ```
- **Bantam AI agent**:
  Launch **Bantam** directly from the System menu (`Left softkey -> Applications -> Bantam`), or run `bantam` in any terminal (`st`) or over SSH. Configure your endpoint and API key via environment variables or `~/.bantam.cfg` when needed.

---

## 5. Command-line hardware reference

### 5.1 Taking photos from the CLI (`bananarchy-photo` and `/dev/video0`)

The `msm8905-cam` kernel module drives the rear 2MP GalaxyCore `GC2395` sensor through MSM8909 `CAMSS` and registers `/dev/video0` (`800x600` 24-bit `RGB3`).

- **Using `bananarchy-photo`**:
  ```bash
  # Capture to ~/Pictures/photo-YYYYMMDD-HHMMSS.jpg and print path
  bananarchy-photo

  # Capture with rear LED flash enabled and open in imv
  bananarchy-photo -f -v

  # Capture to a custom JPEG or PNG file path
  bananarchy-photo ~/my-shot.png
  ```
- **Direct low-level capture (`v4l2-ctl` + `ffmpeg -f rawvideo`)**:
  ```bash
  v4l2-ctl -d /dev/video0 \
    --set-fmt-video=width=800,height=600,pixelformat=RGB3 \
    --stream-mmap --stream-count=1 --stream-to=/tmp/frame.rgb && \
  ffmpeg -hide_banner -loglevel error \
    -f rawvideo -pixel_format rgb24 -video_size 800x600 \
    -i /tmp/frame.rgb -frames:v 1 -y ~/photo.jpg && \
  rm -f /tmp/frame.rgb
  ```

### 5.2 Audio routing, music playback, and microphone recording

Both the rear loudspeaker (`Speaker`, with boosted `RX3 Digital Volume` for loud, clear ringtones and media) and the front earpiece speaker (`Earpiece`, boosted by +6 dB), as well as the internal MEMS microphone (`Mic1`) and 3.5mm headset microphone (`Mic2`), are managed through PipeWire/WirePlumber and `sxmo_audio.sh`:

- **Open an audio file, tracker module (`.mod`, `.xm`, `.it`, `.s3m`), or folder in the native music player (`xmusic`)**:
  ```bash
  xmusic ~/Music/Bananarchy_Chip.mod
  ```
- **List available audio outputs (`Speaker`, `Earpiece`, `Headphones`)**:
  ```bash
  sxmo_audio.sh out list
  ```
- **Switch active output to the rear loudspeaker or front earpiece**:
  ```bash
  sxmo_audio.sh out set "Speaker"
  sxmo_audio.sh out set "Earpiece"
  ```
- **Record from the internal MEMS microphone (`Mic1`)**:
  ```bash
  pw-record --rate=48000 --channels=1 --format=s16 ~/recording.wav
  ```

### 5.3 Flashlight (`white:torch`), keypad backlight (`white:kbd_backlight`), and vibration (`sxmo_vibrate`)

- **Turn rear flashlight on or off**:
  ```bash
  brightnessctl -d white:torch set 1
  brightnessctl -d white:torch set 0
  ```
- **Set keypad backlight brightness (`0`–`255`)**:
  ```bash
  brightnessctl -d white:kbd_backlight set 255
  ```
- **Trigger PM8909 vibration motor (`duration_ms [strength_1_to_3]`)**:
  ```bash
  sxmo_vibrate 350 1   # gentle (1400 mV)
  sxmo_vibrate 350 2   # medium (2100 mV)
  sxmo_vibrate 350 3   # strong (3100 mV)
  ```

### 5.4 Cellular modem, Dual-SIM, and QMI UIM helper

- **Inspect Dual-SIM card status, PIN/PUK state, and active slot**:
  ```bash
  doas /usr/libexec/msm-modem-uim-selection status
  ```
- **Inspect ModemManager registration, operator, and signal quality**:
  ```bash
  mmcli -m any
  ```