Arduino Uno Q Knowledge Base

A hobbyist attempt to create documentation and examples for the Arduino Uno Q, specifically structured for use with LLM-powered code editors like Cursor. This is a work in progress and not official documentation.

🎯 Overview

The Arduino Uno Q is a powerful dual-processor development board that combines:

• MPU (Microprocessor): Qualcomm Dragonwing™ QRB2210 running Debian Linux
• MCU (Microcontroller): STM32U585 running Zephyr RTOS

This repository provides:

• 📚 Documentation - Hardware specs, programming guides, API references (work in progress)
• 💻 Code examples - Working examples for both MCU and MPU
• 🚀 Deployment tools - Command-line scripts for easy deployment
• 🧩 Arduino Bricks - Examples using pre-built containerized components
• 🎨 Working projects - Example applications that demonstrate concepts

✨ Key Features

Hardware Capabilities

• Dual-Processor Architecture: MPU for complex computing, MCU for real-time control
• Connectivity: Wi-Fi 5, Bluetooth 5.1
• Interfaces: I2C/I3C, SPI, UART, CAN, PWM, ADC
• Onboard Features: 8×13 LED matrix, 4× RGB LEDs, Qwiic connector

Software Development

• MCU Programming: Arduino sketches with real-time capabilities
• MPU Programming: Python applications on Debian Linux
• Bridge RPC: Seamless communication between MPU and MCU
• Arduino Bricks: Modular, containerized application components
• Command-Line Tools: Full CLI deployment workflow (no GUI required)

🚀 Quick Start

Prerequisites

1. Arduino Uno Q board
2. Arduino CLI installed:

   curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

3. ADB (Android Debug Bridge) for MPU communication:

   # Linux
   sudo apt-get install adb
   
   # macOS
   brew install android-platform-tools
   
   # Windows - Download from Android Developer site

Example 1: LED Control & Text Display

A complete working example demonstrating:

• Web-based LED control
• LED matrix text display with scrolling animation
• Heart symbol animation
• Non-blocking RPC communication

Deploy in 3 steps:

# 1. Navigate to example
cd knowledge-base/Example-1

# 2. Deploy the application
arduino-app-cli app start /home/arduino/example1

# 3. Access web interface
# Set up port forwarding
adb forward tcp:7000 tcp:7000

# Open browser
open http://localhost:7000

See Example-1 README for detailed instructions.

📖 Documentation Structure

knowledge-base/
├── 01-getting-started/     # Setup guides and first programs
├── 02-hardware/            # Hardware specs, pinout, peripherals
├── 03-software-development/ # Programming guides, libraries, bricks
├── 04-deployment/          # Deployment methods and debugging
├── 05-examples/            # Code examples and templates
├── 06-reference/           # API docs, pin reference, troubleshooting
└── Example-1/              # Complete working example project

📚 Essential Reading

• Getting Started Guide - Set up your development environment
• MCU Programming - Arduino sketches for the MCU
• MPU Programming - Python applications for the MPU
• Bridge RPC Communication - MPU-MCU communication
• CLI Deployment - Command-line deployment guide
• LED Matrix Guide - Display text and graphics

💡 Example Projects

Example 1: LED Control & Text Display

Location: knowledge-base/Example-1/

A complete web-based application featuring:

• ✅ Web UI for LED control
• ✅ LED matrix text scrolling
• ✅ Heart symbol animation
• ✅ Non-blocking animations
• ✅ Docker-based deployment

Features:

• Real-time LED control via web interface
• Scrolling text display on 8×13 LED matrix
• Smooth animations with state machine
• Clear button to reset display
• Works entirely from command line

More Examples

Browse the knowledge-base/05-examples/ directory for:

• Basic sketches (blink, analog read, PWM)
• Sensor examples (temperature, I2C)
• Communication examples (RPC, HTTP)
• Arduino Bricks examples
• AI/ML examples

🛠️ Development Workflow

1. MCU Development (Arduino Sketches)

#include <Arduino_RouterBridge.h>

void setup() {
    Bridge.begin();
    Bridge.provide("myFunction", myFunction);
}

void loop() {
    // Bridge.update() handled automatically
    delay(10);
}

2. MPU Development (Python)

from arduino.app_utils import Bridge
from arduino.app_bricks.web_ui import WebUI

# Call MCU function
result = Bridge.call("myFunction", arg1, arg2)

# Create web UI
ui = WebUI()
App.run()

3. Deployment

