Local Development & Testing

Complete guide to developing Fabrica code on your local machine using VS Code

Before You Start

✓ Visual Studio Code installed
✓ Raspberry Pi Pico 2W with MicroPython
✓ USB cable for connecting Pico to computer
✓ Git installed (optional, for cloning repository)

Step 1: Get the Source Code

Option A: Clone from GitHub (Recommended)

If you have Git installed, clone the repository to your local machine:

git clone https://github.com/aiandrobotics/buildair-ai.git
cd buildair-ai/app/projects/cloth-folding-robot/code

This method allows you to pull updates easily with git pull

Option B: Download from GitHub

If you don't have Git, download the code directly:

Visit github.com/aiandrobotics/buildair-ai
Click the green Code button → Download ZIP
Extract the ZIP file
Navigate to buildair-ai/app/projects/cloth-folding-robot/code

Option C: Use Local Workspace Files

If you have this project already downloaded, the code is located at:

app/projects/cloth-folding-robot/code/

Step 2: Set Up VS Code

1. Install MicroPico Extension

The MicroPico extension (by Paul Ober) provides the best development experience for Raspberry Pi Pico:

Open VS Code
Press Ctrl+Shift+X (or Cmd+Shift+X on Mac)
Search for "MicroPico"
Click Install on the extension by Paul Ober

💡 Features: Auto-completion, code upload, device control, REPL terminal

2. Open the Fabrica Workspace

The Fabrica code includes a pre-configured VS Code workspace file:

In VS Code, go to File → Open Workspace from File...
Navigate to the code directory and select fabrica.code-workspace
Click Open

✓ The workspace file contains recommended settings and extensions for Fabrica development

3. Connect Your Pico

Connect Raspberry Pi Pico 2W to your computer via USB
Wait for the device to be recognized
In VS Code, click the MicroPico icon in the bottom status bar
Select your Pico from the device list (usually shows as "/dev/ttyACM0" on Linux or "COM3" on Windows)

⚠️ If the Pico doesn't appear, make sure MicroPython is installed and the cable supports data transfer (not power-only)

Step 3: Understanding the Code Structure

fabrica/
├── main.py                    # Entry point - runs on boot
├── config.py                  # Configuration (edit for your setup)
├── button.py                  # Button polling & LED blinking
├── servo_controller.py        # PCA9685 PWM driver control
├── motion_plan_executor.py    # Sequential step execution
├── motion_plan_storage.py     # JSON persistence
├── config_mode.py             # Record new sequences
├── logger.py                  # Debug logging system
├── Readme.md                  # Comprehensive documentation
└── fabrica.code-workspace     # VS Code workspace config

File	Purpose	Customize?
main.py	Initializes hardware, runs event loop	No
config.py	Pin assignments, PWM values, default sequences	Yes
button.py	Button polling, short/long press detection	No
servo_controller.py	PCA9685 I2C communication, parallel execution	No
motion_plan_executor.py	Execute sequential steps with parallel motors	No
motion_plan_storage.py	Save/load sequences from flash memory	No
config_mode.py	Interactive button-based programming	Rarely
logger.py	Centralized debug output control	No

Step 4: Upload Code to Pico

Method 1: MicroPico Upload All

Right-click the Explorer pane in VS Code
Select MicroPico → Upload project to Pico
Confirm upload when prompted
Wait for all 8 files to transfer

✓ Fastest method - uploads all files at once maintaining directory structure

Method 2: Individual File Upload

Open any Python file in VS Code
Right-click in the editor
Select Upload current file to Pico
Repeat for all 8 .py files

💡 Useful for testing single-file changes without re-uploading everything

Step 5: Running Code on the Pico

Option A: Run from VS Code

Open main.py in the editor
Right-click → Run current file on Pico
Watch the output in the Terminal panel

=== Robotic Folding Board System ===
Version: 1.0.0 (Build: 2025-12-30)
Starting initialization...
I2C devices found: ['0x40']
Servo controller initialized at 0x40, 50 Hz
Initializing servos to home position (0°)...
Loaded 4 motion plans
System ready. Waiting for button press...

Option B: Standalone Mode (Auto-Run on Boot)

Once uploaded, main.py will automatically run when the Pico powers on:

Disconnect USB from computer
Connect Pico to external 5V power supply
System boots automatically and waits for button press

💡 No computer needed after initial upload - perfect for deployment

Step 6: Debugging Techniques

1. Use the REPL (Interactive Python)

MicroPico provides a REPL terminal for interactive testing:

Click Terminal → New Terminal in VS Code
Select MicroPico REPL
Test code interactively:

>>> import config
>>> print(config.BUTTON_PINS)
[2, 3, 4, 5]
>>> from machine import Pin
>>> led = Pin(6, Pin.OUT)
>>> led.toggle()  # Test LED

2. Enable Detailed Logging

In config.py, ensure logging is enabled:

ENABLE_LOGGING = True # Set to True for debug output

Watch the Terminal for detailed information about button presses, I2C operations, and servo movements.

3. Common Issues & Solutions

Issue	Likely Cause	Solution
PCA9685 not found	I2C wiring or address	Check SDA/SCL connections; verify address 0x40
Button not responding	Debounce or wiring	Verify GP2-GP5 to GND; check BUTTON_DEBOUNCE_MS
Servos not moving	Power supply	Ensure 5V external power connected to PCA9685
Import errors	Files not uploaded	Re-upload all .py files to Pico root directory
Sequence not saving	Flash memory issue	Check logs; ensure motion_plans.json is writable

4. Monitor I2C Communication

The code includes automatic I2C retry logic. Watch for retry messages in the logs:

WARNING: I2C write failed for channel 0 (attempt 1/3): OSError
INFO: I2C write succeeded on retry 1 for channel 0

Occasional retries are normal. Persistent failures indicate wiring problems.

💡 Development Best Practices

1. Version Control: Use Git to track changes. Commit working configurations before making modifications.
2. Backup config.py: Save a copy of your working config.py before tweaking servo calibration.
3. Test incrementally: Upload and test one change at a time rather than multiple changes simultaneously.
4. Use logging: Keep ENABLE_LOGGING = True during development. Disable only for production deployment.
5. Document customizations: Add comments in config.py explaining your specific hardware setup.
6. Safety first: Disconnect servo power when making code changes on a live system.

✅ Development Environment Ready!

You now have a fully configured local development environment for Fabrica. You can edit code, test changes, and upload to the Pico seamlessly.

Next: Learn about Configuration to customize pin assignments, servo calibration, and motion sequences for your specific panel layout.