@typecad/zephyr-esp32s3-rgb 1.0.0-alpha.13

package/README.md

@@ -0,0 +1,77 @@
+# @typecad/zephyr-esp32s3-rgb
+
+The onboard WS2812 ("NeoPixel") RGB LED of the ESP32-S3 DevKitC, as a
+cuttlefish library package for the **Zephyr RTOS** framework.
+
+```sh
+npm install @typecad/zephyr-esp32s3-rgb
+```
+
+```ts
+import { rgbLed } from '@typecad/zephyr-esp32s3-rgb';
+
+rgbLed.color(0, 255, 0).show();       // green
+rgbLed.color('#ff0000').show();       // red, CSS-style hex
+rgbLed.brightness(64).color('#ffffff').show();  // dim white
+rgbLed.off();                          // black + show
+```
+
+`rgbLed` is a preconstructed singleton — import it and chain calls. Colors
+buffer locally; nothing reaches the LED until `show()` (or `off()`).
+
+## What the library carries (so you don't have to)
+
+The native Zephyr path for this LED touches devicetree bindings, pinctrl,
+DMA, and Kconfig before the first blink. This package moves that complexity
+into itself, as three declarative artifacts (see `cuttlefish.library.json`):
+
+| Artifact | File | What it does |
+|---|---|---|
+| C++ shim | `shims/__tc_rgbled.{h,cpp}` | `class RgbLed` over Zephyr's `led_strip_update_rgb()`; the import resolves to this header |
+| Devicetree overlay | `shims/tc-rgb.overlay` | WS2812 node on GPIO48 through the I2S0 peripheral (`worldsemi,ws2812-i2s`, GRB color-mapping, DMA channel 3) |
+| Kconfig | manifest `kconfig` | `CONFIG_LED_STRIP=y`, `CONFIG_I2S=y`, `CONFIG_DMA=y` |
+
+When your program imports the package, the cuttlefish transpiler:
+
+1. registers the import as a library (the package root carries a
+   `cuttlefish.library.json`) and skips transpiling its TypeScript — the
+   package's own types are the compile-time contract;
+2. emits `#include "__tc_rgbled.h"` into your `main.cpp` and writes the shim
+   files into the generated `src/` (CMake picks the `.cpp` up automatically);
+3. appends the overlay fragment to the generated `boards/<board>.overlay`;
+4. appends the Kconfig lines to the generated `prj.conf`.
+
+The I2S backend is upstream Zephyr's own configuration for this board
+(`samples/drivers/led/led_strip`), adapted verbatim — it borrows the I2S0
+peripheral and DMA channel 3, which nothing else in a cuttlefish Zephyr
+project uses. The alternative SPI backend would collide with `spi.*` HAL
+usage; the ESP32-S3's dedicated RMT peripheral has no upstream Zephyr driver.
+
+## Requirements
+
+- **Framework:** `@typecad/framework-zephyr` (importing under another
+  framework fails the transpile with a clear error).
+- **Board target:** `esp32s3_devkitc`.
+- **Hardware revision:** DevKitC **v1.0**, whose RGB LED is on **GPIO48**.
+  v1.1 moved it to GPIO38 — on that revision change one line in
+  `shims/tc-rgb.overlay` (`I2S0_O_SD_GPIO48` → `I2S0_O_SD_GPIO38`). (The
+  mismatch with `boards/board-esp32s3`'s `led: 'GPIO48'` is inherited: the
+  Arduino core also pins v1.0's GPIO48 as `RGB_BUILTIN`.)
+- **Validated on hardware:** 2026-08-21, ESP32-S3 DevKitC (GPIO48 revision),
+  via demo-shadcn — boot color + tap-counter color cycling through the full
+  chain (transpile → shim → overlay → Kconfig → west build → flash).
+
+## Writing a sibling library
+
+This package is the template: an npm package with a `cuttlefish.library.json`
+manifest (`module`, `framework`, `targets`, `include`, `gateToken`, `shims`,
+`kconfig`, `overlay`), a types-only TypeScript API, and the native artifacts.
+An Arduino counterpart (`@typecad/arduino-esp32s3-rgb` over `neopixelWrite`)
+would follow the same manifest with a different framework id — the mechanism
+is per-library, not per-framework-matrix.
+
+## Shim compliance
+
+The shim sources are AUTOSAR C++14 by construction (fixed-width integers,
+`static_cast` only, no heap, `final` class) and must keep passing
+`--autosar=strict` — the repo's compliance test covers them.

package/cuttlefish.library.json

@@ -0,0 +1,18 @@
+{
+  "id": "zephyr-esp32s3-rgb",
+  "module": "@typecad/zephyr-esp32s3-rgb",
+  "framework": "zephyr",
+  "targets": ["esp32s3_devkitc"],
+  "include": "\"__tc_rgbled.h\"",
+  "gateToken": "__tc_rgbled",
+  "shims": [
+    { "path": "shims/__tc_rgbled.h", "outName": "__tc_rgbled.h" },
+    { "path": "shims/__tc_rgbled.cpp", "outName": "__tc_rgbled.cpp" }
+  ],
+  "kconfig": [
+    "CONFIG_LED_STRIP=y",
+    "CONFIG_I2S=y",
+    "CONFIG_DMA=y"
+  ],
+  "overlay": "shims/tc-rgb.overlay"
+}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The onboard addressable RGB LED.
+ *
+ * Buffers color/brightness locally; `show()` pushes one pixel to the strip.
+ * All modifiers chain and return the same instance.
+ */
+export declare class RgbLed {
+    /**
+     * Set the LED color from 8-bit components (0–255 each).
+     * The LED does not change until `show()` is called.
+     */
+    color(r: number, g: number, b: number): this;
+    /**
+     * Set the LED color from a CSS-style hex string
+     * (`'#00ff00'` or `'00ff00'`). Invalid input is ignored.
+     * The LED does not change until `show()` is called.
+     */
+    color(hex: string): this;
+    /**
+     * Scale output brightness (0–255, default 255). Applied at `show()` time,
+     * so the buffered full-brightness color is preserved.
+     */
+    brightness(scale: number): this;
+    /** Push the buffered color to the LED. */
+    show(): this;
+    /** Turn the LED off immediately (black + show). */
+    off(): this;
+}
+/**
+ * The board's onboard RGB LED — the instance to use. A preconstructed
+ * singleton (rather than `new RgbLed()`) so the generated C++ stays a plain
+ * static instance with zero heap use.
+ */
+export declare const rgbLed: RgbLed;

package/dist/index.js

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// @typecad/zephyr-esp32s3-rgb — onboard WS2812 RGB LED (ESP32-S3 DevKitC)
+//
+// A cuttlefish *library package*: `npm install @typecad/zephyr-esp32s3-rgb`,
+// then import and use it like any other TypeScript module. The cuttlefish
+// transpiler resolves the import to the native shim header (`__tc_rgbled.h`)
+// and emits the shim + devicetree overlay + Kconfig into the generated Zephyr
+// application — the class below is never executed, it is the typed API
+// contract your editor sees. The C++ class in shims/__tc_rgbled.h is the
+// implementation this type describes.
+//
+// Board facts carried by this library (instead of by you):
+//   - WS2812 ("NeoPixel") on GPIO48 (DevKitC v1.0; v1.1 moved it to GPIO38)
+//   - driven through the I2S0 peripheral (upstream Zephyr's own configuration
+//     for this board — samples/drivers/led/led_strip)
+//   - GRB wire order handled by the devicetree color-mapping
+// ---------------------------------------------------------------------------
+/**
+ * The onboard addressable RGB LED.
+ *
+ * Buffers color/brightness locally; `show()` pushes one pixel to the strip.
+ * All modifiers chain and return the same instance.
+ */
+export class RgbLed {
+    color(rOrHex, g, b) {
+        // Types-only — lowered to the RgbLed C++ shim by the transpiler.
+        return this;
+    }
+    /**
+     * Scale output brightness (0–255, default 255). Applied at `show()` time,
+     * so the buffered full-brightness color is preserved.
+     */
+    brightness(scale) {
+        return this;
+    }
+    /** Push the buffered color to the LED. */
+    show() {
+        return this;
+    }
+    /** Turn the LED off immediately (black + show). */
+    off() {
+        return this;
+    }
+}
+/**
+ * The board's onboard RGB LED — the instance to use. A preconstructed
+ * singleton (rather than `new RgbLed()`) so the generated C++ stays a plain
+ * static instance with zero heap use.
+ */
+export const rgbLed = new RgbLed();

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@typecad/zephyr-esp32s3-rgb",
+  "version": "1.0.0-alpha.13",
+  "description": "TypeLED for the ESP32-S3 DevKitC onboard WS2812 RGB LED (Zephyr RTOS) — a cuttlefish library package",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "shims",
+    "cuttlefish.library.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/zephyr-esp32s3-rgb"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/zephyr-esp32s3-rgb",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "cpp",
+    "cuttlefish",
+    "cuttlefish-library",
+    "cuttlefish-led",
+    "embedded",
+    "esp32s3",
+    "firmware",
+    "led",
+    "neopixel",
+    "rgb",
+    "smart-led",
+    "typecad",
+    "typescript",
+    "ws2812",
+    "zephyr"
+  ],
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "author": "typecad0",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/shims/__tc_rgbled.cpp

