@typecad/framework-arduino 0.1.0-alpha.1

package/src/cpp-parser.ts

@@ -0,0 +1,361 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — C++ Header Parser
+//
+// Parses C++ header files from Arduino libraries into an IR that can be
+// used for TypeScript type declaration generation.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Arduino-to-TypeCAD type mappings
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps Arduino peripheral C++ types to TypeCAD equivalents.
+ * Uses the instance names (I2C0, SPI0, UART0) as types for simplicity.
+ */
+const ARDUINO_TYPE_MAPPINGS: Record<string, string> = {
+  // I2C - TypeCAD uses I2C0 instance
+  "TwoWire": "I2C0",
+  "TwoWire*": "I2C0",
+  "TwoWire&": "I2C0",
+  // SPI - TypeCAD uses SPI0 instance
+  "SPIClass": "SPI0",
+  "SPIClass*": "SPI0",
+  "SPIClass&": "SPI0",
+  // Serial - TypeCAD uses UART0 instance
+  "HardwareSerial": "UART0",
+  "HardwareSerial*": "UART0",
+  "HardwareSerial&": "UART0",
+  "Stream": "UART0",
+  "Stream*": "UART0",
+  "Stream&": "UART0",
+  // Common Arduino types
+  "Print": "UART0",
+  "Print*": "UART0",
+  "Print&": "UART0",
+};
+
+// ---------------------------------------------------------------------------
+// Parse result types
+// ---------------------------------------------------------------------------
+
+interface CppMethod {
+  name: string;
+  returnType: string;
+  parameters: { type: string; name: string }[];
+  isPublic: boolean;
+}
+
+interface CppClass {
+  name: string;
+  /** Fully qualified name including namespace (e.g., "Microfire::SHT3x") */
+  fullName: string;
+  /** Namespace prefix (e.g., "Microfire") */
+  namespace?: string;
+  methods: CppMethod[];
+  constructors: { parameters: { type: string; name: string }[] }[];
+}
+
+export interface CppParseResult {
+  classes: CppClass[];
+  constants: { name: string; type: string; value: string }[];
+}
+
+// ---------------------------------------------------------------------------
+// Type mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps C++ types to TypeScript types.
+ */
+export function mapCppTypeToTs(cppType: string): string {
+  const trimmed = cppType.trim();
+  
+  // Remove const qualifier
+  const withoutConst = trimmed.replace(/^const\s+/, "");
+  
+  // Check Arduino type mappings first
+  if (ARDUINO_TYPE_MAPPINGS[withoutConst]) {
+    return ARDUINO_TYPE_MAPPINGS[withoutConst];
+  }
+  
+  // Basic type mappings
+  const typeMap: Record<string, string> = {
+    "int": "number",
+    "unsigned int": "number",
+    "uint8_t": "number",
+    "uint16_t": "number",
+    "uint32_t": "number",
+    "int8_t": "number",
+    "int16_t": "number",
+    "int32_t": "number",
+    "float": "number",
+    "double": "number",
+    "bool": "boolean",
+    "void": "void",
+    "char": "string",
+    "char*": "string",
+    "const char*": "string",
+    "std::string": "string",
+    "String": "string",
+    "byte": "number",
+    "word": "number",
+    "size_t": "number",
+  };
+  
+  // Check direct mapping
+  if (typeMap[withoutConst]) {
+    return typeMap[withoutConst];
+  }
+  
+  // Handle pointers - check if base type is an Arduino type
+  if (withoutConst.endsWith("*")) {
+    const baseType = withoutConst.slice(0, -1).trim();
+    if (ARDUINO_TYPE_MAPPINGS[baseType]) {
+      return ARDUINO_TYPE_MAPPINGS[baseType];
+    }
+    return "number";
+  }
+  
+  // Handle references - check if base type is an Arduino type
+  if (withoutConst.endsWith("&")) {
+    const baseType = withoutConst.slice(0, -1).trim();
+    if (ARDUINO_TYPE_MAPPINGS[baseType]) {
+      return ARDUINO_TYPE_MAPPINGS[baseType];
+    }
+    return mapCppTypeToTs(baseType);
+  }
+  
+  // Default to any for unknown types
+  return "any";
+}
+
+// ---------------------------------------------------------------------------
+// Parameter parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts the parameter list from a function signature.
+ */
+export function parseParameters(paramString: string): { type: string; name: string }[] {
+  if (!paramString.trim()) {
+    return [];
+  }
+  
+  const params: { type: string; name: string }[] = [];
+  const parts = paramString.split(",");
+  
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    
+    // Handle default values (remove them for the declaration)
+    const withoutDefault = trimmed.split("=")[0].trim();
+    
+    // Split into tokens to find type and name
+    const tokens = withoutDefault.split(/\s+/);
+    if (tokens.length >= 2) {
+      // Last token is the name, rest is the type
+      let name = tokens[tokens.length - 1];
+      let type = tokens.slice(0, -1).join(" ");
+      
+      // Strip & and * prefixes from parameter names (C++ reference/pointer syntax)
+      // These can appear as &name or *name when the type doesn't include them
+      if (name.startsWith("&") || name.startsWith("*")) {
+        // Move the & or * to the type
+        type = type + name[0];
+        name = name.slice(1);
+      }
+      
+      params.push({ type: mapCppTypeToTs(type), name });
+    } else if (tokens.length === 1) {
+      // Just a type (unnamed parameter)
+      params.push({ type: mapCppTypeToTs(tokens[0]), name: "" });
+    }
+  }
+  
+  return params;
+}
+
+// ---------------------------------------------------------------------------
+// Class parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract content inside a namespace block.
+ */
+function extractNamespaceContent(content: string, namespaceName: string): string {
+  // Find namespace block: namespace Name { ... }
+  const namespaceRegex = new RegExp(`namespace\\s+${namespaceName}\\s*\\{`, 'g');
+  const match = namespaceRegex.exec(content);
+  if (!match) return "";
+  
+  const startIndex = match.index + match[0].length;
+  let braceCount = 1;
+  let endIndex = startIndex;
+  
+  while (endIndex < content.length && braceCount > 0) {
+    if (content[endIndex] === '{') braceCount++;
+    else if (content[endIndex] === '}') braceCount--;
+    endIndex++;
+  }
+  
+  return content.slice(startIndex, endIndex - 1);
+}
+
+/**
+ * Parse classes from content, optionally within a namespace.
+ */
+function parseClassesFromContent(content: string, namespace?: string): CppClass[] {
+  const classes: CppClass[] = [];
+  
+  // Parse class definitions - handle nested braces properly
+  const classStartRegex = /\bclass\s+(\w+)\s*\{?/g;
+  let classStartMatch;
+  
+  while ((classStartMatch = classStartRegex.exec(content)) !== null) {
+    const className = classStartMatch[1];
+    const fullName = namespace ? `${namespace}::${className}` : className;
+    
+    const cppClass: CppClass = {
+      name: className,
+      fullName,
+      namespace,
+      methods: [],
+      constructors: [],
+    };
+    
+    // For header files, try to find method declarations
+    // Match: type name(params);
+    const methodRegex = /(\w+(?:\s*[*&])?)\s+(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?;/g;
+    let methodMatch;
+    
+    while ((methodMatch = methodRegex.exec(content)) !== null) {
+      const returnType = methodMatch[1].trim();
+      const name = methodMatch[2].trim();
+      const params = methodMatch[3];
+      
+      // Skip keywords
+      if (["public", "private", "protected", "virtual", "static", "class", "struct"].includes(returnType)) {
+        continue;
+      }
+      
+      // Check if this is a constructor (name matches class name)
+      if (name === className) {
+        cppClass.constructors.push({
+          parameters: parseParameters(params),
+        });
+      } else {
+        cppClass.methods.push({
+          returnType: mapCppTypeToTs(returnType),
+          name,
+          parameters: parseParameters(params),
+          isPublic: true,
+        });
+      }
+    }
+    
+    classes.push(cppClass);
+  }
+  
+  return classes;
+}
+
+// ---------------------------------------------------------------------------
+// Main parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses a C++ class definition from header content.
+ */
+export function parseCppClass(content: string): CppParseResult {
+  const result: CppParseResult = {
+    classes: [],
+    constants: [],
+  };
+  
+  // Parse top-level constants: const int NAME = value;
+  const constRegex = /const\s+(\w+)\s+(\w+)\s*=\s*([^;]+);/g;
+  let constMatch;
+  while ((constMatch = constRegex.exec(content)) !== null) {
+    result.constants.push({
+      type: mapCppTypeToTs(constMatch[1]),
+      name: constMatch[2],
+      value: constMatch[3].trim(),
+    });
+  }
+  
+  // Parse methods with scope resolution (ClassName::methodName) - for .cpp implementation files
+  const scopeResolutionRegex = /(?:^|\n)\s*(?:(\w+(?:\s*[*&])?)\s+)?(\w+)::(\w+)\s*\(([^)]*)\)\s*(?:const\s*)?(?:\{|;)/g;
+  let scopeMatch;
+  const classesFromImpl = new Map<string, CppClass>();
+  
+  while ((scopeMatch = scopeResolutionRegex.exec(content)) !== null) {
+    const returnType = scopeMatch[1]?.trim();
+    const className = scopeMatch[2];
+    const methodName = scopeMatch[3];
+    const params = scopeMatch[4];
+    
+    // Skip if this looks like a namespace (e.g., std::something)
+    if (!returnType && className.toLowerCase() === className) {
+      continue;
+    }
+    
+    if (!classesFromImpl.has(className)) {
+      classesFromImpl.set(className, {
+        name: className,
+        fullName: className,
+        methods: [],
+        constructors: [],
+      });
+    }
+    
+    const cppClass = classesFromImpl.get(className)!;
+    
+    // Check if this is a constructor (method name matches class name)
+    if (methodName === className) {
+      cppClass.constructors.push({
+        parameters: parseParameters(params),
+      });
+    } else if (returnType) {
+      cppClass.methods.push({
+        returnType: mapCppTypeToTs(returnType),
+        name: methodName,
+        parameters: parseParameters(params),
+        isPublic: true,
+      });
+    }
+  }
+  
+  // Add inferred classes to result
+  for (const cppClass of classesFromImpl.values()) {
+    result.classes.push(cppClass);
+  }
+  
+  // Parse namespaces first
+  const namespaceRegex = /namespace\s+(\w+)\s*\{/g;
+  let nsMatch;
+  const namespaces: string[] = [];
+  
+  while ((nsMatch = namespaceRegex.exec(content)) !== null) {
+    namespaces.push(nsMatch[1]);
+  }
+  
+  // Parse classes within each namespace
+  for (const ns of namespaces) {
+    const nsContent = extractNamespaceContent(content, ns);
+    const nsClasses = parseClassesFromContent(nsContent, ns);
+    result.classes.push(...nsClasses);
+  }
+  
+  // Parse classes outside of namespaces (skip if already found in a namespace)
+  const namespaceClassNames = new Set(result.classes.map(c => c.name));
+  const topLevelClasses = parseClassesFromContent(content);
+  for (const cls of topLevelClasses) {
+    if (!namespaceClassNames.has(cls.name)) {
+      result.classes.push(cls);
+    }
+  }
+  
+  return result;
+}

package/src/debug-codegen.ts

@@ -0,0 +1,155 @@
+// ---------------------------------------------------------------------------
+// Arduino debug code generator — Serial-based debug output
+//
+// Generates Arduino Serial.print/println code for debug breakpoints,
+// logpoints, and initialization. Used by the CLI debug preprocessor.
+// ---------------------------------------------------------------------------
+
+export interface CapturedVariable {
+  name: string;
+  isFunction?: boolean;
+}
+
+export interface LogMessagePart {
+  type: 'text' | 'variable';
+  value: string;
+}
+
+/**
+ * Generate Serial.begin() initialization code for Arduino debug mode.
+ */
+export function generateSerialInitCode(): string[] {
+  return [
+    `// === DEBUG: Initialize Serial ===`,
+    `Serial.begin(9600);`,
+    `while (!Serial) {`,
+    `  delay(10);`,
+    `}`,
+    `Serial.println("🔧 TypeCAD Debug Mode Active");`,
+    `Serial.println("");`,
+    `// === END DEBUG INIT ===`,
+    ``,
+  ];
+}
+
+/**
+ * Generate the Serial debug code for a breakpoint.
+ */
+export function generateBreakpointCode(
+  fileName: string,
+  lineNum: number,
+  originalLine: string,
+  variables: CapturedVariable[],
+  normalizedCondition: string | undefined,
+): string[] {
+  const lines: string[] = [];
+
+  // Comment marker
+  lines.push(`  // === BREAKPOINT: ${fileName}:${lineNum} ===`);
+
+  // If conditional, wrap everything in an if statement
+  if (normalizedCondition) {
+    lines.push(`  if (${normalizedCondition}) {`);
+  }
+
+  // Visual separator
+  lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");`);
+
+  // Breakpoint header (with condition indicator if present)
+  const headerText = normalizedCondition 
+    ? `⏸️  BREAKPOINT: ${fileName}:${lineNum} (condition: ${escapeString(normalizedCondition)})`
+    : `⏸️  BREAKPOINT: ${fileName}:${lineNum}`;
+  lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("${headerText}");`);
+
+  // Original source line (escaped)
+  const escapedLine = escapeString(originalLine);
+  lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("  ${escapedLine}");`);
+
+  // Blank line
+  lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("");`);
+
+  // Variables section
+  if (variables.length > 0) {
+    lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("  Variables:");`);
+    for (const v of variables) {
+      if (v.isFunction) {
+        lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("  • ${v.name} = [function]");`);
+      } else {
+        lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.print("  • ${v.name} = "); Serial.println(${v.name});`);
+      }
+    }
+  } else {
+    lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("  (no variables in scope)");`);
+  }
+
+  // Blank line
+  lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("");`);
+
+  // Continue prompt
+  lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("  [Press ENTER to continue...]");`);
+
+  // Visual separator (end)
+  lines.push(`  ${normalizedCondition ? '  ' : ''}Serial.println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");`);
+
+  // Blocking wait for serial input
+  lines.push(`  ${normalizedCondition ? '  ' : ''}while(Serial.available() == 0) { delay(10); }`);
+  lines.push(`  ${normalizedCondition ? '  ' : ''}while(Serial.available() > 0) { Serial.read(); delay(10); }`);
+
+  // Close conditional if statement
+  if (normalizedCondition) {
+    lines.push(`  }`);
+  }
+
+  // End marker
+  lines.push(`  // === END BREAKPOINT ===`);
+
+  return lines;
+}
+
+/**
+ * Generate code for a logpoint (logs message without stopping execution).
+ */
+export function generateLogpointCode(
+  fileName: string,
+  lineNum: number,
+  parts: LogMessagePart[],
+  variables: CapturedVariable[],
+): string[] {
+  const lines: string[] = [];
+
+  // Comment marker
+  lines.push(`  // === LOGPOINT: ${fileName}:${lineNum} ===`);
+
+  // Build the Serial output
+  lines.push(`  Serial.print("[LOG ${fileName}:${lineNum}] ");`);
+  
+  for (const part of parts) {
+    if (part.type === 'text') {
+      lines.push(`  Serial.print("${escapeString(part.value)}");`);
+    } else if (part.type === 'variable') {
+      // Check if the variable exists in scope
+      const varExists = variables.some(v => v.name === part.value && !v.isFunction);
+      if (varExists) {
+        lines.push(`  Serial.print(${part.value});`);
+      } else {
+        lines.push(`  Serial.print("{${part.value}}"); // variable not in scope`);
+      }
+    }
+  }
+  
+  lines.push(`  Serial.println("");`);
+  lines.push(`  // === END LOGPOINT ===`);
+
+  return lines;
+}
+
+/**
+ * Escape a string for use in Serial.println("...").
+ */
+function escapeString(s: string): string {
+  return s
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r');
+}

