atech 1.0.0a1__py3-none-any.whl

atech/__init__.py

@@ -0,0 +1,71 @@
+"""Atech SDK — open-source Python interface to Atech motherboards.
+
+Two complementary halves:
+
+* **Build** — assemble a project, validate placement, generate firmware,
+  compile with PlatformIO, flash to a board. See :class:`Project`.
+* **Runtime** — talk to a flashed board over USB serial. See
+  :class:`atech.runtime.Board` (also re-exported as :class:`Board` here).
+"""
+
+from atech.build import BuildResult
+from atech.catalog import (
+    BoardSpec,
+    ModuleSpec,
+    get_board,
+    get_module,
+    list_boards,
+    list_modules,
+)
+from atech.errors import (
+    AtechError,
+    BuildError,
+    CatalogError,
+    PlacementError,
+    UploadError,
+)
+from atech.placement import Placement, PlacementIssue
+from atech.project import Project, ProjectModule
+from atech.runtime import (
+    Action,
+    Board,
+    Event,
+    MockTransport,
+    NoBoardFoundError,
+    SerialTransport,
+    discover_ports,
+)
+from atech.upload import UploadResult
+
+__version__ = "1.0.0a1"
+
+__all__ = [
+    # Build half
+    "Project",
+    "ProjectModule",
+    "Placement",
+    "PlacementIssue",
+    "BoardSpec",
+    "ModuleSpec",
+    "BuildResult",
+    "UploadResult",
+    "list_boards",
+    "list_modules",
+    "get_board",
+    "get_module",
+    # Runtime half
+    "Board",
+    "Event",
+    "Action",
+    "SerialTransport",
+    "MockTransport",
+    "discover_ports",
+    "NoBoardFoundError",
+    # Errors
+    "AtechError",
+    "BuildError",
+    "CatalogError",
+    "PlacementError",
+    "UploadError",
+    "__version__",
+]

atech/build.py

