Per anni ho avuto un Fitbit⌚ Versa 3 al polso utilizzandolo come dispositivo di self-tracking e non ho mai aperto la documentazione per sviluppatori. Non per pigrizia — per una scelta razionale. Imparare un SDK proprietario, chiuso, con strumenti specifici e un ecosistema di nicchia non sembrava un investimento sensato.

Il costo zero della curiosità

L'unico modo per liberarsi di una tentazione è cedervi.
— Oscar Wilde, Il ritratto di Dorian Gray

Il mercato degli smartwatch è dominato da Apple Watch e Wear OS. Costruirsi competenze su Fitbit OS significava studiare molto per raggiungere pochi. Poi è arrivata l'AI. E con lei, il costo di quella curiosità è crollato.

Non ho dovuto più scegliere tra "vale il tempo investito" e "voglio capire come funziona". Con Claude Code che conosce le API, genera boilerplate e mi spiega il perché degli errori, la barriera di accesso si è abbassata drasticamente.

Il Versa 3 era al mio polso da anni. Aveva fatto il suo tempo — sapevo già che presto sarei passato a un Galaxy Watch 8. Ma prima di abbandonarlo definitivamente, volevo togliermi la curiosità di sviluppare un'app.

L'idea💡era semplice: dettare una nota vocale dal polso e ritrovarla come file markdown nel mio vault Obsidian.

Fitbit nato per durare, non per crescere

Nel 2020 ho iniziato a usare uno smartwatch Fitbit⌚, il Versa 2, acquistato con l'idea di tenere sotto controllo attività fisica e salute. Mi ci sono trovato bene — abbastanza da passare, qualche anno dopo, al Versa 3. In entrambi i casi, sapevo già che stavo scegliendo un dispositivo con una sola priorità: la batteria 🔋, non le app.

Tre giorni, a volte quattro giorni — mentre il Galaxy Watch 8 muore entro sera. Per mantenere quegli standard, i dispositivi usano processori poco potenti e memoria limitata. Il che rende difficile sviluppare app che richiedano molta energia, non per scelta stilistica ma per necessità fisica.

A differenza di Wear OS — che è essenzialmente Android per wearables— o di watchOS, il sistema operativo Fitbit⌚ è sempre stato chiuso in modo atipico.

Ogni modello richiedeva adattamenti diversi. I sensori erano spesso inaccessibili alle app di terze parti. Accedere al servizio del battito cardiaco in tempo reale? Non per te sviluppatore. Un ecosistema pensato per sopravvivere ai propri standard tecnici, non per espandere il suo mercato.

Spegnimento lento

Il 14 gennaio 2021 Google ha completato l'acquisizione di Fitbit per 2,1 miliardi di dollari — un'operazione annunciata già nel novembre 2019 e rimasta in sospeso per oltre un anno sotto la lente di ingrandimento dei regolatori europei e americani, preoccupati per l'accesso di Google a enormi quantità di dati sanitari personali. Da quel momento, la traiettoria è diventata leggibile. Non è stata una morte improvvisa: è stata una serie di segnali sempre più espliciti, fino all'uscita silenziosa dei due fondatori, Eric Friedman e James Park, all'inizio del 2024.

Settembre 2022

Nel settembre del 2022 Google lancia Fitbit⌚Sense 2 e Versa 4 — i nuovi smartwatch di punta della linea — avendo già deciso internamente che quei dispositivi non avrebbero mai supportato app di terze parti. Solo watch face.

Aprile 2023

Nell'aprile 2023 chiude Fitbit Studio, l'IDE web-based che permetteva agli sviluppatori di scrivere e testare app nel browser — l'unico strumento che rendeva la piattaforma accessibile senza configurazione locale — dismesso senza rimpiazzo.

Giugno 2024

Nel giugno 2024 Google rimuove tutte le app e watch face di terze parti dalla Fitbit App Gallery per gli utenti nell'Area Economica Europea, citando il Digital Markets Act come motivazione regolatoria. Una mossa che, paradossalmente, usa la compliance normativa come copertura per un disimpegno già in atto.

Luglio 2024

