- Related Product: SwitchBot Weather Station
API usage reference link: https://github.com/OpenWonderLabs/SwitchBotAPI
Update SwitchBot's skills to the latest version 1.0.5: https://clawhub.ai/switchbot-dev/switchbot-cloudapi#versions
1. What is a custom page?
In addition to showing default data like temperature, humidity, and weather conditions, SwitchBot Weather Station's screen also features a Custom Page. By utilizing SwitchBot OpenAPI, you can send any text content to the device, transforming the weather station into a desktop information display.
Typical uses:
- Family message board and reminders
- Real-time data dashboard (electricity rates, air quality, stock prices, etc.)
- Birthday countdown and pet feeding reminders
- Pair with scheduled scripts to automatically refresh content
2. How to set up
2.1 Preparation
Obtain the Token and Key for Developers in SwitchBot App
- Open the SwitchBot app.
- Tap Profile -> Preferences -> About -> App Version.
- Tap the App Version (e.g. 6.24) several times (5~15 times) in succession to open the Developer Options.
- When you tap "Developer Options," you'll see the token information.
Obtain Device ID
Call the device list interface to get your Weather Station's deviceID
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.toolIn the returned results, find device where deviceType is "WoIOSensor" or contains the words “Weather Station” , and record its deviceID.
2.2 API Description
Endpoint: `POST https://api.switch-bot.com/v1.1/devices/{deviceId}/commands`
Request Body:
{
"command": "customPage",
"parameter": "The text content you want to display",
"commandType": "command"
}Authentication Method (v1.1)
Each request requires the following HTTP Headers:
| Title | Description |
Authorization |
your Token |
sign |
HMAC-SHA256 signature, Base64 encoded |
t |
Current timestamp (milliseconds) |
nonce |
Random strings (such as UUID) |
Signature Algorithm:
sign = Base64( HMAC-SHA256( secret, token + t + nonce ) )3. Text Format and Limitations
| Maximum Length | Approximately 300 bytes (UTF-8 encoding).
| Line Breaks | ⚠️ Not supported. `\n`, `\r\n`, and `<br>` are all ineffective; text can only wrap naturally depending on screen width |
| Language | Supports Chinese, Japanese, English, and their mixtures |
| Emoji | Supports basic emojis (e.g., ✅🎂🐱📅🏠); note that emojis typically occupy 4 bytes |
| Overly Long Text | Returns `statusCode: 190`, message `"invalid params"` |
| Empty Text | An empty string can be sent to clear the page |
Formatting Suggestions
As line breaks are not supported, it is recommended to use the following separators to enhance readability:
Emojis as separators: `📅Date 🌡Temperature 💨Air`
Vertical line separator: `Date|Temperature|Air Quality`
Space + symbol: `[Date] [Temperature] [Air]`
4. Example Use Cases
Each of the following example texts is limited to 300 bytes and can be copied for direct use.
🏠 Home Reminder
① Family Message Board
📋 Family Announcement Tonight at 7 PM Family Dinner Remember to bring keys The delivery is in the cabinet by the door There are clothes in the washing machine, remember to hang them up② Birthday/Anniversary Countdown
🎂 Mom's birthday is in 15 days 💍 Wedding anniversary is in 32 days 📅 Dad's check-up on 6/20 Baby's vaccine on 6/15③ Waste Sorting Reminder
🗑 Today is Wednesday, kitchen waste day. Tomorrow: recyclable materials. This Friday: hazardous waste. Remember to take them downstairs before 8 PM.🐱 Pet Care
④ Pet Feeding Reminder
🗑 Today is Wednesday, kitchen waste day. Tomorrow: recyclable materials. This Friday: hazardous waste. Remember to take them downstairs before 8 PM.🚄 Transportation
⑤ Commuting Information
🚇 Subway Line 1 Morning Peak: Operating normally, estimated commute 42 minutes 🚌 Bus Route 345 First bus 6:00 Last bus 22:30 Real-time: 3 stations away⑥ High-speed Rail/Flight Reminder
✈️Tomorrow AA 287 LAX→JFK Departs 07:35 Terminal 4 Leave by 5:30AM Weather at dest: Clear 54°F📊 Financial Information
⑦ Stock Market Snapshot
📈US Stocks S&P500:5,234↑0.8% NASDAQ:16,340↑1.2% DOW:39,150↑0.5% 10Y:4.35% Updated:2:58PM🌤 Weather and Environment
⑧ Weather + Air Quality
🌤Los Angeles Today:Partly cloudy 77°F/64°F Air:Good AQI42 PM2.5:12 Tomorrow:Sunny 81°F/66°F UV:Moderate 💧Humidity 55%⚡ Energy Management
⑨ Home Electricity Monitoring
⚡This month:186kWh Tier:1 (84kWh left) Est. month-end:245kWh Yesterday:6.2kWh Rate:~$0.15/kWh YTD cost:$387📬 Mail and Express Delivery
⑩ Mail + Express Delivery Combined
📬Email Today:12 received Unread:3 (1 urgent) 📦Packages USPS:Out for delivery ETA 2pm FedEx:Shipped arrives tmrw Amazon:Delivered🏠 Smart Home Integration
⑪ Indoor Environment Panel
🏠Living Room 24.5°C 💧58% CO2: 620ppm ✅ Bedroom 23.1°C 💧62% Air Conditioner: Cooling 26°C Running Air Purifier: Auto Mode Filter Life 78%💪 Health Management
⑫ Health Check-in
💪Today's Health Drink Water: 1200ml/2000ml Steps: 6580 steps Sedentary Reminder: Time to get up and walk! Weight Trend: This week -0.3kg Sleep: 7h12m5. Advanced: Automatic Timed Updates
With a scheduled script, you can turn the Weather Station into a real-time information dashboard that automatically pulls data from various sources and updates the display.
6. Common Issue Troubleshooting
❌ statusCode: 190 — "invalid params"
Cause: The text exceeds the 300-byte limit.
❌ statusCode: 100 but no change on the screen
Make sure you have swiped to the custom page of the Weather Station (the Custom Page is not the default home screen)
Wait a few seconds, as there may be a slight delay in device refresh
Confirm that the deviceID is correct
❌ 401 Unauthorized
Check if the Token is correct and if there are any extra spaces
Check the signature algorithm: HMAC-SHA256(secret, token + t + nonce) → Base64
Confirm that `t` is a millisecond timestamp (13 digits), not in seconds
Ensure the system clock is accurate; a significant time deviation can lead to authentication failure
❌ Signature Error (sign is incorrect)
Common mistakes:
The concatenation order must be token + t + nonce (not secret + token + ...)
The secret is the key for HMAC and does not participate in the concatenated string
The final result must be Base64 encoded
Ensure that no extra characters, such as line breaks, are mixed in
❌ Line breaks not effective
This is a normal phenomenon. Testing has confirmed that `\n`, `\r\n`, and `<br>` cannot produce line breaks. Text can only wrap naturally based on the screen width. It is recommended to use emoji or symbols as visual separators.
❌ Some emojis display abnormally
The screen of the Weather Station supports basic emojis (within the Unicode BMP range), but complex combination emojis (such as skin tone modifiers and ZWJ sequences) may not display correctly. It is recommended to use simple emojis: ✅❌📅🌤🏠💧⚡📬🐱🎂📊💪🚇
💡 Other Tips
Clear Page: Send an empty string `""` as the parameter.
API Call Frequency: It is recommended not to exceed one call per minute to avoid triggering rate limiting.
Multiple Devices: If there are multiple Weather Stations, each one needs to be called separately using its own deviceId.
Comments
0 comments
Please sign in to leave a comment.