Getting Started with Cuttlefish

Write firmware in TypeScript. Cuttlefish turns it into the C++ that runs on Zephyr boards — ESP32, nRF52, RP2040, STM32, and more.

About Cuttlefish

Cuttlefish is a tool that turns TypeScript into firmware for small, low-cost computers like the ESP32-S3, nRF52840, and RP2040.

• You write firmware in TypeScript, and Cuttlefish turns it into the C++ the board runs
• It checks your code for common hardware mistakes as you type, not after you upload
• The result runs as fast as hand-written code, with nothing extra slowing it down
• You can write tests in TypeScript and run them on the real board
• It works with typeCAD, which lets you design the circuit board itself in code

Quick Start

1. Install Node.js

   • Download and install Node.js (LTS version recommended)
   • Verify: node --version

2. Install the Zephyr Toolchain Embedded targets build on Zephyr, which needs a Zephyr toolchain. The installer bundled with @typecad/framework-zephyr sets one up in a single command — no preinstalled Python, conda, or SDK, and it works the same on Linux, macOS, and Windows (no WSL):

   npx --package @typecad/framework-zephyr zephyr-installer

   You get an interactive checklist of toolchain platforms — pick only the ones you need (for example arm for nRF/STM32/RP2040, esp32 for ESP32/S2/S3, ~150–300 MB each) instead of the full 1.5 GB bundle. Cuttlefish finds the installed environment automatically; no shell activation or PATH setup is required.

   Prefer scripting it? Select platforms up front:

   npx --package @typecad/framework-zephyr zephyr-installer --platforms arm,esp32

3. Create Your First Project

   npx @typecad/cuttlefish create my-project --target esp32s3_devkitc
   cd my-project

   create checks the installed toolchain, shows you every board your Zephyr tree supports, and installs the project’s dependencies for you. (If you passed --no-install, run npm install now.)

4. Write Firmware Edit src/main.ts:

   import { GPIO, Time } from '@typecad/hal';
   import { LED } from '@typecad/board';
   
   // Construction carries the configuration — there is no setup() to write.
   const led = new GPIO(LED, GPIO.OUTPUT);
   
   while (true) {
     led.toggle();
     Time.sleep(1000);
   }

5. Compile and Upload

   npx @typecad/cuttlefish build --compile --upload --port COM4

Later, --modify adds toolchain platforms (--prune removes the unselected ones), and --delete uninstalls everything. See the Zephyr framework guide for board targets, devicetree details, and cuttlefish doctor — and the installer README for every flag.

Next Steps

• GPIO & Digital I/O — Pin modes, read/write, toggle
• Communication Buses — I2C, SPI, UART
• Ownership Model — How peripherals are safely managed
• CLI Reference — Full command reference
• Examples — Ready-to-run firmware examples

Quick Reference

Task	Syntax
Create project	npx @typecad/cuttlefish create my-project --target esp32s3_devkitc
Install Zephyr toolchain	npx --package @typecad/framework-zephyr zephyr-installer --platforms arm,esp32
Compile	npx @typecad/cuttlefish build --compile
Upload	npx @typecad/cuttlefish build --upload --port COM4
Watch mode	npx @typecad/cuttlefish build --watch --compile
Diagnostics	npx @typecad/cuttlefish build --diagnostics