package/src/displays/ili9341-spi.ts

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// Built-in display profiles for @typecad/framework-arduino.
+//
+// Each profile describes a common display's capabilities. Projects reference
+// them by name in cuttlefish.config.ts:
+//   display: { profile: 'ili9341-spi', cs: 5, dc: 21, rst: 22 }
+// ---------------------------------------------------------------------------
+
+import type { DisplayProfile } from "@typecad/cuttlefish/api/shared";
+import { SSD1309_I2C } from "./ssd1309-i2c.js";
+import { ST7796_SPI } from "./st7796-spi.js";
+
+export const ILI9341_SPI: DisplayProfile = {
+  driver: "ili9341",
+  width: 320,
+  height: 240,
+  colorFormat: "rgb565",
+  rotation: 1,
+  backlight: 17,
+  spiPins: { mosi: 23, sck: 18, miso: 19 },
+};
+
+/** Registry of all built-in profiles. Keyed by profile name. */
+export const BUILT_IN_PROFILES: Record<string, DisplayProfile> = {
+  "ili9341-spi": ILI9341_SPI,
+  "st7796-spi": ST7796_SPI,
+  "ssd1309-i2c": SSD1309_I2C,
+};
+
+/** Get the registry as a Map (for resolveDisplayProfile). */
+export function getProfileRegistry(): Map<string, DisplayProfile> {
+  return new Map(Object.entries(BUILT_IN_PROFILES));
+}

