NetDeck M1: hardware sandbox — full-frame sprite rendering + firmware build

- render into a full-frame RAM second buffer (TFT_eSprite/PSRAM on device,
  SDL shim framebuffer in the emulator) and push to the ST7789 as one
  continuous SPI stream per frame (MiataDrive anti-tearing pattern)
- keyboard stale-byte flush at boot end; device-trackball constants branch
- examples/NetDeck/platformio.ini: self-contained firmware build
  (pio run -d examples/NetDeck), ESP32-S3 compile verified
  (RAM 6.7% / Flash 5.5%), binary at firmware/NetDeck_M1_261114.bin
- STATUS.md: M1 tracker + on-device flashing checklist
- IDEAS.md: capture map-scroll and companion-app ideas
This commit is contained in:
Dejvino
2026-11-14 11:04:24 +01:00
parent 2bfd6c6428
commit 3dcafa25e7
6 changed files with 189 additions and 85 deletions
+118 -77
View File
@@ -1,10 +1,11 @@
/**
* @file NetDeck.ino
* @brief NetDeck — Breach & Board: Milestone 0 emulator sandbox.
* @brief NetDeck — Breach & Board: Milestone 1 hardware sandbox.
*
* Milestone 0 (DESIGN.md §7): the Milestone-1 hardware sandbox prepared and
* tested locally, without hardware. This sketch exercises every tech piece
* the real build needs, on the SDL2 emulator first:
* Milestone 1 (DESIGN.md §7): the same M0 sandbox sketch prepared for the
* T-Deck hardware. Rendering goes into a full-frame RAM sprite and is pushed
* to the ST7789 as one continuous SPI stream (anti-flicker, see present());
* the emulator draws straight into the SDL shim framebuffer instead.
*
* - shared tactical view (320x192) + HUD bar, ONE coordinate space:
* bulkhead doors and their network door nodes occupy the same spot
@@ -43,6 +44,33 @@ TFT_eSPI tft;
TouchDrvGT911 touch;
static bool touchAvail = false;
// ---------------------------------------------------------------------------
// Full-frame rendering — draw into a RAM buffer, push to the panel once per
// frame (the MiataDrive anti-flicker pattern: thousands of small draw calls
// racing the panel's scan-out cause tearing; one continuous SPI stream writes
// each pixel exactly once). Emulator: the SDL shim framebuffer IS the second
// buffer, so we draw straight into it.
// ---------------------------------------------------------------------------
#ifndef EMULATOR
static TFT_eSprite fb(&tft); // full-frame 320x240x16 buffer (PSRAM)
static TFT_eSprite *const GFXP = &fb;
#else
static TFT_eSPI *const GFXP = &tft;
#endif
#ifndef EMULATOR
// Push the finished frame to the ST7789 as one continuous SPI stream.
static void present()
{
if (!fb.created()) return;
tft.startWrite();
fb.pushSprite(0, 0);
tft.endWrite();
}
#else
static void present() {} // shim blits the SDL framebuffer
#endif
// ---------------------------------------------------------------------------
// Game state
// ---------------------------------------------------------------------------
@@ -379,9 +407,9 @@ static void renderMap(bool dim)
for (int tx = 0; tx < nd::TILE_COLS; tx++) {
uint16_t c = tileColor(row[tx]);
if (dim) c = dim565(c);
tft.fillRect(tx * nd::TILE, ty * nd::TILE, nd::TILE, nd::TILE, c);
GFXP->fillRect(tx * nd::TILE, ty * nd::TILE, nd::TILE, nd::TILE, c);
if (row[tx] == 'A') { // airlock outline pops on the floor
tft.drawRect(tx * nd::TILE, ty * nd::TILE, nd::TILE, nd::TILE,
GFXP->drawRect(tx * nd::TILE, ty * nd::TILE, nd::TILE, nd::TILE,
dim ? dim565(nd::C_FLOOR) : nd::C_FLOOR);
}
}
@@ -395,14 +423,14 @@ static void renderNetwork(bool full)
int x0 = nodePx(l[0]), y0 = nodePy(l[0]);
int x1 = nodePx(l[1]), y1 = nodePy(l[1]);
if (full) {
tft.drawLine(x0, y0, x1, y1, nd::C_LINK);
GFXP->drawLine(x0, y0, x1, y1, nd::C_LINK);
} else {
// dotted line: every other pixel of a Bresenham walk
int dx = abs(x1 - x0), sx = x0 < x1 ? 1 : -1;
int dy = -abs(y1 - y0), sy = y0 < y1 ? 1 : -1;
int err = dx + dy, step = 0;
for (;;) {
if ((step++ & 1) == 0) tft.drawPixel(x0, y0, nd::C_GHOST);
if ((step++ & 1) == 0) GFXP->drawPixel(x0, y0, nd::C_GHOST);
if (x0 == x1 && y0 == y1) break;
int e2 = 2 * err;
if (e2 >= dy) { err += dy; x0 += sx; }
@@ -418,28 +446,28 @@ static void renderNetwork(bool full)
int a = PACKET_PATH[seg], b = PACKET_PATH[seg + 1];
int px = nodePx(a) + (nodePx(b) - nodePx(a)) * f / per;
int py = nodePy(a) + (nodePy(b) - nodePy(a)) * f / per;
tft.fillCircle(px, py, full ? 2 : 1, nd::C_PACKET);
if (full) tft.drawPixel(px, py, TFT_WHITE);
GFXP->fillCircle(px, py, full ? 2 : 1, nd::C_PACKET);
if (full) GFXP->drawPixel(px, py, TFT_WHITE);
// nodes: filled icons + labels (Network) vs hollow outlines (Cameras)
for (int i = 0; i < 8; i++) {
int nx = nodePx(i), ny = nodePy(i);
bool flashing = (nodeFlash == i && (int32_t)(millis() - nodeFlashUntil) < 0);
if (full) {
tft.fillCircle(nx, ny, 6, flashing ? nd::C_CURSOR : NODES[i].color);
tft.drawCircle(nx, ny, 6, TFT_BLACK);
tft.setTextDatum(TC_DATUM);
tft.setTextColor(nd::C_TEXTDIM);
tft.drawString(NODES[i].label, nx, ny + 9);
GFXP->fillCircle(nx, ny, 6, flashing ? nd::C_CURSOR : NODES[i].color);
GFXP->drawCircle(nx, ny, 6, TFT_BLACK);
GFXP->setTextDatum(TC_DATUM);
GFXP->setTextColor(nd::C_TEXTDIM);
GFXP->drawString(NODES[i].label, nx, ny + 9);
} else {
tft.drawCircle(nx, ny, 6, flashing ? nd::C_CURSOR : nd::C_GHOST);
GFXP->drawCircle(nx, ny, 6, flashing ? nd::C_CURSOR : nd::C_GHOST);
}
}
if (full) {
tft.setTextDatum(TL_DATUM);
tft.setTextColor(nd::C_TEXTDIM);
tft.drawString("NETWORK", 4, 4);
GFXP->setTextDatum(TL_DATUM);
GFXP->setTextColor(nd::C_TEXTDIM);
GFXP->drawString("NETWORK", 4, 4);
}
}
@@ -449,21 +477,21 @@ static void renderBeacon()
int bx = beaconTX * nd::TILE + nd::TILE / 2;
int by = beaconTY * nd::TILE + nd::TILE / 2;
uint16_t c = (viewMode == VM_NETWORK) ? dim565(nd::C_BEACON) : nd::C_BEACON;
tft.fillTriangle(bx, by - 3, bx + 3, by, bx, by + 3, c);
tft.fillTriangle(bx, by - 3, bx - 3, by, bx, by + 3, c);
GFXP->fillTriangle(bx, by - 3, bx + 3, by, bx, by + 3, c);
GFXP->fillTriangle(bx, by - 3, bx - 3, by, bx, by + 3, c);
}
static void meterBar(int x, int y, int w, int h, int pct, uint16_t c)
{
tft.drawRect(x, y, w, h, nd::C_BORDER);
GFXP->drawRect(x, y, w, h, nd::C_BORDER);
int fw = (w - 2) * pct / 100;
if (fw > 0) tft.fillRect(x + 1, y + 1, fw, h - 2, c);
if (fw > 0) GFXP->fillRect(x + 1, y + 1, fw, h - 2, c);
}
static void renderHud()
{
tft.fillRect(nd::HUD_X, nd::HUD_Y, nd::HUD_W, nd::HUD_H, nd::C_HUDBG);
tft.drawFastHLine(nd::HUD_X, nd::HUD_Y, nd::HUD_W, nd::C_BORDER);
GFXP->fillRect(nd::HUD_X, nd::HUD_Y, nd::HUD_W, nd::HUD_H, nd::C_HUDBG);
GFXP->drawFastHLine(nd::HUD_X, nd::HUD_Y, nd::HUD_W, nd::C_BORDER);
// 4 exploit daemon slots: keycap, name, cooldown bar
static const char *const NAMES[4] = { "FRENZY", "BLIND", "OVRCLK", "PATCH" };
@@ -472,48 +500,48 @@ static void renderHud()
int x = 6 + i * 58, y = nd::HUD_Y + 6;
bool flashing = (slotFlash == (uint32_t)i && (int32_t)(millis() - slotFlashUntil) < 0);
uint16_t tc = flashing ? nd::C_CURSOR : nd::C_TEXT;
tft.setTextColor(tc);
tft.setTextDatum(TL_DATUM);
tft.drawString(String("[") + char('1' + i) + "]", x, y);
tft.setTextColor(nd::C_TEXTDIM);
tft.drawString(NAMES[i], x + 18, y);
GFXP->setTextColor(tc);
GFXP->setTextDatum(TL_DATUM);
GFXP->drawString(String("[") + char('1' + i) + "]", x, y);
GFXP->setTextColor(nd::C_TEXTDIM);
GFXP->drawString(NAMES[i], x + 18, y);
meterBar(x, y + 14, 48, 6, COOL[i], nd::C_GOOD);
}
// RAM + thermal load
tft.setTextColor(nd::C_TEXT);
tft.drawString("RAM 4/6", 246, nd::HUD_Y + 6);
GFXP->setTextColor(nd::C_TEXT);
GFXP->drawString("RAM 4/6", 246, nd::HUD_Y + 6);
meterBar(246, nd::HUD_Y + 16, 56, 7, 42, nd::C_WARN);
tft.setTextColor(nd::C_TEXTDIM);
tft.drawString("TEMP", 246, nd::HUD_Y + 25);
GFXP->setTextColor(nd::C_TEXTDIM);
GFXP->drawString("TEMP", 246, nd::HUD_Y + 25);
// pause hint / state
tft.setTextDatum(TR_DATUM);
tft.setTextColor(paused ? nd::C_FREEZE : nd::C_TEXT);
tft.drawString("SPACE", nd::HUD_X + nd::HUD_W - 6, nd::HUD_Y + 6);
tft.setTextColor(paused ? nd::C_FREEZE : nd::C_TEXTDIM);
tft.drawString(paused ? "RESUME" : "PAUSE", nd::HUD_X + nd::HUD_W - 6, nd::HUD_Y + 16);
tft.setTextDatum(TL_DATUM);
GFXP->setTextDatum(TR_DATUM);
GFXP->setTextColor(paused ? nd::C_FREEZE : nd::C_TEXT);
GFXP->drawString("SPACE", nd::HUD_X + nd::HUD_W - 6, nd::HUD_Y + 6);
GFXP->setTextColor(paused ? nd::C_FREEZE : nd::C_TEXTDIM);
GFXP->drawString(paused ? "RESUME" : "PAUSE", nd::HUD_X + nd::HUD_W - 6, nd::HUD_Y + 16);
GFXP->setTextDatum(TL_DATUM);
// view mode indicator
tft.setTextColor(nd::C_FREEZE);
tft.setTextDatum(TR_DATUM);
tft.drawString(viewMode == VM_CAMERAS ? "VIEW: CAMERAS [P]" : "VIEW: NETWORK [P]",
GFXP->setTextColor(nd::C_FREEZE);
GFXP->setTextDatum(TR_DATUM);
GFXP->drawString(viewMode == VM_CAMERAS ? "VIEW: CAMERAS [P]" : "VIEW: NETWORK [P]",
nd::HUD_X + nd::HUD_W - 6, nd::HUD_Y + 32);
tft.setTextDatum(TL_DATUM);
GFXP->setTextDatum(TL_DATUM);
// squad health pips
tft.setTextColor(nd::C_TEXTDIM);
tft.drawString("SQUAD", 6, nd::HUD_Y + 30);
GFXP->setTextColor(nd::C_TEXTDIM);
GFXP->drawString("SQUAD", 6, nd::HUD_Y + 30);
static const int HP[3] = { 4, 5, 2 }; // of 5 (M3 groundwork)
for (int i = 0; i < 3; i++) {
int x = 48 + i * 58;
for (int s = 0; s < 5; s++) {
uint16_t c = s < HP[i] ? nd::C_GOOD : nd::C_BORDER;
tft.fillRect(x + s * 8, nd::HUD_Y + 34, 6, 8, c);
GFXP->fillRect(x + s * 8, nd::HUD_Y + 34, 6, 8, c);
}
tft.setTextColor(nd::C_TEXTDIM);
tft.drawString(String("M") + String(i + 1), x - 10, nd::HUD_Y + 30);
GFXP->setTextColor(nd::C_TEXTDIM);
GFXP->drawString(String("M") + String(i + 1), x - 10, nd::HUD_Y + 30);
}
}
@@ -523,12 +551,12 @@ static void renderCursor()
if (viewMode == VM_CAMERAS) {
// tile snap highlight + crosshair
int tx = curX / nd::TILE, ty = curY / nd::TILE;
tft.drawRect(tx * nd::TILE, ty * nd::TILE, nd::TILE, nd::TILE, c);
tft.drawCircle(curX, curY, 3, c);
tft.drawPixel(curX, curY, c);
GFXP->drawRect(tx * nd::TILE, ty * nd::TILE, nd::TILE, nd::TILE, c);
GFXP->drawCircle(curX, curY, 3, c);
GFXP->drawPixel(curX, curY, c);
} else {
tft.drawCircle(curX, curY, 4, c);
tft.drawCircle(curX, curY, 1, c);
GFXP->drawCircle(curX, curY, 4, c);
GFXP->drawCircle(curX, curY, 1, c);
}
}
@@ -536,14 +564,14 @@ static void renderCursor()
static void renderFreezeTint()
{
for (int y = 0; y < nd::VIEW_H; y += 3) {
tft.drawFastHLine(0, y, nd::VIEW_W, 0x0000);
GFXP->drawFastHLine(0, y, nd::VIEW_W, 0x0000);
}
tft.setTextDatum(TR_DATUM);
tft.setTextColor(nd::C_FREEZE, 0x0000);
GFXP->setTextDatum(TR_DATUM);
GFXP->setTextColor(nd::C_FREEZE, 0x0000);
if ((millis() / 500) & 1) {
tft.drawString("* TACTICAL FREEZE *", nd::VIEW_W - 4, 4);
GFXP->drawString("* TACTICAL FREEZE *", nd::VIEW_W - 4, 4);
}
tft.setTextDatum(TL_DATUM);
GFXP->setTextDatum(TL_DATUM);
}
static void render()
@@ -555,9 +583,9 @@ static void render()
// HUD separator (flashes when the view mode switches)
uint16_t bc = (int32_t)(millis() - viewFlashUntil) < 0 ? nd::C_CURSOR : nd::C_BORDER;
tft.drawFastHLine(nd::HUD_X, nd::HUD_Y - 1, nd::HUD_W, bc);
GFXP->drawFastHLine(nd::HUD_X, nd::HUD_Y - 1, nd::HUD_W, bc);
if ((int32_t)(millis() - viewFlashUntil) < 0) {
tft.drawRect(0, 0, nd::VIEW_W, nd::VIEW_H, nd::C_CURSOR);
GFXP->drawRect(0, 0, nd::VIEW_W, nd::VIEW_H, nd::C_CURSOR);
}
renderCursor();
@@ -569,20 +597,20 @@ static void render()
// ---------------------------------------------------------------------------
static void drawBoot()
{
tft.fillScreen(TFT_BLACK);
tft.setFreeFont(&FreeSansBold18pt7b);
tft.setTextDatum(MC_DATUM);
tft.setTextColor(nd::C_FREEZE);
tft.drawString("NETDECK", 160, 74);
tft.setTextColor(nd::C_CURSOR);
tft.drawString("BREACH & BOARD", 160, 108);
tft.setTextFont(2);
tft.setTextColor(nd::C_TEXTDIM);
tft.drawString("M0 // EMULATOR SANDBOX", 160, 136);
tft.drawString("p: cameras/network space: freeze", 160, 158);
tft.drawString("ball: cursor enter: select", 160, 174);
tft.setTextDatum(TL_DATUM);
tft.setTextFont(1);
GFXP->fillScreen(TFT_BLACK);
GFXP->setFreeFont(&FreeSansBold18pt7b);
GFXP->setTextDatum(MC_DATUM);
GFXP->setTextColor(nd::C_FREEZE);
GFXP->drawString("NETDECK", 160, 74);
GFXP->setTextColor(nd::C_CURSOR);
GFXP->drawString("BREACH & BOARD", 160, 108);
GFXP->setTextFont(2);
GFXP->setTextColor(nd::C_TEXTDIM);
GFXP->drawString("M1 // SANDBOX", 160, 136);
GFXP->drawString("p: cameras/network space: freeze", 160, 158);
GFXP->drawString("ball: cursor enter: select", 160, 174);
GFXP->setTextDatum(TL_DATUM);
GFXP->setTextFont(1);
}
// ---------------------------------------------------------------------------
@@ -591,7 +619,7 @@ static void drawBoot()
static void hardwareInit()
{
Serial.begin(115200);
Serial.println("NetDeck M0 — emulator sandbox");
Serial.println("NetDeck M1 — hardware sandbox");
pinMode(BOARD_POWERON, OUTPUT); // power rail first (battery boot)
digitalWrite(BOARD_POWERON, HIGH);
@@ -631,6 +659,14 @@ static void hardwareInit()
void setup()
{
hardwareInit();
#ifndef EMULATOR
// second buffer for flicker-free full-frame pushes
fb.setColorDepth(16);
if (!fb.createSprite(tft.width(), tft.height()))
Serial.println("NetDeck: framebuffer alloc failed (blank screen)");
#endif
drawBoot();
stateT0 = millis();
lastFrameMs = stateT0;
@@ -644,7 +680,11 @@ void loop()
if (now - stateT0 >= nd::BOOT_MS) {
gameState = ST_RUN;
stateT0 = now;
resetTrackball(); // swallow stale edges from floating pins
// swallow stale keyboard bytes + trackball edges from floating pins
for (int i = 0; i < 8; i++) {
if (Wire.requestFrom((uint8_t)0x55, (uint8_t)16) == 0) break;
}
resetTrackball();
Serial.println("[boot] entering sandbox (view: cameras)");
}
delay(1);
@@ -674,4 +714,5 @@ void loop()
}
render();
present();
}
+29
View File
@@ -0,0 +1,29 @@
; NetDeck — Breach & Board firmware (Milestone 1 hardware sandbox)
;
; The root platformio.ini's src_dir is global, so this sketch ships its own
; project config: build with pio run -d examples/NetDeck
; Board + shared library discovery point back at the repo root.
[platformio]
default_envs = T-Deck
boards_dir = ../../boards
; sketch lives at the project root (the emulator Makefile includes it from
; there), so scan the project root instead of a src/ folder
src_dir = .
[env:T-Deck]
platform = espressif32@6.3.0
board = T-Deck
framework = arduino
lib_extra_dirs = ../../lib
upload_speed = 921600
monitor_speed = 115200
build_flags =
-DBOARD_HAS_PSRAM=1
-DCORE_DEBUG_LEVEL=1
-DARDUINO_USB_CDC_ON_BOOT=1
-DDISABLE_ALL_LIBRARY_WARNINGS
; Full-frame push needs headroom: 80 MHz halves the frame transfer vs the
; stock 40 MHz (same setting as the other full-frame sketches). If the
; panel shows artifacts, drop to 40000000.
-DSPI_FREQUENCY=80000000
Binary file not shown.
+6
View File
@@ -10,6 +10,12 @@
---
## 0. Design decisions
- T-Deck & Emulator are the primary targets. Plays nicely on T-Deck, but it isn't hard-dependent on it. There are multiple ways for the player to achieve their goal.
---
## 1. High Concept & Core Fantasy
You are not a soldier on the ground—you are the **Tactical Netrunner** strapped into a ruggedized portable cyberdeck in the breach airlock. Your 3-person marine fireteam is breaching derelict megacorp vessels overrun by rogue security droids and hostile ship-AI subsystems.
+7
View File
@@ -0,0 +1,7 @@
# Map scrolling
- move directly via trackball? by dragging touchscreen?
- move by alt+trackball?
- touch to click vs move / trackball to move cursor vs map
# Companion app
- play on the T-Deck, have it connected over WiFi/BT to a computer/phone that shows a different view (bigger map, stats etc.)
+29 -8
View File
@@ -7,12 +7,12 @@ milestone lands.
| Milestone | Scope | Status |
| --- | --- | --- |
| **M0 — Emulator** | SDL2 emulator support + M1 surface tested locally | **done** |
| M1 — Hardware Sandbox | Boot on ST7789 DMA, shared tactical view (Cameras/Network) + HUD, cursor, `Space` freeze, `P` view switch | prepared (emulator-verified, needs device bring-up) |
| **M1 — Hardware Sandbox** | Full-frame sprite rendering to ST7789, shared tactical view + HUD, cursor, `Space` freeze, `P` view switch | **compiled + emulator-verified; on-device check pending** |
| M2 — Network Graph & Traces | Node graph in Network view (door nodes on bulkhead tiles), link routing, ICE crack, red trace + `X` sever | planned |
| M3 — Squad vs. Droids | Ship floorplan in Cameras view, 3 marines → beacon, 4 droids, gunfire | planned |
| M4 — Cyber-Physical Bridge | Hive link + `1` FRENZY.EXE turns droids on each other (shared coordinate space) | planned |
## M0 (this milestone)
## M0 (done)
- `src/netdeck/nd_layout.h` — shared constants: 320x192 tactical view + HUD bar
(one coordinate space), palette, fixed-timestep timings.
@@ -28,10 +28,31 @@ milestone lands.
- Emulator: `make APP=NetDeck run` / `smoke` from `emulator/`; host gained `Tab`
key mapping (`emulator/src/main.cpp`).
## M1 remaining (hardware bring-up, same sketch)
## M1 (this milestone)
- ST7789 via DMA double-buffered transfers (two 153.6 KB SRAM DMA buffers).
- Real keyboard-controller init timing + stale-byte grace on device.
- Trackball sensitivity on real hardware (`TB_IMPULSE`/`TB_FRICTION` device branch).
- Frame cost check: full 320x240 redraw must fit ~30 fps at 80 MHz SPI; move to
incremental/two-buffer rendering if not.
- **Flicker-free full-frame rendering** (`examples/NetDeck/NetDeck.ino`):
all drawing goes into a RAM second buffer — `TFT_eSprite fb` (PSRAM,
320x240x16) on device, the SDL shim framebuffer in the emulator — and is
pushed as **one continuous SPI stream** (`present()` → `startWrite() /
fb.pushSprite(0,0) / endWrite()`), the proven MiataDrive anti-tearing
pattern (commit d542d6f).
- **Firmware build**: self-contained `examples/NetDeck/platformio.ini`
(`pio run -d examples/NetDeck`; board + libs resolved against the repo
root `boards/` and `lib/`). ESP32-S3 / arduino-esp32 2.0.9:
**RAM 6.7%, Flash 5.5%**, binary at `firmware/NetDeck_M1_261114.bin`.
- **Keyboard bring-up**: stale-byte flush from the 0x55 controller at boot
end (before the first frame), on top of the 1400 ms boot grace.
- **Trackball device branch**: `TB_IMPULSE`/`TB_FRICTION` constants split
for device vs emulator edge rates.
- Emulator frames are pixel-identical to the M0 baseline (regression
verified: cameras / network / freeze / beacon click).
### Flashing + on-device checklist (needs the physical T-Deck)
1. `pio run -d examples/NetDeck -t upload` (or flash
`firmware/NetDeck_M1_261114.bin`).
2. Boot screen `M1 // SANDBOX` shows for 1.4 s, then the Cameras view.
3. `P` flips to Network view (dimmed ship + labeled graph), `Tab` too.
4. `Space` freezes (CRT scanlines, sim/packets halt); cursor stays live.
5. Trackball: smooth momentum cursor, tile snap in Cameras, node targeting
in Network; Enter = beacon drop / node select; screen tap works too.