A luglio Google chiude l'interfaccia web di Fitbit.com per visualizzare le metriche di salute, forzando gli utenti sull'app mobile.

Agosto 2024

Il brand sopravvive come linea di fitness tracker e band, ma i Versa e Sense — i dispositivi su cui si poteva sviluppare — non si producono più. L'SDK esiste ancora, tecnicamente. Ma sviluppare per hardware discontinuato è come imparare a programmare per il Nokia N900: affascinante come esercizio, inutile come investimento.

Google ha usato Fitbit OS come piattaforma di transizione e ora lo sta lasciando spegnere lentamente.

Il futuro è Wear OS e Health Connect — non Fitbit.

LLuevellin 🌧️

A Medellín la pioggia arriva puntuale ogni pomeriggio, rapida e densa. I residenti la conoscono bene, tanto da aver ribattezzato ironicamente la città "Lluevellin" — un gioco di parole che smonta il mito della "Città dell'Eterna Primavera". È in una di queste pause sospese tra un temporale e l'altro che mi sono seduto al computer e ho deciso di sviluppare un'app per il Fitbit⌚.

npm install -g @fitbit/sdk-cli

Non ho fatto in tempo a finire di digitare il primo comando che era già comparso il primo errore. Un benvenuto tutt'altro che incoraggiante. Ma il vero ostacolo, scoprii subito, non era il codice — era configurare l'ambiente di sviluppo.

Step 😕 - SDK CLI

Il Fitbit SDK CLI (@fitbit/sdk-cli) non riceve aggiornamenti da oltre sei anni. L'ultima versione è la 1.7.3. Stai usando una libreria che vive nella stessa fascia temporale della versione 10 di Node.js che era supportata fino al 30 aprile 2021.

La CLI dipende da keytar, un modulo nativo di Node.js che funge da ponte tra l'applicazione e il sistema operativo per la gestione sicura delle credenziali — Keychain su MacOS, Credential Vault su Windows e libsecret su Linux.

Essendo scritto in C++, il modulo viene compilato tramite node-gyp al momento dell'installazione. A partire da Node.js 20, alcune modifiche strutturali al Javascript V8 Engine hanno reso le versioni precedenti di keytar incompatibili, causando errori critici sia in fase di compilazione che di esecuzione.

Ho incollato l'errore a Claude Code. La risposta è arrivata in trenta secondi: la versione di Node, il modulo responsabile, e la versione LTS da usare come target. Nessuna ricerca su StackOverflow, nessun thread del 2022 da interpretare.

Step 1️⃣ - Node version Manager

Il mio primo passo, quindi, non è stato installare la CLI, ma nvm-windows per gestire più versioni di Node.js in parallelo — e fissare la versione a 18.20.5 LTS.

Claude Code aveva indicato esattamente quella versione: abbastanza recente per essere mantenuta, abbastanza vecchia per essere compatibile con keytar.

Su Windows c'è un ulteriore dettaglio che la documentazione non enfatizza abbastanza: nvm-windows richiede una shell aperta come Amministratore. Non come raccomandazione — come requisito. Aprendo PowerShell normalmente e provando a eseguire nvm install o nvm use, si ottengono errori di permessi che non indicano esplicitamente cosa manca.

Il tipo di errore che ti porta a rileggere la documentazione due volte prima di realizzare che la soluzione è semplicemente: tasto destro → "Esegui come amministratore".

nvm install 18.20.5
nvm use 18.20.5
node -v   # deve rispondere: v18.20.5
npm -v    # deve rispondere una versione 10.x

Step 2️⃣ - Visual Studio Build Tools

Il secondo ostacolo: Visual Studio Build Tools. Per compilare keytar su Windows servono il toolset VC++ e il Windows 10/11 SDK.

npm ERR! gyp ERR! node -v v18.20.5
npm ERR! gyp ERR! node-gyp -v v9.1.0
npm ERR! gyp ERR! not ok

Se mancano, l'installazione si interrompe con un errore poco eloquente che sembra un problema di configurazione ma è in realtà una dipendenza non documentata.

gyp ERR! find VS - missing any Windows SDK

