Opciones de Desarrollador: Cómo Configurar la Página Personalizada de SwitchBot Weather Station

• Producto Relacionado: SwitchBot Weather Station

Enlace de referencia para uso de API: https://github.com/OpenWonderLabs/SwitchBotAPI

Actualice las habilidades de SwitchBot a la última versión 1.0.5: https://clawhub.ai/switchbot-dev/switchbot-cloudapi#versions

1. ¿Qué es una página personalizada?

Además de mostrar datos predeterminados como temperatura, humedad y condiciones meteorológicas, la pantalla de SwitchBot Weather Station también cuenta con una Página Personalizada. Al utilizar SwitchBot OpenAPI, puede enviar cualquier contenido de texto al dispositivo, transformando la estación meteorológica en un panel de información de escritorio.

Usos típicos:

• Tablón de mensajes y recordatorios familiares
• Cuadro de mando de datos (tarifas eléctricas, calidad del aire, cotizaciones bursátiles, etc.)
• Cuenta regresiva de cumpleaños y recordatorios de alimentación de mascotas
• Emparejar con scripts programados para actualizar automáticamente el contenido

2. Cómo configurar

2.1 Preparación

Obtenga el Token y la Clave para Desarrolladores en la aplicación SwitchBot

• Abra la aplicación SwitchBot.
• Toque Perfil -> Preferencias -> Acerca de -> Versión de la aplicación.
• Toque la versión de la aplicación (por ejemplo, 6.24) varias veces (de 5 a 15 veces) consecutivamente para abrir las Opciones de Desarrollador.
• Cuando toque "Opciones de Desarrollador", verá la información del token.

Obtenga el ID del Dispositivo

Llamar a la interfaz de lista de dispositivos para obtener el deviceID de su Weather Station

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

En los resultados devueltos, busque el dispositivo donde deviceType sea "WoIOSensor" o contenga las palabras “Weather Station”, y anote su deviceID.

2.2 Descripción de la API

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

Cuerpo de la Solicitud:

{
  "command": "customPage",
  "parameter": "El contenido de texto que desea mostrar",
  "commandType": "command"
}

Método de Autenticación (v1.1)​  

Cada solicitud requiere los siguientes encabezados HTTP:

Algoritmo de Firma:

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

3. Formato de Texto y Limitaciones

| Longitud Máxima | Aproximadamente 300 bytes (codificación UTF-8). 

| Saltos de Línea | ⚠️ No soportados. `\n`, `\r\n` y `<br>` no funcionan; el texto solo puede ajustarse naturalmente según el ancho de la pantalla |

| Idioma | Soporta chino, japonés, inglés y sus combinaciones |

| Emoji | Soporta emojis básicos (por ejemplo, ✅🎂🐱📅🏠💧⚡📬); tenga en cuenta que los emojis suelen ocupar 4 bytes |

| Texto Demasiado Largo | Devuelve `statusCode: 190`, mensaje `"invalid params"` |

| Texto Vacío | Se puede enviar una cadena vacía para limpiar la página |

Sugerencias de Formato

Dado que no se admiten saltos de línea, se recomienda usar los siguientes separadores para mejorar la legibilidad:

Emojis como separadores: `📅Fecha 🌡Temperatura 💨Aire`

Separador de línea vertical: `Fecha|Temperatura|Calidad del Aire`

Espacio + símbolo: `[Fecha] [Temperatura] [Aire]`

4. Casos de Uso de Ejemplo

Cada uno de los siguientes textos de ejemplo está limitado a 300 bytes y puede copiarse para uso directo.

🏠 Recordatorio en Casa

① Tablón de Mensajes Familiar

📋 Anuncio Familiar Cena familiar esta noche a las 7 PM Recuerden traer llaves La entrega está en el armario junto a la puerta Hay ropa en la lavadora, recuerden colgarla

② Cuenta Regresiva de Cumpleaños/Aniversario

🎂 El cumpleaños de mamá es en 15 días 💍 Aniversario de boda en 32 días 📅 Chequeo de papá el 20/6 Vacuna del bebé el 15/6

③ Recordatorio de Clasificación de Residuos

🗑 Hoy es miércoles, día de residuos de cocina. Mañana: materiales reciclables. Este viernes: residuos peligrosos. Recuerden bajarlos antes de las 8 PM.

🐱 Cuidado de Mascotas

④ Recordatorio de Alimentación de Mascotas

🗑 Hoy es miércoles, día de residuos de cocina. Mañana: materiales reciclables. Este viernes: residuos peligrosos. Recuerden bajarlos antes de las 8 PM.

