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

40 KiB
Raw Blame History

Bananarchy Linux — user, flashing & customization manual

Bananarchy Banner

This manual covers flashing, operating, and customizing Bananarchy Linux (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. System overview & workspace contents

1.1 System images (images/)

  • images/bananarchy-nokia-argon.img — partitioned 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.
  • images/boot-bananarchy-nokia-argon.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 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, and direct < 2 ms C-level 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) 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) & 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 & Dual-SIM modem: Loudspeaker, boosted (+6 dB) earpiece, internal MEMS and headset microphones, ModemManager + q6voiced call audio routing, and Dual-SIM UIM slot switching (msm-modem-uim-selection).
    • Rear 2MP camera & 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 & 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:

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):
    • From Bananarchy Linux: open the Power menu (End / Power key or System menu -> Power) and select Reboot to EDL (or run sxmo_power.sh 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 / 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. Enter lk2nd Fastboot mode either by selecting Reboot to Fastboot from the Power menu (sxmo_power.sh fastboot) or by holding D-Pad up while powering on the phone.
  2. Flash the system image to userdata: 
    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:

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

Explicit locking & waking: X11 screensaver/DPMS blanking is disabled (the display is blanked explicitly by Sxmo, not by the X server), and automatic idle locking is disabled so the phone only locks when explicitly requested (Power -> Lock / Lock (Screen off), XDrawer -> Lock, 2× End / Power, or closing the physical slider). To save battery, the display still blanks automatically after a period of inactivity (SXMO_UNLOCK_IDLE_TIME, default 30s; SXMO_LOCK_IDLE_TIME, default 8s once locked) without locking. When the screen is off, 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 (DMenu, XDrawer, Dialer, Call Log, Call Screen, Contacts, SMS, Files, Camera, Themes, Modem, Networks, Ringtones, Wallpapers)

All fourteen core phone overlays are compiled as shared-object plugins (/usr/lib/dwm/plugins/*.so), preloaded at dwm startup (dwm-plugin <name> --preload with an exclusive /tmp/dwm_plugin_<name>.lock single-instance guard), and awakened over /tmp/dwm_plugin_<name>.fifo in < 2 ms:

  1. DMenu (dmenu.so / dmenu / xdmenu) — Zero-Lag System & Context Menus:

    • Open / Close: Press Left softkey (Menu) for the System menu (sys) or Right softkey (Back) inside an application for its Context menu (ctx); press the same softkey or Escape to close.
    • Built-in Native Menus & < 0.5 ms In-Place Transitions: Renders sys, ctx, applications (including Nano, Bantam, Files, Camera, Dialer, Contacts), scripts, modem, config, power (with Reboot, Reboot to Fastboot, Reboot to EDL, and Poweroff via sxmo_power.sh), audio, notifications, wm, timezone, games, st, nano, sthotkeys, and confirmation prompts directly inside the resident 240x296 plugin window without spawning shell scripts or new X11 connections. Submenu transitions (@menu:...) and hardware toggles (@toggle:flashlight, @toggle:brightness, @toggle:autosuspend, @toggle:autocallscreenoff, @toggle:bluetooth, @toggle:dnd) update in place in < 0.5 ms.
    • Client Socket Mode (/tmp/dwm_plugin_dmenu.sock): Any script piping items into /usr/bin/dmenu or sxmo_dmenu.sh streams its item list over the Unix domain socket to the resident dmenu.so daemon and receives the user's selection instantaneously, while /tmp/dwm_plugin_dmenu.active provides zero-overhead sxmo_dmenu.sh isopen checks.

  2. 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, Ringer Mode [Ring+Vib / Vibrate / Silent / DND], Flashlight, Sound, Microphone, Screen Brightness, Keypad Backlight); Left/Right adjusts sliders or cycles modes/toggles; Return flips toggles; 1–8 jumps directly to row 1–8; Escape or both softkeys closes the drawer.

  3. Dialer (dialer.so / xdialer) — Keypad Dialer with Contact, USSD & *#06# 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 +.
    • Direct USSD Codes & *#06# Dual-SIM IMEI Display:
      • Typing *#06# immediately opens the Device IMEI (*#06#) modal showing both IMEI 1 (SIM Slot 1), IMEI 2 (SIM Slot 2), and IMEI SV.
      • Typing any USSD / MMI code (*...# or #...#, e.g., *100#) switches the center softkey to SEND. Pressing Call (green) or Center OK (Return) sends the USSD request directly and opens an in-dialer USSD Session Modal with scrollable response text and an interactive reply input box for multi-step carrier menus.
    • 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.

  4. 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.

  5. Call Screen (callscreen.so / xcallscreen) — Incoming & Active Call Manager:

    • Automatic Invocation: Automatically wakes the display and opens on incoming calls (sxmo_modem.sh checkforincomingcalls -> xcallscreen incoming <callid> <number>) and outgoing calls (sxmo_modemdial.sh / placePhoneCall() -> xcallscreen outgoing <callid> <number>). Pressing Call (green) while a call is active reopens xcallscreen from anywhere.
    • Incoming Call Controls: Displays the resolved contact name from ~/.config/sxmo/contacts.tsv, phone number, INCOMING CALL badge, and ring timer. Press Call (green), Left softkey (Accept), 1, or Center OK (Return) (on Answer Call) to accept the call; press * or 0 (or OK on Silence Ring) to mute the ringtone and vibration while keeping the call screen open; press End (red), Right softkey (Reject), #, or OK on Reject Call to decline the call.
    • In-Call Controls & Call Recording: Displays live MM:SS call duration and four interactive control rows (Up/Down + OK or direct hotkeys):
      • [1] / * — Microphone Mute: toggles hardware QDSP6 (DEC1 MUX, ADC3 Volume, VoiceMMode1 Capture Mixer) and PipeWire microphone mute (ON / MUTED).
      • [2] / # — Call Recording: starts/stops recording call audio via pw-record (16 kHz mono WAV) to ~/Recordings/call_<caller>_YYYYMMDD_HHMMSS.wav with a live REC MM:SS indicator, automatically finalizing the recording when the call ends.
      • [3] — Audio Route: switches call audio between EARPIECE and SPEAKER (sxmo_audio.sh + ALSA EAR_S / SPK DAC Switch).
      • Left / Right — Call Volume: adjusts in-call volume in 5% increments (5%–100%).
      • [0] / Left softkey (DTMF) — DTMF Keypad Mode: toggles DTMF tone mode where pressing 0–9, *, or # sends DTMF tones via mmcli --send-dtmf.
      • End (red) or Right softkey (Hangup): hangs up the active call (sxmo_modemcall.sh hangup).

  6. 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, Import from SIM, Export to SIM, Call Contact, Send SMS, Edit Contact, Delete Contact).
    • SIM Card Import & Export (Dual-SIM Aware): Select Import from SIM or Export to SIM in the Options menu (or Copy to SIM inside a contact's detail view) to transfer contacts between ~/.config/sxmo/contacts.tsv and the SIM card phonebook (EF_ADN / SM). If both SIM 1 and SIM 2 are installed, Contacts prompts you to choose between SIM 1 and SIM 2; if only one SIM is installed, it uses that slot automatically.
    • Contact Details View: Provides one-click actions for Call Contact, Send SMS, Read Messages, Open in Dialer, Copy to SIM, 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.

  7. 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), dynamic center softkey action (Send when focused on Recipient/Message vs. Draft when focused on the Save Draft button), and asynchronous sending via sxmo_modemsendsms.sh (Call key, Send SMS button, or Left softkey).

  8. 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.

  9. 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 and a 1-second V4L2 poll() frame watchdog. 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.

  10. Theme Manager (themes.so / xthemes) — Unified .Xresources Theme Browser & Customizer (~/.xthemes/*.xth):

  • Open: Select Themes from the Sxmo System menu, Apps menu, or Config menu, or run xthemes.
  • Theme Files (~/.xthemes/*.xth): Every .xth file in ~/.xthemes/ is a standard Xresources file defining theme.name, theme.fontFace, theme.iconFontFace, theme.baseFontSize (from which sizeSmall, sizeMain, sizeIcon, and sizeLarge are proportionally derived across all UI elements), core and surface colors (theme.bgMain, theme.bgBar, theme.bgHeader, theme.selBg, theme.selFg, theme.accent, theme.fgMain, theme.fgMuted, etc.), and synchronized dwm.*, dmenu.*, st.*, and svkbd.* resources. Pre-installed themes (20 total) include Default.xth, BananaGold.xth, CatppuccinLatte.xth, CatppuccinMocha.xth, Cyberpunk.xth, Dracula.xth, EverforestDark.xth, GitHubDark.xth, GruvboxDark.xth, GruvboxLight.xth, Kanagawa.xth, LinuxConsole.xth, MatrixGreen.xth, MonokaiPro.xth, NordFrost.xth, OneDark.xth, RosePine.xth, SolarizedDark.xth, SolarizedLight.xth, and TokyoNight.xth.
  • Controls & Live Switching: Up/Down browses installed themes with live color swatches and typography details; Center OK (Return), Call (green), or keys 1–9 immediately writes ~/.Xresources, runs xrdb -load ~/.Xresources, and broadcasts RELOAD_THEME to dwm, dmenu, st, and all resident DWM plugins for zero-restart live theme switching.
  • Built-in Theme Customizer & Options (Left softkey or */#): Supports Customize Theme Colors/Font (* shortcut — adjust Font Face, Base Size, Main BG, Bar BG, Header BG, Selected BG, Selected FG, Accent, Font Color, and Muted Color with Left/Right presets or press Return to enter any 6-digit #RRGGBB hex code via the keypad), Save Current as New Theme (# shortcut), Duplicate Theme, Edit .xth in Nano, Reset Default Theme, and Delete Theme, plus CLI xthemes --apply <ThemeName> and xthemes --export-default.
  1. Modem, Dual-SIM & PIN/PUK Manager (modem.so / xmodem) — Dual-SIM Slot Provisioning, PIN/PUK Entry, Radio & AT Console:
  • Open: Select Modem from the Sxmo System menu (Left softkey), or run xmodem (xmodem unlock, xmodem info, xmodem at, xmodem log, xmodem ussd). Also opens automatically when the active SIM card is PIN- or PUK-locked (sxmo_hook_modem.sh).
  • Tabs (Left/Right or 1 / 2 / 3 / 4):
    • 1:SIMs (Dual-SIM & PIN/PUK Management): Inspects both physical Qualcomm UIM card slots (qmicli -pd qrtr://0 --uim-get-card-status + /usr/libexec/msm-modem-uim-selection status), displaying each slot's presence (PRESENT / EMPTY), active Primary GW provisioning badge ([ACTIVE]), lock state (READY, PIN-LOCK, PUK-LOCK), remaining PIN1/PUK1 retries, operator, and ICCID. Selecting a slot (Return or Left softkey) opens the SIM Slot Actions menu:
      • Activate SIM Slot 1 / 2: Switches Qualcomm QMI primary-gw-provisioning to the chosen physical SIM slot, persists preferred_sim_slot in /etc/conf.d/msm-modem-uim-selection, and restarts ModemManager.
      • Unlock SIM PIN: Masked numeric PIN dialog (4–8 digits, * toggles show/hide digits) with live remaining retry counter.
      • Unblock SIM with PUK: Guided 3-step wizard (8-digit PUK1 -> new 4–8 digit PIN -> confirm new PIN).
      • Enable / Disable PIN Lock: Toggles SIM PIN verification requirement on power-up.
      • Change SIM PIN: Guided 3-step wizard (Current PIN -> New PIN -> Confirm New PIN).
    • 2:Radio (Modem Controls & USSD): Displays live signal strength (% and visual bar), registration state, access technology (LTE / UMTS / GSM), operator name, both IMEI 1 and IMEI 2, and phone number, plus interactive rows to switch Network Mode (4G/3G/2G, 3G/2G, 4G Only, 3G Only, 2G Only), Send USSD Code, toggle Modem Power, and Restart ModemManager.
    • 3:AT (Direct AT Command Console): Send any AT command directly to the Qualcomm modem (/dev/wwan0at1 / /dev/wwan0at0) and view the multi-line response in real time. Supports multi-tap AT command entry ([ABC]/[abc]/[123]/[Sym], # cycles mode, * inserts +?=,",;*#), a quick preset selector (AT, ATI, AT+CGSN, AT+CSQ, AT+CREG?, AT+COPS?, AT+CPIN?, AT+CCID, AT+CGDCONT?, AT+CGPADDR, AT+CFUN?, AT+CLCC), and scrollable output.
    • 4:Log (Modem Log): Color-coded history of calls, SMS events, and USSD responses from $SXMO_LOGDIR/modemlog.tsv.
  1. Networks & Bluetooth Manager (networks.so / xnetworks / xbluetooth) — Wi-Fi, Cellular APN, Tethering & Bluetooth:
  • Open: Select Networks or Bluetooth from the Sxmo System menu (Left softkey), or run xnetworks / xbluetooth.
  • Tabs (Left/Right or 1 / 2 / 3):
    • 1:Wi-Fi: Toggle Wi-Fi radio ON/OFF, scan (* or Rescan Networks), toggle Wi-Fi Hotspot, and browse saved/nearby SSIDs with signal bars, security badges (WPA2/OPEN), and [CONNECTED] status. Selecting an SSID opens Connect / Switch, Enter Password (multi-tap abc/Abc/ABC/123/Sym keypad modal with * password visibility toggle), Disconnect, or Forget Network.
    • 2:Cell/APN: Toggle Mobile Data (sxmo_modemdata.sh), view current cellular IPv4 address and bearer interface (wwan0), edit APN Configuration (APN Name, Username, Password, and Save & Activate APN), and toggle USB Tethering.
    • 3:Bluetooth: Toggle Bluetooth controller power (doas rfkill unblock bluetooth + bluetoothctl power on/off), scan for nearby devices (* or Scan Nearby (8s)), and manage paired/discovered devices (Connect, Disconnect, Pair & Trust, Forget / Remove).
  1. Ringtones & Ringer Manager (ringtones.so / xringtones) — Ringtone Browser, Live Preview & Ringer Settings:
  • Open: Select Ringtones from the System, Config, Audio, or Apps menu, or run xringtones.
  • Tabs (Left/Right or 1 / 2):
    • 1:Ringtones: Lists built-in synthesized ringtones (/usr/share/sxmo/ringtones/*.wav and /usr/share/sxmo/ring.ogg) alongside user audio files in ~/Ringtones/ and ~/Music/. Press * or Left softkey (Play / Stop) to preview any ringtone live via mpv, and press Return (Set Ring) to save it as the active incoming call ringtone (~/.config/sxmo/ringtone).
    • 2:Settings: Adjust Ringer Mode (Ring + Vibrate, Ring Only, Vibrate Only, Silent), Ring Duration (10s–60s), Ring Loop Count (3x–50x), Vibrate Strength (Level 1–3), and Test Vibration (~/.config/sxmo/ringsettings).
  1. Desktop Wallpaper Manager (wallpapers.so / xwallpapers / xbackground) — Live Preview & Wallpaper Selector:
  • Open: Select Wallpapers from the System, Config, or Apps menu, or run xwallpapers / xbackground.
  • Controls: Browses system wallpapers (/usr/share/wallpapers/) and user photos (~/Pictures/Wallpapers/ and ~/Pictures/) with a live decoded portrait thumbnail, image resolution, and file size. Press Left / Right (or #) to cycle the scaling mode (Fill (Crop), Scale (Stretch), Fit (Max), Center (1:1), Tile), press * or Left softkey (View [*]) to toggle a full-screen preview, and press Return (Apply) to apply the wallpaper immediately via feh and persist it in ~/.config/sxmo/wallpaper.

3.1.3 Standalone Keypad Games (Snake & Tetris)

Two classic monochrome/Gameboy-styled X11 games (src/games/snake.cpp -> /usr/bin/snake, src/games/tetris.cpp -> /usr/bin/tetris) are included in the Games submenu (Left softkey -> Games):

  1. Snake (snake):

    • Controls: 2 / Up, 8 / Down, 4 / Left, 6 / Right to steer (with a 2-turn input queue and immediate mid-step turn response); 5 / Return / # / * / P to pause, resume, or start a new game after Game Over; BackSpace / Right softkey / Escape / Q to quit.
    • Gameplay: Wrap-around playfield edges (24x28 grid) with progressive speed scaling (+1 px/s per 5 food eaten) and automatic pause on focus loss.

  2. Tetris (tetris):

    • Controls: 4 / Left and 6 / Right to move horizontally; 2 / Up to rotate clockwise (with wall kicks); 8 / Down for soft drop; 0 / 5 / Return / Space for hard drop (or resume/new game when paused/game over); # / * / P to pause/resume; BackSpace / Right softkey / Escape / Q to quit.
    • Gameplay: 4-shade beveled Gameboy palette, next-piece preview box, score/lines/level/best stats, progressive gravity scaling (+1 px/s per 10 lines cleared), and automatic pause on focus loss.

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: 
    ssh user@172.16.42.1
  • Bantam AI agent: Launch Bantam directly from the Sxmo menu (Left softkey -> Applications -> Bantam, which opens an st terminal with $HOME as its default working directory), or run bantam in any 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): 
    # 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