Ho chiesto a Claude Code cosa significasse quel messaggio. Mi ha spiegato che node-gyp cercava il compilatore C++ di Windows e non lo trovava — e mi ha indicato esattamente quale workload selezionare nell'installer: "Desktop development with C++". Non "installa Visual Studio", non "cerca online" — il nome preciso del workload, spuntabile alla prima schermata.

Il CLI compilerà keytar dal sorgente — vedrai output di compilazione C++ girare nel terminale.

Una volta installato, l'autenticazione avviene via OAuth2: npx fitbit apre il browser, accedi con il tuo account Fitbit/Google, il terminale ti restituisce la shell interattiva:

fitbit$

Un bridge, due bande, e un orologio invisibile

Il Developer Bridge è il canale di comunicazione websocket tra la CLI sul PC, l'app Fitbit sullo smartphone, e il dispositivo fisico. Per farlo funzionare, devi abilitarlo sia nell'app sul telefono che nelle impostazioni del Versa 3. C'è anche un passaggio preliminare non ovvio: accettare i termini della piattaforma sviluppatori. Se lo salti, il bridge non funziona e non ti dice perché. Ma il problema più insidioso è un altro.

Quale banda WiFi 2.4/5GHz?

I router moderni, come l'Arris TG2482 fornito da Tigo, trasmettono su due bande di frequenza: 2.4GHz e 5GHz. Le due bande non sono intercambiabili — la 2.4 GHz copre distanze maggiori e penetra meglio muri e ostacoli, ma è più lenta e soggetta a interferenze; la 5 GHz, al contrario, offre velocità più elevate e meno congestione, a scapito però di un raggio d'azione più ridotto.

Il Fitbit Versa 3 supporta esclusivamente il Wi-Fi 2.4 GHz. Se il tuo smartphone è connesso alla banda 5 GHz — configurazione predefinita su qualsiasi router dual-band moderno — il Developer Bridge non funzionerà: i due dispositivi sembreranno sulla stessa rete, ma in realtà sono su due canali diversi.
Il sintomo è silenzioso:

fitbit$ connect device
No devices are connected and available

Nessun errore esplicito. Nessuna indicazione sulla causa. Solo quel "No devices are connected" che ti fa dubitare🤔 del cavo, del Bluetooth, del firmware.

Stavo per ricominciare da capo con il setup quando ho descritto la situazione a Claude Code — il modello, il messaggio, la configurazione di rete. La risposta ha nominato direttamente il problema: il Versa 3 è solo 2.4GHz, e se il telefono è sulla banda 5GHz il bridge non si stabilisce perché i due dispositivi sono, tecnicamente, su reti diverse. Una cosa che non trovi nel getting started ufficiale e che Claude Code sapeva perché era già finita in decine di thread di debug su forum ormai abbandonati.

La soluzione: entrare nelle impostazioni WiFi del telefono, selezionare esplicitamente la rete 2.4GHz (di solito ha lo stesso SSID con un suffisso _2G o _2.4, a seconda del router), verificare che anche il Versa 3 sia sulla stessa banda.

Il computer di sviluppo può stare dove vuole — la comunicazione avviene attraverso il telefono come bridge, non direttamente. C'è anche una questione di ordine.

Nella shell fitbit$, i comandi vanno eseguiti in sequenza precisa:

fitbit$ connect phone     # prima: il bridge con lo smartphone
fitbit$ connect device    # poi: il dispositivo

Invertirli significa che l'orologio risulta invisibile — non perché non sia connesso, ma perché la CLI non ha ancora riconosciuto il telefono come intermediario.

Il valore delle rovine

Con l'ambiente configurato, fitbit$ build-and-install — e funziona.

L'app gira sul Versa 3: detti una nota dal polso, il telefono la trascrive, Obsidian la riceve come file markdown. Il flusso base funziona. Ci sono gap — il pulsante +Task non propaga il flag corretto al companion, la lingua di trascrizione è hardcoded in it-IT — ma per una v0.1.0 costruita in un pomeriggio su una piattaforma tecnicamente morta, è abbastanza per chiudere il cerchio.

