# Bananarchy Linux — user, flashing & customization manual

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

This manual covers flashing, operating, and customizing **Bananarchy Linux** (`v0.0.1`, Sxmo `240x320` native edition) on **Qualcomm MSM8905 / 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`)** & **Nokia 6300 4G (`nokia-leo`)**

---

## 1. What is prepared in this workspace

### 1.1 System images (`images/`)
- `images/bananarchy-nokia-argon.img` (linked as `images/nokia-argon-sxmo.img`) — raw partitioned image (`256 MiB` `ext2` `pmOS_boot` + `ext4` `pmOS_root`) ready for EDL flashing to `userdata` or raw `dd` to a microSD card.
- `images/bananarchy-nokia-argon.sparse.img` (linked as `images/nokia-argon-sxmo.sparse.img`) — Android sparse image for `fastboot flash userdata`.
- `images/boot-bananarchy-nokia-argon.img` (linked as `images/boot-nokia-argon-sxmo.img`) — standalone Android `boot.img` with Linux `6.12.1-msm8916`, initramfs, and appended DTB.
- 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 & EDL programmer (`bootloader/`)
- `bootloader/lk2nd-msm8909.img` — secondary bootloader (`lk2nd`) providing Fastboot and `extlinux` boot discovery for MSM8905/MSM8909 devices.
- `bootloader/loaders/8110.mbn` — signed Qualcomm Sahara/Firehose programmer (`05c6:9008`).

### 1.3 Integrated hardware & UX tweaks
1. **Native 1:1 `240x320` resolution, cross-compiled Xlibre, `Fira Code` ligatures & ultra-low-latency Sxmo X11 UI**:
   - **Cross-compiled Xlibre (`X11Libre/xserver` 25.2.0)**: compiled specifically for ARMv7 Cortex-A7 (`-O2 -march=armv7-a -mtune=cortex-a7 -mfpu=neon-vfpv4 -mfloat-abi=hard -fno-plt -fomit-frame-pointer`) with all 3D/GLX/Glamor/VGA/DGA/XVideo bloat stripped out, rootless `elogind` device management, and `modesetting` KMS + `ShadowFB` (`drmModeDirtyFB` partial rectangle SPI updates) with automatic software cursor fallback on `/dev/dri/card0` (`panel-mipi-dbi`).
   - **Non-Nerd `Fira Code` with OpenType ligatures**: `Fira Code` (`font-fira-code`) is configured as the primary system and terminal font across Fontconfig, Xft, `st`, `dmenu`, `dwm`, `conky`, and `dunst`, with `DejaVu SansM Nerd Font` used strictly as a fallback for Private Use Area icon glyphs.
   - **Patched `sxmo-st` (`st`) with HarfBuzz ligatures & XIM**: patched with `libharfbuzz` (`hb.c`/`hb.h`) shaping (`liga`, `calt`, `clig`, `dlig`) so multi-character programming operators (`->`, `=>`, `!=`, `<=`, `>=`, `===`, `::`, `//`, `/*`) render as continuous ligatures at `pixelsize=18`, alongside full `XIM` (`fcitx5-t9`) input support.
   - **Patched `sxmo-dmenu` (`dmenu`) (`< 15 ms` startup)**: full-screen `240x296` 10-line vertical menu (positioned flush at `Y = 24..320` right below the 24px `dwm` bar, with a `26px` search bar and ten `27px` item rows) with a `#383838` top search bar, `#005577` prompt badge, `#1c1c1c` item list, `XIM` (`XSetLocaleModifiers("")`, `XSetICFocus`, `Xutf8LookupString`) for live `fcitx5-t9` search filtering and `#` mode switching, C-level focus preservation (`prevfocuswin`), and direct Nokia keypad bindings.
   - **Patched `sxmo-dwm` (`dwm`) (`< 2 ms` display wake/unlock & native plugin system)**: configured for `240x320` (`bh = 24`, `#323232` top bar, `#005577` active tag/border, vertical `bstack` layout default, overflow-protected Pango status bar rendering keeping the right-aligned clock always visible, and a transparent-backgrounded bottom desktop softkey bar displaying `"Menu"` and `"Names"` over the wallpaper). Directly polls `/dev/input/by-path/platform-gpio-keys-event` (`SW_LID`) and intercepts locked-state wake keys (`XF86PowerOff`, `XF86PickupPhone`, `XF86KbdLcdMenu1`, `XF86KbdLcdMenu2`) in C to toggle `/sys/class/backlight/backlight/brightness` and `/sys/class/leds/white:kbd_backlight/brightness` in `< 2 ms` before running Sxmo state hooks asynchronously.
   - **Preloaded DWM plugins (`src/dwm-plugins/` & `src/xdrawer/`, `< 10 ms` FIFO wakeup)**: `dwm` dynamically loads `.so` plugins from `/usr/lib/dwm/plugins/` and `~/.local/lib/dwm/plugins/` (`xdrawer.so`, `dialer.so`, `calllog.so`, `contacts.so`) and preloads them as resident background daemons (`dwm-plugin <name> --preload`) at startup. Each daemon keeps its X11 window, offscreen `Pixmap`, Xft/Pango layouts (`15px` `Fira Code, DejaVuSansM Nerd Font`), and `stat()`-cached Sxmo TSV state initialized in memory while sleeping at 0% CPU on `/tmp/dwm_plugin_<name>.fifo`.
