Options développeur : Comment configurer la page personnalisée de la Station Météo SwitchBot

• Produit concerné : Station Météo SwitchBot

Lien de référence pour l’utilisation de l’API : https://github.com/OpenWonderLabs/SwitchBotAPI

Mettre à jour les compétences SwitchBot vers la dernière version 1.0.5 : https://clawhub.ai/switchbot-dev/switchbot-cloudapi#versions

1. Qu’est-ce qu’une page personnalisée ?

En plus d’afficher les données par défaut comme la température, l’humidité et les conditions météorologiques, l’écran de la Station Météo SwitchBot propose également une Page Personnalisée. En utilisant SwitchBot OpenAPI, vous pouvez envoyer n’importe quel contenu texte à l’appareil, transformant ainsi la station météo en un affichage d’informations pour bureau.

Utilisations typiques :

• Tableau d’affichage familial et rappels
• Tableau de bord des données (tarifs d'électricité, qualité de l'air, cours boursiers, etc.)
• Compte à rebours d’anniversaire et rappels d’alimentation pour animaux
• Association avec des scripts programmés pour rafraîchir automatiquement le contenu

2. Comment configurer

2.1 Préparation

Obtenir le Token et la Clé pour développeurs dans l’application SwitchBot

• Ouvrez l’application SwitchBot.
• Appuyez sur Profil -> Préférences -> À propos -> Version de l’application.
• Appuyez plusieurs fois (5 à 15 fois) successivement sur la version de l’application (par ex. 6.24) pour ouvrir les Options développeur.
• Lorsque vous appuyez sur « Options développeur », vous verrez les informations du token.

Obtenir l’ID de l’appareil

Appelez l’interface de la liste des appareils pour obtenir le deviceID de votre Station Météo

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

Dans les résultats retournés, trouvez l’appareil où deviceType est "WoIOSensor" ou contient les mots « Weather Station », et notez son deviceID.

2.2 Description de l’API

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

Corps de la requête :

{
  "command": "customPage",
  "parameter": "Le contenu texte que vous souhaitez afficher",
  "commandType": "command"
}

Méthode d’authentification (v1.1)​  

Chaque requête nécessite les en-têtes HTTP suivants :

Algorithme de signature :

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

3. Format de texte et limitations

| Longueur maximale | Environ 300 octets (encodage UTF-8). 

| Sauts de ligne | ⚠️ Non pris en charge. `\n`, `\r\n` et `<br>` sont tous inefficaces ; le texte ne peut se retourner que naturellement selon la largeur de l’écran |

| Langue | Prise en charge du chinois, japonais, anglais et leurs mélanges |

| Emoji | Prise en charge des emojis basiques (ex. : ✅🎂🐱📅🏠💧⚡📬) ; notez que les emojis occupent généralement 4 octets |

| Texte trop long | Renvoie `statusCode: 190`, message `"invalid params"` |

| Texte vide | Une chaîne vide peut être envoyée pour effacer la page |

Suggestions de formatage

Comme les sauts de ligne ne sont pas pris en charge, il est recommandé d’utiliser les séparateurs suivants pour améliorer la lisibilité :

Emojis comme séparateurs : `📅Date 🌡Température 💨Air`

Séparateur barre verticale : `Date|Température|Qualité de l’air`

Espace + symbole : `[Date] [Température] [Air]`

4. Exemples d’utilisation

Chacun des textes d’exemple suivants est limité à 300 octets et peut être copié pour une utilisation directe.

🏠 Rappel à la maison

① Tableau d’affichage familial

📋 Annonce familiale Ce soir à 19h Dîner familial Pensez à prendre les clés La livraison est dans le placard près de la porte Il y a des vêtements dans la machine à laver, pensez à les étendre

② Compte à rebours anniversaire/anniversaire de mariage

🎂 Anniversaire de maman dans 15 jours 💍 Anniversaire de mariage dans 32 jours 📅 Contrôle de papa le 20/6 Vaccin bébé le 15/6

③ Rappel tri des déchets

🗑 Aujourd’hui mercredi, jour des déchets de cuisine. Demain : recyclables. Ce vendredi : déchets dangereux. Pensez à les descendre avant 20h.

🐱 Soins aux animaux

④ Rappel alimentation animaux

🗑 Aujourd’hui mercredi, jour des déchets de cuisine. Demain : recyclables. Ce vendredi : déchets dangereux. Pensez à les descendre avant 20h.

🚄 Transport

⑤  Rappel train à grande vitesse/vol