Il collegamento con Obsidian è possibile grazie al plugin obsidian live-sync che sincronizza le note del vault su un'istanza CouchDB self-hosted. Da lì, basta esporre un layer di accesso HTTP sopra CouchDB, un'API che mappa le operazioni di lettura e scrittura sulle note.

Il companion dell'app Fitbit chiama quegli endpoint via HTTPS con autenticazione: legge i task, salva le note vocali, aggiorna i file markdown. Nessun servizio cloud di terze parti, nessuna dipendenza esterna — solo Fitbit, telefono, e un server che parla con il mio vault.

È qui che il bilancio si chiarisce.

Il setup è stato complesso, non in modo intellettualmente stimolante ma nel modo frustrante delle dipendenze legacy che si rompono in silenzio. Ogni errore aveva una causa precisa — una versione di Node troppo nuova, un compilatore assente, una banda WiFi sbagliata — ma nessuna di queste cause era documentata in modo che la collegasse direttamente al sintomo. Claude Code le conosceva tutte, perché erano già finite in thread di debug, issue tracker, e post su forum che esistono ancora da qualche parte nell'indice ma che nessuno aggiorna più.

Non è stata magia. È stato qualcosa di più utile: una memoria collettiva degli errori già fatti da altri, resa interrogabile.

Il punto non è che Fitbit OS valga ancora la pena. Non vale. Ma vale la pena notare che il tipo di esplorazione che una volta era riservato a chi aveva tempo da investire in ecosistemi di nicchia — ora è accessibile a chiunque abbia un pomeriggio libero e un modello linguistico con una buona memoria storica delle API deprecate.

La piattaforma è morta. Il caso d'uso è sopravvissuto.

🔗Sitografia

2016

[0] Parmy Olson, Fitbit's Game Plan For Making Your Company Healthy, Forbes, 08/01/2016

2018

[0] Michael Sawh, Wear OS v Fitbit OS: Let the smartwatch OS battle commence, Wareable, 22/05/2018

[1] Ian Savchenko , Making an App for Fitbit OS: My Impressions, Dev, 05/08/2018

[2] RootAsJay, Beginner guide overview: Develop a Fitbit clock face, Medium, 24/11/2018

2019

[0] Yotam Kadishay, JavaScript V8 Engine Explained, Medium, 23/01/2019

[1]  Paul Ryan, The V8 Engine and JavaScript Optimization Tips, DigitalOcean, 09/10/2019

2020

[0] Redazione, Llega a Fitbit la actualización Fitbit OS 5.1 que mejora las funciones en Sense y Versa 3, Alimarket, 11/12/2020

2021

[0] Jessica Bursztynsky, Google closes its Fitbit acquisition, CNBC, 14/01/2021

[1] João Neto, Getting started with Fitbit development - Part I: Sign Up, Fitbit Studio, CLI, Visual Studio Code, and Hello World, Blog, 21/03/2021

2022

[0] Community, Fitbit Studio is now shutdown for development use, Forum, 20/03/2023

2023

[1] Code & Chill, Instalar múltiples versiones de Node.js en Windows con NVM (Node version Manager), Medium, 31/12/2023

2024

[0] Matt Evans, RIP Fitbit smartwatches – an end we could see coming a mile away, TechRadar, 18/08/2024

[1] Redazione, Google Fit Shutdown: What Developers Need to Know and How to Prepare, Spike, 11/09/2024

[2] Alex Perry , Is Google Fitbit in trouble? Website shutdown revitalizes concern about the brand's future, Mashable, 25/09/2024

[3] Stephen Sheehan, Fitbit Website Shutdown: What Does the Future Hold For Fitness Trackers?, Garage Gym Reviews, 15/11/2024

2026

[0] Andrew Liszewski, Fitbit’s founders launch a new platform for monitoring your entire family’s health, The Verge, 03/02/2026

[1] Ina Fried, Fitbit's founders push AI into family caregiving, Axios, 03/02/2026

📺Videografia

[0] Google for Developers, Google I/O 2012 - Breaking the JavaScript Speed Limit with V, Youtube, 2012