2. **Multi-mode `fcitx5-t9` keypad engine (`src/fcitx5-t9/`)**:
   - Supports 6 input modes cycled with `#` (`XF86NumericPound`): `abc`, `Abc`, `ABC`, `Sym`, `Ctl`, and `123`, updating the live top-bar status indicator (`[abc]`, `[Abc]`, `[ABC]`, `[Sym]`, `[Ctl]`, `[123]`) in real time.
   - Locks the candidate popup bar to the bottom of the screen (`X = 1, Y = 290, W = 238, H = 30`) with fixed-width 28-character monospace formatting (`Fira Code 9.5`), so neither the popup window nor individual letters ever jump when cycling through candidates.
   - Includes instant case toggling during preedit, full 32-character ASCII punctuation/symbol entry, terminal control sequences (`^A`–`^Z`, `Esc`, `Tab`, `F1`–`F12`), and a `550ms` long-press `*` `Ctrl+` modifier latch.
3. **Bantam AI agent (`prebuilt/bantam/bantam`)**:
   - Fetched from the latest `master` branch of `https://code.luxferre.top/luxferre/bantam-cpp`, cross-compiled for `armv7`, and installed to `/usr/bin/bantam` and `/usr/local/bin/bantam` (with no default `.bantam.cfg` pre-created).
4. **Mainline 6.12.1-msm8916 QDSP6 audio (loudspeaker, earpiece, MEMS & headset mics), voice call & LTE modem stack**:
   - Patched `q6core`, `q6afe`, `q6afe-dai`, `q6voice-dai`, `q6mvm`, and device trees (`VoiceMMode1` DAI + PM8909 WCD codec).
   - Automatic PM8909 WCD analog codec register initialization at boot (`CDC_A_MICB_1_VAL` `0xf141 = 0x60` for 2.8V internal MEMS microphone bias, and `CDC_A_RX_EAR_CTL` `0xf1c0 |= 0x20` for +6 dB earpiece PA gain).
   - WirePlumber `50-s16le.lua` (`S16LE` sample format enforcement), ALSA UCM2 profiles (`qdsp6.conf`, `HiFi.conf`, and `VoiceCall.conf`), `q6voiced` (`card=0, device=2`), `sxmo_audio.sh` / `sxmo_modemaudio.sh` PipeWire UCM profile switching, `sxmo_ob.sh` (`WOB_DISABLE_PLEDGE=1`), `rmtfs`, `msm-modem-uim-selection`, `msm8909-modem-wwan-port`, and `ModemManager` (`mmcli`).
