Opzioni per sviluppatori: come configurare la pagina personalizzata di SwitchBot Home Dashboard E-Ink

• Gerelateerd product: SwitchBot Home Dashboard E-Ink

API-gebruiksreferentielink: https://github.com/OpenWonderLabs/SwitchBotAPI

Update SwitchBot's skills naar de nieuwste versie 1.0.5: https://clawhub.ai/switchbot-dev/switchbot-cloudapi#versions

1. Wat is een aangepaste pagina?

Naast het tonen van standaardgegevens zoals temperatuur, luchtvochtigheid en weersomstandigheden, beschikt het scherm van de SwitchBot Home Dashboard E-Ink ook over een Aangepaste Pagina. Door gebruik te maken van SwitchBot OpenAPI kunt u elke tekstinhoud naar het apparaat sturen, waardoor het weerstation verandert in een desktop-informatieweergave.

Typische toepassingen:

• Familieberichtbord en herinneringen
• Gegevensdashboard (elektriciteitstarieven, luchtkwaliteit, aandelenkoersen, enz.)
• Verjaardagsaftelling en herinneringen voor het voeren van huisdieren
• Koppelen met geplande scripts om inhoud automatisch te vernieuwen

2. Hoe in te stellen

2.1 Voorbereiding

Verkrijg de Token en Key voor ontwikkelaars in de SwitchBot-app

• Open de SwitchBot-app.
• Tik op Profiel -> Voorkeuren -> Over -> App-versie.
• Tik meerdere keren (5~15 keer achter elkaar) op de App-versie (bijv. 6.24) om de Ontwikkelaarsopties te openen.
• Wanneer u op "Ontwikkelaarsopties" tikt, ziet u de tokeninformatie.

Verkrijg apparaat-ID

Roep de apparaatlijst-interface aan om de deviceID van uw Home Dashboard E-Ink te verkrijgen

curl -s https://api.switch-bot.com/v1.1/devices \
  -H "Authorization: your Token" \
  -H "sign: signature" \
  -H "t: timestamp" \
  -H "nonce: Random string" | python3 -m json.tool

In de geretourneerde resultaten zoekt u het apparaat waar deviceType "WoIOSensor" is of de woorden “Home Dashboard E-Ink” bevat, en noteer het deviceID.

2.2 API-beschrijving

Endpoint: `POST https://api.switch-bot.com/v1.1/devices/{deviceId}/commands`

Request Body:

{
  "command": "customPage",
  "parameter": "De tekstinhoud die u wilt weergeven",
  "commandType": "command"
}

Authenticatiemethode (v1.1)​  

Elke aanvraag vereist de volgende HTTP-headers:

Handtekeningalgoritme:

sign = Base64( HMAC-SHA256( secret, token + t + nonce ) )

3. Tekstformaat en beperkingen

| Maximale lengte | Ongeveer 300 bytes (UTF-8-codering). 

| Regelsprongen | ⚠️ Niet ondersteund. `\n`, `\r\n` en `<br>` zijn allemaal niet effectief; tekst kan alleen natuurlijk worden afgebroken afhankelijk van de schermbreedte |

| Taal | Ondersteunt Chinees, Japans, Engels en hun mengsels |

| Emoji | Ondersteunt basisemoji's (bijv. ✅🎂🐱📅🏠); let op dat emoji's meestal 4 bytes innemen |

| Te lange tekst | Geeft `statusCode: 190`, bericht `"invalid params"` terug |

| Lege tekst | Een lege tekenreeks kan worden verzonden om de pagina te wissen |

Formatteringssuggesties

Aangezien regelsprongen niet worden ondersteund, wordt aanbevolen de volgende scheidingstekens te gebruiken om de leesbaarheid te verbeteren:

Emoji's als scheidingstekens: `📅Datum 🌡Temperatuur 💨Lucht`

Verticaal lijnscheidingsteken: `Datum|Temperatuur|Luchtkwaliteit`

Spatie + symbool: `[Datum] [Temperatuur] [Lucht]`

4. Voorbeeldgebruik

Elke van de volgende voorbeeldteksten is beperkt tot 300 bytes en kan direct worden gekopieerd voor gebruik.

🏠 Herinnering thuis

① Familieberichtbord

📋 Familiebericht Vanavond om 19:00 uur familie-etentje Vergeet de sleutels niet De levering ligt in het kastje bij de deur Er ligt was in de wasmachine, vergeet niet op te hangen

② Verjaardags-/jubileumaftelling

🎂 Moeder is over 15 dagen jarig 💍 Huwelijksverjaardag over 32 dagen 📅 Vader's controle op 20/6 Baby's vaccinatie op 15/6

③ Afvalscheiding herinnering

🗑 Vandaag is woensdag, groente- en tuinafval. Morgen: recyclebare materialen. Deze vrijdag: gevaarlijk afval. Vergeet ze voor 20:00 uur naar beneden te brengen.

🐱 Zorg voor huisdieren

④ Herinnering huisdieren voeren

🗑 Vandaag is woensdag, groente- en tuinafval. Morgen: recyclebare materialen. Deze vrijdag: gevaarlijk afval. Vergeet ze voor 20:00 uur naar beneden te brengen.