package/src/displays/ssd1309-i2c.ts

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// SSD1309 OLED display profile — 128×64 1-bit monochrome OLED over I2C.
+//
+// The Adafruit_SSD1306 library drives SSD1309-class panels via the same API.
+// displayClass: "oled" uses the same deferred, backing-store mono capability
+// path as e-ink panels (UI_NATIVE_MONO + UI_REQUIRES_BACKING_STORE), while
+// keeping the profile semantically accurate for page-buffered OLED hardware.
+// ---------------------------------------------------------------------------
+
+import type { DisplayProfile } from "@typecad/cuttlefish/api/shared";
+
+export const SSD1309_I2C: DisplayProfile = {
+  driver: "ssd1309",
+  width: 128,
+  height: 64,
+  colorFormat: "mono",
+  displayClass: "oled",
+  rotation: 0,
+};

package/src/displays/st7796-spi.ts

@@ -0,0 +1,23 @@
+// ---------------------------------------------------------------------------
+// Built-in profile for the ST7796S 320×480 SPI TFT.
+//
+// Targets the Adafruit_ST7735_and_ST7789_Library fork that exposes the
+// Adafruit_ST7796S class. RGB565 (the library hardcodes 565 in its init
+// sequence; see display-adapters/st7796.ts for the 666 constraint).
+//
+// Reference usage in cuttlefish.config.ts:
+//   display: { profile: 'st7796-spi', cs: 5, dc: 17, rst: 16 }
+// ---------------------------------------------------------------------------
+
+import type { DisplayProfile } from "@typecad/cuttlefish/api/shared";
+
+export const ST7796_SPI: DisplayProfile = {
+  driver: "st7796",
+  width: 480,
+  height: 320,
+  nativeWidth: 320,
+  nativeHeight: 480,
+  colorFormat: "rgb565",
+  rotation: 1, // landscape → effective 480×320
+  spiPins: { mosi: 23, sck: 18, miso: 19 },
+};

