OctaneOS isn’t a ROM you flash and forget. It’s a custom Linux distribution built from source, specifically for Octane hardware, reproducible from a clean machine. Here’s how it works.
Table of Contents
The Foundation: Batocera Linux
OctaneOS starts as a fork of Batocera Linux — the gold standard for retro emulation distros. Batocera gives us a proven emulation engine, EmulationStation as the frontend, and a mature RetroArch core library. It’s not reinventing the wheel. It’s taking the best wheel available and fitting it to hardware it was never designed to run on.
The catch: Batocera has no Allwinner A733 support. None. So everything below the emulation layer — the kernel, the device tree, the display driver, the hardware abstraction — had to be built from scratch.
The Build System: Buildroot
Batocera is built on Buildroot, a tool that compiles an entire Linux system from source — kernel, rootfs, libraries, applications — into a single flashable image. Every dependency is pinned. Every build is reproducible. You can clone the repo, run the build, and get the exact same image every time.For OctaneOS, Buildroot is where Octane-specific hardware support lives. The A733 board definition, the custom device tree, the kernel config, the Octane-specific packages — all of it is expressed as Buildroot config and fed into the build pipeline.
The Kernel: Allwinner A733 BSP
The kernel is Linux 5.15 from Radxa’s Allwinner AIOT BSP — the same kernel the Cubie A7S ships with. It has drivers for the A733’s hardware: the LCD0 DPI interface for the screen, the TWI I2C buses for the button expander and touch controller, USB-C DisplayPort Alt Mode for dock output, and the PCIe FFC expansion port for the MT7921K WiFi card.The Armbian community’s A733 build serves as a reference throughout. When something isn’t documented, that codebase is the first place to look.
The Device Tree: Teaching Linux About Octane
A device tree is how Linux learns what hardware is connected and how to talk to it. For OctaneOS, a custom device tree tells the kernel exactly what Octane is: which pins drive the DPI screen, which I2C bus the MCP23017 button expander lives on, how the USB-C port is configured, where the PCIe WiFi card is wired in.This is one of the most hardware-specific pieces of the entire build. Get it wrong and the screen doesn’t come up. Get it right and the kernel just handles everything.
The CI Pipeline: GitHub Actions
Every push to the OctaneOS repo triggers a GitHub Actions build. The full Buildroot compile runs in the cloud and the output image is stored as a build artifact — meaning the build is always in a known state, anyone can reproduce it without a beefy local machine, and everything is auditable.
The wrinkle: A full OctaneOS build spans multiple CI sessions — weeks of cumulative build time across iterative runs as the A733 target has been developed from scratch. The solution came from a lateral observation — if a job is deliberately structured to fail at a checkpoint after caching its build artifacts, the next run picks up exactly where the last one left off. What looks like a failed build is actually a save state. The build crosses the finish line across multiple runs without losing any work.
One additional blocker required outside help to clear. Two packages in the Batocera build — ecwolf and same-cdi — depend on source repositories hosted on private Bitbucket infrastructure that CI runners can’t reach. suckbluefrog from the Batocera-Multilib community solved this by providing pre-packaged Buildroot download cache tarballs for both packages, allowing the build to proceed without needing access to those private repos. Without that contribution, CI would have been dead in the water on those packages indefinitely.
What’s Octane-Specific on Top
Once the base system builds cleanly, OctaneOS layers on everything that makes it Octane:
Three mode detection — handheld, docked, and wireless streaming, automatic based on USB-C state and WiFi connection
RetroAchievements — configured and credentialed out of the box
Cover art dock mode — screen switches to full-screen cover art when docked
Streetpass daemon — background WiFi beacon for passive community interactions
GameOctane app — on-device community hub, news, leaderboards, updates
OTA update system — signed update packages pushed from GameOctane.com
None of this ships in upstream Batocera. All of it is Octane’s.
Where It Stands Now
The build environment is up. The A733 target is defined. GitHub Actions CI is running. The hard work ahead is hardware bring-up — getting the DPI screen talking, validating the device tree against real silicon, and running the first ROM.
That milestone — first game running on real Octane hardware — is when OctaneOS stops being a build system and starts being a gaming OS. We’ll document every step getting there.
If you want to understand the full hardware and software picture before diving into the build system, the platform spec covers everything — SoC selection, GPIO allocation, dock architecture, WiFi design, and the phase plan. It lives in the repo alongside the code: Octane Platform Spec v1.3
Follow along at GameOctane.com or watch the commits at github.com/GameOctane/OctaneOS
New to Octane? Start here: Introducing Octane — We’re Building the Retro Handheld You Actually Own
