bananarchy/README.md

# Bananarchy Linux

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

**Bananarchy** is a keypad-first Linux distribution hardforked from postmarketOS (`v26.06` / Alpine `edge` `armv7`), purpose-built for **Qualcomm MSM8905 (Snapdragon 205)** and **Qualcomm MSM8909 (Snapdragon 210)** smart feature phones with **240x320 QVGA non-touch displays** and **physical 12-key T9 keypads**.

See [The Bananarchy Manifesto](./MANIFESTO.md) for the rationale behind this entire project.

Bananarchy targets an ultra-lightweight **Sxmo X11 (`sxmo-de-dwm`)** environment (with all Wayland components removed), featuring:

- **Cross-compiled Xlibre (`X11Libre/xserver` 25.2.0) display server**: `modesetting` KMS + `ShadowFB` Damage partial-rectangle SPI transfers, software cursor fallback, and rootless `elogind` integration.
- **Patched `sxmo-dwm` with native C/C++ plugin architecture**: `240x320` vertical `bstack` layout, 24px Pango status bar with an overflow-protected right-aligned clock, transparent-backgrounded `"Menu"` and `"Names"` desktop softkey labels, direct C `SW_LID` slider and locked-key wake handling in `< 2 ms`, and a dynamic `.so` plugin API (`dwm_plugin.h`) with preloaded resident daemons (`--preload`) and non-blocking FIFO IPC (`< 10 ms` wakeup latency).
- **Preloaded `240x320` keypad-driven DWM plugins (`dmenu`, `xdrawer`, `dialer`, `calllog`, `callscreen`, `contacts`, `sms`, `files`, `camera`, `themes`)**:
  - **`DMenu` (`dmenu.so` / `dmenu` / `xdmenu`)**: zero-lag (`< 2 ms` popup/close) resident `240x320` full-screen 10-line vertical menu (`240x296` flush below the 24px top bar) with a `#383838` search bar, `#005577` prompt badge, `XIM` `fcitx5-t9` text input, in-place `< 0.5 ms` native Sxmo submenu transitions (`Sys`, `Apps`, `Scripts`, `Modem`, `Config`, `Power`, `St`, `Nano`), and a `/tmp/dwm_plugin_dmenu.sock` client interface serving all `/usr/bin/dmenu` and `sxmo_dmenu.sh` pipes instantaneously.
  - **`XDrawer` (`xdrawer.so` / `xdrawer`)**: global phone controls overlay invoked from anywhere by pressing **both softkeys simultaneously**, providing instant sliders and toggles for speaker volume, earpiece volume, flashlight, sound mute, microphone mute, screen brightness, and keypad backlight.
  - **`Dialer` (`dialer.so` / `xdialer`)**: opens automatically from the idle desktop when pressing any **`0`–`9`, `*`, or `#` key** (inserting that character immediately), with live T9/number contact filtering, hold-`0` for `+`, and single-press **Call** dialing.
  - **`Call Log` (`calllog.so` / `xcalllog`)**: opens automatically from the idle desktop when pressing the **Call (green)** button, with `All` / `Missed` / `In` / `Out` tabs, contact resolution, call durations, and instant redial.
  - **`Call Screen` (`callscreen.so` / `xcallscreen`)**: dedicated incoming, outgoing, and in-call screen integrated with Sxmo's `ModemManager` call lifecycle (`sxmo_modem.sh`, `sxmo_modemcall.sh`, `sxmo_modemdial.sh`), displaying resolved caller name and phone number, accepting/rejecting incoming calls via physical **Call (green)** and **End (red)** buttons (plus `*`/`0` ringtone silence), live `MM:SS` call timer, microphone mute/unmute (`1`/`*`), live call recording to `~/Recordings/call_<caller>_<timestamp>.wav` (`2`/`#`), earpiece/speaker audio routing (`3`), volume control (`Left`/`Right`), and DTMF tone keypad mode (`0` / `Left softkey`).
  - **`Contacts` (`contacts.so` / `xcontacts`)**: full-featured phonebook application opened from the idle desktop via the **Right softkey (`Names`)** or from the Sxmo menu, integrated with `~/.config/sxmo/contacts.tsv` (live T9/number search, call/SMS/dialer actions, built-in contact editor with keypad multi-tap name entry and recent-caller number picker, and contact deletion).
  - **`SMS Manager` (`sms.so` / `xsms`)**: conversation thread manager, bubble message history reader, and multi-tap keypad SMS composer/draft editor (with dynamic `Send` / `Draft` center softkey action) integrated with `$SXMO_LOGDIR/<number>/sms.txt`, `draft.txt`, `modemlog.tsv`, and `sxmo_modemsendsms.sh`.
  - **`File Manager` (`files.so` / `xfiles`)**: graphical directory browser with live T9/number filtering, dotfiles toggle (`*`), sort mode cycle (`#`), file operations (new folder/file, rename, copy, cut/move, paste, delete, properties, edit in `nano`, open terminal here), built-in text viewer, and built-in `libjpeg`/`libpng` image previewer.
  - **`Camera` (`camera.so` / `xcamera`)**: live V4L2 `/dev/video0` (`800x600` `RGB24` -> `240x180` 4:3) viewfinder with 1-second frame watchdog, auto-flash (`*`/`1`), continuous torch (`0`/`2`), digital zoom (`1x`/`2x`/`4x` via `Up`/`Down`), 3-second self-timer (`#`/`3`), direct `libjpeg` photo capture to `~/Pictures/photo-YYYYMMDD-HHMMSS.jpg`, and built-in photo gallery.
  - **`Theme Manager` (`themes.so` / `xthemes`)**: unified `.Xresources` theme browser and live customizer managing `~/.xthemes/*.xth` (where every `.xth` file is a valid `Xresources` file controlling `theme.*`, `dwm.*`, `dmenu.*`, `st.*`, and `svkbd.*` colors, font face, and `baseFontSize` with proportional derived font sizes, pre-populated with 20 themes: `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`). Applying or editing a theme reloads `dwm`, `dmenu`, `st`, and all resident DWM plugins live without restarting X11.
