luxferre/bananarchy
1
0
Fork 0
Code Issues Actions Activity
Files
ad012360c3587d1242b6341531ca162c9b7155a5
bananarchy/MANUAL.md
T

20 KiB
Raw Blame History

Bananarchy Linux — user, flashing & customization manual

Bananarchy Banner

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 (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 & 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)
    • 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:

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, with passwordless doas configured for wheel in /etc/doas.d/50-sxmo.conf)
  • 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.

5. Camera, audio, flashlight & cellular modem reference

5.1 Taking photos with the rear camera (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: Open the System menu (Left softkey) or Apps menu (Left softkey -> Apps) and select Camera (bananarchy-photo --menu). From the Camera menu you can:
    • Take photo: capture a photo to ~/Pictures/photo-YYYYMMDD-HHMMSS.jpg and immediately open it in imv.
    • Take photo (flash): turn on the rear flashlight (white:torch), capture a photo, restore the flashlight state, and open the photo in imv.
    • View photos: browse all saved photos in ~/Pictures using imv (press Right softkey inside imv to navigate, zoom, rotate, or quit).
  • From the CLI (bananarchy-photo): 
    # 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): 
    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): 
    sxmo_audio.sh out list
  • Switch active output to the rear loudspeaker: 
    sxmo_audio.sh out set "Speaker"
  • Switch active output to the front earpiece speaker: 
    sxmo_audio.sh out set "Earpiece"
  • Record from the internal MEMS microphone (Mic1): 
    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: 
    brightnessctl -d white:torch set 1
brightnessctl -d white:torch set 0
  • Set keypad backlight brightness (0–255): 
    brightnessctl -d white:kbd_backlight set 255

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

  • Inspect modem registration, operator, and signal quality: 
    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.
Reference in New Issue View Git Blame Copy Permalink