🚄 Vervoer

⑤ Hoge snelheidstrein/vlucht herinnering

✈️Morgen AA 287 LAX→JFK Vertrek 07:35 Terminal 4 Vertrek om 5:30 uur Weer op bestemming: Helder 54°F

📊 Financiële informatie

⑥ Aandelenmarktoverzicht

📈VS Aandelen S&P500:5.234↑0,8% NASDAQ:16.340↑1,2% DOW:39.150↑0,5% 10J:4,35% Bijgewerkt:14:58

🌤 Weer en milieu

⑦ Weer + luchtkwaliteit

🌤Los Angeles Vandaag: Gedeeltelijk bewolkt 77°F/64°F Lucht: Goed AQI42 PM2.5:12 Morgen: Zonnig 81°F/66°F UV: Matig 💧Vochtigheid 55%

⚡ Energiebeheer

⑧ Thuis elektriciteitsmonitoring

⚡Deze maand:186kWh Niveau:1 (84kWh over) Geschatte maandafsluiting:245kWh Gisteren:6,2kWh Tarief:~$0,15/kWh Kosten dit jaar:$387

📬 Post en expreslevering

⑨ Post + expreslevering gecombineerd

📬E-mail Vandaag:12 ontvangen Ongelezen:3 (1 urgent) 📦Pakketten USPS:Onderweg ETA 14:00 FedEx:Verzonden aankomst morgen Amazon:Bezorgd

🏠 Slimme huisintegratie  
 
⑩ Binnenmilieupaneel

🏠Woonkamer 24,5°C 💧58% CO2: 620ppm ✅ Slaapkamer 23,1°C 💧62% Airco: Koelen 26°C Aan Luchtzuiveraar: Automodus Filterlevensduur 78%

💪 Gezondheidsbeheer

⑪ Gezondheid check-in

💪Vandaag Gezondheid Drinkwater: 1200ml/2000ml Stappen: 6580 stappen Zittende herinnering: Tijd om op te staan en te lopen! Gewichtstrend: Deze week -0,3kg Slaap: 7u12m

5. Geavanceerd: Automatische tijdgestuurde updates

Grazie a uno script programmato, è possibile trasformare la Home Dashboard E-Inkrologica in un pannello informativo che recupera automaticamente i dati da varie fonti e aggiorna il display.  

6. Veelvoorkomende probleemoplossing

❌ statusCode: 190 — "invalid params"

Oorzaak: De tekst overschrijdt de limiet van 300 bytes.

❌ statusCode: 100 maar geen wijziging op het scherm​

Zorg ervoor dat u naar de aangepaste pagina van het Home Dashboard E-Ink hebt geswiped (de Aangepaste Pagina is niet het standaard startscherm)​ 

Wacht enkele seconden, want er kan een lichte vertraging zijn bij het vernieuwen van het apparaat​ 

Bevestig dat de deviceID correct is​ 

❌ 401 Unauthorized​

Controleer of de Token correct is en of er geen extra spaties zijn​ 

Controleer het handtekeningalgoritme: HMAC-SHA256(secret, token + t + nonce) → Base64​ 

Bevestig dat `t` een milliseconden-tijdstempel is (13 cijfers), niet in seconden​ 

Zorg dat de systeemklok correct is; een grote tijdsafwijking kan leiden tot authenticatiefouten

❌ Handtekeningfout (sign is onjuist)​

Veelvoorkomende fouten:​

De samenvoegvolgorde moet token + t + nonce zijn (niet secret + token + ...)​

De secret is de sleutel voor HMAC en maakt geen deel uit van de samengevoegde tekenreeks​

Het eindresultaat moet Base64-gecodeerd zijn​

Zorg ervoor dat er geen extra tekens, zoals regelsprongen, zijn toegevoegd

❌ Regelsprongen niet effectief

Dit is een normaal fenomeen. Tests hebben bevestigd dat `\n`, `\r\n` en `<br>` geen regelsprongen kunnen produceren. Tekst kan alleen natuurlijk worden afgebroken op basis van de schermbreedte. Het wordt aanbevolen emoji's of symbolen als visuele scheidingstekens te gebruiken.

❌ Sommige emoji's worden abnormaal weergegeven

Het scherm van het Home Dashboard E-Ink ondersteunt basisemoji's (binnen het Unicode BMP-bereik), maar complexe combinatie-emoji's (zoals huidskleurmodifiers en ZWJ-sequenties) worden mogelijk niet correct weergegeven. Het wordt aanbevolen eenvoudige emoji's te gebruiken: ✅❌📅🌤🏠💧⚡📬🐱🎂📊💪🚇

💡 Andere tips

Pagina wissen: stuur een lege tekenreeks `""` als parameter.

API-aanroepfrequentie: het wordt aanbevolen niet meer dan één oproep per minuut te doen om rate limiting te voorkomen.

Meerdere apparaten: als er meerdere Home Dashboard E-Inks zijn, moet elk afzonderlijk worden aangeroepen met zijn eigen deviceId.