- **Patched `sxmo-st` terminal (`pixelsize=18`)**: **HarfBuzz (`libharfbuzz`) OpenType ligature shaping** (`liga`, `calt`, `clig`, `dlig`) and `XIM` support.
- **Typography**: non-Nerd **`Fira Code` (`font-fira-code`) with ligatures** as the primary system and terminal font (with `DejaVu SansM Nerd Font` used strictly as an icon fallback).
- **Custom 6-mode `fcitx5-t9` input engine**: fixed bottom candidate bar (`X=1, Y=290, W=238, H=30`) with a constant 28-character monospace preedit layout supporting lowercase, one-shot Shift, Caps Lock, all 32 ASCII punctuation symbols, terminal control codes (`^A`-`^Z`, `Esc`, `Tab`, `F1`-`F12`), and direct numeric entry with live top-bar mode indication (`[abc]`, `[Abc]`, `[ABC]`, `[Sym]`, `[Ctl]`, `[123]`).
- **Low memory footprint**: sub-95 MB idle RAM usage on 512 MB devices.
- **Full Qualcomm QDSP6/Q6Voice audio & modem routing**: loudspeaker, earpiece speaker, and internal/headset microphones with PM8909 WCD analog codec 2.8V micbias, +6 dB EAR PA gain, and GSM/WCDMA/LTE voice routing (`ModemManager` + `q6voiced`).
- **Rear 2MP camera support**: `msm8905-cam` V4L2 driver for GalaxyCore `GC2395` + MSM8909 `CAMSS` on `/dev/video0`, native `xcamera` DWM plugin, and the `bananarchy-photo` CLI utility.
- **Pre-integrated Bantam AI agent**: cross-compiled from `https://code.luxferre.top/luxferre/bantam-cpp` and integrated into the Sxmo **Apps** menu (`Applications -> Bantam`, launching in an `st` terminal with `$HOME` as its default working directory).
- **Complete on-device development & scripting stack**: `git`, `gcc`/`g++`, `make`, GNU `coreutils`, `nano` (`$EDITOR`, pre-configured in `/etc/nanorc` with `-FEDSMAGic/max%_T2`), `ed`, `less` (`$PAGER="less -RXF"`), `rlwrap`, `frotz` (Z-machine interactive fiction interpreter), `janet` + `jpm`, `perl` + `IO::Socket::SSL`, `tcl` + `tcllib`/`tcl-tls`/`sqlite-tcl`, `sqlite`, `i2c-tools`, and `v4l-utils`.

