FlashDock SDK

FlashDock SDK is the firmware foundation of FlashDock Platform, a premium terminal framework made especially for microcontrollers.

Repository target: github.com/YukiCodepth/flashdock-platform

Public product names:

• Product: FlashDock
• Full product: FlashDock Platform
• Firmware SDK: FlashDock SDK
• Desktop app: FlashDock Studio
• OS layer: FlashDock OS
• Company/startup identity: FlashDock Labs

It is not a Linux terminal emulator. It is a portable command console that can run over UART, USB CDC, BLE, RTT, Telnet, WebSocket, or any byte stream you wire to its transport trait.

The product direction is bigger than a parser: FlashDock should become a firmware SDK plus desktop companion workflow for adding a professional terminal to ESP32, STM32, RP2040/RP2350, Arduino-style, FreeRTOS, bare-metal, and future custom OS projects.

What It Does

• prompt like fd:<user>[$#]
• banner on start
• echo and backspace handling
• ANSI arrow-key editing for left/right/home/end/delete
• command history navigation with up/down arrows
• Ctrl-C to cancel the current line
• exit, quit, or Ctrl-D to close the session
• ANSI clear-screen support
• command roles and permissions
• history and completion primitives
• no-heap command parsing
• static command registry with groups and metadata
• built-in help, clear, about, and commands
• structured text/JSON-lines output for tools
• script replay for firmware smoke tests
• portable hardware/debug command packs with diagnostics, Wi-Fi control, driver visibility, watchdog health, and fault reporting
• no_std library for firmware use
• host demo and tests for local development
• universal distro primitives for secure first boot, Linux-like shell commands, project manifests, packages, component inventory, and cross-MCU tiers

Repository Layout

crates/flashdock                  The reusable microcontroller terminal core
crates/flashdock-packs            Hardware/debug command packs and traits
crates/flashdock-adapters         ESP32/STM32/RP board and transport manifests
crates/flashdock-os               Premium MCU OS kernel/service primitives
crates/flashdock-studio-protocol  Descriptor protocol for FlashDock Studio
firmware/esp32-idf                Verified classic ESP32 ESP-IDF reference port
firmware/stm32f401-blackpill      UART-first STM32F401CCU6 firmware target
firmware/rp2350-pico2             USB CDC/UART Pico 2 adapter contract
samples/cross-board-demo          Shared ESP32/STM32F401/Pico 2 smoke harness
samples/esp32-s3-demo             Host-checkable ESP32-S3 reference harness
samples/host-demo                 Host-side terminal and command-pack demo
samples/platform-demo             Platform descriptor and OS primitive demo
tools/flashdock-connect           Desktop serial connector and auto-detect TUI
docs/                             Product, reference, and porting notes

Product Docs

• Product vision
• Roadmap
• Competitive gap
• Release checklist
• Universal distro plan
• Repository strategy
• ESP32-S3 bring-up
• Classic ESP32 bring-up
• STM32 bring-up
• RP2350 bring-up
• FlashDock Connect desktop terminal
• Studio security model

Hardware Bring-Up

FlashDock no longer depends on owning an ESP32-S3 to continue. The current hardware roadmap is:

• ESP32 DevKit: primary wireless reference port because it is already flashable, smoke-tested, and now owns the first real Wi-Fi command path.
• Raspberry Pi Pico 2 / RP2350: verified USB/no-wireless portability target and future OS experiment board.
• STM32F401CCU6 Black Pill: build-ready USART1 terminal target, with physical smoke testing parked until ST-Link plus USB-UART hardware is ready.
• ESP32-S3 DevKit: still supported as an optional USB Serial/JTAG target.

Phase 7 added three ESP firmware paths:

• firmware/esp32-s3-idf: primary ESP-IDF-backed USB Serial/JTAG terminal.
• firmware/esp32-s3-hal: experimental pure Rust esp-hal no-std path.
• firmware/esp32-idf: verified classic ESP32 UART terminal path.

Check tools and the connected board:

scripts/esp32/setup-tools.sh
scripts/esp32/board-info.sh

The ESP scripts default to classic ESP32 on /dev/cu.usbserial-0001; override with FLASHDOCK_BOARD=esp32s3 FLASHDOCK_PORT=/dev/cu.debug-console when S3 hardware is connected.

For the verified classic ESP32 path:

FLASHDOCK_BOARD=esp32 FLASHDOCK_PORT=/dev/cu.usbserial-0001 scripts/esp32/check-idf.sh
FLASHDOCK_BOARD=esp32 FLASHDOCK_PORT=/dev/cu.usbserial-0001 scripts/esp32/build-idf.sh
FLASHDOCK_BOARD=esp32 FLASHDOCK_PORT=/dev/cu.usbserial-0001 FLASHDOCK_MONITOR=0 scripts/esp32/flash-idf.sh
FLASHDOCK_PORT=/dev/cu.usbserial-0001 scripts/esp32/smoke-serial.sh

For ESP32 release-candidate validation, prefer the one-command product flow:

FLASHDOCK_BOARD=esp32 \
FLASHDOCK_PORT=/dev/cu.usbserial-0001 \
FLASHDOCK_WIFI_SSID="your-2.4ghz-wifi" \
FLASHDOCK_WIFI_PASS="your-password" \
FLASHDOCK_WIFI_PING_HOST=8.8.8.8 \
scripts/esp32/release-check.sh

This performs board-info, check, build, flash, baseline terminal smoke, terminal UX smoke, OS-surface smoke, Wi-Fi/NVS persistence, and factory-reset cleanup. Use FLASHDOCK_REQUIRE_WIFI=0 only for a local dry run; the ESP32 release phase is not considered merge-ready until Wi-Fi persistence passes on hardware. The release script unsets FLASHDOCK_WIFI_* during firmware build/flash so smoke-test credentials are not embedded in the firmware image.

flash-idf.sh builds the ESP-IDF firmware first, then flashes the generated ELF with standalone espflash. This avoids cargo espflash rebuilding with the wrong Rust target settings on macOS.

Provision Wi-Fi either through the shell or, for private lab images only, at build time with the explicit build-time variable names:

FLASHDOCK_BUILD_WIFI_SSID="your-wifi" FLASHDOCK_BUILD_WIFI_PASS="your-password" \
  FLASHDOCK_BOARD=esp32 scripts/esp32/flash-idf.sh

wifi all
wifi select
wifi join <ssid|number> <password>
wifi status
net status
net ping 8.8.8.8
wifi forget

Optional hardware Wi-Fi smoke tests are environment-driven so secrets never enter the repo:

FLASHDOCK_PORT=/dev/cu.usbserial-0001 \
FLASHDOCK_SMOKE_MODE=wifi \
FLASHDOCK_WIFI_SSID="your-wifi" \
FLASHDOCK_WIFI_PASS="your-password" \
FLASHDOCK_WIFI_PING_HOST=8.8.8.8 \
scripts/esp32/smoke-serial.sh

Use FLASHDOCK_SMOKE_MODE=persistence to verify NVS reconnect after a shell reboot, and add FLASHDOCK_WIFI_FORGET_AFTER=1 when you want the smoke test to clean up saved credentials at the end.

Secrets are redacted from command output, debug output, and flash reads.

ESP32 release-candidate firmware now exposes real GPIO, Wi-Fi scan/connect/ping, I2C0 scan on GPIO21/GPIO22 at 100 kHz, an NVS-backed /config filesystem, and FlashDock OS control-plane surfaces through tasks, logs, drivers, watchdog, faults, and diag.

Desktop Connector

FlashDock Connect is the first laptop-side terminal helper. It finds likely FlashDock serial ports, verifies firmware through a safe handshake, and opens an interactive session without requiring users to remember the lower-level monitor command.

scripts/desktop/install-cli.sh
flashdock-connect list
scripts/desktop/connect-esp32.sh
scripts/desktop/watch-macos.sh

Use exit, quit, or Ctrl-] to leave an interactive FlashDock Connect session. See FlashDock Connect for the optional macOS LaunchAgent setup.

