Developer Options: How to Setup SwitchBot Weather Station Custom Page

• 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.tool

In 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:

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: 7h12m

5. 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.