@typecad/framework-zephyr 1.0.0-alpha.10 → 1.0.0-alpha.11

package/src/display/profiles.ts

@@ -56,6 +56,19 @@ export const ZEPHYR_DISPLAY_PROFILES: Record<string, ZephyrDisplayProfile> = {
     rotation: 1,
     backlight: 'backlight',
   },
+  'ssd1306-zephyr': {
+    // Monochrome OLED (SSD1306-class, 128x64, 1bpp). Driven through Zephyr's
+    // generic display API (the ssd1306 driver + a DT display node). The GFX
+    // runtime (gfx.ts mono branch) keeps a full page-framebuffer and pushes it
+    // on display_flush — the standard model for page-buffered OLEDs. Direct
+    // display.* ops only (no @typecad/ui CuttlefishGFX rendering on mono).
+    driver: 'ssd1306-zephyr',
+    dtLabel: 'display0',
+    width: 128,
+    height: 64,
+    colorFormat: 'mono',
+    rotation: 0,
+  },
 };
 
 /** The default profile used when resolveDisplayOp is probed without a display.init. */

package/src/display/ui-adapter.ts

@@ -551,6 +551,11 @@ static inline void display_targetPrint(CuttlefishDisplayTarget* t, const char* s
 export const zephyrDisplayAdapterGenerator: DisplayAdapterGenerator = (display) => {
   const profile = ZEPHYR_DISPLAY_PROFILES[display.driver];
   if (!profile) return undefined as unknown as DisplayAdapterCode;
+  // The UI adapter is RGB565/SPI (TFT) only. Monochrome panels (OLED) use the
+  // direct display.* GFX runtime (gfx.ts mono branch) — there is no
+  // CuttlefishGFX UI rendering path for mono. Decline so cuttlefish does not
+  // emit an incompatible RGB565 adapter for a mono profile.
+  if (profile.colorFormat === 'mono') return undefined as unknown as DisplayAdapterCode;
   return zephyrUiDisplayAdapter(profile, {
     scanlineSync: display.scanlineSync,
     miso: display.spiPins?.miso,

package/src/doctor.ts

@@ -1,56 +1,77 @@
-// ---------------------------------------------------------------------------
-// @typecad/framework-zephyr — Zephyr environment doctor
-//
-// `cuttlefish doctor` (Zephyr framework) — verify the installed Zephyr RTOS is
-// reachable and inside the framework's declared compat range, and preview how
-// the configured board target resolves for that version. Exits 0 if the
-// environment is OK, non-zero otherwise. Mirrors framework-arduino's doctor
-// shape (dispatched via the framework's `doctor` export).
-// ---------------------------------------------------------------------------
-
-import * as ui from '@typecad/cuttlefish/utils/ui';
-import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
-import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './toolchain/compat.js';
-
-/**
- * Verify the installed Zephyr is reachable + inside the supported range, and
- * preview board-target normalization for the configured target. Sets
- * process.exitCode = 1 on an out-of-range Zephyr.
- */
-export function runDoctor(): void {
-  ui.printHeader();
-  ui.printStep('Checking Zephyr environment...');
-
-  const base = process.env.ZEPHYR_BASE;
-  const version = detectZephyrVersion();
-  const result = checkZephyrCompat(version);
-
-  ui.printInfo(`ZEPHYR_BASE ..... ${base ?? '(not set)'}`);
-  ui.printInfo(`Zephyr version .. ${version ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
-  ui.printInfo(`Supported range . ${result.range ?? '(none declared)'}`);
-
-  if (result.status === 'out-of-range') {
-    ui.printError(`Zephyr ${version} is OUTSIDE the supported range (${result.range}).`);
-    ui.printInfo(
-      "Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.",
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  if (result.status === 'undetectable') {
-    ui.printWarning('Could not detect the Zephyr version (is ZEPHYR_BASE set?) — compat check skipped.');
-  } else {
-    ui.printInfo('Zephyr compat ... OK');
-  }
-
-  // Preview how the configured board target resolves for this Zephyr version
-  // (e.g. a stale bare id would be qualified at build time). The loader extracts
-  // frameworkData.buildTarget to a top-level field.
-  const config = loadCuttlefishConfig(process.cwd());
-  const buildTarget = config?.buildTarget;
-  if (buildTarget) {
-    const resolved = resolveBoardTarget(buildTarget, version);
-    ui.printInfo(`Board target .... ${buildTarget}${resolved === buildTarget ? '' : ` → ${resolved}`}`);
-  }
-}
+// ---------------------------------------------------------------------------
+// @typecad/framework-zephyr — Zephyr environment doctor
+//
+// `cuttlefish doctor` (Zephyr framework) — verify west (the Zephyr build tool)
+// is installed + responsive, the Zephyr RTOS is inside the framework's declared
+// compat range, and the configured board target exists in the checkout. Exits 0
+// if the environment is OK, non-zero otherwise. Mirrors framework-arduino's
+// doctor shape (dispatched via the framework's `doctor` export) and reuses
+// checkZephyrEnv so the detection logic can be shared with the build/test gates.
+// ---------------------------------------------------------------------------
+
+import * as ui from '@typecad/cuttlefish/utils/ui';
+import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
+import { checkZephyrEnv } from './toolchain/env-check.js';
+
+/**
+ * Verify west is installed + responsive, the Zephyr RTOS is inside the supported
+ * range, and the configured board target exists in the checkout. Sets
+ * process.exitCode = 1 on failure. Thin presenter over checkZephyrEnv.
+ */
+export function runDoctor(): void {
+  ui.printHeader();
+  ui.printStep('Checking Zephyr environment...');
+
+  const config = loadCuttlefishConfig(process.cwd());
+  const buildTarget = config?.buildTarget;
+
+  const result = checkZephyrEnv(buildTarget);
+  const c = result.check;
+
+  // west (the Zephyr build tool) — the analog of arduino-cli presence.
+  if (c.westFound) {
+    const ver = c.westVersion ?? 'found';
+    const src = c.westSource ? `  (${c.westSource})` : '';
+    ui.printInfo(`west ............. ${ver}  ✓${src}`);
+  } else {
+    ui.printError('west ............. NOT FOUND');
+  }
+
+  // Zephyr RTOS version + declared compat range.
+  ui.printInfo(`ZEPHYR_BASE ...... ${c.zephyrBase ?? '(not set)'}`);
+  ui.printInfo(`Zephyr version .. ${c.zephyrVersion ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
+  ui.printInfo(`Supported range . ${c.compatRange ?? '(none declared)'}`);
+
+  if (c.compatStatus === 'out-of-range') {
+    ui.printError(`Zephyr ${c.zephyrVersion} is OUTSIDE the supported range (${c.compatRange}).`);
+  } else if (c.compatStatus === 'undetectable') {
+    ui.printWarning('Could not detect the Zephyr version (is ZEPHYR_BASE set?) — compat check skipped.');
+  } else {
+    ui.printInfo('Zephyr compat ... OK');
+  }
+
+  // Board target — the analog of the Arduino core presence check.
+  if (buildTarget) {
+    const resolved = c.resolvedBoardTarget ?? buildTarget;
+    const arrow = resolved === buildTarget ? '' : ` → ${resolved}`;
+    if (c.boardTargetSupported === false) {
+      ui.printError(`Board target .... ${buildTarget}${arrow}  NOT found in this Zephyr checkout`);
+      ui.printInfo('  → check the board id, or run: west boards');
+    } else if (c.boardTargetSupported === undefined) {
+      ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
+      ui.printInfo('(could not verify board presence — no ZEPHYR_BASE boards/ tree found)');
+    } else {
+      ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
+    }
+  } else {
+    ui.printInfo('(no buildTarget in cuttlefish.config.ts — skipping board check)');
+  }
+
+  // Exit code — mirrors framework-arduino's doctor.
+  if (result.ok) {
+    ui.printSuccess('Environment OK');
+    return; // exitCode stays unset => 0
+  }
+  for (const line of result.messages) ui.printInfo(line);
+  process.exitCode = 1;
+}

package/src/dt-config/kconfig.ts

@@ -11,6 +11,9 @@
 export interface KconfigUsage {
   usesAdc?: boolean;
   usesPwm?: boolean;
+  usesDac?: boolean;
+  usesFS?: boolean;
+  usesHwtimer?: boolean;
   usesI2c?: boolean;
   usesSpi?: boolean;
   usesUart?: boolean;
@@ -49,9 +52,12 @@ export function resolveKconfigFragments(
 
   if (usage.usesAdc) m.set('CONFIG_ADC', 'y');
   if (usage.usesPwm) m.set('CONFIG_PWM', 'y');
+  if (usage.usesDac) m.set('CONFIG_DAC', 'y');
   if (usage.usesI2c) m.set('CONFIG_I2C', 'y');
   if (usage.usesSpi) m.set('CONFIG_SPI', 'y');
   if (usage.usesWdt) m.set('CONFIG_WATCHDOG', 'y');
+  // Hardware timers via the counter driver.
+  if (usage.usesHwtimer) m.set('CONFIG_COUNTER', 'y');
   if (usage.usesDisplay) {
     m.set('CONFIG_DISPLAY', 'y');
     m.set('CONFIG_SPI', 'y');
@@ -257,6 +263,19 @@ export function resolveKconfigFragments(
     m.set('CONFIG_SETTINGS', 'y');
     m.set('CONFIG_SETTINGS_ZMS', 'y');
   }
+  // Filesystem: littlefs on the storage partition. CONFIG_FILE_SYSTEM_LITTLEFS
+  // selects the littlefs backend but NOT FLASH/FLASH_MAP (the partition lookup
+  // needs them), so all three are set explicitly — same shape as the
+  // preferences/ZMS block. The overlay points the storage_partition at the FS
+  // (see dt-config/overlay.ts). NOTE: a program using BOTH fs.* and
+  // preferences.* shares the one storage_partition between littlefs and ZMS —
+  // dedicate separate partitions if both are needed (the manifest flags this).
+  if (usage.usesFS) {
+    m.set('CONFIG_FLASH', 'y');
+    m.set('CONFIG_FLASH_MAP', 'y');
+    m.set('CONFIG_FILE_SYSTEM', 'y');
+    m.set('CONFIG_FILE_SYSTEM_LITTLEFS', 'y');
+  }
   // usesUart: the board enables the console UART by default; the overlay (not
   // Kconfig) is where a UART node would be enabled, so no symbol here.
   // Random: <zephyr/random/random.h> sys_rand_get is backed by the random

package/src/dt-config/overlay.ts

@@ -84,6 +84,11 @@ export function generateOverlay(
   if (usage.usesUart && chip.uart) {
     for (const c of chip.uart.controllers) block(c.nodeLabel);
   }
+  // DAC: enable the chip's DAC device node when the program uses dac.*. The
+  // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)).
+  if (usage.usesDac && chip.dac) {
+    block(chip.dac.device);
+  }
   if (display) {
     // Emit a full display DT node definition. Boards like the ESP32 devkit
     // have no display node in their base DT, so a bare `&display0 { status }`

package/src/framework.manifest.ts

@@ -113,9 +113,13 @@ export default defineFrameworkManifest({
       },
     },
     dac: {
-      supported: false,
-      unsupportedReason: 'No DAC lowering implemented in the framework (not applicable on nRF52840; ESP32 variants with DAC not yet wired).',
-      ops: { 'dac.write': 'unsupported' },
+      // ESP32 DAC (2× 8-bit channels on GPIO25/26) via the Zephyr DAC driver
+      // (dac_channel_setup + dac_write_value). nRF52840 / ESP32-S3 have no DAC;
+      // usage there lowers to a comment and profileDiagnostics flags it
+      // (zephyr-dac-pin-unavailable).
+      supported: true,
+      partialCoverage: true,
+      ops: { 'dac.write': 'supported' },
     },
     interrupts: {
       supported: true,
@@ -287,7 +291,7 @@ export default defineFrameworkManifest({
       supported: true,
       partialCoverage: false,
       unsupportedReason: undefined,
-      drivers: ['ili9341-zephyr', 'st7796-zephyr'],
+      drivers: ['ili9341-zephyr', 'st7796-zephyr', 'ssd1306-zephyr'],
       colorFormat: 'rgb565',
       ops: {
         'display.init': 'supported',
@@ -370,10 +374,17 @@ export default defineFrameworkManifest({
       },
     },
     fs: {
-      supported: false,
-      unsupportedReason: 'No filesystem lowering on Zephyr (Zephyr has its own FS API; not wired).',
+      // littlefs on the board's storage_partition, via <zephyr/fs/fs.h>. The
+      // shim mounts at /lfs lazily (formats on first use) and the HAL paths are
+      // treated as paths within the filesystem. Requires CONFIG_FILE_SYSTEM +
+      // CONFIG_FILE_SYSTEM_LITTLEFS (emitted by the scaffold when fs.* is used)
+      // and the storage_partition node.
+      supported: true,
       partialCoverage: false,
-      ops: unsupportedOps('fs.'),
+      ops: {
+        'fs.begin': 'supported', 'fs.read_text': 'supported', 'fs.write_text': 'supported',
+        'fs.exists': 'supported', 'fs.remove': 'supported',
+      },
     },
     mdns: {
       supported: false,
@@ -410,10 +421,17 @@ export default defineFrameworkManifest({
       ops: { 'temp.read': 'unsupported' },
     },
     hwtimer: {
-      supported: false,
-      unsupportedReason: 'No hardware-timer lowering on Zephyr (timers are handled via the k_timer polyfill, not hwtimer.*).',
-      partialCoverage: false,
-      ops: unsupportedOps('hwtimer.'),
+      // Hardware timers via the Zephyr counter driver (<zephyr/drivers/counter.h>).
+      // set_frequency → top value (counter_freq/hz) + on_overflow callback;
+      // start arms both; stop halts. A chip declares its free counters
+      // (e.g. nRF RTC1; RTC0 is kernel-owned). This is distinct from the JS
+      // setInterval/setTimeout k_timer polyfill, which is unaffected.
+      supported: true,
+      partialCoverage: true,
+      ops: {
+        'hwtimer.set_frequency': 'supported', 'hwtimer.on_overflow': 'supported',
+        'hwtimer.start': 'supported', 'hwtimer.stop': 'supported',
+      },
     },
     capacitive: {
       // FT6336U capacitive touch is handled via the strategy-owned touch adapter
@@ -481,6 +499,8 @@ export default defineFrameworkManifest({
   polyfills: {
     emitted: [
       { id: 'cuttlefish_halt', domain: 'standard', notes: 'Mapped to a k_msleep halt loop (exceptions disabled)' },
+      { id: 'string_methods', domain: 'embedded', notes: 'STL-free __tc_* string helpers (const char*, inline ASCII case conv, <cstring> only)' },
+      { id: 'static_array', domain: 'embedded', notes: 'STL-free __tc_StaticArray<T,N> wrapper for no-<vector> mutated/struct array literals' },
       { id: 'timer_methods', domain: 'embedded', notes: 'k_timer + k_work pool (system workqueue); callbacks run in thread context' },
       { id: 'async_runtime', domain: 'embedded', notes: 'Heap-free static Promise/microtask runtime (generateStaticAsyncRuntime), pumped in loop()' },
     ],
@@ -537,9 +557,9 @@ export default defineFrameworkManifest({
     // pure string-snapshot tests (no hardware); they are the safety net that
     // catches regressions like silent pull-resistor / interrupt no-ops.
     halResolutionTests: [
-      'adc', 'ble', 'board', 'dac', 'gpio', 'http', 'i2c', 'interrupts', 'mqtt',
-      'power', 'preferences', 'pulse', 'pwm', 'random', 'spi', 'timing', 'tone',
-      'uart', 'wdt', 'worker',
+      'adc', 'ble', 'board', 'dac', 'fs', 'gpio', 'http', 'hwtimer', 'i2c',
+      'interrupts', 'mqtt', 'power', 'preferences', 'pulse', 'pwm', 'random',
+      'spi', 'timing', 'tone', 'uart', 'wdt', 'worker',
     ],
   },
 
@@ -555,4 +575,8 @@ export default defineFrameworkManifest({
   // `cuttlefish doctor` prints the detected Zephyr version + compat result and
   // previews how the configured board target resolves for that version.
   doctor: { available: true },
+
+  // `cuttlefish licenses` enumerates the Zephyr kernel + west manifest projects
+  // and resolves each one's SPDX license (mirrors framework-arduino).
+  licenses: { available: true },
 });

package/src/index.ts

@@ -16,6 +16,12 @@ export { Toolchain } from './toolchain/index.js';
 // mod.doctor (see framework-package.ts).
 export { runDoctor as doctor } from './doctor.js';
 
+// `cuttlefish licenses` — enumerate the Zephyr kernel + west manifest projects
+// and resolve each one's SPDX license. Re-exported under the dispatcher-facing
+// alias `licenses` so the loader picks it up as mod.licenses (see
+// framework-package.ts). Mirrors framework-arduino's presenter.
+export { runLicensesPresenter as licenses } from './licenses.js';
+
 // Chip descriptor registry (for downstream tooling / additional boards).
 export {
   chipForTarget,