5. **Rear 2MP camera (`src/msm8905-cam/` & `bananarchy-photo`) & SY7807 torch LED (`src/leds-msm8905-torch/`)**:
   - `msm8905-cam.ko`: powers PM8909 LDOs (`L2` 1.2V, `L6` 1.8V, `L17` 2.85V) and `CAMSS_MCLK0` (24 MHz on GPIO 26), configures the GalaxyCore `GC2395` MIPI CSI-2 sensor (`blsp_i2c3` `0x37`) and MSM8909 `CAMSS` (`CSIPHY0 -> CSID0 -> ISPIF -> VFE0 RDI0 -> VBIF -> CMA`), and exposes `/dev/video0` (`800x600` 24-bit `RGB3` V4L2 capture device).
   - `bananarchy-photo`: CLI and Sxmo menu camera utility (`Camera` in the Sxmo System and Apps menus) supporting instant JPEG/PNG photo capture, optional flash (`-f`), and `imv` photo viewing (`-v`).
   - `leds-msm8905-torch.ko`: exposes `/sys/class/leds/white:torch` (`GPIO 31`), configures WCD micbias/earpiece registers at boot, and hooks PM8909 `PON` clean shutdown.
6. **Memory & swap tuning for 512 MB RAM**:
   - `384 MiB` ZSTD-compressed `zram0` swap (priority `100`) + `512 MiB` `/swapfile` (priority `10`), with `vm.swappiness=100` and `vm.page-cluster=0`.
7. **Preinstalled on-device development & scripting stack**:
   - **C / C++ toolchain & CLI utilities**: `gcc`, `g++`, `musl-dev`, `make`, `git`, GNU `coreutils`, `nano` (default `$EDITOR`, configured system-wide via `/etc/nanorc` equivalent to `nano -FEDSMAGic/max%_T2`), `ed`, GNU `less` (default `$PAGER="less -RXF"`), `rlwrap`, `frotz`
   - **Janet**: `janet`, `janet-dev`, `jpm` (Janet package manager)
   - **Perl**: `perl`, `perl-io-socket-ssl` (`IO::Socket::SSL`)
   - **Tcl & SQLite**: `tcl`, `tcl-lib` (`tcllib`), `tcl-tls`, `sqlite` (`sqlite3`), `sqlite-tcl` (`tcl-sqlite`)
   - **Hardware & media utilities**: `bananarchy-photo`, `v4l-utils` (`v4l2-ctl`), `i2c-tools`, `ffmpeg`, `mpv`, `imv`

---

## 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 will:
1. Temporarily pause host `ModemManager` so it does not interfere with `05c6:9008`.
2. Wait for the phone to appear in Qualcomm EDL mode (`05c6:9008`):
   - **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 / Fastboot**: the script automatically sends `adb reboot edl` or `fastboot oem edl` if detected.
3. Upload `bootloader/loaders/8110.mbn` via Sahara and connect to eMMC via Firehose.
4. Back up `gpt.bin`, `fsc`, `fsg`, `modemst1`, `modemst2`, `persist`, and `boot` into `./backup/` (if not already backed up).
5. Flash `lk2nd-msm8909.img` to `boot`, flash `images/bananarchy-<device>.img` to `userdata`, clear the stock `system` superblock, and reboot into Bananarchy Linux.

---

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

