OpenQQuantify - Multi-Agent Arduino Project Generator

OpenQQuantify is a multi-agent LLM system that automatically generates complete Arduino projects from natural language descriptions. The system breaks down hardware project creation into 4 specialized agents that work in sequence.

🤖 What Each Agent Does

Agent 1 - Bill of Materials (BOM) Generator

Purpose: Converts natural language project descriptions into detailed component lists

• Input: Plain English project description ("Build a greenhouse monitor...")
• Output: JSON with components, quantities, descriptions, and initial pin assignments
• AI Focus: Component selection, compatibility checking, quantity estimation

Agent 2 - Wiring Specification Generator

Purpose: Creates detailed wiring diagrams and pin connections

• Input: Component list from Agent 1
• Output: JSON with precise pin-to-pin connections and wiring specifications
• AI Focus: Pin mapping, electrical compatibility, connection validation

Agent 3 - Code Generator

Purpose: Generates Arduino IDE-compatible code for the project

• Input: Wiring specification from Agent 2
• Output: Complete Arduino sketch with libraries, setup, and main loop
• AI Focus: Code synthesis, library integration, hardware abstraction

Agent 4 - Build Guide Generator

Purpose: Creates step-by-step assembly and programming instructions

• Input: Wiring spec from Agent 2 + Code from Agent 3
• Output: Human-readable build guide with assembly steps and troubleshooting
• AI Focus: Technical writing, safety considerations, testing procedures

🚀 Quick Start

Option 1: Web Interface (Recommended)

1. Start the Flask server:

   python flask_app.py

2. Open your browser to http://localhost:5000

3. Use the visual interface:

   • Enter your project description in the test area
   • Click "Run Full Pipeline" to execute all agents in sequence
   • View results for each agent (BOM, Wiring, Code, Build Guide)
   • Use the visual workflow editor to connect data sources and APIs

Option 2: Command Line Interface

Setup

python -m venv venv
venv\Scripts\activate  # Windows
# or: source venv/bin/activate  # macOS/Linux

pip install -e .

Run Individual Agents

Agent 1 - Generate BOM:

openq-agent1 "Build a soil-moisture monitor with OLED display using Arduino Mega 2560" \
             -o outputs/agent1/soil.json

Agent 2 - Generate Wiring:

openq-agent2 -i outputs/agent1/soil.json \
             -o outputs/agent2/soil_wiring.json

Agent 3 - Generate Code:

openq-agent3 -i outputs/agent2/soil_wiring.json \
             -o outputs/agent3/soil_code.json

Agent 4 - Generate Build Guide:

openq-agent4 -i outputs/agent2/soil_wiring.json \
             -c outputs/agent3/soil_code.json \
             -o outputs/agent4/soil_steps.json

🎯 Example: Greenhouse Monitor Project

Input Description

"Build an Arduino Mega 2560 greenhouse monitor that reads temperature, humidity and light, logs data to a local SQLite DB, and blinks an LED when humidity < 30%."

Agent 1 Output (BOM)

{
  "components": [
    {"component_name": "Arduino Mega 2560", "quantity": 1},
    {"component_name": "DHT22", "description": "Temperature/humidity sensor", "quantity": 1},
    {"component_name": "BH1750", "description": "Digital light sensor", "quantity": 1},
    {"component_name": "LED", "quantity": 1},
    {"component_name": "Resistor 220Ω", "quantity": 1}
  ]
}

Agent 2 Output (Wiring)

{
  "connections": [
    {"from_": ["DHT22", "DATA"], "to": ["Arduino Mega 2560", "D2"]},
    {"from_": ["BH1750", "SDA"], "to": ["Arduino Mega 2560", "D20"]},
    {"from_": ["LED", "anode"], "to": ["Arduino Mega 2560", "D13"]}
  ]
}

Agent 3 Output (Code)

{
  "code_blocks": [{
    "component": "Arduino Mega 2560",
    "code": "#include <DHT.h>\n#include <BH1750.h>\n\nvoid setup() {\n  // Initialization code\n}\n\nvoid loop() {\n  // Main program logic\n}"
  }]
}

Agent 4 Output (Build Guide)

{
  "assembly_steps": [
    {"step": 1, "title": "Gather Materials", "instructions": "Collect all components..."},
    {"step": 2, "title": "Wire Sensors", "instructions": "Connect DHT22 to pin D2..."}
  ],
  "testing_procedures": [...],
  "troubleshooting": {...}
}

🔧 Web Interface Features

Visual Workflow Designer

• Drag and drop agent boxes to design your workflow
• Connect purple lines between agents to show data flow
• Configure data sources: Add component databases, APIs, custom code
• Real-time status: See each agent's progress during execution

Configuration Boxes

• Data Ingestion: Connect component databases and specifications
• APIs: Integrate external services (pin mappings, documentation)
• Custom Code: Add code templates and custom logic

Interactive Results

• Expandable sections for each agent output
• JSON formatting with syntax highlighting
• Error handling with detailed debugging information
• Export capabilities for generated projects

📁 Project Structure

OpenQQuantify/
├── agents/arduino/          # Core agent implementations
│   ├── agent1arduino.py    # BOM Generator
│   ├── agent2arduino.py    # Wiring Spec Generator  
│   ├── agent3arduino.py    # Code Generator
│   └── agent4arduino.py    # Build Guide Generator
├── templates/               # Web interface
│   └── agent_orchestration.html
├── utils/                   # Shared utilities
│   └── logging_config.py    # Centralized logging
├── outputs/                 # Generated project files
│   ├── agent1/             # BOM outputs
│   ├── agent2/             # Wiring outputs
│   ├── agent3/             # Code outputs
│   └── agent4/             # Build guide outputs
├── flask_app.py            # Web server
└── README.md

⚙️ Configuration

Environment Setup

Create a .env file with your OpenAI API key:

OPENAI_API_KEY=sk-your-api-key-here

Supported Arduino Boards

• Arduino Nano
• Arduino Mega 2560
• ESP32 (coming soon)
• Raspberry Pi Pico (coming soon)

🐛 Troubleshooting

Common Issues

1. Agent2 validation errors: Usually caused by software components (databases) being included in wiring
2. Missing libraries: Ensure all Arduino libraries are installed in your IDE
3. Pin conflicts: Check that pins aren't being used by multiple components

Debug Mode

Enable verbose logging by setting the logging level:

# In your script or web interface
logging.basicConfig(level=logging.DEBUG)

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Resources

• Arduino IDE Download
• Arduino Pin Reference
• OpenAI API Documentation

---

Ready to build your next Arduino project? 🚀

• Start with the web interface at http://localhost:5000
• Or jump into the CLI with openq-agent1 "your project description"