xteink-4-in-a-row

xteink-4-in-a-row

Minimal firmware scaffold for a custom Xteink X4 project built around a Connect Four-style game.

Original blog post referencing this project

Current scope

• Minimal ESP32-C3 firmware scaffold
• Small source tree for board, app, game, and storage code
• Provisional Xteink-oriented input, battery, and idle-sleep plumbing
• Persistent settings and stats storage
• Device-oriented e-ink rendering path plus serial fallback/debug rendering
• Release and web flasher planning docs
• Attribution and license boundaries for CrossPoint Reader references

Current assumptions

These are provisional and should be verified before real bring-up or flashing:

• target SoC: ESP32-C3
• flash size: 16 MB
• app image offset: 0x10000
• dual-OTA-slot layout is desirable for a later browser flasher flow
• button inputs are read through the public Xteink X4-style ADC ladder / power button layout
• battery sensing uses a provisional GPIO0 divider read and optional USB sense on GPIO20

No hardware flashing is performed by this scaffold.

Layout

• src/main.cpp - tiny firmware entry point
• src/app/ - app shell and menu flow
• src/board/ - device-specific display, input, and power hooks
• src/game/ - Connect Four rules and state
• src/storage/ - settings, saves, and stats
• include/ - shared project config
• docs/crosspoint-boundaries.md - attribution and reuse rules
• docs/flashing-and-releases.md - release artifact and web flasher plan

Build

This repo is scaffolded for PlatformIO + Arduino on ESP32-C3.

pio run

The included platformio.ini and partitions.csv are placeholders for early bring-up and must be verified against the actual Xteink X4 hardware before device flashing.

First bring-up

The current repo is now prepared for a first manual bring-up attempt. See docs/first-bringup.md for:

• build artifact location
• backup commands
• first flash command
• current hardware assumptions and risks

Host-friendly validation

There is also a lightweight logic check script for the core Connect Four rules and obvious bot scenarios:

python tests/run_logic_checks.py

CrossPoint Reader boundaries

CrossPoint Reader and its separate flasher are useful references, but this repo does not currently include copied CrossPoint code, assets, or branding. See docs/crosspoint-boundaries.md for the exact reuse rules.