Apri la confezione del Divoom Times Gate, lo colleghi alla corrente e guardi cinque schermi LCD illuminarsi con quotazioni azionarie, previsioni meteo e animazioni pixel art predefinite. L'app funziona bene. Ma continui a chiederti: posso inviare i miei dati a quegli schermi? Posso scrivere uno script che visualizzi una dashboard personalizzata sullo schermo tre, lasciando l'orologio attivo sullo schermo uno?
La risposta breve è sì, ma non nel modo che potresti aspettarti. Divoom non ha pubblicato una documentazione API ufficiale per Times Gate. La community degli sviluppatori ha invece effettuato il reverse engineering dell'API di rete locale del dispositivo, ha creato librerie in Python, Rust e C# e lo ha integrato in piattaforme come Home Assistant. Questa guida spiega come comunica effettivamente Times Gate, cosa può fare la sua API LAN locale e quali strumenti ti permetteranno di iniziare a sviluppare più rapidamente.
La guida ufficiale alla configurazione di Times Gate sul canale YouTube di Divoom.
Come Times Gate comunica con la tua rete
Prima di scrivere una sola riga di codice, devi capire una cosa che mette in difficoltà quasi ogni sviluppatore la prima volta: Times Gate non espone un'API locale appena lo accendi. Quando il dispositivo si avvia, si connette ai server cloud di Divoom utilizzando MQTT per la messaggistica in tempo reale e HTTPS per la sincronizzazione dei dati. Solo dopo il completamento di questo handshake iniziale con il cloud l'endpoint HTTP locale diventa disponibile sulla tua rete.
Questa architettura è diversa da quella del Pixoo-64, che funziona come un dispositivo locale più semplice. Se hai già utilizzato l'API REST del Pixoo-64 (illustrata nella nostra guida per principianti all'API del Pixoo-64), aspettati una curva di apprendimento più ripida con Times Gate. La dipendenza dal cloud significa che durante la configurazione ti serve una connessione Wi-Fi attiva con accesso a Internet, e l'API locale scomparirà se il dispositivo perde il collegamento al cloud.
Perché è importante? Perché influenza ogni decisione su come controllare il dispositivo. Se stai creando una dashboard per la casa intelligente che deve continuare a funzionare anche in caso di interruzione della connessione a Internet, ti servirà una strategia di fallback. Se invece esegui semplicemente script dalla tua scrivania, l'handshake con il cloud è una configurazione una tantum e in seguito l'API locale funziona senza problemi.
Times Gate non è un dispositivo a schermo singolo con un'API aggiunta in un secondo momento. È una dashboard a cinque schermi che, di fatto, è completamente programmabile, una volta capito come comunicare con essa.
L'API LAN locale: cosa puoi controllare direttamente
Una volta che Times Gate è connesso al Wi-Fi e ha completato il suo handshake con il cloud, espone un'API HTTP sulla rete locale. Gli sviluppatori della community hanno mappato le funzionalità principali attraverso la sperimentazione e il reverse engineering. Ecco cosa puoi effettivamente fare con quell'endpoint:
- Cambiare i canali degli schermi — indicare a ciascuno dei cinque schermi di visualizzare un canale diverso (orologio, meteo, ticker azionario, statistiche social, arte pixel personalizzata).
- Inviare pixel art personalizzata — inviare dati grezzi dei pixel a uno schermo specifico, così da poter visualizzare qualsiasi contenuto che rientri in una griglia di 128×128.
- Controllare luminosità e volume — regolare programmaticamente l'intensità del display e l'uscita audio.
- Interrogare lo stato del dispositivo — leggere lo stato attuale di ogni schermo, i canali attivi e le informazioni sulla connessione.
L'API comunica tramite HTTP standard, il che significa che puoi utilizzarla da qualsiasi linguaggio in grado di effettuare una richiesta di rete: Python, JavaScript, Rust, Go e persino uno script shell con curl. Per le richieste locali non sono necessari token di autenticazione o chiavi API; il dispositivo si fida di qualsiasi richiesta proveniente dalla stessa rete locale.
Un sviluppatore nella community Divoom su Reddit ha posto la stessa domanda che si pongono molti nuovi proprietari di Times Gate: "Mi interessa controllarlo programmaticamente invece di usare soltanto l'app mobile. Qualcuno sa se esiste un'API?" La discussione ha rivelato che l'API locale, sebbene completamente non documentata da Divoom, è tutt'altro che abbandonata e risponde regolarmente.
Consiglio per la configurazione
Prima di iniziare a scrivere le chiamate API, assicurati che Times Gate sia connesso alla stessa rete Wi-Fi del tuo computer di sviluppo e che abbia completato l'avvio (gli schermi dovrebbero mostrare dati in tempo reale, non uno stato di caricamento). Se l'endpoint API locale non risponde, riavvia il dispositivo e verifica che abbia accesso a Internet.
Invio di widget personalizzati su cinque schermi
È qui che Times Gate diventa interessante. A differenza di un display a pixel con un solo schermo, hai a disposizione cinque griglie indipendenti da 128×128. Questo significa che puoi creare una vera dashboard desktop: prezzi delle azioni in tempo reale sullo schermo uno, grafici delle criptovalute sullo schermo due, un widget meteo sullo schermo tre, il numero di iscritti al tuo canale YouTube sullo schermo quattro e un'animazione personalizzata di pixel art sullo schermo cinque.
Il processo per inviare contenuti personalizzati segue lo stesso schema, indipendentemente dallo schermo scelto. Esegui il rendering dei dati in un bitmap di 128×128 pixel, codificalo nel formato previsto dall'API (in genere RGB grezzo o una variante compressa) e invialo tramite una richiesta HTTP POST all'endpoint locale, specificando l'indice dello schermo. Il dispositivo aggiorna immediatamente la visualizzazione.
Per le implementazioni pratiche, la maggior parte degli sviluppatori elabora i propri dati lato server utilizzando una libreria grafica leggera — Pillow di Python è una scelta comune — e poi invia il bitmap risultante a Times Gate a intervalli regolari. Un semplice script Python che recupera i prezzi delle azioni da un'API gratuita, li mostra come testo e mini-grafico su una tela di 128×128 pixel e invia il risultato allo schermo uno ogni 60 secondi è un progetto che puoi realizzare in un pomeriggio.
L'illuminazione ambientale a doppio bordo, con 12 effetti RGB personalizzabili, è accessibile anche tramite API, sebbene il supporto della community per il controllo programmatico dell'illuminazione sia ancora in fase di sviluppo rispetto agli endpoint per il controllo dello schermo.
Strumenti della community per lo sviluppo di Times Gate
Non è necessario creare tutto da zero. La community di sviluppatori che ruota attorno ai dispositivi Divoom ha prodotto diverse librerie e strumenti che integrano l'API HTTP grezza in qualcosa di più pratico. Se hai già usato l'API di Pixoo-64, alcuni di questi strumenti ti saranno familiari: diversi sono stati sviluppati originariamente per Pixoo e successivamente estesi per supportare gli endpoint di Times Gate.
| Strumento | Linguaggio | Cosa fa | Ideale per |
|---|---|---|---|
| pixoo-rest | Python (server REST) | Esegue un server REST locale che integra le API HTTP Divoom; supporta il disegno di pixel, linee, rettangoli e testo, oltre al download automatico delle immagini | Sviluppatori che desiderano un livello middleware REST tra la propria app e il dispositivo |
| divoom-cli | Rust | Strumento e libreria da riga di comando; include il rilevamento dei dispositivi LAN, il cambio di canale e l'invio diretto di pixel grezzi | Sviluppatori Rust e chiunque preferisca gli script da riga di comando alla scrittura di un server |
| Divoom.Api | C# / .NET | Libreria .NET che integra le API dei dispositivi Divoom; originariamente sviluppata per i dispositivi Timebox | Sviluppatori C# nell'ecosistema .NET |
| divoom-gateway | Gateway REST (interfaccia Swagger UI) | Gateway API REST indipendente con specifica OpenAPI e interfaccia Swagger; racchiude le API HTTP Divoom grezze per qualsiasi linguaggio | I team che desiderano un livello API documentato e indipendente dal linguaggio, con un’interfaccia di esplorazione integrata |
Ogni strumento adotta un approccio diverso. Pixoo-rest è il punto di partenza più popolare per gli sviluppatori Python perché gestisce i dettagli del protocollo e offre endpoint chiari come /api/draw/text oppure /api/draw/rectangle. Il divoom-cli basato su Rust è eccellente se vuoi un binario compilato da chiamare dagli script shell o dai processi cron. Divoom.Api copre l’ambito .NET. E divoom-gateway è la scelta giusta se stai creando qualcosa in più linguaggi e vuoi una documentazione Swagger pronta all’uso.
L’ecosistema Rust merita una menzione speciale perché il progetto pixoo-rest e il crate Rust divoom includono entrambi un’API per la ricerca dei dispositivi: chiami una funzione e trova ogni dispositivo Divoom sulla tua LAN. È davvero utile quando hai più display o quando l’indirizzo IP del dispositivo cambia dopo il riavvio del router.
Integrazione di Home Assistant
Se utilizzi Home Assistant, non devi scrivere un’applicazione personalizzata per controllare il Times Gate. L’API HTTP locale è direttamente accessibile tramite l’integrazione dei comandi REST di Home Assistant, il che significa che puoi inviare chiamate API come parte di qualsiasi automazione.
La configurazione è semplice. Definisci un comando REST nel tuo configuration.yaml che punti all’indirizzo IP locale del Times Gate e all’endpoint API che vuoi chiamare. Poi attivi quel comando da qualsiasi automazione: la pressione di un pulsante, un trigger temporale, una modifica dello stato di un altro sensore o un comando vocale. La discussione della community di Home Assistant sui dispositivi Divoom include esempi funzionanti di configurazioni di comandi REST che cambiano i canali dello schermo, inviano immagini personalizzate e regolano la luminosità in base ai sensori di luce ambientale.
Le idee pratiche di automazione realizzate dai proprietari di Times Gate con Home Assistant includono il passaggio di tutti e cinque gli schermi a un orologio in “modalità concentrazione” quando avvia un timer Pomodoro, la visualizzazione degli avvisi meteo quando scatta un’allerta temporali, la visualizzazione di una notifica del campanello con un’animazione pixel personalizzata quando qualcuno suona e la rotazione delle statistiche dei social media ogni pochi minuti durante una diretta streaming.
Un aspetto da tenere presente: poiché Times Gate necessita della connessione iniziale al cloud prima che l’API locale sia disponibile, dovresti aggiungere alla tua automazione di Home Assistant una condizione che verifichi se il dispositivo risponde prima di inviargli comandi. Un semplice controllo tramite ping evita l’accumulo di messaggi di errore nei log in caso di interruzione della connessione Internet.
Cosa non può ancora fare l’API
Essere onesti sui limiti fa parte di una buona guida per sviluppatori. L’API della community di Times Gate è potente, ma presenta vincoli concreti che dovresti conoscere prima di costruirci attorno un sistema destinato alla produzione.
Primo, non esiste una documentazione API ufficiale. Tutto ciò che la community sa deriva dal reverse engineering, il che significa che l’API potrebbe cambiare con un aggiornamento del firmware senza preavviso. Se costruisci qualcosa di critico basandoti sull’API locale, prepara un piano di riserva, anche se consiste semplicemente nel verificare che i tuoi script funzionino ancora dopo ogni aggiornamento del firmware.
Secondo, la dipendenza dal cloud è un requisito imprescindibile. Un utente del subreddit Home Assistant lo ha scoperto a proprie spese quando ha provato a usare il suo dispositivo Divoom in una VLAN isolata senza accesso a Internet. L’API REST semplicemente non rispondeva finché non consentiva al dispositivo di raggiungere prima i server cloud di Divoom. Se stai pianificando una configurazione di casa intelligente completamente isolata, Times Gate potrebbe non essere il display adatto a quell’ambiente.
Terzo, il supporto degli strumenti della community specifico per Times Gate è ancora in crescita. Molte librerie sono state scritte originariamente per Pixoo-64 o Timebox e poi estese per supportare gli endpoint di Times Gate, ma non tutte le funzionalità sono state verificate su tutti i modelli di dispositivo. Se usi una libreria non progettata originariamente per Times Gate, testa ogni chiamata API singolarmente prima di farci affidamento.
Sicurezza degli aggiornamenti del firmware
Dopo ogni aggiornamento del firmware di Times Gate, esegui un test rapido dei tuoi script API prima di dare per scontato che tutto funzioni ancora. Fissa la versione del firmware se hai una pipeline di automazione stabile che non puoi permetterti di interrompere.
Domande frequenti
Times Gate dispone di un’API ufficiale?
No. Divoom non ha pubblicato una documentazione API ufficiale per Times Gate. Tuttavia, la community di sviluppatori ha sottoposto a reverse engineering l’API HTTP locale e ha creato librerie in Python, Rust e C# che rendono pratico controllare il dispositivo tramite programmi.
Posso controllare Times Gate senza una connessione Internet?
Non completamente. Times Gate richiede una connessione iniziale al cloud tramite MQTT e HTTPS prima che l'API LAN locale diventi disponibile. Una volta completata questa procedura di handshake, le chiamate all'API locale funzionano senza un accesso continuo a Internet; tuttavia, se il dispositivo si riavvia o perde alimentazione, dovrà riconnettersi ai server cloud di Divoom prima che l'API locale torni a rispondere.
Quali linguaggi di programmazione dispongono di librerie della community?
Python (pixoo-rest), Rust (divoom-cli e il crate divoom) e C# (Divoom.Api per .NET). È disponibile anche divoom-gateway, un gateway API REST autonomo con interfaccia utente Swagger, compatibile con qualsiasi linguaggio in grado di effettuare richieste HTTP.
Home Assistant supporta Times Gate?
Sì, tramite l'integrazione dei comandi REST di Home Assistant. Definisci un comando REST che punti all'endpoint dell'API locale di Times Gate e attivalo da qualsiasi automazione. La community di Home Assistant offre esempi funzionanti di integrazione dei dispositivi Divoom.
Posso inviare widget personalizzati a singoli schermi?
Sì. Ciascuno dei cinque schermi LCD da 128×128 può visualizzare contenuti indipendenti. Puoi inviare pixel art, testo o dati renderizzati personalizzati a uno schermo specifico indirizzandolo tramite il parametro dell'indice dello schermo dell'API.
Come procedere
Se possiedi già un Times Gate, inizia eseguendo un semplice comando curl sull'API locale per cambiare il canale di uno schermo: sarà il tuo momento "hello world". Da lì, scegli lo strumento della community più adatto al tuo linguaggio preferito e crea un piccolo progetto: un ticker azionario, una dashboard meteo o un'animazione personalizzata per le notifiche. Times Gate premia la sperimentazione e, una volta che avrai fatto fare qualcosa di personalizzato a uno schermo, gli altri quattro seguiranno naturalmente.
Se provieni dal mondo Pixoo-64, la nostra guida per principianti all'API di Pixoo-64 illustra il modello più semplice di API REST locale utilizzato da Pixoo: un contesto utile per comprendere cosa è cambiato con l'architettura connessa al cloud di Times Gate. Per la configurazione dell'hardware e la documentazione ufficiale del prodotto, la pagina dei manuali dei prodotti Divoom contiene le guide aggiornate.
Divoom Times Gate
Cinque schermi LCD indipendenti da 128×128, connessi al Wi-Fi e completamente programmabili tramite API locali e strumenti della community. Widget integrati per azioni, criptovalute, meteo e statistiche social.
Visualizza Times Gate