1. Hold **D-Pad up** while powering on the phone to enter `lk2nd` Fastboot mode.
2. Flash the sparse system image to `userdata`:
   ```bash
   fastboot flash userdata ./images/bananarchy-nokia-argon.sparse.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 & multi-mode T9 input guide

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

| Physical key | Linux keysym / event | Action in Sxmo |
| :--- | :--- | :--- |
| **Left softkey (`Menu`)** | `XF86KbdLcdMenu1` (`KEY_MENU`) | Open **System menu**, close open menu, or wake & unlock when locked |
| **Right softkey (`Names` / `Back`)** | `XF86KbdLcdMenu2` / `BackSpace` (`KEY_BACK`) | On empty desktop: open **`Contacts` (`Names`)** phonebook plugin; 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 (Speaker, Earpiece, Flashlight, Sound, Microphone, Screen, Keypad) from anywhere |
| **Digits `0`–`9`, `*`, `#` (on idle desktop)** | `0`–`9`, `asterisk`, `numbersign` | Open **`Dialer`** (`xdialer`) and immediately insert the pressed digit/`*`/`#` |
| **Call (green)** | `XF86PickupPhone` / `XF86Phone` (`KEY_SEND`) | Answer incoming call when ringing; on empty desktop: open **`Call Log`** (`xcalllog`); when locked: wake & unlock; in menus: confirm (`Return`); in apps: **2×** **Focus next window**, **3×** **Toggle tiling layout** |
| **End / Power (red)** | `XF86PowerOff` | Wake & unlock when locked, close open plugin/menu, or: **1×** **Power menu** (`space` shutter in Megapixels), **2×** cycle screen state, **3×** (or hold `400ms`) launch new terminal |
| **D-Pad up / down** | `Up` / `Down` | Navigate menus/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`) / 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 |

> **Waking & unlocking after screen fade**:
> When the screen turns off after inactivity (or when the slider is closed), you can wake and unlock the phone in a single action by either:
> - **Opening the slider** (`SW_LID` off), or
> - Pressing **End / Power (red)**, **Left softkey**, **Right softkey**, or **Call (green)** once.

#### 3.1.1 Window tiling modes & switching combos
By default, Sxmo `dwm` is configured with the **vertical bottom-stack (`bstack`, `TTT`)** layout as default, so opening multiple `st` terminals stacks them **vertically (one terminal under another)** to maximize line width on the `240x320` portrait screen.

You can switch between **vertical stack (`TTT`, `bstack`)**, **horizontal tile (`[]=`, `tile`)**, **deck (`[D]`, `deck`)**, and **fullscreen monocle (`[M]`, `monocle`)** layouts — as well as switch focus between open terminals — using any of the following combos:

1. **Direct physical keypad combos**:
   - **Triple-press Call (green) (`3× Call`)**: cycles the current DWM layout (`TTT` -> `[]=` -> `[D]` -> `[M]` -> `TTT`).
   - **Double-press Call (green) (`2× Call`)**: switches focus to the next open window/terminal (`Super+j`).
   - **Triple-press End / Power (red) (`3× End`)**: opens a new `st` terminal (with HarfBuzz `Fira Code` ligature support) tiled in the active layout.
2. **External keyboard / `xdotool` (`MODKEY` = `Mod4` / `Super`)**:
   - `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 focused window up/down in the stack
   - `Mod4+1`..`4`: switch to workspace tag `1`..`4`
   - `Mod4+Shift+q`: close focused window

#### 3.1.2 Preloaded DWM plugins (`XDrawer`, `Dialer`, `Call Log`, `Contacts`, `SMS`, `Files`, `Camera`)
All seven core phone overlays are compiled as shared-object plugins (`/usr/lib/dwm/plugins/*.so`), preloaded at `dwm` startup (`dwm-plugin <name> --preload`), and awakened over `/tmp/dwm_plugin_<name>.fifo` in `< 10 ms`:

1. **`XDrawer` (`xdrawer.so` / `xdrawer`) — Global Phone Controls**:
   - **Open / Close**: Press **both softkeys simultaneously** (`KEY_MENU` + `KEY_BACK`) from anywhere, or select `XDrawer` from the Sxmo menu.
   - **Controls**: `Up`/`Down` selects a row (**Speaker Volume**, **Earpiece Volume**, **Flashlight**, **Sound**, **Microphone**, **Screen Brightness**, **Keypad Backlight**); `Left`/`Right` adjusts sliders or toggles; `Return` flips toggles; `1`–`7` jumps directly to row `1`–`7`; `Escape` or both softkeys closes the drawer.