---

## Supported MSM8909 / MSM8905 devices

| Device | Codename | SoC | CPU / RAM | Display & panel firmware | Device tree (`.dtb`) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Nokia 8110 4G** | `nokia-argon` | Qualcomm MSM8905 (SD205) | 2x Cortex-A7 @ 1.1 GHz, 512 MB | 2.4" 240x320 SPI (`nokia,argon-gc9305-v2-panel.bin`) | `qcom-msm8905-nokia-argon.dtb` |
| **Nokia 2720 Flip** | `nokia-beatles` | Qualcomm MSM8905 (SD205) | 2x Cortex-A7 @ 1.1 GHz, 512 MB | 2.8" 240x320 SPI (`nokia,beatles-gc9305-panel.bin`) | `qcom-msm8905-nokia-beatles.dtb` |
| **Nokia 800 Tough** | `nokia-tough` (`nokia-coconut`) | Qualcomm MSM8905 (SD205) | 2x Cortex-A7 @ 1.1 GHz, 512 MB | 2.4" 240x320 SPI (`nokia,coconut-gc9305-panel.bin`) | `qcom-msm8905-nokia-coconut.dtb` |
| **Nokia 8000 4G** | `nokia-sparkler` | Qualcomm MSM8909 (SD210) | 4x Cortex-A7 @ 1.1 GHz, 512 MB | 2.8" 240x320 SPI (`nokia,sparkler-gc9307-hlt-28-panel.bin`) | `qcom-msm8909-nokia-sparkler.dtb` |
| **Nokia 6300 4G** *(sibling)* | `nokia-leo` | Qualcomm MSM8909 (SD210) | 4x Cortex-A7 @ 1.1 GHz, 512 MB | 2.4" 240x320 SPI (`nokia,leo-gc9305-hlt-24-panel.bin`) | `qcom-msm8909-nokia-leo.dtb` |

---

## Repository structure

