Musique Robot: a FIP radio stations player

# Musique Robot - Executive Summary

**Project:** Internet Radio with Physical Interface  
**Platform:** Raspberry Pi Zero 2 W + Pimoroni Pirate Audio HAT  
**Status:** ✅ Production Ready  
**Completion Date:** January 23, 2026

---

## Overview

The Musique Robot is a dedicated FIP Radio player featuring:
- **Physical button controls** for instant station switching (4 Presets)
- **1.3" color display** showing realtime track information and album art
- **Web interface** for full control and station browsing
- **Auto-start functionality** - works immediately on power-up via system services

---

## Key Features

### Instant Station Access
Four dedicated buttons provide one-touch access to favorite FIP stations:
- **Button A** → FIP Nationale
- **Button B** → FIP Groove
- **Button X** → FIP Pop
- **Button Y** → FIP Jazz

### Rich Visual Experience
- **Realtime Metadata:** Displays Song Title, Artist, and Album via active Radio France API integration.
- **Album Artwork:** High-resolution cover art fetched dynamically and injected into the display driver.
- **Hardware Integration:** 240x240 IPS Color Display (ST7789).

### Robust Architecture
- **Systemd Services:** Application starts automatically at boot and auto-restarts on failure.
- **Headless Operation:** Designed to run 24/7 without user intervention.
- **Iris Web Interface:** Full remote control available at `http://musiquerobot.local:6680/iris`.

---

## Technical Achievements

### System Architecture
- **Mopidy:** Core music server (v3.4.2)
- **Custom Button Daemon:** Dedicated Python service (`musique-buttons`) replacing standard GPIO handlers for superior responsiveness.
- **Custom Metadata Plugin:** `mopidy-radiofrance` extension rewritten to use modern GraphQL API, solving previous data fetch issues.

### Complex Solutions Implemented
1.  **Radio France Integration (GraphQL):**
    - Migrated from deprecated REST API to GraphQL.
    - Implemented robust polling loop with rate-limit handling.
    - Added Album Art injection feature to bridge Mopidy Core and Display Driver.

2.  **Hardware Button Optimization:**
    - Diagnosed and fixed "broken button" issue (was software configuration).
    - Mapped all 4 buttons (A, B, X, Y) to distinct stations.
    - Implementation migrated from manual scripts to a production-grade Systemd service.

---

## System Specifications

**Hardware:**
- Raspberry Pi Zero 2 W
- Pimoroni Pirate Audio HAT
- ST7789 1.3" Display
- Custom 3D Printed Case ([Source Model](https://makerworld.com/en/models/981581-pirate-audio-line-out-pi-case))

**Software Stack:**
- Raspberry Pi OS
- Mopidy 3.4.2
- Python 3.11
- Custom Plugins: `mopidy-radiofrance`
- Background Services: `mopidy`, `musique-buttons`

---

## Project Deliverables

### Documentation
1.  **Project_Blueprint_MR.md** - As-Built technical configuration
2.  **USER_GUIDE.md** - Daily usage instructions
3.  **BUTTON_GUIDE.md** - Button mapping and troubleshooting
4.  **radio_france_api_integration.md** - API technical details
5.  **SYSTEM_SUMMARY.md** - File structure overview

### Codebase
- **musique_robot_buttons.py** - Production GPIO handler
- **mopidy_radiofrance/** - Custom API Plugin source code
- **mopidy.conf** - Optimized configuration

---

## Conclusion

The Musique Robot has graduated from a prototype to a polished, production-ready device. All hardware features are fully utilized, including the previously dormant Button Y. The software stack is robust, self-healing, and provides a premium user experience with rich metadata and album art.

**The device is ready for daily use.** 🎵 📻

---

## Development Methodology: Agentic Workflow

This project was developed using **Google Antigravity**, an advanced agentic coding system.

*   **Agent Role (Google Antigravity):** Autonomous execution of all software engineering tasks, including:
    *   Reverse-engineering the Radio France GraphQL API.
    *   Developing custom Mopidy plugins (`mopidy-radiofrance`).
    *   Writing and deploying production system services (`musique-buttons`).
    *   Debugging remote hardware via SSH.
    *   Generating comprehensive documentation.
*   **Human Role:**
    *   High-level intent definition and feature requests.
    *   Hardware provisioning and network configuration.
    *   Physical assembly (3D printed case).
    *   User Acceptance Testing (UAT) of physical buttons and display.

---

## Message from the Human: 
I just love FIP radio stations, they play the best music on this stupid planet, so I made a dedicated device.