@@ -0,0 +1,103 @@
+// ---------------------------------------------------------------------------
+// __tc_rgbled.cpp — RgbLed shim implementation
+// See __tc_rgbled.h for the contract. AUTOSAR C++14 compliant.
+// ---------------------------------------------------------------------------
+
+#include "__tc_rgbled.h"
+
+namespace {
+
+const std::int32_t kHexDigitCount = 6;
+const std::uint32_t kHexBase = 16U;
+const std::uint32_t kChannelMax = 255U;
+
+std::uint8_t channel_scaled(std::uint8_t value, std::uint8_t scale)
+{
+  const std::uint32_t product = (static_cast<std::uint32_t>(value) * static_cast<std::uint32_t>(scale)) / kChannelMax;
+  return static_cast<std::uint8_t>(product);
+}
+
+std::uint8_t hex_digit_value(char c)
+{
+  if ((c >= '0') && (c <= '9'))
+  {
+    return static_cast<std::uint8_t>(c - '0');
+  }
+  if ((c >= 'a') && (c <= 'f'))
+  {
+    return static_cast<std::uint8_t>((c - 'a') + 10);
+  }
+  if ((c >= 'A') && (c <= 'F'))
+  {
+    return static_cast<std::uint8_t>((c - 'A') + 10);
+  }
+  return kChannelMax + 1U;  // sentinel: not a hex digit
+}
+
+}  // namespace
+
+const struct device* RgbLed::strip_device()
+{
+  return DEVICE_DT_GET(DT_ALIAS(led_strip));
+}
+
+RgbLed& RgbLed::color(std::uint8_t r, std::uint8_t g, std::uint8_t b)
+{
+  pixel_.r = r;
+  pixel_.g = g;
+  pixel_.b = b;
+  return *this;
+}
+
+RgbLed& RgbLed::color(const char* hex)
+{
+  if (hex == nullptr)
+  {
+    return *this;
+  }
+  const char* p = hex;
+  if (p[0] == '#')
+  {
+    p = &p[1];
+  }
+  std::uint32_t value = 0U;
+  for (std::int32_t i = 0; i < kHexDigitCount; ++i)
+  {
+    const std::uint8_t digit = hex_digit_value(p[i]);
+    if (digit > kChannelMax)
+    {
+      return *this;  // invalid input — ignored, buffered color untouched
+    }
+    value = (value * kHexBase) + static_cast<std::uint32_t>(digit);
+  }
+  pixel_.r = static_cast<std::uint8_t>((value >> 16) & 0xFFU);
+  pixel_.g = static_cast<std::uint8_t>((value >> 8) & 0xFFU);
+  pixel_.b = static_cast<std::uint8_t>(value & 0xFFU);
+  return *this;
+}
+
+RgbLed& RgbLed::brightness(std::uint8_t scale)
+{
+  scale_ = scale;
+  return *this;
+}
+
+RgbLed& RgbLed::show()
+{
+  struct led_rgb out{};
+  out.r = channel_scaled(pixel_.r, scale_);
+  out.g = channel_scaled(pixel_.g, scale_);
+  out.b = channel_scaled(pixel_.b, scale_);
+  static_cast<void>(led_strip_update_rgb(strip_device(), &out, 1U));
+  return *this;
+}
+
+RgbLed& RgbLed::off()
+{
+  pixel_.r = 0U;
+  pixel_.g = 0U;
+  pixel_.b = 0U;
+  return show();
+}
+
+RgbLed rgbLed;

