DigiRadio/Software/APP/igiRadio/Documentation/PROJECT_ANALYSIS.md

PROJECT_ANALYSIS — DigiRadio (fonte: documentazione firmware)

Data analisi: 2026-08-18
Fonte primaria: Software/docs/manual/ (non modificata)
Firmware di riferimento: 0.8.5+

---

1. Documenti analizzati

File	Contenuto
ch-intro.tex	Introduzione prodotto
ch-hardware.tex	PCB, pinout, catena audio
ch-firmware.tex	Architettura firmware ESP32-S3
ch-si4684.tex	Tuner FM/DAB, tune, seek, RDS, DLS
ch-adau1701.tex	DSP SigmaStudio, mixer, EQ, safeload
ch-bt1035.tex	Modulo BT classic A2DP (UART AT), I2S da ADAU
ch-sigmastudio.tex	Design SigmaStudio
ch-api.tex	HTTP REST API (protocollo app)
ch-classes.tex	Classi firmware
ch-build.tex	Build/flash
ch-licensing.tex	Licenze

Documentazione aggiuntiva letta: Software/CLAUDE.md, Software/docs/security-flash-nvs.md, BleProvisioning.cpp.

---

2. Distinzione critica: BLE vs controllo

Controllo dispositivo (tuner, audio, preset, BT config)

Trasporto documentato: HTTP JSON REST su TCP porta 80 (Wi‑Fi).

• Setup mode: SoftAP DigiRadio-<suffix> → http://192.168.4.1/
• STA mode: stessa API su IP LAN o mDNS digiradio-<suffix>.local
• NON esiste un protocollo GATT proprietario documentato per tuner/audio/preset.

BLE (ESP32-S3 onboard)

Solo provisioning Wi‑Fi in setup mode (ch-api.tex §BLE provisioning):

• Stack: ESP-IDF wifi_provisioning + scheme_ble
• Sicurezza: Security1 (protocomm)
• Proof of possession (PoP): serial number dispositivo (stesso valore di GET /api/health → serialNumber)
• Nome servizio BLE: SSID SoftAP = DigiRadio-<suffix> (es. DigiRadio-CC4DB4)
• Su successo: credenziali salvate in NVS, reboot in STA
• Non è un endpoint HTTP — nessuna REST call

Bluetooth Audio (streaming verso speaker esterno)

Modulo separato FSC-BT1035 (classic BR/EDR A2DP), controllato dal firmware via UART AT, esposto all'app solo tramite HTTP /api/bluetooth/*.

L'iPhone non si collega in A2DP al DigiRadio per ascoltare: il DigiRadio invia audio al Bose/Speaker via BT1035.

---

3. Architettura hardware (sintesi)

Si4684 (SPI) ──I2S──► ADAU1701 (I2S master 48 kHz) ──I2S──► BT1035 ──A2DP──► Speaker
ESP32-S3 (Wi‑Fi/BLE, HTTP server, opz. I2S test)

Sorgenti audio nel DSP: Si4684 (radio), ESP32 I2S (stream locale / phone push).

---

4. Endpoint HTTP documentati (controllo app)

Metodo	Path	Funzione
GET	/api/health	Stato, fw, serial, chip boot
POST	/api/wifi	Provisioning STA (reboot)
POST	/api/wifi/scan	Scan reti vicine
GET	/api/tuner/status	Stato tuner FM/DAB
GET	/api/tuner/services	Lista servizi DAB
POST	/api/tuner/tune	Sintonia FM/DAB
POST	/api/tuner/play	Play servizio DAB
POST	/api/tuner/seek	Seek FM up/down
POST	/api/tuner/scan	Scan singola stazione
POST	/api/tuner/scan/full	Scan completo banda FM
GET/PUT	/api/audio/profile	Profilo mixer/EQ/master
POST	/api/audio/reset	Reset profilo factory
POST	/api/audio/stereo-enhance	Enhancement stereo 0–100
POST	/api/audio/bass-enhance	Enhancement bass 0–100
POST	/api/audio/beep	Beep diagnostico ADAU
GET	/api/dsp/params	Tabella parametri SigmaStudio
PUT	/api/dsp/param	Scrittura cella raw (live)
POST	/api/dsp/program	Upload blob DSP (reboot)
POST	/api/system/ota	OTA firmware ESP32 (reboot)
GET/POST	/api/streaming	Web radio MP3 URL
PUT	/api/stream/phone	Push PCM stereo 48 kHz da phone
GET	/api/bluetooth/status	Stato BT1035
POST	/api/bluetooth/pair	Modalità discoverable
POST	/api/bluetooth/pair/stop	Esci pairing
POST	/api/bluetooth/disconnect	Disconnect A2DP
GET	/api/bluetooth/paired	Lista paired
POST	/api/bluetooth/scan	Scan speaker vicini
POST	/api/bluetooth/connect	Connect A2DP + opz. save
GET/POST/DELETE	/api/bluetooth/speaker	Speaker default
POST	/api/bluetooth/reconnect	Reconnect manuale
POST	/api/bluetooth/auto-reconnect	Retry count 0–15
GET	/api/stations	Lista preset
POST	/api/stations	Aggiungi preset
POST	/api/stations/remove	Rimuovi preset
POST	/api/stations/reorder	Riordina preset
POST	/api/stations/tune	Richiama preset

---

5. Funzionalità per schermata app

Area	Supportato (documentato)	Note
Connessione Wi‑Fi	✅	BLE prov. + SoftAP + POST /api/wifi
FM tune/seek/scan	✅	RSSI, SNR, RDS PS/RT
DAB tune/play/services	✅	DLS, ensemble, service list
Preset	✅	CRUD + reorder + recall
Volume/mixer/EQ	✅	Via audio profile
DSP raw params	✅	Escape hatch tecnico
BT speaker pairing	✅	Via HTTP → BT1035 AT
OTA firmware	✅	POST /api/system/ota
OTA DSP	✅	POST /api/dsp/program
Phone audio stream	✅	PUT /api/stream/phone
Web radio stream	✅	POST /api/streaming
Artwork album	❌	UNKNOWN — non in API
Batteria dispositivo	❌	Alimentato da rete
AUX/USB come sorgente UI	❌	Non esposto in API
Notifiche push BLE stato	❌	Nessun GATT documentato

---

6. Implicazioni per igiRadio

1. DigiRadioService → implementazione HTTP REST (URLSession), non GATT custom.
2. BLE layer → solo Wi‑Fi provisioning (ESP protocomm Security1 + PoP = serial).
3. MockDigiRadioService → stessa interfaccia, dati fittizi.
4. Discovery → mDNS .local, IP manuale, o join SoftAP in setup.
5. Real-time → polling selettivo su /api/tuner/status quando in radio; nessuna notifica BLE documentata.

---

7. UNKNOWN — specification required

Voce	Motivo
UUID GATT controllo tuner/audio	Non documentati — controllo è HTTP
Artwork/metadata streaming	Non in API tuner
Protocol version field	Solo fw in health
Hardware revision API	Solo serialNumber + chip flags