# Deploy using arduino-app-cli
arduino-app-cli app start /path/to/app

# Or use Docker Compose
docker-compose up -d

🔧 Tools & Technologies

Development Tools

• Arduino CLI - Compile and upload sketches
• Arduino App CLI - Deploy full applications
• ADB - File transfer and port forwarding
• Docker - Containerized applications (Arduino Bricks)

Programming Languages

• C++ (Arduino) - MCU sketches
• Python 3 - MPU applications
• JavaScript - Web interfaces
• YAML - Configuration files

Key Libraries

• Arduino_RouterBridge - MCU-side RPC communication
• arduino.app_utils - MPU-side Bridge client
• Arduino Bricks - Pre-built containerized components

📦 Arduino Bricks

Arduino Bricks are modular, pre-built Docker containers that provide common functionality:

• WebUI Brick - Web interface framework
• HTTP Server Brick - HTTP server capabilities
• MQTT Brick - MQTT client/server
• Database Brick - Database connectivity

See Bricks Catalog for complete list.

🤖 LLM-Powered Editor Integration

This knowledge base is specifically structured for use with LLM-powered code editors like Cursor:

• Structured Documentation - Organized in a way that's easy for AI to parse and understand
• Code Examples - Working examples that can serve as templates
• LLM Context File - llm-context.md provides project context for AI assistants
• Clear Patterns - Consistent code structure and naming conventions

Using with Cursor

1. Open this repository in Cursor
2. The AI assistant can reference the knowledge base when answering questions
3. Use examples as starting points for new projects
4. The structured format helps AI understand the Arduino Uno Q development workflow

Note: This is a hobbyist project. Always refer to official Arduino documentation for authoritative information.

🗂️ Project Structure

.
├── README.md                    # This file
├── llm-context.md              # AI assistant context file
└── knowledge-base/             # Main documentation
    ├── README.md               # Knowledge base overview
    ├── 01-getting-started/     # Getting started guides
    ├── 02-hardware/            # Hardware documentation
    ├── 03-software-development/ # Software guides
    ├── 04-deployment/          # Deployment guides
    ├── 05-examples/            # Code examples
    ├── 06-reference/           # API references
    └── Example-1/              # Complete example project
        ├── mcu/                # MCU code (Arduino sketch)
        ├── mpu/                # MPU code (Python)
        ├── assets/             # Web UI files
        ├── app.yaml            # App configuration
        └── sketch.yaml         # MCU build configuration

🔗 Resources

Official Documentation

• Arduino Uno Q Product Page
• Hardware Documentation
• User Manual
• Arduino Programming Docs

Community

• Arduino Forum
• Arduino Support

🐛 Troubleshooting

Common issues and solutions:

• Port forwarding: Use adb forward tcp:7000 tcp:7000 to access web servers
• RPC timeouts: Ensure functions are non-blocking or return quickly
• LED matrix not working: Use matrixBegin() and matrixWrite() from Arduino framework
• Deployment errors: Check /Data/Local/Tmp directory exists on Arduino

See Troubleshooting Guide for more.

📝 Contributing

Contributions are welcome! This knowledge base aims to be comprehensive and up-to-date.

1. Review existing documentation
2. Test examples before suggesting changes
3. Follow the existing documentation structure
4. Update relevant sections when adding new features

📄 License & Disclaimer

This knowledge base is a hobbyist project provided as-is for educational and development purposes.

Important:

• This is not official Arduino documentation
• Always refer to Arduino's official documentation for authoritative information
• Examples and documentation may contain errors or become outdated
• Use at your own risk

The goal is to create documentation that works well with LLM-powered editors, but it's a work in progress.

🙏 Acknowledgments

• Arduino team for the Uno Q platform and official documentation
• Community contributors and examples
• Inspired by Donn Felker's llm-context.md approach

⚠️ Disclaimer

This is a hobbyist project created to help with LLM-powered development. It is:

• Not affiliated with or endorsed by Arduino
• Not a replacement for official documentation
• A work in progress that may contain errors
• Intended for learning and experimentation

Always verify information against official Arduino documentation.

📞 Support

• 📖 Check the Knowledge Base
• 🐛 See Troubleshooting Guide
• 💬 Arduino Forum
• 📧 Arduino Support

---

A hobbyist project made with ❤️ for experimenting with LLM-powered development on Arduino Uno Q

This is not official documentation. Always refer to Arduino's official docs for production use.

Last updated: 2025