```text
bananarchy/
├── README.md                              # Project architecture, build system, and quickstart guide
├── MANIFESTO.md                           # The Bananarchy Manifesto
├── MANUAL.md                              # Complete flashing, keypad, T9, camera, audio, Bantam, and modem manual
├── flash-edl.sh                           # Automated USB EDL flasher wrapper (sudo + ModemManager handling)
├── flash-edl.py                           # Multi-device Qualcomm Sahara/Firehose EDL flasher
├── rebuild-image.sh                       # Builds boot.img, MBR raw .img, and Android .sparse.img
├── chroot-shell.sh                        # Rootless Docker armv7 package & rootfs customization shell
├── artwork/                               # Bananarchy master icon, generated icons, wallpapers, and splashes
│   ├── icon-large.png                     # Master 1024x1024 Bananarchy emblem
│   ├── icon-{512..16}.png                 # Downsampled RGB square icons
│   ├── icon-transparent-{512..32}.png     # Alpha-keyed RGBA icons for UI themes
│   ├── favicon.ico                        # Multi-resolution ICO
│   ├── wallpaper-240x320.png / .jpg       # Default Sxmo 240x320 portrait wallpaper
│   ├── wallpaper-240x320-centered.png/.jpg# Centered 240x320 portrait wallpaper
│   ├── wallpaper-320x240.png / .jpg       # Landscape 320x240 QVGA wallpaper
│   ├── wallpaper-240x240.png              # Square 240x240 wallpaper (Nokia 2720 Flip external display)
│   ├── splash-240x320.png / .ppm          # 240x320 boot splash image
│   └── banner-800x240.png                 # Project header banner
├── bootloader/
│   ├── lk2nd-msm8909.img                  # lk2nd secondary bootloader for MSM8905/MSM8909
│   └── loaders/
│       └── 8110.mbn                       # Qualcomm Sahara/Firehose programmer (05c6:9008)
├── devices/                               # Device definitions, DTBs, and MIPI-DBI panel init sequences
│   ├── common-msm8909/                    # Shared udev keypad rules, WirePlumber S16LE, ALSA UCM2, zram
│   ├── nokia-argon/                       # Nokia 8110 4G device package, DTS/DTB, and GC9305 panel init
│   ├── nokia-beatles/                     # Nokia 2720 Flip device package, DTS/DTB, and GC9305 panel init
│   ├── nokia-tough/                       # Nokia 800 Tough device package, DTS/DTB, and GC9305 panel init
│   └── nokia-sparkler/                    # Nokia 8000 4G & 6300 4G device package, DTS/DTB, and GC9307/9305 init
├── patches/
│   ├── kernel/
│   │   ├── 0001-msm8909-qdsp6-voice-sound-nokia-argon-6.12.patch
│   │   ├── 0002-msm8905-nokia-beatles-and-coconut-dts.patch
│   │   └── config-bananarchy-msm8909.armv7
│   ├── edl/
│   │   └── 0001-edl-msm8909-32bit-elf-and-multi-cmd-firehose.patch
│   ├── sxmo/
│   │   └── 0001-bananarchy-sxmo-240x320-keypad-ui.patch
│   ├── xlibre/
│   │   ├── 0001-xlibre-msm8905-spi-drm-and-shared-vt.patch
│   │   ├── 0002-xf86-input-libinput-xlibre25.patch
│   │   └── 0003-xf86-video-fbdev-xlibre25.patch
│   └── fcitx5-t9/
│       └── 0001-bananarchy-multimode-t9-and-fcitx5-5.1.19.patch
├── src/
│   ├── sxmo-dwm/                          # Patched sxmo-dwm (240x320 bstack, Pango bar, desktop softkey bar & plugin API)
│   ├── dwm-plugins/                       # DWM plugins (dialer, calllog, callscreen, contacts, sms, files, camera, themes), theme.h & runner
│   ├── xdrawer/                           # XDrawer global phone controls DWM plugin (xdrawer.so / xdrawer)
│   ├── sxmo-dmenu/                        # Patched sxmo-dmenu zero-lag DWM plugin (dmenu.so) & client/fallback (dmenu / xdmenu)
│   ├── sxmo-st/                           # Patched sxmo-st terminal with HarfBuzz Fira Code ligature shaping & XIM
│   ├── xf86-input-libinput/               # X11Libre xf86-input-libinput DDX driver
│   ├── xf86-video-fbdev/                  # X11Libre xf86-video-fbdev fallback DDX driver
│   ├── fcitx5-t9/                         # C++20 source of Bananarchy's 6-mode fcitx5-t9 input method
│   ├── leds-msm8905-torch/                # Kernel driver for SY7807 rear torch LED, WCD codec init & PM8909 PON shutdown
│   └── msm8905-cam/                       # Kernel V4L2 driver for GC2395 2MP rear camera & MSM8909 CAMSS (/dev/video0)
├── overlay/
│   └── rootfs/                            # Complete Bananarchy rootfs overlay (OS branding, Sxmo X11, audio, camera, T9, .xthemes)
├── prebuilt/
│   ├── xlibre/                            # Prebuilt armv7 Xlibre Xorg binary and modesetting/libinput/fbdev DDX modules
│   ├── sxmo-x11/                          # Prebuilt armv7 patched dwm, dmenu.so/dmenu, 9 C++ DWM plugins, and st (HarfBuzz ligatures)
│   ├── kernel-6.12.1-msm8916/             # Prebuilt QDSP6/Q6Voice .ko, torch .ko, camera .ko, and 5 device DTBs
│   ├── fcitx5-t9/                         # Prebuilt armv7 libt9.so and fcitx5 addon/inputmethod configs
│   └── bantam/                            # Prebuilt armv7 bantam AI agent binary
└── scripts/
    ├── generate-artwork.py                # Generates all wallpapers, icons, and splashes from icon-large.png
    ├── mipi-dbi-cmd.py                    # Compiles MIPI-DBI panel .txt init sequences into .bin firmware
    ├── build-xlibre.sh                    # Cross-compiles Xlibre + xf86-input-libinput + xf86-video-fbdev for armv7 Cortex-A7
    ├── build-sxmo-x11.sh                  # Cross-compiles sxmo-st (HarfBuzz), sxmo-dmenu (dmenu.so + dmenu), sxmo-dwm & DWM plugins
    ├── build-kernel-audio.sh              # Cross-compiles Linux 6.12.1-msm8916 QDSP6/torch/camera modules & DTBs
    ├── build-fcitx5-t9.sh                 # Cross-compiles src/fcitx5-t9 for armv7
    ├── build-bantam.sh                    # Fetches master from https://code.luxferre.top/luxferre/bantam-cpp & cross-compiles for armv7
    ├── apply-bananarchy-overlay.sh        # Applies overlay, prebuilts, artwork, and device DTB to rootfs
    └── configure-rootfs-from-scratch.sh   # Full rootfs configuration script from base Alpine/pmOS packages
```