✈️Demain AA 287 LAX→JFK Départ 07:35 Terminal 4 Partir avant 5:30 Météo à destination : Clair 54°F

📊 Informations financières

⑥ Aperçu boursier

📈Bourse US S&P500 :5 234↑0,8% NASDAQ :16 340↑1,2% DOW :39 150↑0,5% 10Y :4,35% Mise à jour :14h58

🌤 Météo et environnement

⑦ Météo + Qualité de l’air

🌤Los Angeles Aujourd’hui : Partiellement nuageux 77°F/64°F Air : Bon AQI42 PM2.5 :12 Demain : Ensoleillé 81°F/66°F UV : Modéré 💧Humidité 55%

⚡ Gestion de l’énergie

⑧ Suivi électricité domestique

⚡Ce mois :186kWh Palier :1 (84kWh restants) Est. fin de mois :245kWh Hier :6,2kWh Tarif :~0,15$/kWh Coût cumulé :387$

📬 Courrier et livraison express

⑨ Courrier + Livraison express combinés

📬Email Aujourd’hui :12 reçus Non lus :3 (1 urgent) 📦Colis USPS : En cours de livraison ETA 14h FedEx : Expédié arrive demain Amazon : Livré

🏠 Intégration domotique  
 
⑩ Panneau environnement intérieur

🏠Salon 24,5°C 💧58% CO2 : 620ppm ✅ Chambre 23,1°C 💧62% Clim : Refroidissement 26°C En marche Purificateur d’air : Mode auto Durée de vie filtre 78%

💪 Gestion de la santé

⑪ Bilan santé

💪Santé du jour Boire de l’eau : 1200ml/2000ml Pas : 6580 pas Rappel sédentarité : Il est temps de se lever et marcher ! Tendance poids : Cette semaine -0,3kg Sommeil : 7h12m

5. Avancé : mises à jour automatiques programmées

Grâce à un script programmé, vous pouvez transformer la station météo en un tableau de bord d'informations qui récupère automatiquement des données provenant de diverses sources et met à jour l'affichage.  

6. Résolution des problèmes courants

❌ statusCode : 190 — « invalid params »

Cause : Le texte dépasse la limite de 300 octets.

❌ statusCode : 100 mais aucun changement à l’écran​

Assurez-vous d’avoir fait glisser vers la page personnalisée de la Station Météo (la Page Personnalisée n’est pas l’écran d’accueil par défaut)​ 

Attendez quelques secondes, car il peut y avoir un léger délai de rafraîchissement de l’appareil​ 

Confirmez que le deviceID est correct​ 

❌ 401 Non autorisé​

Vérifiez si le Token est correct et s’il n’y a pas d’espaces superflus​ 

Vérifiez l’algorithme de signature : HMAC-SHA256(secret, token + t + nonce) → Base64​ 

Confirmez que `t` est un horodatage en millisecondes (13 chiffres), pas en secondes​ 

Assurez-vous que l’horloge système est précise ; un écart de temps important peut entraîner un échec d’authentification

❌ Erreur de signature (sign incorrect)​

Erreurs courantes :​

L’ordre de concaténation doit être token + t + nonce (et non secret + token + ...)​

Le secret est la clé pour HMAC et ne fait pas partie de la chaîne concaténée​

Le résultat final doit être encodé en Base64​

Assurez-vous qu’aucun caractère supplémentaire, comme des sauts de ligne, ne soit inséré

❌ Sauts de ligne inefficaces

C’est un phénomène normal. Les tests ont confirmé que `\n`, `\r\n` et `<br>` ne produisent pas de sauts de ligne. Le texte ne peut que se retourner naturellement selon la largeur de l’écran. Il est recommandé d’utiliser des emojis ou des symboles comme séparateurs visuels.

❌ Certains emojis s’affichent anormalement

L’écran de la Station Météo prend en charge les emojis basiques (dans la plage Unicode BMP), mais les emojis complexes combinés (comme les modificateurs de ton de peau et les séquences ZWJ) peuvent ne pas s’afficher correctement. Il est recommandé d’utiliser des emojis simples : ✅❌📅🌤🏠💧⚡📬🐱🎂📊💪🚇

💡 Autres conseils

Effacer la page : Envoyez une chaîne vide `""` en paramètre.

Fréquence des appels API : Il est recommandé de ne pas dépasser un appel par minute pour éviter le blocage de la fréquence.

Plusieurs appareils : S’il y a plusieurs Stations Météo, chacune doit être appelée séparément avec son propre deviceId.