2. **`Dialer` (`dialer.so` / `xdialer`) — Keypad Dialer with Contact Integration**:
   - **Open**: On the empty desktop, press any **`0`–`9`, `*`, or `#` key** (which opens the dialer and immediately inserts that character), or launch **Dialer** from the Sxmo menu or Call Log.
   - **Dialing & T9 Filtering**: Typing digits filters saved contacts (`~/.config/sxmo/contacts.tsv`) and recent numbers (`modemlog.tsv`) by phone number and T9 contact name in real time. Hold **`0`** (`>= 420 ms`) or press **D-Pad `Right`** / **Left softkey (`+Sign`)** to insert `+`.
   - **Navigation & Calling**: `Up`/`Down` selects a matching contact or recent number; **Call (green)** or **Center `OK` (`Return`)** places the call immediately; **Right softkey (`Clear` / `Close`)** or **`BackSpace`** deletes digits or closes the dialer; **Left softkey (`Call Log`)** when empty switches directly to the Call Log.

3. **`Call Log` (`calllog.so` / `xcalllog`) — Call History Viewer**:
   - **Open**: On the empty desktop, press **Call (green)** (`XF86PickupPhone` / `XF86Phone`), or select **Call Log** from the Sxmo menu or Dialer.
   - **Controls**: `Left`/`Right` switches between **`All`**, **`Missed`**, **`In`**, and **`Out`** filter tabs; `Up`/`Down` scrolls through call entries (showing direction icon, resolved contact name or number, timestamp, and call duration); **Call (green)** or **Center `OK` (`Return`)** dials the selected entry; **Left softkey (`Dialer`)** opens the selected number in the Dialer; **Right softkey (`Close`)** or `Escape` closes the Call Log.

4. **`Contacts` (`contacts.so` / `xcontacts` / `sxmo_contactmenu.sh`) — Full-Featured Phonebook**:
   - **Open**: On the empty desktop, press the **Right softkey (`Names`)**, or select **Contacts** from the Sxmo menu.
   - **Phonebook List & Live Search**: Typing `0`–`9` filters contacts in real time by T9 name or phone number; `Up`/`Down` scrolls; **Call (green)** immediately calls the selected contact; **Center `OK` (`Return`)** opens the contact's details & actions card; **Left softkey (`Options`)** opens the options menu (**New Contact**, **Add from Recent**, **Call Contact**, **Send SMS**, **Edit Contact**, **Delete Contact**).
   - **Contact Details View**: Provides one-click actions for **Call Contact**, **Send SMS**, **Read Messages**, **Open in Dialer**, **Edit Contact**, and **Delete Contact**.
   - **Built-in Contact Editor**: Supports adding new contacts or editing existing contacts directly in the `240x320` UI. In the **Name** field, keypad keys `0`–`9` provide multi-tap character entry (`#` cycles case mode `[Abc]` -> `[ABC]` -> `[abc]` -> `[123]`, `*` inserts space). In the **Number** field, hold `0` or press `Right` to insert `+`, or select **Use Recent Number** to pick from recent unknown callers in `modemlog.tsv`. Press **Left softkey (`Save`)** or select **Save Contact** to write directly to `~/.config/sxmo/contacts.tsv`.