🚄 Transporte

⑤ Recordatorio de Tren de Alta Velocidad/Vuelo

✈️Mañana AA 287 LAX→JFK Sale 07:35 Terminal 4 Salir a las 5:30 AM Clima en destino: Despejado 54°F

📊 Información Financiera

⑥ Resumen del Mercado de Valores

📈Acciones EE.UU. S&P500:5,234↑0.8% NASDAQ:16,340↑1.2% DOW:39,150↑0.5% 10Y:4.35% Actualizado:2:58PM

🌤 Clima y Medio Ambiente

⑦ Clima + Calidad del Aire

🌤Los Ángeles Hoy: Parcialmente nublado 77°F/64°F Aire: Bueno AQI42 PM2.5:12 Mañana: Soleado 81°F/66°F UV: Moderado 💧Humedad 55%

⚡ Gestión de Energía

⑧ Monitoreo de Electricidad en Casa

⚡Este mes:186kWh Nivel:1 (84kWh restantes) Est. fin de mes:245kWh Ayer:6.2kWh Tarifa:~$0.15/kWh Costo acumulado:$387

📬 Correo y Entregas Exprés

⑨ Correo + Entregas Exprés Combinadas

📬Correo Hoy:12 recibidos No leídos:3 (1 urgente) 📦Paquetes USPS:En reparto ETA 2pm FedEx:Enviado llega mañana Amazon:Entregado

🏠 Integración de Hogar Inteligente  
 
⑩ Panel de Ambiente Interior

🏠Sala 24.5°C 💧58% CO2: 620ppm ✅ Dormitorio 23.1°C 💧62% Aire acondicionado: Enfriando 26°C Funcionando Purificador de aire: Modo automático Vida útil filtro 78%

💪 Gestión de Salud

⑪ Registro de Salud

💪Salud de hoy Beber agua: 1200ml/2000ml Pasos: 6580 pasos Recordatorio sedentario: ¡Hora de levantarse y caminar! Tendencia de peso: Esta semana -0.3kg Sueño: 7h12m

5. Avanzado: Actualizaciones Automáticas Programadas

Con un script programado, puedes convertir la estación meteorológica en un panel de información que recopila automáticamente datos de diversas fuentes y actualiza la pantalla.  

6. Solución de Problemas Comunes

❌ statusCode: 190 — "invalid params"

Causa: El texto supera el límite de 300 bytes.

❌ statusCode: 100 pero no hay cambio en la pantalla​

Asegúrese de haber deslizado hasta la página personalizada de la Weather Station (la Página Personalizada no es la pantalla de inicio predeterminada)​ 

Espere unos segundos, ya que puede haber un pequeño retraso en la actualización del dispositivo​ 

Confirme que el deviceID sea correcto​ 

❌ 401 No autorizado​

Verifique si el Token es correcto y si no hay espacios adicionales​ 

Revise el algoritmo de firma: HMAC-SHA256(secret, token + t + nonce) → Base64​ 

Confirme que `t` sea una marca de tiempo en milisegundos (13 dígitos), no en segundos​ 

Asegúrese de que el reloj del sistema sea exacto; una desviación significativa de tiempo puede causar fallo de autenticación

❌ Error de Firma (sign es incorrecto)​

Errores comunes:​

El orden de concatenación debe ser token + t + nonce (no secret + token + ...)​

El secret es la clave para HMAC y no participa en la cadena concatenada​

El resultado final debe estar codificado en Base64​

Asegúrese de que no haya caracteres adicionales, como saltos de línea, mezclados

❌ Saltos de línea no efectivos

Esto es un fenómeno normal. Las pruebas han confirmado que `\n`, `\r\n` y `<br>` no pueden producir saltos de línea. El texto solo puede ajustarse naturalmente según el ancho de la pantalla. Se recomienda usar emojis o símbolos como separadores visuales.

❌ Algunos emojis se muestran de forma anormal

La pantalla de la Weather Station soporta emojis básicos (dentro del rango BMP de Unicode), pero los emojis de combinación compleja (como modificadores de tono de piel y secuencias ZWJ) pueden no mostrarse correctamente. Se recomienda usar emojis simples: ✅❌📅🌤🏠💧⚡📬🐱🎂📊💪🚇

💡 Otros Consejos

Limpiar Página: Envíe una cadena vacía `""` como parámetro.

Frecuencia de Llamadas API: Se recomienda no exceder una llamada por minuto para evitar activar limitaciones de tasa.

Múltiples Dispositivos: Si hay varias Weather Stations, cada una debe ser llamada por separado usando su propio deviceId.