bananarchy/MANUAL.md

# 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 & enlarged fonts**:
   - Sway runs at `output * scale 1` (`SXMO_SWAY_SCALE=1`) with Xwayland disabled to save RAM.
   - Enlarged fonts across all UI layers: `Sxmo 13` window titles and `24px` top bar, `34pt`/`14pt` Conky clock/date positioned cleanly above the Bananarchy emblem wallpaper, `15px` bold Wofi full-screen menus (`240x296`), `13pt` Foot terminal font, `220x28` Wob volume/brightness overlay, and `12pt` Dunst notifications.
2. **Multi-mode `fcitx5-t9` keypad engine (`src/fcitx5-t9/`)**:
   - Supports 6 input modes cycled with `#` (`XF86NumericPound`): `abc`, `Abc`, `ABC`, `Sym`, `Ctl`, and `123`.
   - Includes instant case toggling during preedit, full 32-character ASCII punctuation/symbol entry, terminal control sequences (`^A`–`^Z`, `Esc`, `Tab`, `F1`–`F12`), and a `450ms` 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, voice call & LTE modem stack**:
   - Patched `q6core`, `q6afe`, `q6afe-dai`, `q6voice-dai`, `q6mvm`, and device trees (`VoiceMMode1` DAI + PM8909 WCD codec).
   - WirePlumber `50-s16le.lua` (`S16LE` sample format enforcement), ALSA UCM2 profiles (`HiFi.conf` and `VoiceCall.conf`), `q6voiced`, `rmtfs`, `msm-modem-uim-selection`, `msm8909-modem-wwan-port`, and `ModemManager`.
5. **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`.
6. **Preinstalled on-device development & scripting stack**:
   - **C / C++ toolchain & build tools**: `gcc`, `g++`, `musl-dev`, `make`, `git`, `nano`
   - **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`)

---

## 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** | `XF86KbdLcdMenu1` (`KEY_MENU`) | Open **System menu**, close open menu, or wake & unlock when locked |
| **Right softkey / Back** | `XF86KbdLcdMenu2` / `BackSpace` (`KEY_BACK`) | Open **App context menu** (or close menu if open); in apps/T9 preedit acts as `BackSpace` |
| **Call (green)** | `XF86PickupPhone` (`KEY_SEND`) | Wake & unlock when locked, confirm (`Return`) in menus, or: **1×** answer call / **App context menu**, **2×** **Focus next window**, **3×** **Toggle tiling layout** (`vertical` -> `horizontal` -> `tabbed`) |
| **End / Power (red)** | `XF86PowerOff` | Wake & unlock when locked, close open 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 T9 preedit: toggle letter case (`a` ↔ `A`) or jump `+4` / `-4` candidates; in idle `Ctl` mode: `Page_Up` / `Page_Down` |
| **D-Pad left / right** | `Left` / `Right` | Move cursor; 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 Sway is configured with **`default_orientation vertical` (`splitv`)**, so opening multiple terminals stacks them **vertically (one terminal under another)** to maximize line width on the `240x320` portrait screen.

You can switch between **vertical (`splitv`, one under another)**, **horizontal (`splith`, side-by-side)**, and **tabbed (`tabbed`, full-screen tabs)** 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 container layout (`vertical splitv` -> `horizontal splith` -> `tabbed` -> `vertical splitv`).
   - **Double-press Call (green) (`2× Call`)**: switches focus to the next open window/terminal (e.g., jumps between the top and bottom terminals).
   - **Triple-press (or hold `400ms`) End / Power (red) (`3× End`)**: opens a new `Foot` terminal tiled in the active layout.
2. **Terminal context menu (`Right softkey` or `1× Call (green)` inside `Foot`)**:
   - **Next window**: switch focus to the next open terminal/window.
   - **Toggle layout**: cycle `splitv` -> `splith` -> `tabbed`.
   - **Tile vertical**: immediately arrange open windows vertically (one under another) and set future splits to vertical.
   - **Tile horizontal**: immediately arrange open windows horizontally (side-by-side) and set future splits to horizontal.
   - **New terminal** / **Close terminal**: open a new terminal or close the focused terminal.
3. **System windows menu (`Left softkey` -> `Windows`)**:
   - **Next window**: focus the next window in the workspace.
   - **`splitv -> splith -> tabbed`**: cycle container layout mode.
   - **Split vertical** / **Split horizontal** / **Tabbed layout**: switch directly to the chosen layout.
   - **Switch menu** / **Move menu** / **Kill window**: switch to any window across workspaces, move windows between positions/workspaces, or close the focused window.
4. **External keyboard / `swaymsg` (`$mod` = `Mod4` / `Super`)**:
   - `Mod4+v`: vertical split (`splitv`)
   - `Mod4+b`: horizontal split (`splith`)
   - `Mod4+e`: toggle split orientation (`layout toggle split` between vertical and horizontal)
   - `Mod4+w`: tabbed layout (`layout tabbed`)
   - `Mod4+s`: stacking layout (`layout stacking`)
   - `Mod4+f`: toggle fullscreen (`fullscreen`)
   - `Mod4+Up` / `Mod4+Down` / `Mod4+Left` / `Mod4+Right`: move focus between tiled windows
   - `Mod4+Shift+Up` / `Mod4+Shift+Down` / `Mod4+Shift+Left` / `Mod4+Shift+Right`: reposition focused window

### 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 `900ms` preedit status banner (`[Mode: abc]`, `[Mode: Abc]`, `[Mode: ABC]`, `[Mode: Sym]`, `[Mode: Ctl]`, `[Mode: 123]`).
- **Auto-commit timeout**: `600ms` for keys with `<= 10` candidates, or `750ms` 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 (`>= 450ms`)**:
  - **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` |
| **`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)
- **USB networking SSH**:
  ```bash
  ssh user@172.16.42.1
  ```
- **Bantam AI agent**:
  Run `bantam` in the terminal (`Foot`) or over SSH. Configure your endpoint/API key via environment variables or `~/.bantam.cfg` when needed.