# SmartPi Agentic Assistant

An LLM-Powered, Expandable Raspberry Pi Pico W Personal Assistant with 64×64 LED Matrix Display

![SmartPi Assistant](https://fab.cba.mit.edu/classes/863.25/people/SrikanthNadhamuni/final/index.html)

## Overview

The **SmartPi Agentic Assistant** is a compact, low-power personal assistant that transforms your digital information overload into actionable insights. It uses **large language models (LLMs)** to process emails, calendar events, weather data, and Slack messages, then displays them as concise, prioritized messages on a beautiful 64×64 RGB LED matrix.

### Key Features

- 🎨 **64×64 RGB LED Display** - Vibrant, high-resolution matrix with themed color schemes
- 📡 **WiFi Connectivity** - Raspberry Pi Pico W with built-in wireless
- 🧠 **LLM Integration** - Google Gemini processes and summarizes your data
- 🔄 **Message Queue** - Intelligent rotation with priority handling
- 🎵 **Audio Alerts** - I²S amplifier with speaker for notifications
- 🔌 **MCP Protocol** - Model Context Protocol for extensible agent integration
- 📊 **n8n Workflows** - Automated data aggregation and processing
- 🛠️ **Modular Design** - Easy to expand with additional sensors and features

## System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Cloud / n8n                             │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐       │
│  │  Calendar   │  │   Gmail     │  │   Weather    │       │
│  │    API      │  │    API      │  │     API      │       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬───────┘       │
│         │                 │                 │               │
│         └─────────────────┼─────────────────┘               │
│                           │                                 │
│                  ┌────────▼─────────┐                       │
│                  │  Google Gemini   │                       │
│                  │  LLM Processing  │                       │
│                  └────────┬─────────┘                       │
│                           │                                 │
│                  ┌────────▼─────────┐                       │
│                  │  n8n Workflow    │                       │
│                  └────────┬─────────┘                       │
└───────────────────────────┼─────────────────────────────────┘
                            │ HTTP/MCP
┌───────────────────────────▼─────────────────────────────────┐
│                   Local Network                              │
│                  ┌────────────────┐                          │
│                  │  MCP Bridge    │                          │
│                  │     Server     │                          │
│                  │   (Python)     │                          │
│                  └────────┬───────┘                          │
│                           │ HTTP                             │
│                  ┌────────▼───────┐                          │
│                  │   SmartPi      │                          │
│                  │   Pico W       │                          │
│                  │  (CircuitPy)   │                          │
│                  └────────┬───────┘                          │
│                           │                                  │
│                  ┌────────▼───────┐                          │
│                  │  64×64 LED     │                          │
│                  │    Matrix      │                          │
│                  └────────────────┘                          │
└──────────────────────────────────────────────────────────────┘
```

## Quick Start

### Prerequisites

- Raspberry Pi Pico W
- 64×64 RGB LED Matrix (P2, HUB75 interface)
- SmartPi PCB (custom design included)
- 5V 4A power supply
- Computer with Python 3.8+

### 1. Hardware Assembly

See [hardware/mechanical/assembly/ASSEMBLY_GUIDE.md](hardware/mechanical/assembly/ASSEMBLY_GUIDE.md) for detailed instructions.

Quick steps:
1. Fabricate or order the SmartPi PCB
2. Solder components
3. Connect LED matrix via HUB75 cable
4. Wire audio subsystem (MAX98357 + speaker)
5. Connect power supply

### 2. Firmware Installation

See [docs/SETUP.md](docs/SETUP.md) for complete setup instructions.

```bash
# 1. Install CircuitPython on Pico W
# 2. Copy firmware files to CIRCUITPY drive
cp firmware/main.py /Volumes/CIRCUITPY/
cp firmware/message_queue.py /Volumes/CIRCUITPY/
cp firmware/wifi_config.py /Volumes/CIRCUITPY/

# 3. Configure WiFi
cp firmware/secrets.py.template firmware/secrets.py
# Edit secrets.py with your WiFi credentials

# 4. Upload to Pico W
cp firmware/secrets.py /Volumes/CIRCUITPY/
```

### 3. Bridge Server Setup

```bash
cd bridge/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure
cp env.template .env
# Edit .env with your SmartPi IP address

# Run server
python smartpi_mcp_server.py
```

### 4. n8n Workflow

1. Import workflow from `n8n/input-processing-n8n-workflow-original.json`
2. Configure credentials (Google Calendar, Gmail, Gemini API)
3. Add extension nodes (see `n8n/README.md`)
4. Update HTTP Request node with bridge URL
5. Execute workflow

## Project Structure

```
smartpi/
├── firmware/                 # CircuitPython code for Pico W
│   ├── main.py              # Main firmware with WiFi & HTTP server
│   ├── message_queue.py     # Message queue handler
│   ├── wifi_config.py       # WiFi connection manager
│   └── secrets.py.template  # WiFi credentials template
├── bridge/                  # MCP Bridge Server
│   ├── smartpi_mcp_server.py   # FastAPI MCP server
│   ├── requirements.txt     # Python dependencies
│   ├── config.yaml          # Server configuration
│   └── README.md            # Bridge documentation
├── n8n/                     # n8n workflow files
│   └── README.md            # Workflow setup guide
├── hardware/                # Hardware design files
│   ├── pcb/                # PCB designs (Eagle, Gerber)
│   ├── enclosure/          # 3D models (Fusion 360, STL)
│   ├── bom/                # Bill of Materials
│   └── README.md           # Hardware documentation
├── tests/                   # Test scripts
│   ├── test_bridge.py      # Bridge server tests
│   └── test_pico_endpoint.py # Device endpoint tests
├── docs/                    # Documentation
│   ├── SETUP.md            # Complete setup guide
│   ├── API.md              # API documentation
│   └── DEPLOYMENT.md       # Deployment instructions
└── README.md               # This file
```

## Documentation

- **[Setup Guide](docs/SETUP.md)** - Complete hardware and software setup
- **[API Documentation](docs/API.md)** - All endpoints and data formats
- **[Deployment Guide](docs/DEPLOYMENT.md)** - Production deployment strategies
- **[Hardware Guide](hardware/README.md)** - PCB design, BOM, and assembly
- **[Assembly Guide](hardware/mechanical/assembly/ASSEMBLY_GUIDE.md)** - Step-by-step hardware assembly
- **[Bridge README](bridge/README.md)** - MCP bridge server setup
- **[n8n README](n8n/README.md)** - Workflow integration guide
- **[Testing README](tests/README.md)** - Test scripts and validation

## Features

### Display Themes

Each message type has a dedicated color theme:

| Theme | Use Case | Colors |
|-------|----------|--------|
| 📅 Calendar | Events & meetings | Orange/Purple |
| 📧 Email | Important messages | Blue |
| 🌤️ Weather | Weather updates | Cyan/Teal |
| 💬 Slack | Team notifications | Purple/Cyan |
| ⚪ Neutral | System messages | Gray |

### Message Priority

Messages are automatically sorted by priority:

- 🔴 **Urgent** - Time-sensitive items (displayed first)
- 🟠 **Important** - Significant updates
- ⚪ **Normal** - Standard information

### Intelligent Features

- **Word Wrapping** - Automatic text fitting for 64×64 display
- **Queue Management** - Up to 50 messages with rotation
- **WiFi Resilience** - Auto-reconnect on connection loss
- **Audio Alerts** - Theme-specific notification sounds
- **Real-time Updates** - Push-based message delivery

## Technology Stack

### Hardware
- **Raspberry Pi Pico W** - RP2040 dual-core + WiFi
- **64×64 RGB LED Matrix** - P2 2mm pitch, HUB75 interface
- **MAX98357 I²S Amplifier** - Digital audio output
- **Custom PCB** - Interface board (designed in EAGLE/Fusion 360)

### Firmware
- **CircuitPython** - Python on microcontrollers
- **adafruit_rgbmatrix** - LED matrix driver
- **adafruit_httpserver** - Lightweight HTTP server
- **WiFi & SocketPool** - Network connectivity

### Software
- **Python + FastAPI** - MCP bridge server
- **n8n** - Workflow automation
- **Google Gemini** - LLM text processing
- **MCP Protocol** - Model Context Protocol

### Cloud Services
- **Google Calendar API** - Event aggregation
- **Gmail API** - Email summaries
- **OpenWeatherMap API** - Weather data (optional)
- **Slack API** - Team notifications (future)

## Testing

Run automated tests to verify system components:

```bash
# Test bridge server
python tests/test_bridge.py

# Test SmartPi device
python tests/test_pico_endpoint.py 10.0.0.230
```

See [tests/README.md](tests/README.md) for detailed testing instructions.

## API Endpoints

### SmartPi Device (Pico W)

- **POST /messages** - Receive message batch
- **GET /status** - Get device status
- **POST /clear** - Clear message queue

### MCP Bridge Server

- **POST /mcp** - MCP tool invocation
- **POST /push** - Direct message push
- **GET /health** - Health check
- **GET /.well-known/mcp.json** - MCP manifest

See [docs/API.md](docs/API.md) for complete API reference.

## Examples

### Send Message via Bridge

```bash
curl -X POST http://localhost:5055/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "push_messages",
    "args": {
      "messages": [
        {
          "text": "Meeting in 30 minutes!",
          "theme": "calendar",
          "priority": "urgent"
        }
      ]
    }
  }'