Installable Firmware Bundles

FlashDock can now describe a board release as a .flashdock bundle: firmware plus manifest, checksums, package metadata, and optional TinyML model assets. ESP32 is the first installable target.

scripts/release/build-esp32-bundle.sh
flashdock-connect install dist/flashdock-esp32-v0.1.0.flashdock --port /dev/cu.usbserial-0001
flashdock-connect install dist/flashdock-esp32-v0.1.0.flashdock --port /dev/cu.usbserial-0001 --ml-runtime flashdock-native
flashdock-connect install dist/flashdock-esp32-v0.1.0 --dry-run --plain

The same bundle also carries raw firmware for developers. User login passwords and Wi-Fi secrets are never embedded in the artifact.

Until FlashDock Labs owns and publishes an official product domain, firmware metadata points to the GitHub repository instead of a placeholder domain.

For normal Arduino-style blink without opening an IDE:

flashdock-connect wifi --port /dev/cu.usbserial-0001
flashdock-connect quickstart blink --port /dev/cu.usbserial-0001 --run
flashdock-connect quickstart blink --port /dev/cu.usbserial-0001 --run --with-wifi saved
flashdock-connect recover-os --port /dev/cu.usbserial-0001

--with-wifi saved makes the user app reconnect after boot using the saved FlashDock Wi-Fi profile. The ESP32 still disconnects briefly during the reboot between flashdock_os and user_app.

