Skip to content

SPECIFICATION.MD

Latest commit

 

History

History
72 lines (44 loc) · 4.63 KB

SPECIFICATION.MD

File metadata and controls

72 lines (44 loc) · 4.63 KB
Raw

MoSy — System & File Behavioral Specification

1. Core Dispatcher (main.py)

  • Role: Orchestrates the system pipeline and enforces a strict 20 ms (50 Hz) control cycle.
  • Nominal Execution Behavior:
    1. Captures high-precision frame start time via time.perf_counter().
    2. Sequentially polls telemetry ingestion, AI policy inference, and kinematic mapping.
    3. Computes active processing time $\Delta t$. If $\Delta t < 20\text{ ms}$, suspends thread execution for time.sleep(0.020 - \Delta t) to maintain 50 Hz cycle timing.
  • Exception & Termination Handling:
    • Catches KeyboardInterrupt (Ctrl+C), safely closes the open UART serial handle via serial_reader.close(), and exits gracefully.

2. Telemetry Ingestion Pipeline (src/telemetry/)

serial_reader.py (UART Ingestion)

  • Connected Hardware: Opens pyserial connection with the HS-1 suit ESP32-C3 at 115200 baud. Operates in non-blocking mode, continuously flushing stale buffers for zero-latency frame reading.
  • Dry-Run Fallback: If the COM/serial port is missing, logs a warning and returns None without crashing.

bno055_mapper.py (Sensor Normalization)

  • Processing: Receives raw HS-1 JSON packets (shoulder, forearm, hand) and normalizes Euler angles to $[-1.0, 1.0]$. Populates the initial slots of the 112-dimensional state vector np.ndarray(shape=(1, 112)).
  • Resilience: Defaults missing segment values to 0.0 to preserve vector shape.

3. AI Inference Core (src/ai_core/onnx_engine.py)

  • Execution Profile: Loads models/mosy_policy.onnx via onnxruntime. Ingests [1, 112] state vectors and outputs an 8-joint action array [1, 8] bounded within $[-1.0, 1.0]$ in $< 0.1\text{ ms}$.

4. Kinematics & Actuation (src/kinematics/)

servo_mapper.py (Action Translator)

  • Reads joint bounds, direction flags, and offsets from config/joints.json. Scales target actions to angular displacement, applies inversions/offsets, and converts angles to microsecond PWM pulse durations ($500,\mu\text{s} \dots 2500,\mu\text{s}$).

pca9685_driver.py (I2C Servo Controller)

  • Hardware Mode: Sends 12-bit PWM register values ($0 \dots 4095$) over I2C (0x40) to PCA9685.
  • Dry-Run Mode: Catches missing I2C interface faults and bypasses physical writes, allowing headless simulation.

MoSy: Core Motion Control System Overview

MoSy (Motion Synthesis Engine) acts as the central intelligence and primary control system for the entire hardware-software pipeline. Rather than executing logic directly on the robot, all neural policy inference, telemetry translation, and kinematic calculations are offloaded to MoSy running on the host machine.

  ┌─────────────────────────┐         ┌─────────────────────────────────┐         ┌─────────────────────────┐
  │  HS-1 Suit (ESP32-C3)   │  UART   │      MoSy Engine (Host PC)     │   I2C   │    PCA9685 Driver Board │
  │                         ├────────►│                                 ├────────►│                         │
  │  "The Eyes"             │  JSON   │  "The Brain"                    │   PWM   │  "The Actuators"        │
  │  Streams orientation    │         │  Runs 50 Hz AI Policy Loop      │         │  Drives 8x Servos       │
  └─────────────────────────┘         └─────────────────────────────────┘         └─────────────────────────┘

Key Responsibilities

  • Central Control Dispatcher: Functions as the operational hub, executing a tight 50 Hz ($20\text{ ms}$) loop that synchronizes telemetry input with hardware actuation.
  • Telemetry Interpreter: Ingests raw orientation payloads (shoulder, forearm, hand) sent from the HS-1 suit and normalizes them into a 112-dimensional state vector tensor [1, 112].
  • Neural Policy Engine: Processes the state vector through a compiled ONNX reinforcement learning policy (<0.1 ms execution latency) to compute optimal joint action values [1, 8].
  • Kinematic Actuation Command: Translates abstract action values into calibrated microsecond PWM pulse durations ($500,\mu\text{s} \dots 2500,\mu\text{s}$) based on config/joints.json and dispatches raw 12-bit register commands directly to the PCA9685 servo driver via I2C.