```

### Direct Device Push

```bash
curl -X POST http://10.0.0.230:5000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"text": "Hello SmartPi!", "theme": "neutral", "priority": "normal"}
    ]
  }'
```

### Check Device Status

```bash
curl http://10.0.0.230:5000/status
```

## Future Enhancements (Phase 2)

- 🎤 **Voice Commands** - ICS-43434 I²S MEMS microphone integration
- 🌐 **Web Dashboard** - Browser-based message control
- 📱 **Mobile App** - iOS/Android companion app
- 🔔 **Custom Alerts** - User-defined notification rules
- 📊 **Analytics** - Message statistics and insights
- 🔗 **MQTT Support** - Alternative to HTTP for IoT integration
- 👥 **Multi-Device** - Broadcast to multiple SmartPi units

## Contributing

This is an open-source project. Contributions are welcome!

### Areas for Contribution

- Hardware improvements (PCB v2, enclosure designs)
- Firmware enhancements (new features, optimization)
- Additional n8n workflow integrations
- Documentation improvements
- Testing and bug reports

## License

- **Software** (firmware, bridge, workflows): MIT License
- **Hardware** (PCB, enclosure): CERN OHL-P v2 / CC BY-SA 4.0
- **Documentation**: CC BY-SA 4.0

You are free to use, modify, and distribute this project. Attribution appreciated!

## Credits

**Project**: SmartPi Agentic Assistant  
**Author**: Srikanth Nadhamuni  
**Course**: MAS.863 - How to Make (Almost) Anything  
**Institution**: MIT Center for Bits and Atoms  
**Year**: 2025

### Acknowledgments

- Neil Gershenfeld and the MIT CBA team
- Adafruit for excellent CircuitPython libraries
- n8n community for workflow automation tools
- RGB Matrix community for HUB75 documentation

## Resources

### Project Links

- **Project Website**: [fab.cba.mit.edu/classes/863.25/people/SrikanthNadhamuni/final](https://fab.cba.mit.edu/classes/863.25/people/SrikanthNadhamuni/final/index.html)
- **Documentation**: See `docs/` directory
- **Hardware Files**: See `hardware/` directory

### External Resources

- [CircuitPython Documentation](https://circuitpython.org/)
- [Raspberry Pi Pico W](https://www.raspberrypi.com/products/raspberry-pi-pico/)
- [HUB75 Protocol](https://github.com/hzeller/rpi-rgb-led-matrix)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [n8n Workflow Automation](https://n8n.io/)

## Support

For questions, issues, or suggestions:

1. Check the documentation in `docs/`
2. Review hardware guides in `hardware/`
3. Run test scripts in `tests/`
4. Check serial console logs (Pico W)
5. Review bridge server logs

## Version History

- **v1.0.0** (2025-11) - Initial release
  - WiFi-enabled Pico W firmware
  - MCP bridge server
  - n8n workflow integration
  - Complete documentation

---

**Built with ❤️ at MIT Center for Bits and Atoms**

© 2025 Srikanth Nadhamuni — MAS.863 Final Project