README.md
# F1C100S Linux Game Boy Advance
A four-layer, GBA-shaped tscircuit handheld built around the tested F1C100S Linux design. The editable source is `index.circuit.tsx`; the generated PCB, schematic, circuit JSON, Gerbers, drill files, BOM and position data are derived artifacts.
This revision is designed and software-checked for fabrication, but it has not yet been physically assembled or boot-tested. Do not confuse zero software DRC with hardware qualification: first articles still need rail, thermal, display timing, audio and USB measurements.
## Hardware
- Allwinner F1C100S ARM9 SoC with 32 MiB integrated DDR1 and the complete tested support circuit.
- 16 MiB W25Q128 SPI NOR plus 4-bit microSD for boot/root filesystem. The TF-01A socket now finishes 0.399 mm behind a dedicated right-edge PCB recess, so the card mouth is genuinely enclosure-accessible instead of buried inside the board outline.
- 50-pin 0.5 mm RGB666 connector for the 3.5-inch 320 × 480 ER-TFT035IPS-6 family. The panel is rotated 90° into landscape; its flex folds back into the right-side connector toward the left. The 3D view uses a purpose-built, manufacturer-dimensioned assembly model: 55.50 × 84.96 × 2.50 mm outer stack, 48.96 × 73.44 mm active area, metal backlight frame, capacitive-touch bezel, 50-way 0.5 mm FPC, copper fingers, stiffener, driver area, and the installed cable rise from `J_LCD`. The board also routes the panel serial-control and optional touch signals.
- Twelve controls: D-pad, A/B/X/Y and bottom-half Start/Select use the verified Game Boy's 15 mm actuators; L/R use JLCPCB `C33543626` (`TS66135ZJ 022`), the 13.5 mm long-stem variant of the original low-profile 7.3 × 6.1 mm right-angle switch family. The housings stop flush with the top PCB edge and only the round stems extend 9.6 mm beyond it. A PCF8575 I²C expander presents the controls to Linux as active-low GPIO inputs.
- Native USB 2.0 device/FEL on USB-C with independent 5.1 kΩ CC pull-downs and USBLC6-2 ESD protection.
- Four-AAA 4.8–6.4 V battery input with resettable fuse, hard power switch and Schottky OR-ing with USB power. The 4.8 V minimum leaves headroom for the AP63203 buck after the input protection losses. Following the AGB-001 bottom-control layout, the power slider is on the lower-left and the volume control is on the lower-right when the console is viewed from the front. The electrical switch is recessed 7.4 mm behind the PCB edge for a guarded enclosure slider, so it cannot be brushed directly during play.
- Rounded, non-plated battery-cable exit beside the right-facing battery connector, with a conservative 5.95 mm connector-to-cutout bend corridor matching the tall-switch Game Boy reference's enclosure routing.
- AP63203 buck to 3.3 V, followed by dedicated 2.5 V DRAM, 1.2 V core and 2.8 V analog rails.
- F1C100S headphone output feeding a volume control and PAM8403 mono bridge amplifier. `J_SPK` is the amplified two-wire **BTL speaker output** for a 4–8 Ω internal speaker: pin 1 is `SPK+`, pin 2 is `SPK-`, and neither pin may be connected to ground.
- Reset button and a removable SPI-flash chip-select boot shunt in the upper-left service area outside the landscape LCD envelope.
- Bottom-side rear-edge JST-SH service connectors for standard UART programming, I²C and SPI. These occupy the AGB-001's top/rear expansion area rather than the front controls or lower grip area.
The LCD panel, speaker and 4×AAA holder are cable-connected mechanical parts and are not placed by JLCPCB. Every fitted PCB component has an explicit JLCPCB/LCSC part number and a renderable, non-placeholder 3D model; `jlc-availability.json` is the point-in-time, quantity-aware live-stock audit.
## Fabrication rules
- Board envelope: 144.5 × 82 mm, custom rounded handheld outline.
- Stack: four copper layers, 1.6 mm FR-4, 1 oz outer copper / default JLC inner copper.
- Minimum routed trace/clearance: 0.12 / 0.10 mm.
- Every signal/power via: **0.30 mm finished hole, 0.45 mm copper pad**.
- Minimum via finished-hole edge spacing: 0.20 mm.
- Battery-cable edge cut: 5 mm wide, 11 mm overall cutout length, with 9.5 mm extending into the PCB and a rounded closed end.
- MicroSD access bay: the local right board edge is pulled in to x=65 mm, leaving 0.399 mm from the TF-01A footprint to the routed edge.
- Ground pours on all four layers; the dense processor module is routed first and reserved from carrier routing.
JLCPCB currently lists 0.30/0.45 mm vias within its multilayer capability and requires 0.20 mm via hole-to-hole spacing. Re-run the fab’s own upload DFM because fabrication capabilities and panelization decisions can change.
## Build and verify
```sh
bun install
bun run typecheck
bun run build
bun run verify
bun run check:source
bun run check:netlist
bun run check:shorts
bun run audit:jlc
```
`bun run verify` rejects any emitted `*_error`, any via not exactly 0.30/0.45 mm, insufficient via finished-hole spacing, missing critical hardware, missing controls, a fitted part without a JLCPCB number, or a fitted part without a non-placeholder 3D model. `check:shorts` performs the independent Gerber-mode shorts test on all copper layers. The inventory audit also requires stock to cover this board's fitted quantity. Inventory is not reserved; check it again at order time.
## Linux bring-up
Use an F1C100S-capable U-Boot and Linux configuration. Mainline Linux supports the CPU, SPI NOR, microSD, UART, I²C/GPIO expander and USB device path; the complete LCD pipeline still normally uses the display-enabled Lichee Pi Nano/F1C100S BSP.
1. Build U-Boot/SPL for 32 MiB F1C100S DRAM and enable SPI0, MMC0, UART0 and USB FEL.
2. Include `firmware/carrier.dtsi` in the board DTS. It enables storage, console, fixed-device USB and the PCF8575 gamepad.
3. For a display-enabled BSP, adapt `firmware/display-bsp-example.dtsi` and initialize the ILI9488 over PE7–PE10 before enabling RGB scanout. Confirm the exact panel order code and timing table; the example timings are only a safe bring-up starting point.
4. Fit `JP_BOOT` for SPI-flash boot. Remove it for reliable USB FEL recovery from blank/bad flash.
5. Use a 3.3 V UART adapter at 115200 8N1 on `J_UART`; its standard-programmer order is pin 1 RX, pin 2 GND, pin 3 TX.
The controller appears as a normal Linux input device through `gpio-keys-polled`. The 8 ms polling interval avoids depending on GPIO-expander interrupt support in older BSP kernels.
## Display connector notes
The selected 50-pin family uses RGB666 mode straps on pins 7–9. Pins 11–14 carry VSYNC, HSYNC, DOTCLK and DE; pins 15–32 carry DB17–DB0. Pins 33–38 carry the serial-control bus used for panel initialization. Pins 44–47 are available for optional I²C touch clock/data/reset/interrupt. The board supplies 3.3 V panel logic/analog power. An AP3031 boost/current regulator drives the three series backlight LEDs at a regulated 100 mA using a 2 Ω sense network; the backlight is enabled whenever the 3.3 V rail is on.
The intended panel is the [BuyDisplay 3.5-inch IPS 320×480 capacitive-touch display](https://www.buydisplay.com/3-5-inch-ips-320x480-tft-lcd-display-capacitive-touch-screen). Its native portrait shape does not lock the Linux framebuffer to portrait: mount the panel 90° clockwise for a landscape handheld and configure the framebuffer/application rotation accordingly. In that mounting, the flex tail is on the display's right, folds/rises under the panel, and enters the bottom-contact `J_LCD` toward the left. The display back is modeled 7 mm above the component-side PCB surface, leaving room for the populated electronics beneath it while keeping the front glass below the 15 mm control actuators. Confirm the ordered panel's 50-pin pinout and flex-tail drawing against ER-TFT035IPS-6 before fabrication, because BuyDisplay offers multiple interface options on the same product page.
## Rear service connectors
All three service headers are bottom-side JST-SH connectors on the top/rear enclosure edge. I²C and SPI are side-entry; UART uses the upward-entry `C160389` from the official standard-programmer package because its side-entry sibling is no longer stocked:
- `J_UART` (3-pin): RX, GND, TX. This follows the standard tscircuit JST programmer pin order.
- `J_I2C` (4-pin): GND, 3V3, SDA (PE12), SCL (PE11).
- `J_SPI` (6-pin): GND, 3V3, SCLK (PE9), MOSI (PE8), MISO (PE10), CS (PE7).
`J_SPI` intentionally exposes the same SPI1 bus used to initialize the LCD controller. Disconnect external SPI hardware during panel initialization, or guarantee that its chip-select is inactive and its MISO output is high-impedance, to avoid contention.
## Power and first-article checks
- Use four alkaline or NiMH AAA cells only through the battery connector, and treat 4.8 V at the connector as the minimum specified operating voltage. Do not connect Li-ion cells directly; there is no charger or protection circuit.
- USB-C is a device/sink port, not a host or USB-PD source.
- Before fitting the SoC, verify the switched input and 3.3/2.5/1.2/2.8 V rails for polarity and tolerance.
- On the first assembled unit, current-limit the supply, confirm power sequencing and thermal rise, then validate the 24 MHz oscillator and UART before booting flash.
- Final USB differential impedance depends on the ordered JLCPCB four-layer stackup. Ask the fab to impedance-check the selected stackup if USB margin matters.
## References
- Tested starting point: https://tscircuit.com/seveibar/f1c100s-linux-dev-board
- Game Boy reference: https://tscircuit.com/abse/gameboy
- Earlier GBA work-in-progress: https://tscircuit.com/abse/gameboy-advance
- Official Nintendo AGB-001 manual and physical-control diagram: https://www.nintendo.com/eu/media/downloads/support_1/game_boy_advance_4/GBA_Manual_UK_DE_FR.pdf
- JLCPCB capabilities: https://jlcpcb.com/capabilities/pcb-capabilities/
- AP63200/AP63203 buck-regulator datasheet: https://www.diodes.com/datasheet/download/AP63200-AP63201-AP63203-AP63205.pdf
- AP3031 LED-driver datasheet: https://datasheet.lcsc.com/lcsc/1811081712_Diodes-Incorporated-AP3031KTR-G1_C82636.pdf
- ER-TFT035IPS-6 datasheet: https://www.buydisplay.com/download/manual/ER-TFT035IPS-6_Datasheet.pdf
- Intended BuyDisplay panel: https://www.buydisplay.com/3-5-inch-ips-320x480-tft-lcd-display-capacitive-touch-screen
- Linux F1C100S pinctrl: https://github.com/torvalds/linux/blob/master/drivers/pinctrl/sunxi/pinctrl-suniv-f1c100s.c
