bananarchy/MANUAL.md

Bananarchy Linux — User, Flashing & Customization Manual

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 DIY 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:

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:

   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:

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:

  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.