5. **`SMS Manager / Editor` (`sms.so` / `xsms` / `sxmo_modemtext.sh`) — Conversations & Composer**:
   - **Open**: Select **Texts** from the Sxmo system menu (`Left softkey`), or choose **Send SMS** / **Read Messages** from Contacts.
   - **Conversations List**: Shows all SMS threads and drafts from `~/.local/share/sxmo/modem/<number>/sms.txt` with contact name resolution, message previews, and timestamps. Press `0`–`9` for live T9/number search, `*` for a new message, **Center `OK` (`Return`)** to open the conversation, **Call (green)** to call the sender, or **Left softkey (`Options`)** for **New Message**, **Open Thread**, **Reply / Compose**, **Call Number**, **Save/View Contact**, and **Delete Thread**.
   - **Thread View**: Displays incoming (`Recv`, green left accent) and outgoing (`Sent`, blue/gold right accent) message bubbles; `Up`/`Down` scrolls; **Center `OK` (`Return`)** opens the reply composer; **Call (green)** calls the contact.
   - **Multi-Tap SMS Composer**: Supports picking a recipient from Contacts/Recents or entering a number directly (hold `0` for `+`), multi-tap text entry on keys `0`–`9` and `*` (`#` cycles `[Abc]` -> `[ABC]` -> `[abc]` -> `[123]`), live character and SMS segment counter (`0/160`), automatic draft persistence (`draft.txt`), and asynchronous sending via `sxmo_modemsendsms.sh` (`Call` key, `Send SMS` button, or `Left softkey`).

6. **`File Manager` (`files.so` / `xfiles` / `sxmo_files.sh`) — Graphical Directory Browser & Viewer**:
   - **Open**: Select **Files** from the Sxmo system menu (`Left softkey`) or press `Mod4+d`.
   - **Browser Controls**: `Up`/`Down` navigates files and directories; `Return`/`Right` enters a directory or opens the selected file; `Left`/`BackSpace` ascends to the parent directory (`..`); `0`–`9` filters items in real time; `*` toggles hidden dotfiles (`.*`); `#` cycles sort order (**Name** -> **Date** -> **Size**).
   - **Built-in Viewers & File Actions (`Left softkey`)**: Text files and scripts open in a fast built-in scrollable viewer (with `Left softkey` shortcut to edit in `st -e nano`); JPEG and PNG images open in a built-in `libjpeg`/`libpng` previewer (`Left`/`Right` steps through images in the folder, `Left softkey` opens full screen in `feh`). The **Actions** menu supports **Open**, **Edit in Nano**, **New Folder**, **New File**, **Rename**, **Copy**, **Cut / Move**, **Paste Here**, **Properties**, **Toggle Hidden (`*`)**, **Cycle Sort (`#`)**, **Open Terminal Here**, and **Delete**.

7. **`Camera` (`camera.so` / `xcamera`) — Live Viewfinder & Photo Gallery**:
   - **Open**: Select **Camera** from the Sxmo system menu (`Left softkey`) or run `xcamera` / `bananarchy-photo --menu`.
   - **Live Viewfinder**: Streams `800x600` `RGB24` frames directly from `/dev/video0` (`msm8905-cam` / `GC2395`) into a `240x180` 4:3 viewfinder with a center reticle. Press **Center `OK` (`Return`)**, **`5`**, or **Call (green)** to snap a JPEG photo to `~/Pictures/photo-YYYYMMDD-HHMMSS.jpg`; `*` or `1` toggles **Auto-Flash**; `0` or `2` toggles continuous **Torch** (`white: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.
   - **Built-in Photo Gallery**: Browse captured photos with `Left`/`Right` or `Up`/`Down`, press `Return` to open full-screen in `feh`, or press **Left softkey (`Delete`)** to delete a photo.

### 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`), displaying a `1500ms` preedit status banner (`[Mode: abc]`, `[Mode: Abc]`, `[Mode: ABC]`, `[Mode: Sym]`, `[Mode: Ctl]`, `[Mode: 123]`).
- **Auto-commit timeout**: `1500ms` for keys with `<= 10` candidates, or `1800ms` for keys with `> 10` candidates (`1` and `*` in `abc`/`Abc`/`ABC`, `*` in `Sym`, `9` in `Ctl`). 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 without changing mode, 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 previously committed text.
- **Long-press (`>= 550ms`)**:
  - **Hold `0`–`9`**: commits the digit (`0`–`9`) immediately in any mode.
  - **Hold `*`**:
    - In `123` mode: commits a decimal point (`.`) immediately.
    - In all other modes: toggles a one-shot **`Ctrl+` modifier latch** (`[Ctrl+ LATCH ON]` / `[Ctrl+ LATCH OFF]`; mode prefix shows `+^`, e.g. `abc+^`). The next committed key (`a`–`z`, `[`, `\`, `]`, `^`/`6`, `_`/`-`) is sent as `Ctrl+<key>`.
  - **Hold `#`**: commits a literal `#` character immediately in any mode.