@@ -0,0 +1,82 @@
+"""PlatformIO build wrapper.
+
+Shells out to ``pio run`` in the given project directory. Captures the build
+artifact path on success and surfaces logs on failure.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from atech.errors import BuildError
+
+
+@dataclass
+class BuildResult:
+    """Outcome of a PlatformIO build."""
+
+    project_dir: Path
+    success: bool
+    firmware_path: Optional[Path]
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+def _pio_executable() -> str:
+    exe = shutil.which("pio") or shutil.which("platformio")
+    if not exe:
+        raise BuildError(
+            "PlatformIO CLI not found on PATH.\n"
+            "\n"
+            "PlatformIO is bundled with `atech` — installing the SDK installs it too,\n"
+            "so this usually means atech was installed into a different environment\n"
+            "than the one you're running from. Fixes, in order of likelihood:\n"
+            "  1. Activate the venv where you installed atech, then retry.\n"
+            "  2. Reinstall into the current environment:  pip install --force-reinstall atech\n"
+            "  3. Install PlatformIO directly:             pip install platformio\n"
+            "\n"
+            "Verify with:  python -c \"import platformio; print(platformio.__version__)\""
+        )
+    return exe
+
+
+def run_build(project_dir: Path, *, capture: bool = True) -> BuildResult:
+    """Run ``pio run`` in ``project_dir`` and return the result."""
+    project_dir = Path(project_dir).expanduser().resolve()
+    if not (project_dir / "platformio.ini").is_file():
+        raise BuildError(
+            f"no platformio.ini at {project_dir}. Run Project.generate() first."
+        )
+
+    cmd = [_pio_executable(), "run", "-d", str(project_dir)]
+    proc = subprocess.run(
+        cmd,
+        capture_output=capture,
+        text=True,
+    )
+    firmware = _locate_firmware(project_dir) if proc.returncode == 0 else None
+    return BuildResult(
+        project_dir=project_dir,
+        success=proc.returncode == 0,
+        firmware_path=firmware,
+        stdout=proc.stdout or "",
+        stderr=proc.stderr or "",
+        returncode=proc.returncode,
+    )
+
+
+def _locate_firmware(project_dir: Path) -> Optional[Path]:
+    """Find the firmware.bin PlatformIO emitted, if any."""
+    build_root = project_dir / ".pio" / "build"
+    if not build_root.is_dir():
+        return None
+    for env_dir in build_root.iterdir():
+        candidate = env_dir / "firmware.bin"
+        if candidate.is_file():
+            return candidate
+    return None

atech/catalog/__init__.py

@@ -0,0 +1,43 @@
+"""Bundled catalog of Atech boards and modules."""
+
+from atech.catalog.loader import (
+    get_board,
+    get_module,
+    iter_module_files,
+    list_boards,
+    list_modules,
+    load_boards,
+    load_modules,
+    load_modules_from,
+    module_dir,
+)
+from atech.catalog.models import (
+    ActionDecl,
+    BoardSpec,
+    EventDecl,
+    ModuleDriver,
+    ModuleSpec,
+    ModuleTemplates,
+    Pin,
+    PortSpec,
+)
+
+__all__ = [
+    "ActionDecl",
+    "BoardSpec",
+    "EventDecl",
+    "ModuleDriver",
+    "ModuleSpec",
+    "ModuleTemplates",
+    "Pin",
+    "PortSpec",
+    "get_board",
+    "get_module",
+    "iter_module_files",
+    "list_boards",
+    "list_modules",
+    "load_boards",
+    "load_modules",
+    "load_modules_from",
+    "module_dir",
+]

atech/catalog/data/boards/14port.yaml

@@ -0,0 +1,181 @@
+# Atech 14-Port motherboard
+#
+# Portrait board with three columns of slots. Left column (ports 1-6) and
+# right column (ports 9-14) run top→bottom; a single isolated slot (port 7)
+# sits top-middle. The Reset button (port 12) and USB-C jack (port 8) are
+# reserved and break adjacency in their columns.
+#
+# Sourced from backend/motherboard/board.yaml (14port_board).
+
+id: 14port
+name: "Atech 14-Port Board"
+
+microcontroller:
+  type: esp32
+  variant: ESP32-S3
+  flash_size_kb: 8192
+  ram_size_kb: 512
+
+platformio_env: esp32-s3-devkitc-1
+platformio_framework: arduino
+
+# Reserved port ids that exist on the layout but cannot host a module.
+reserved:
+  - port_8       # USB-C jack (bottom-middle)
+  - port_12      # Reset button (right column)
+
+# 2D physical layout (matches the frontend renderer). Numbers are slot ids
+# (one-based), "" is a physical gap, text labels are reserved positions.
+# Portrait orientation: port_7 is top-middle, USB-C (port_8) is bottom-middle.
+layout:
+  - ["9", "10", "11", "Restart", "13", "14"]   # right column, top→bottom
+  - ["7", "",   "",   "",        "",   "USB-C"] # middle: 7 top, USB-C bottom
+  - ["1", "2",  "3",  "4",       "5",  "6"]     # left column, top→bottom
+
+notes: |
+  12 module slots in 3 columns: left (1-6), middle (just port_7), right
+  (9-14). Top edge ports: 1, 7, 9. Bottom edge ports: 6, 14. Corners:
+  top-left=port_1, top-right=port_9, bottom-left=port_6, bottom-right=port_14.
+  Port_7 is isolated in the middle column with NO adjacent slots — ideal for
+  a single central component (main display, primary sensor, IMU). For
+  4-wheeled vehicles, place motors at the four corner ports. Double-width
+  modules (size=2) must use one adjacent pair: left side [1,2], [2,3], [3,4],
+  [4,5], [5,6]; right side [9,10], [10,11], [13,14]. The Reset button at
+  port_12 breaks adjacency between ports 11 and 13.
+
+ports:
+  - id: port_1
+    name: "Port 1"
+    type: universal
+    slot_number: 1
+    side: left
+    pins:
+      - {gpio: 9, function: signal}
+      - {gpio: 8, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_2
+    name: "Port 2"
+    type: universal
+    slot_number: 2
+    side: left
+    pins:
+      - {gpio: 5, function: signal}
+      - {gpio: 4, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_3
+    name: "Port 3"
+    type: universal
+    slot_number: 3
+    side: left
+    pins:
+      - {gpio: 17, function: signal}
+      - {gpio: 18, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, uart]
+
+  - id: port_4
+    name: "Port 4"
+    type: universal
+    slot_number: 4
+    side: left
+    pins:
+      - {gpio: 16, function: signal}
+      - {gpio: 15, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, uart]
+
+  - id: port_5
+    name: "Port 5"
+    type: universal
+    slot_number: 5
+    side: left
+    pins:
+      - {gpio: 11, function: signal}
+      - {gpio: 10, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_6
+    name: "Port 6"
+    type: universal
+    slot_number: 6
+    side: left
+    pins:
+      - {gpio: 13, function: signal}
+      - {gpio: 12, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_7
+    name: "Port 7"
+    type: universal
+    slot_number: 7
+    side: top
+    pins:
+      - {gpio: 6, function: signal}
+      - {gpio: 7, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  # Port 8 reserved for USB-C (bottom-middle, not a module slot)
+
+  - id: port_9
+    name: "Port 9"
+    type: universal
+    slot_number: 9
+    side: right
+    pins:
+      - {gpio: 40, function: signal}
+      - {gpio: 41, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio]
+
+  - id: port_10
+    name: "Port 10"
+    type: universal
+    slot_number: 10
+    side: right
+    pins:
+      - {gpio: 1, function: signal}
+      - {gpio: 2, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_11
+    name: "Port 11"
+    type: universal
+    slot_number: 11
+    side: right
+    pins:
+      - {gpio: 43, function: signal}
+      - {gpio: 44, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio]
+
+  # Port 12 reserved for Reset button (right column, not a module slot)
+
+  - id: port_13
+    name: "Port 13"
+    type: universal
+    slot_number: 13
+    side: right
+    pins:
+      - {gpio: 39, function: signal}
+      - {gpio: 38, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio]
+
+  - id: port_14
+    name: "Port 14"
+    type: universal
+    slot_number: 14
+    side: right
+    pins:
+      - {gpio: 36, function: signal}
+      - {gpio: 35, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio]
+
+adjacent_port_pairs:
+  # Left column (vertically adjacent)
+  - ["port_1", "port_2"]
+  - ["port_2", "port_3"]
+  - ["port_3", "port_4"]
+  - ["port_4", "port_5"]
+  - ["port_5", "port_6"]
+  # Right column (vertically adjacent, skipping Reset at port_12)
+  - ["port_9", "port_10"]
+  - ["port_10", "port_11"]
+  - ["port_13", "port_14"]

atech/catalog/data/boards/8port.yaml

@@ -0,0 +1,103 @@
+# Atech 8-Port motherboard
+#
+# Two rows of port columns flanking a reserved Restart button (port 6) and
+# USB-C jack (port 8). Six general-purpose module slots: 1-5 and 7. Double-
+# width modules can span [1,2] or [3,4]; the gap below row 2 separates the
+# pairs, and Restart/USB-C make 5-7 non-adjacent.
+#
+# Sourced from backend/motherboard/board.yaml (8port_board).
+
+id: 8port
+name: "Atech 8-Port Board"
+
+microcontroller:
+  type: esp32
+  variant: ESP32-S3
+  flash_size_kb: 8192
+  ram_size_kb: 512
+
+platformio_env: esp32-s3-devkitc-1
+platformio_framework: arduino
+
+# Reserved port ids that exist on the layout but cannot host a module.
+reserved:
+  - port_6
+  - port_8
+
+# 2D physical layout (matches the frontend renderer). Numbers are slot ids
+# (one-based), "" is a physical gap, text labels are reserved positions.
+layout:
+  - ["1", "2", "", "3", "4"]
+  - ["5", "Restart", "", "7", "USB-C"]
+
+notes: |
+  6 module slots arranged as right column (1, 2, 3, 4) and left column (5, 7).
+  Two adjacent pairs for double-width modules: [1,2] and [3,4]. Port 5 and
+  port 7 are NOT adjacent — the Restart button at port 6 and the USB-C jack
+  at port 8 break that column. Corners (useful for vehicle motor placement):
+  top-left=port_5, top-right=port_1, bottom-left=port_7, bottom-right=port_4.
+
+ports:
+  - id: port_1
+    name: "Port 1"
+    type: universal
+    slot_number: 1
+    side: right
+    pins:
+      - {gpio: 5,  function: signal}
+      - {gpio: 4,  function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_2
+    name: "Port 2"
+    type: universal
+    slot_number: 2
+    side: right
+    pins:
+      - {gpio: 7,  function: signal}
+      - {gpio: 6,  function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_3
+    name: "Port 3"
+    type: universal
+    slot_number: 3
+    side: right
+    pins:
+      - {gpio: 9,  function: signal}
+      - {gpio: 10, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog]
+
+  - id: port_4
+    name: "Port 4"
+    type: universal
+    slot_number: 4
+    side: right
+    pins:
+      - {gpio: 1,  function: signal}
+      - {gpio: 2,  function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio]
+
+  - id: port_5
+    name: "Port 5"
+    type: universal
+    slot_number: 5
+    side: left
+    pins:
+      - {gpio: 43, function: signal}
+      - {gpio: 44, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio]
+
+  - id: port_7
+    name: "Port 7"
+    type: universal
+    slot_number: 7
+    side: left
+    pins:
+      - {gpio: 15, function: signal}
+      - {gpio: 16, function: signal_b}
+    compatible_interfaces: [i2c, digital, gpio, analog, uart]
+
+adjacent_port_pairs:
+  - ["port_1", "port_2"]
+  - ["port_3", "port_4"]

atech/catalog/data/modules/aht20/aht20.cpp

@@ -0,0 +1,131 @@
+/**
+ * @file aht20.cpp
+ * @brief AHT20 Temperature & Humidity Sensor implementation for Athera
+ *
+ * Background FreeRTOS task triggers measurements every ~2s.
+ * Public methods return cached values for non-blocking access.
+ */
+
+#include "aht20.h"
+#include <Arduino.h>
+
+static void measureTaskTrampoline(void* param) {
+    ((AHT20*)param)->_measureTaskLoop();
+}
+
+AHT20::AHT20(I2CInterface* i2c, uint8_t address)
+    : _i2c(i2c)
+    , _address(address)
+    , _measureTask(nullptr)
+    , _temperature(0)
+    , _humidity(0)
+{
+}
+
+bool AHT20::begin() {
+    // Wait for sensor power-on
+    vTaskDelay(pdMS_TO_TICKS(100));
+
+    if (!isConnected()) {
+        Serial.println("AHT20 not responding!");
+        return false;
+    }
+
+    // Check calibration status and init if needed
+    if (!_initCalibration()) {
+        Serial.println("AHT20 calibration failed!");
+        return false;
+    }
+
+    // Start background measurement task on Core 0
+    xTaskCreatePinnedToCore(
+        measureTaskTrampoline,
+        "AHT20",
+        2048,
+        this,
+        1,       // Lower priority than IMU
+        &_measureTask,
+        0
+    );
+
+    Serial.println("AHT20 initialized");
+    return true;
+}
+
+float AHT20::readTemperature() { return _temperature; }
+float AHT20::readHumidity() { return _humidity; }
+
+bool AHT20::isConnected() {
+    _i2c->beginTransmission(_address);
+    return _i2c->endTransmission() == 0;
+}
+
+// ========== Background task ==========
+
+void AHT20::_measureTaskLoop() {
+    // Initial delay to let sensor settle
+    vTaskDelay(pdMS_TO_TICKS(500));
+
+    while (true) {
+        if (_triggerMeasurement()) {
+            vTaskDelay(pdMS_TO_TICKS(80));  // Measurement takes ~75ms
+            _readMeasurement();
+        }
+        vTaskDelay(pdMS_TO_TICKS(2000));  // Measure every ~2s
+    }
+}
+
+// ========== Private methods ==========
+
+bool AHT20::_initCalibration() {
+    // Read status byte
+    if (_i2c->requestFrom(_address, (size_t)1) < 1) return false;
+    uint8_t status = _i2c->read();
+
+    // If not calibrated (bit 3), send init command
+    if (!(status & 0x08)) {
+        _i2c->beginTransmission(_address);
+        _i2c->write((uint8_t)0xBE);
+        _i2c->write((uint8_t)0x08);
+        _i2c->write((uint8_t)0x00);
+        if (_i2c->endTransmission() != 0) return false;
+        vTaskDelay(pdMS_TO_TICKS(10));
+    }
+
+    return true;
+}
+
+bool AHT20::_triggerMeasurement() {
+    _i2c->beginTransmission(_address);
+    _i2c->write((uint8_t)0xAC);
+    _i2c->write((uint8_t)0x33);
+    _i2c->write((uint8_t)0x00);
+    return _i2c->endTransmission() == 0;
+}
+
+bool AHT20::_readMeasurement() {
+    if (_i2c->requestFrom(_address, (size_t)7) < 7) return false;
+
+    uint8_t data[7];
+    for (int i = 0; i < 7; i++) {
+        data[i] = _i2c->read();
+    }
+
+    // Check busy bit
+    if (data[0] & 0x80) return false;
+
+    // Humidity: data[1], data[2], upper 4 bits of data[3]
+    uint32_t humRaw = ((uint32_t)data[1] << 12) |
+                      ((uint32_t)data[2] << 4) |
+                      ((uint32_t)data[3] >> 4);
+
+    // Temperature: lower 4 bits of data[3], data[4], data[5]
+    uint32_t tempRaw = (((uint32_t)data[3] & 0x0F) << 16) |
+                       ((uint32_t)data[4] << 8) |
+                       (uint32_t)data[5];
+
+    _humidity = (humRaw / 1048576.0f) * 100.0f;
+    _temperature = (tempRaw / 1048576.0f) * 200.0f - 50.0f;
+
+    return true;
+}

atech/catalog/data/modules/aht20/aht20.h

@@ -0,0 +1,71 @@
+/**
+ * @file aht20.h
+ * @brief AHT20 Temperature & Humidity Sensor for Athera
+ *
+ * Integrated temperature and humidity sensor with I2C interface.
+ * Uses a background FreeRTOS task to periodically trigger measurements
+ * and cache results — public getters return cached values instantly.
+ *
+ * Specifications:
+ * - Temperature: -40 to +125°C
+ * - Humidity: 0-100% RH
+ * - Interface: I2C (400kHz)
+ * - Address: 0x38
+ * - Measurement time: ~75ms
+ *
+ * Athera Connector:
+ * - Line A: SDA
+ * - Line B: SCL
+ */
+
+#ifndef AHT20_MODULE_H
+#define AHT20_MODULE_H
+
+#include <i2c_interface.h>
+#include "i2c_hardware.h"   // exposes WireI2C so generated globals can construct a bus
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+class AHT20 {
+public:
+    static constexpr uint8_t ADDR_DEFAULT = 0x38;
+
+    /**
+     * @brief Construct AHT20 sensor
+     * @param i2c Pointer to I2C interface
+     * @param address I2C address (default 0x38)
+     */
+    AHT20(I2CInterface* i2c, uint8_t address = ADDR_DEFAULT);
+
+    /**
+     * @brief Initialize sensor and start background measurement task
+     * @return true on success
+     */
+    bool begin();
+
+    /** @brief Read cached temperature in Celsius */
+    float readTemperature();
+
+    /** @brief Read cached relative humidity in %RH */
+    float readHumidity();
+
+    /** @brief Check if sensor is responding */
+    bool isConnected();
+
+    // Background task function (public for static callback, do not call directly)
+    void _measureTaskLoop();
+
+private:
+    I2CInterface* _i2c;
+    uint8_t _address;
+    TaskHandle_t _measureTask;
+
+    volatile float _temperature;
+    volatile float _humidity;
+
+    bool _initCalibration();
+    bool _triggerMeasurement();
+    bool _readMeasurement();
+};
+
+#endif // AHT20_MODULE_H