Build the non-S3 firmware targets:

scripts/stm32/setup-tools.sh
scripts/stm32/build-blackpill.sh
scripts/rp2350/build-pico2.sh

For Pico 2 USB-only verification:

scripts/rp2350/setup-tools.sh
scripts/rp2350/uf2-pico2.sh
scripts/rp2350/flash-pico2.sh
scripts/rp2350/smoke-serial.sh

flash-pico2.sh expects /Volumes/RPI-RP2 by default. On newer Pico 2 bootloaders macOS may mount /Volumes/RP2350; use FLASHDOCK_PICO2_VOLUME=/Volumes/RP2350 in that case.

Branch Workflow

main is the stable default branch. Each major build phase gets a dedicated phase branch:

• phase/01-core-terminal
• phase/02-command-packs
• phase/03-esp32-s3-demo
• phase/04-flashdock-os
• phase/05-cross-board-support
• phase/06-studio-and-security
• phase/07-esp32-s3-hardware-bringup
• phase/08-non-s3-hardware-roadmap
• phase-09-integrated-premium-platform
• phase-10-esp32-product-hardening
• phase-11-esp32-release-candidate
• phase-12-flashdock-connect
• phase-13-instant-desktop-experience
• phase-14-universal-distro-foundation
• phase-15-esp32-os-v1
• phase-16-esp32-daily-use-polish
• phase-17-esp32-full-hardware-control
• phase-18-terminal-only-project-programming
• phase-19-package-extension-system
• phase-20-esp32-ota-recovery-production
• phase-21-pico2-full-usb-board
• phase-22-stm32f401-lightweight-runtime
• phase-23-more-mcu-families
• phase-24-flashdock-studio
• phase-25-startup-product-release

Merge a phase into main only after tests pass, demos work, docs are updated, and the phase has a clear working result.

Run Locally

cargo test --workspace
cargo run -p flashdock-host-demo
cargo run -p flashdock-platform-demo
cargo run -p flashdock-esp32-s3-demo
cargo run -p flashdock-cross-board-demo

Firmware Integration Shape

Board code implements flashdock::Transport for its serial device:

use flashdock::{Transport, Result};

struct BoardUart;

impl Transport for BoardUart {
    fn read(&mut self, byte: &mut u8) -> Result<bool> {
        // Return Ok(false) if no byte is available yet.
        todo!()
    }

    fn write(&mut self, bytes: &[u8]) -> Result<usize> {
        todo!()
    }

    fn flush(&mut self) -> Result<()> {
        Ok(())
    }
}

Then create a terminal and call poll() from a task or main loop.

Product Editions

• Core: open firmware terminal engine, no_std, no heap required.
• Pro: hardware command packs, history, tab completion, structured output, scripts, desktop companion.
• Enterprise: auth, permissions, audit hooks, production-safe remote access.

Current Platform Status

Implemented now:

• Premium terminal core APIs
• Portable hardware/debug command-pack traits
• ESP32, optional ESP32-S3, STM32F401, and Pico 2 adapter manifests
• Host-checkable ESP32-S3 firmware scaffold
• Cross-board ESP32, STM32F401 Black Pill, and Pico 2 smoke scaffold
• Premium OS scheduler, queue, event, VFS, driver registry, watchdog, retained fault ring, and message-bus primitives
• Studio protocol descriptors for future desktop tooling
• Studio/security protocol primitives for remote sessions and audit events
• ESP32-S3 ESP-IDF and experimental esp-hal hardware firmware paths
• Verified classic ESP32 ESP-IDF firmware path with serial smoke coverage
• ESP32 FlashDock OS v1 foundation with secure setup/login, Linux-like shell commands, project scripts, package metadata, hardware inventory, and host-assisted build/package actions
• FlashDock Connect setup/login prompt, watch mode, trusted firmware detection, and ESP32 NVS credential recovery helper
• Verified Pico 2/RP2350 USB CDC firmware path with BOOTSEL/UF2 flashing and serial smoke coverage
• Flashable STM32F401 Black Pill USART1 firmware path

Not implemented yet:

• Physically verified STM32F401 flash and UART smoke test on connected hardware
• Real I2C, filesystem, and sensor drivers beyond the ESP32/Pico terminal smoke paths
• A physically verified ESP32-S3 flash on S3 hardware
• FlashDock Studio GUI
• Cross-board production security/auth backends beyond the ESP32 NVS reference