package/src/graphics/ili9341.ts

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// ILI9341 — display driver resolver built on the Adafruit_ILI9341 library.
+//
+// Maps each DisplayHALOp to a method call on a library-instantiated
+// Adafruit_ILI9341 object. The library owns SPI, command sequences, fonts,
+// and glyph rendering — we own the tree, layout, and reactive driver.
+//
+// The framework instantiates one library object per mount; ui.mount's
+// display.init emits the constructor + begin() + setRotation(), and
+// subsequent ops reference the same object by name (__tc_display).
+// ---------------------------------------------------------------------------
+
+import type { DisplayHALOp } from "@typecad/cuttlefish/api/shared";
+
+/** Display-side object variable name (instantiated by display.init). */
+export const DISPLAY_VAR = "__tc_display";
+
+/** The library's required headers — emitted as forced includes. */
+export const ILI9341_INCLUDES = ["<Adafruit_GFX.h>", "<Adafruit_ILI9341.h>"];
+
+export interface ILI9341Context {
+  bus: string;
+  cs: number;
+  dc: number;
+  rst: number;
+  width: number;
+  height: number;
+  rotation?: number;
+  backlight?: number;
+  spiFrequency?: number;
+}
+
+/** Render a color value as a C++ hex literal (e.g. 0x07e0) for readable RGB565. */
+function hexColor(c: number): string {
+  return `0x${c.toString(16)}`;
+}
+
+/**
+ * Resolve a display HAL op to a method call on the Adafruit_ILI9341 object.
+ * Returns undefined for ops this driver does not handle.
+ */
+export function resolveILI9341Op(
+  op: DisplayHALOp,
+  ctx: ILI9341Context,
+): { code?: string; expression?: string } | undefined {
+  switch (op.operation) {
+    case "display.init":
+      return {
+        code: [
+          ctx.backlight ? `pinMode(${ctx.backlight}, OUTPUT); digitalWrite(${ctx.backlight}, HIGH);` : ``,
+          `display_init();`,
+        ].filter(Boolean).join("\n"),
+      };
+    case "display.fill_rect":
+      // Adafruit_GFX fillRect(x, y, w, h, color) — color is uint16 RGB565.
+      return {
+        code: `${DISPLAY_VAR}.fillRect(${op.x}, ${op.y}, ${op.w}, ${op.h}, ${hexColor(op.color)});`,
+      };
+    case "display.draw_rect":
+      return {
+        code: `${DISPLAY_VAR}.drawRect(${op.x}, ${op.y}, ${op.w}, ${op.h}, ${hexColor(op.color)});`,
+      };
+    case "display.draw_text":
+      // Set cursor + color + size, then print. print() is the Print mixin
+      // (not in the auto-gen d.ts but present on the real C++ object).
+      return {
+        code: [
+          `${DISPLAY_VAR}.setCursor(${op.x}, ${op.y});`,
+          `${DISPLAY_VAR}.setTextColor(${hexColor(op.color)});`,
+          `${DISPLAY_VAR}.setTextSize(2);`,
+          `${DISPLAY_VAR}.print(${JSON.stringify(op.text)});`,
+        ].join("\n"),
+      };
+    case "display.flush":
+      // ILI9341 is immediate — draws go straight to the panel. No flush.
+      return { code: `/* flush: ${op.rects.length} rect(s) — immediate draw */` };
+    default:
+      return undefined;
+  }
+}