package/shims/__tc_rgbled.h

@@ -0,0 +1,42 @@
+// ---------------------------------------------------------------------------
+// __tc_rgbled.h — RgbLed shim for @typecad/zephyr-esp32s3-rgb
+//
+// Emitted into the generated application's src/ by the cuttlefish transpiler
+// when the @typecad/zephyr-esp32s3-rgb import is used. The TypeScript class
+// in the package's src/index.ts is the typed contract; this class is the
+// implementation. Calls render verbatim, so the method names and the global
+// `rgbLed` instance are the API — do not rename one without the other.
+//
+// Targets the devicetree node aliased `led-strip` (contributed by this
+// library's overlay fragment: WS2812 on GPIO48 via the I2S0 peripheral).
+// AUTOSAR C++14 compliant (no heap, no C-style casts, fixed-width ints).
+// ---------------------------------------------------------------------------
+
+#ifndef TC_RGBLED_H_
+#define TC_RGBLED_H_
+
+#include <cstdint>
+#include <zephyr/device.h>
+#include <zephyr/drivers/led_strip.h>
+
+class RgbLed final
+{
+public:
+  RgbLed& color(std::uint8_t r, std::uint8_t g, std::uint8_t b);
+  RgbLed& color(const char* hex);
+  RgbLed& brightness(std::uint8_t scale);
+  RgbLed& show();
+  RgbLed& off();
+
+private:
+  static const struct device* strip_device();
+
+  // Value-initialized: layout-agnostic (led_rgb may carry a leading scratch
+  // member under CONFIG_LED_STRIP_RGB_SCRATCH).
+  struct led_rgb pixel_{};
+  std::uint8_t scale_ = 255U;
+};
+
+extern RgbLed rgbLed;
+
+#endif  // TC_RGBLED_H_

