{ "examples": [ { "slug": "blink", "title": "Blink", "description": "The classic Blink — the smallest complete Cuttlefish project. Toggle the onboard LED on an ESP32-S3 and test it in hardware with @typecad/expect.", "tags": [ "esp32s3", "gpio", "digital-out", "expect" ], "board": "ESP32-S3 DevKitC", "tree": { "name": "blink", "path": "", "type": "folder", "children": [ { "name": "src", "path": "src", "type": "folder", "children": [ { "name": "main.ts", "path": "src/main.ts", "type": "file", "lang": "typescript", "html": "

// ---------------------------------------------------------------------------\n// main.ts — Blink\n//\n// The \"Hello World\" of embedded development: toggle the onboard LED every\n// second. This is the smallest complete Cuttlefish project — it demonstrates\n// the full author → build → run loop with the absolute minimum of code.\n//\n// Everything here is plain TypeScript. Cuttlefish transpiles it to C++ that\n// runs on the board; nothing below is a runtime shim, a mock, or special\n// syntax. What you read is what ships.\n// ---------------------------------------------------------------------------\n\n// `@typecad/hal` is the hardware surface: one class per peripheral, lowered\n// onto the target framework's own drivers. `@typecad/board` is a per-board\n// package that exposes the board's pins as typed values — here `LED` is the\n// built-in LED pin.\nimport { GPIO, Time } from '@typecad/hal';\nimport { LED } from '@typecad/board';\n\n// Construction IS the configuration: the flags you pass are the flags the\n// generated gpio configure call receives. OUTPUT_INIT_HIGH sets the output's\n// initial level atomically, so the LED starts ON without a separate write\n// (no configure-then-write glitch window).\nconst led = new GPIO(LED, GPIO.OUTPUT | GPIO.OUTPUT_INIT_HIGH);\n\n// Cuttlefish's top-level `while (true)` is the embedded main loop. There is\n// no setup() to write; top-level statements run once before it, and the loop\n// becomes the driver's iteration.\nwhile (true) {\n  // Toggle flips the pin's level in one atomic driver call — cheaper and\n  // clearer than read-then-write.\n  led.toggle();\n\n  // Time.sleep blocks for N milliseconds (k_msleep on Zephyr, the platform's\n  // own sleep elsewhere), so timing here is as accurate as the board's clock.\n  Time.sleep(1000);\n}\n

" } ] }, { "name": "tests", "path": "tests", "type": "folder", "children": [ { "name": "main.test.ts", "path": "tests/main.test.ts", "type": "file", "lang": "typescript", "html": "

// ---------------------------------------------------------------------------\n// main.test.ts — hardware test for the Blink example\n//\n// Cuttlefish ships a hardware test framework, @typecad/expect, that runs\n// vitest-style assertions *on the board itself* over a serial connection.\n// You write the test in TypeScript; it is transpiled alongside main.ts,\n// flashed with it, and the results stream back as the board runs.\n//\n// This lets you assert physical behavior — \"the LED pin actually toggles\" —\n// not just software state. Run it against a connected board with:\n//\n//   npx cuttlefish-test --port COM4\n// ---------------------------------------------------------------------------\n\nimport { describe, done } from '@typecad/expect';\nimport { GPIO } from '@typecad/hal';\nimport { LED } from '@typecad/board';\n\n// One GPIO configured once; the test drives and reads the same pin.\nconst led = new GPIO(LED, GPIO.OUTPUT);\n\n// `describe` chains `.it(...).expect(...)`, mirroring vitest/jest. Each\n// `.expect()` reads live hardware state at the moment it runs.\ndescribe(\"LED toggles\")\n  .it(\"can be set on\")\n    // Write a concrete level and read the pin back — the full driver\n    // write/read round-trip on real hardware.\n    .expect((led.set(true), led.get() ? 1 : 0)).toBe(1)\n  .it(\"toggles to the opposite level\")\n    .expect((led.toggle(), led.get() ? 1 : 0)).toBe(0);\n\n// `done()` finalizes the chain and flushes the results over serial. Without\n// it, no output is emitted — tests don't implicitly report.\ndone();\n

" } ] }, { "name": "cuttlefish.config.ts", "path": "cuttlefish.config.ts", "type": "file", "lang": "typescript", "html": "

// ---------------------------------------------------------------------------\n// cuttlefish.config.ts — Project configuration\n//\n// Targets the ESP32-S3 DevKitC. This is the canonical modern target: a\n// Zephyr RTOS build over devicetree, compiled with `west`.\n// ---------------------------------------------------------------------------\n\nimport type { CuttlefishConfig } from '@typecad/cuttlefish/api';\n\nconst config: CuttlefishConfig = {\n  // Entry point — the main TypeScript file to transpile. Top-level\n  // statements become the program's setup, and `while (true)` is the main\n  // loop the Zephyr entry drives.\n  entry: './src/main.ts',\n\n  // Target architecture — ESP32-S3 (Xtensa LX7 dual-core).\n  target: 'esp32s3',\n\n  // MCU package — silicon-level pin/port definitions for the ESP32-S3.\n\n  // Board target — generates the board module from the data pack\n  // (the built-in LED, USB serial, the fixed bus controllers).\n  board: 'esp32s3_devkitc/esp32s3/procpu',\n\n  // Framework package — controls code generation. Zephyr lowers each HAL\n  // call onto the Zephyr driver API against the board's devicetree.\n  framework: '@typecad/framework-zephyr',\n\n  // Framework data — the Zephyr board target passed to `west build`.\n  frameworkData: {\n    buildTarget: 'esp32s3_devkitc/esp32s3/procpu',\n  },\n\n  // Output — emit the Zephyr application into ./out.\n  output: {\n    framework: 'zephyr',\n    outDir: './out',\n  },\n\n  // Toolchain — drive compilation/upload through west (esptool under it).\n  toolchain: {\n    type: 'west',\n  },\n\n  // Hardware test runner (@typecad/expect / `npm run test:hw`). The test\n  // files below are transpiled alongside main.ts, flashed with them, and\n  // the results stream back over serial as the board runs.\n  test: {\n    port: 'COM4',\n    baudRate: 115200,\n    timeout: 30000,\n    include: ['src/**/*.test.ts'],\n  },\n};\n\nexport default config;\n

" }, { "name": "package.json", "path": "package.json", "type": "file", "lang": "json", "html": "

{\n  \"name\": \"blink\",\n  \"version\": \"1.0.0\",\n  \"private\": true,\n  \"description\": \"Blink \\u2014 the smallest complete Cuttlefish project\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"build\": \"cuttlefish build\",\n    \"compile\": \"cuttlefish build --compile\",\n    \"upload\": \"cuttlefish build --compile --upload\",\n    \"test:hw\": \"cuttlefish-test\",\n    \"preview\": \"cuttlefish preview --config ./cuttlefish.config.ts\"\n  },\n  \"dependencies\": {\n    \"@typecad/framework-zephyr\": \"^1.0.0-alpha.14\",\n    \"@typecad/expect\": \"^1.0.0-alpha.14\"\n  }\n}\n

" }, { "name": "tsconfig.json", "path": "tsconfig.json", "type": "file", "lang": "json", "html": "

{\n  \"compilerOptions\": {\n    \"target\": \"ESNext\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"noEmit\": true,\n    \"skipLibCheck\": true,\n    \"esModuleInterop\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"types\": []\n  },\n  \"include\": [\n    \"src/**/*.ts\",\n    \"cuttlefish.config.ts\"\n, \"tests/main.test.ts\"  ]\n}\n

" } ] } }, { "slug": "ui-counter", "title": "Tap Counter", "description": "The smallest complete Cuttlefish UI project — a screen with a label and a button on an ESP32-S3 + ST7796S TFT. A reactive signal holds the count; each tap updates the label on the next display tick.", "tags": [ "esp32s3", "ui", "display", "st7796", "touch", "signal" ], "board": "ESP32-S3 DevKitC", "tree": { "name": "ui-counter", "path": "", "type": "folder", "children": [ { "name": "src", "path": "src", "type": "folder", "children": [ { "name": "counter.ui.css", "path": "src/counter.ui.css", "type": "file", "lang": "css", "html": "

/* ---------------------------------------------------------------------------\n   counter.ui.css — styles for the tap counter screen\n   ------------------------------------------------------------------------- */\n\n/* The screen is the required root of every UI template. Flexbox (resolved at\n   build time through Yoga) stacks the label above the button and centers both\n   on the 320x240 viewport. */\nscreen {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  justify-content: center;\n  gap: 16px;\n  background: #0f172a;\n}\n\n#label {\n  font-size: 24px;\n  color: #f8fafc;\n}\n\n#tapBtn {\n  font-size: 18px;\n  color: #ffffff;\n  background: #2563eb;\n  padding: 12px 24px;\n  border-radius: 8;\n}\n

" }, { "name": "counter.ui.html", "path": "src/counter.ui.html", "type": "file", "lang": "html", "html": "

<link rel=\"stylesheet\" href=\"counter.ui.css\">\n\n<!-- The screen is the required root of every UI template. The elements below\n     are reachable from main.ts as screen.label and screen.tapBtn. -->\n<screen id=\"counter\">\n  <text id=\"label\">taps: 0</text>\n  <button id=\"tapBtn\">tap me</button>\n</screen>\n

" }, { "name": "main.ts", "path": "src/main.ts", "type": "file", "lang": "typescript", "html": "

// ---------------------------------------------------------------------------\n// main.ts — Tap counter (split layout)\n//\n// The smallest complete Cuttlefish UI project using the split layout: the\n// template lives in counter.ui.html and the logic lives here. main.ts imports\n// the baked screen tree, mounts it to the display, and wires the button.\n//\n// This is Pattern B — logic in TypeScript, markup in a .ui.html file. Contrast\n// with the single-file .ui layout, which keeps script, style, and template in\n// one file. Everything below is plain TypeScript that Cuttlefish lowers to C++;\n// @typecad/ui is compile-time only and never ships to the device.\n// ---------------------------------------------------------------------------\n\nimport { ui } from '@typecad/ui';\n// `screen` is the baked tree from counter.ui.html. Every element with an id in\n// that file is reachable here as screen.<id>, typed against the template.\nimport { screen } from './counter.ui.html';\n\n// mount() initializes the configured display (see cuttlefish.config.ts) and\n// draws the first frame.\nui.mount(screen);\n\n// A signal is @typecad/ui's reactive primitive — read it with count(), update\n// it with count.set(v). It lowers to a device variable plus a dirty flag.\nconst count = ui.signal(0);\n\n// onClick fires on touch release within ~600ms (touch wiring is in the config).\n// Each tap advances the signal; no manual redraw call is needed.\nscreen.tapBtn.onClick(() => {\n  count.set(count() + 1);\n});\n\n// ui.bind re-evaluates the label's text each tick and redraws it only when the\n// value changes. This is the split-layout equivalent of the {count} binding a\n// single-file .ui template gets for free.\nui.bind(screen.label, 'text', () => `taps: ${count()}`);\n

" } ] }, { "name": "types", "path": "types", "type": "folder", "children": [ { "name": "counter.ui.d.html.ts", "path": "types/counter.ui.d.html.ts", "type": "file", "lang": "typescript", "html": "

// Auto-generated by cuttlefish (UI lowering). Do not edit.\nimport type { TextElement, ButtonElement, ViewElement, CheckElement, SelectElement, RadioElement, ProgressElement, RangeElement, InputElement, CanvasElement } from \"@typecad/ui\";\ninterface CounterScreenGroup {\n  label: TextElement;\n  tapBtn: ButtonElement;\n}\ninterface ScreenGroups {\n  counter: CounterScreenGroup;\n}\nexport interface ScreenTree {\n  counter: ViewElement;\n  label: TextElement;\n  tapBtn: ButtonElement;\n  groups: ScreenGroups;\n}\nexport const screen: ScreenTree;

" } ] }, { "name": "cuttlefish.config.ts", "path": "cuttlefish.config.ts", "type": "file", "lang": "typescript", "html": "

// ---------------------------------------------------------------------------\n// cuttlefish.config.ts — Project configuration\n//\n// Targets an ESP32-S3 DevKitC driving an ST7796S SPI TFT (320x480 RGB565)\n// with an FT6336U capacitive touch overlay, on the Zephyr framework. The\n// `display` block is what makes this a UI project — without it,\n// ui.mount(screen) has nothing to draw to.\n// ---------------------------------------------------------------------------\n\nimport type { CuttlefishConfig } from '@typecad/cuttlefish/api';\n\nconst config: CuttlefishConfig = {\n  // Entry point — the TypeScript logic. It imports the template\n  // (counter.ui.html) and wires the UI; the transpiler resolves the .ui.html\n  // import into a baked screen tree at build time.\n  entry: './src/main.ts',\n\n  // Target architecture — ESP32-S3 (Xtensa LX7 dual-core).\n  target: 'esp32s3',\n\n  // MCU package — silicon-level pin/port definitions for the ESP32-S3.\n\n  // Board target — generates the board module from the data pack.\n  board: 'esp32s3_devkitc/esp32s3/procpu',\n\n  // Framework package — Zephyr lowers each HAL call onto the Zephyr driver\n  // API against the board's devicetree.\n  framework: '@typecad/framework-zephyr',\n\n  // Build target — the Zephyr board target passed to `west build`.\n  frameworkData: {\n    buildTarget: 'esp32s3_devkitc/esp32s3/procpu',\n  },\n\n  // Output — emit the Zephyr application into ./out.\n  output: {\n    framework: 'zephyr',\n    outDir: './out',\n  },\n\n  // Toolchain — drive compilation/upload through west (esptool under it).\n  toolchain: {\n    type: 'west',\n  },\n\n  // PSRAM — the N16R8 module's 8 MB octal PSRAM hosts the large scroll and\n  // canvas allocations the UI runtime makes on a 320x480 panel.\n  psram: 'opi',\n\n  // Display profile — the ST7796S over SPI. The profile fills in the driver,\n  // dimensions (320x480), color format (RGB565), and rotation; we only state\n  // the wiring. antialias smooths text edges on the TFT.\n  display: {\n    profile: 'st7796-zephyr',\n    cs: 5,\n    dc: 17,\n    rst: 16,\n    spiFrequency: 80000000,\n    colorOrder: 'bgr',\n    // This panel's power-on default is already non-inverted; leave inversion\n    // off to match its native state.\n    invertDisplay: false,\n    antialias: true,\n\n    // Touch — FT6336U capacitive controller over I2C. The button in\n    // counter.ui needs this to register taps. calibration maps raw touch\n    // readings to display pixels.\n    touch: {\n      library: 'FT6336U',\n      i2cAddress: 0x38,\n      i2cFrequency: 400000,\n      irq: 15,\n      resetPin: 4,\n      sda: 8,\n      scl: 9,\n      calibration: { xMin: 0, xMax: 320, yMin: 0, yMax: 480 },\n    },\n  },\n};\n\nexport default config;\n

" }, { "name": "package.json", "path": "package.json", "type": "file", "lang": "json", "html": "

{\n  \"name\": \"ui-counter\",\n  \"version\": \"1.0.0\",\n  \"private\": true,\n  \"description\": \"ESP32-S3 + ST7796S tap counter \\u2014 the smallest complete Cuttlefish UI project\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"build\": \"cuttlefish build\",\n    \"compile\": \"cuttlefish build --compile\",\n    \"upload\": \"cuttlefish build --compile --upload\",\n    \"preview\": \"cuttlefish preview --config ./cuttlefish.config.ts\"\n  },\n  \"dependencies\": {\n    \"@typecad/framework-zephyr\": \"^1.0.0-alpha.14\",\n    \"@typecad/ui\": \"^1.0.0-alpha.14\"\n  }\n}\n

" }, { "name": "tsconfig.json", "path": "tsconfig.json", "type": "file", "lang": "json", "html": "

{\n  \"compilerOptions\": {\n    \"target\": \"ESNext\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"noEmit\": true,\n    \"skipLibCheck\": true,\n    \"esModuleInterop\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"types\": []\n  },\n  \"include\": [\n    \"src/**/*.ts\",\n    \"src/**/*.ui.html\",\n    \"cuttlefish.config.ts\"\n  ]\n}\n

" } ] } } ] }