---

## Build & customization workflow

### 1. Regenerate artwork assets
Whenever `artwork/icon-large.png` is updated, regenerate all icons, `240x320` wallpapers, and boot splashes:
```bash
./scripts/generate-artwork.py
```

### 2. Recompile core components (optional — prebuilts included)
All components are pre-compiled in `prebuilt/` and `overlay/rootfs/`, and can be rebuilt from source at any time using rootless Docker (`alpine:3.24`):
```bash
# Rebuild cross-compiled Xlibre (X11Libre/xserver) + libinput/fbdev DDX drivers
./scripts/build-xlibre.sh

# Rebuild patched sxmo-st (HarfBuzz Fira Code ligatures), sxmo-dmenu (dmenu.so + dmenu), sxmo-dwm & all 8 DWM plugins
./scripts/build-sxmo-x11.sh

# Rebuild multi-mode fcitx5-t9 input engine (src/fcitx5-t9 -> prebuilt/fcitx5-t9)
./scripts/build-fcitx5-t9.sh

# Fetch latest master from https://code.luxferre.top/luxferre/bantam-cpp and cross-compile Bantam AI agent
./scripts/build-bantam.sh

# Rebuild Linux 6.12.1-msm8916 QDSP6/Q6Voice audio modules, torch LED module, camera module & DTBs
./scripts/build-kernel-audio.sh
```

### 3. Customize rootfs packages or configs
```bash
./chroot-shell.sh
# Inside the container shell:
#   pkg-add <pkg>
#   pkg-del <pkg>
#   pkg-search <pattern>
```

### 4. Build flashable device images
```bash
# Build for Nokia 8110 4G (default)
./rebuild-image.sh nokia-argon

# Or build for Nokia 2720 Flip, Nokia 800 Tough, or Nokia 8000 4G:
./rebuild-image.sh nokia-beatles --mkinitfs
./rebuild-image.sh nokia-tough --mkinitfs
./rebuild-image.sh nokia-sparkler --mkinitfs
```
Output images are written to `images/`:
- `images/bananarchy-<device>.img` (raw partitioned MBR image for EDL `userdata` or microSD card)
- `images/bananarchy-<device>.sparse.img` (Android sparse image for `fastboot flash userdata`)
- `images/boot-bananarchy-<device>.img` (kernel + initramfs + DTB boot image)

---

## Flashing via USB EDL (`05c6:9008`)

```bash
sudo ./flash-edl.sh nokia-argon
```
See [MANUAL.md](MANUAL.md) for complete EDL, Fastboot, and microSD installation instructions, keypad navigation shortcuts, and the multi-mode T9 reference.

## Credits

All Bananarchy-specific components were initially created by Luxferre and released into the public domain with no warranties.

Alpine Linux, postmarketOS/Nura and other third-party components are guided by their respective licensing terms.