Opciones de Desarrollador: Cómo Configurar la Página Personalizada de SwitchBot Pantalla E-Ink para el Hogar

• Producto Relacionado: SwitchBot Pantalla E-Ink para el Hogar

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 Pantalla E-Ink para el Hogar también cuenta con una Página Personalizada. Al utilizar SwitchBot OpenAPI, puede enviar cualquier contenido de texto al dispositivo, transformando la Pantalla E-Ink para el Hogar 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 Pantalla E-Ink para el Hogar

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 “Pantalla E-Ink para el Hogar”, 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 Pantalla E-Ink para el Hogar 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 Pantalla E-Ink para el Hogar (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 Pantalla E-Ink para el Hogar 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 Pantalla E-Ink para el Hogars, cada una debe ser llamada por separado usando su propio deviceId.