package/shims/tc-rgb.overlay

@@ -0,0 +1,45 @@
+/*
+ * Onboard WS2812 RGB LED — ESP32-S3 DevKitC, GPIO48, I2S backend.
+ *
+ * Adapted from Zephyr's in-tree sample overlay for this exact board:
+ *   samples/drivers/led/led_strip/boards/esp32s3_devkitc_procpu.overlay
+ *   Copyright (c) 2024-2025 Espressif Systems (Shanghai) Co., Ltd.
+ *   SPDX-License-Identifier: Apache-2.0
+ *
+ * Appended to the generated boards/<board>.overlay when the library's
+ * __tc_rgbled include token appears in the emitted sources. color-mapping
+ * uses raw LED_COLOR_ID values (GREEN=2, RED=1, BLUE=3 — the WS2812 GRB
+ * wire order) to keep the fragment include-free.
+ */
+
+/ {
+	aliases {
+		led-strip = &led_strip;
+	};
+};
+
+&i2s0_default {
+	group1 {
+		pinmux = <I2S0_O_SD_GPIO48>;
+	};
+};
+
+i2s_led: &i2s0 {
+	status = "okay";
+
+	dmas = <&dma 3>;
+	dma-names = "tx";
+
+	led_strip: ws2812@0 {
+		compatible = "worldsemi,ws2812-i2s";
+
+		reg = <0>;
+		chain-length = <1>;
+		color-mapping = <2 1 3>; /* GRB: LED_COLOR_ID_GREEN, _RED, _BLUE */
+		reset-delay = <500>;
+	};
+};
+
+&dma {
+	status = "okay";
+};

package/src/index.ts

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// @typecad/zephyr-esp32s3-rgb — onboard WS2812 RGB LED (ESP32-S3 DevKitC)
+//
+// A cuttlefish *library package*: `npm install @typecad/zephyr-esp32s3-rgb`,
+// then import and use it like any other TypeScript module. The cuttlefish
+// transpiler resolves the import to the native shim header (`__tc_rgbled.h`)
+// and emits the shim + devicetree overlay + Kconfig into the generated Zephyr
+// application — the class below is never executed, it is the typed API
+// contract your editor sees. The C++ class in shims/__tc_rgbled.h is the
+// implementation this type describes.
+//
+// Board facts carried by this library (instead of by you):
+//   - WS2812 ("NeoPixel") on GPIO48 (DevKitC v1.0; v1.1 moved it to GPIO38)
+//   - driven through the I2S0 peripheral (upstream Zephyr's own configuration
+//     for this board — samples/drivers/led/led_strip)
+//   - GRB wire order handled by the devicetree color-mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * The onboard addressable RGB LED.
+ *
+ * Buffers color/brightness locally; `show()` pushes one pixel to the strip.
+ * All modifiers chain and return the same instance.
+ */
+export class RgbLed {
+  /**
+   * Set the LED color from 8-bit components (0–255 each).
+   * The LED does not change until `show()` is called.
+   */
+  color(r: number, g: number, b: number): this;
+
+  /**
+   * Set the LED color from a CSS-style hex string
+   * (`'#00ff00'` or `'00ff00'`). Invalid input is ignored.
+   * The LED does not change until `show()` is called.
+   */
+  color(hex: string): this;
+
+  color(rOrHex: number | string, g?: number, b?: number): this {
+    // Types-only — lowered to the RgbLed C++ shim by the transpiler.
+    return this;
+  }
+
+  /**
+   * Scale output brightness (0–255, default 255). Applied at `show()` time,
+   * so the buffered full-brightness color is preserved.
+   */
+  brightness(scale: number): this {
+    return this;
+  }
+
+  /** Push the buffered color to the LED. */
+  show(): this {
+    return this;
+  }
+
+  /** Turn the LED off immediately (black + show). */
+  off(): this {
+    return this;
+  }
+}
+
+/**
+ * The board's onboard RGB LED — the instance to use. A preconstructed
+ * singleton (rather than `new RgbLed()`) so the generated C++ stays a plain
+ * static instance with zero heap use.
+ */
+export const rgbLed: RgbLed = new RgbLed();