Software Architecture

High-level overview of Fabrica's control software structure

System Overview

The Fabrica software is built on MicroPython and follows a modular, layered architecture. It separates hardware control (servos, buttons) from the application logic (motion planning, configuration), making the system easier to maintain and extend.

+---------------------------------------------------------------+
|                      Application Layer                        |
|                         (main.py)                             |
|  - Event Loop                                                 |
|  - State Management (Normal vs Config Mode)                   |
|  - Error Handling & Logging                                   |
+---------------------------------------------------------------+
           |                            |
           v                            v
+-----------------------+    +----------------------------------+
|      Input Logic      |    |          Motion Logic            |
|     (ButtonHandler)   |    |      (MotionPlanExecutor)        |
+-----------------------+    +----------------------------------+
           |                            |
           v                            v
+-----------------------+    +----------------------------------+
|    Hardware Drivers   |    |         Device Drivers           |
|  (Machine.Pin, I2C)   |    |       (ServoController)          |
+-----------------------+    +----------------------------------+
           |                            |
           v                            v
+---------------------------------------------------------------+
|                       Physical Hardware                       |
|           (Buttons, LEDs, PCA9685, Servo Motors)              |
+---------------------------------------------------------------+

Core Components

Main Controller

main.py

The brain of the operation. It initializes the hardware, loads configuration, and enters an infinite loop to poll for button presses. It decides whether to execute a folding sequence or enter configuration mode.

Servo Controller

servo_controller.py

Abstracts the complexity of the PCA9685 PWM driver. It handles I2C communication and provides high-level methods like execute_parallel() to move multiple servos simultaneously.

Motion Executor

motion_plan_executor.py

Interprets the motion plans (lists of steps). It coordinates the timing and sequencing of folding operations, ensuring that panels move in the correct order (sequential steps) or together (parallel steps).

Config & Storage

config.py & motion_plan_storage.py

Manages system settings and persistent storage. Motion plans are saved to a JSON file, allowing users to record new sequences without reprogramming the controller.

Execution Flow

  1. 1

    Initialization

    On startup, main.py initializes the I2C bus and verifies connection to the PCA9685 board. It loads saved motion plans from motion_plans.json (or falls back to defaults in config.py).

  2. 2

    Event Loop

    The system enters a low-latency loop, polling the buttons every few milliseconds. It uses a debounce algorithm to prevent false triggers from mechanical switch noise.

  3. 3

    Action Trigger

    Short Press: Triggers MotionPlanExecutor to run the sequence associated with that button.
    Long Press (3s): Enters ConfigMode, allowing the user to record a new sequence for that button.

  4. 4

    Servo Execution

    Commands are sent via I2C to the PCA9685, which generates precise PWM signals for the servos. The ServoController manages the "Flip Up" (0° → 180°) and "Return" (180° → 10°) motion.

←
Software & Code: Configuration
Software & Code: Code Structure
→