#### Modes 1–3: `abc` (lowercase), `Abc` (one-shot Shift), `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 & 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 & 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 & 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**:
  Run `bantam` in the terminal (`st`) or over SSH. Configure your endpoint/API key via environment variables or `~/.bantam.cfg` when needed.

---

## 5. Camera, audio, flashlight & cellular modem reference

### 5.1 Taking photos with the rear camera (`xcamera`, `bananarchy-photo` & `/dev/video0`)

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

- **From the Sxmo keypad UI (`xcamera` / `camera.so`)**:
  Open the **System menu** (`Left softkey`) and select **Camera** (`xcamera`). The native DWM camera plugin streams a live `240x180` viewfinder from `/dev/video0` with:
  - **Shutter (`Return` / `5` / `Call`)**: encodes an `800x600` JPEG directly to `~/Pictures/photo-YYYYMMDD-HHMMSS.jpg`.
  - **Auto-Flash (`*` / `1`) & Continuous Torch (`0` / `2`)**: controls `white:torch` during or before capture.
  - **Digital Zoom (`Up` / `Down`)**: cycles `1.0x`, `2.0x`, and `4.0x` center-crop zoom.
  - **Self-Timer (`#` / `3`)**: toggles a 3-second countdown before capture.
  - **Built-in Gallery (`Left softkey`)**: browse and delete saved photos in `~/Pictures` or press `Return` to open full-screen in `feh`.
- **From the CLI (`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
  ```
- **Why `v4l2-ctl` + `ffmpeg -f rawvideo` is used under the hood**: Alpine's `libavdevice` links against `libv4l2.so.0`, whose `v4l2_mmap` wrapper on 32-bit ARM (`musl` 64-bit `off_t`) misaligns variadic `syscall(SYS_mmap2, ...)` arguments. Capturing via `v4l2-ctl` and encoding via `ffmpeg -f rawvideo` bypasses `libv4l2` completely.

### 5.2 Switching speakers (loudspeaker vs. earpiece) & recording microphone audio

Both the rear loudspeaker (`Speaker` / `SPK_OUT`) and the front earpiece speaker (`Earpiece` / `EAR`, boosted by +6 dB in `CDC_A_RX_EAR_CTL`), as well as the internal MEMS microphone (`Mic1` / `AMIC3`, biased at 2.8V in `CDC_A_MICB_1_VAL`) and 3.5mm headset microphone (`Mic2` / `AMIC2`), are managed through PipeWire/WirePlumber and `sxmo_audio.sh`:

- **List available audio outputs (`Speaker`, `Earpiece`, `Headphones`)**:
  ```bash
  sxmo_audio.sh out list
  ```
- **Switch active output to the rear loudspeaker**:
  ```bash
  sxmo_audio.sh out set "Speaker"
  ```
- **Switch active output to the front earpiece speaker**:
  ```bash
  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`)

- **Turn rear flashlight on / 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
  ```

### 5.4 GSM / WCDMA / LTE modem & voice calls (`ModemManager` & `q6voiced`)

- **Inspect modem registration, operator, and signal quality**:
  ```bash
  mmcli -m any
  ```
- **Place or manage voice calls and SMS**:
  Use the Sxmo **Phone** / **Texts** menu (`Left softkey`) or `mmcli -m any --voice-list-calls` / `mmcli -m any --messaging-list-sms`. In-call audio is automatically routed between the modem (`VoiceMMode1`) and the PM8909 WCD codec by the `q6voiced` service and `sxmo_modemaudio.sh`.