La pantalla de apps de Miblo: página, tarjetas, marcos y capas

La pantalla de apps#

La rotación de pantallas del Miblo Desk (Resumen, Límites, Sesiones) tiene la pantalla de apps, que dibuja tu programa. Necesita Miblo 1.30 o más nuevo en el computador y en el Miblo Desk: un dispositivo más antiguo no recibe nada más que su actualización (miblo status y Miblo Hub lo dicen), y en gadgets responde offline. La pantalla puede ser:

• una página web (Miblo 1.45, la forma estándar): HTML, CSS y JavaScript que Miblo Hub dibuja en el computador (page());

Las tres siguientes son la forma antigua, obsoleta desde Miblo 1.45 pero funcional:

• una tarjeta: un título y hasta cuatro elementos (un número grande, un anillo, una barra, una línea de texto, un gráfico diminuto), dibujada por el propio Miblo con sus fuentes y colores;

• un marco: una imagen completa de 240x240, guardada en la flash de Miblo;

• una capa: la tarjeta dibujada sobre un marco. Es el camino correcto hacia una pantalla hermosa: el fondo va una vez, luego solo cambia el número.

Reglas que siempre se cumplen:

• Miblo va primero. Las alertas, "te necesita", la configuración y los códigos siempre se dibujan sobre la pantalla de apps.

• El nombre de tu programa siempre está en la pantalla, para que la persona sepa de quién es. Es el tool que pasas a screen().

• Cada programa tiene su propia pantalla. Con varias apps, la pantalla de apps muestra una a la vez y pasa a la siguiente después del tiempo propio de cada una (miblo apps dwell <id> <seconds>, de 5 a 120; 15 s por defecto). Un tiempo por app, ninguno global.

• Los límites son los de este computador, no los de tu programa. Cada tasa de esta página (tarjetas, show, peek, request, marcos, animaciones) es un balde en el puente, compartido por todos los programas y todas las apps oficiales que estén activadas. Ejecuta dos ejemplos seguidos y el segundo puede recibir rate_limited: espera retryAfter segundos.

• Cuándo se muestran las apps lo decide la persona (miblo apps when, la página del Miblo Desk o Miblo Hub): cuando nadie está trabajando (por defecto: tras 60 s sin ninguna sesión de IA corriendo ni esperando), siempre en la rotación, cuando una app pide la pantalla (solo cuando tu programa llama a request(), abajo) o solo cuando yo lo pida (fijada o un vistazo).

screen()#

const screen = miblo.screen({ tool: 'steps' });

screen = miblo.screen("steps")

tool sigue las reglas del tool de una sesión (de 1 a 20 caracteres, no un nombre de Claude Code, sin _ al inicio). Cada escritura lleva el encabezado x-miblo-sdk-tool; el paquete lo envía por ti. La pantalla de un programa es la de su app declarada (ver Apps), si no, la de su nombre.

page(), data() y quality()#

Desde Miblo 1.45, la forma estándar de dibujar la pantalla es una página web: Miblo Hub la renderiza a 240x240 en el computador y transmite al Miblo Desk solo los píxeles que cambiaron. La guía completa, con el manifest, window.miblo y las limitaciones, está en Apps del Desk de página.

await screen.page('weather.html', { data: { city: 'Recife', temp: 29 }, quality: 'auto', max: 'high' });
await screen.data({ city: 'Recife', temp: 30 });   // the page hears it with miblo.on('data')
await screen.quality('ultra');                     // or the page itself: miblo.quality('ultra')
await screen.clear();

• page(file, { data, quality, max }): file es un archivo .html relativo a la carpeta de trabajo del programa (la página de una app del Desk instalada siempre es un archivo de su propio paquete); su CSS, imágenes, fuentes, scripts y videos están a su lado y se cargan por ruta relativa. data es JSON, de hasta 16 KB, y llega a la página como window.miblo.data. Devuelve { ok, page, quality, max, current }.

• data(obj): JSON nuevo para la página (hasta 16 KB); la página lo escucha con miblo.on('data', fn).

• quality(q, { max }): 'auto' (por defecto), 'verylow' (objetivo de 30 fps), 'low' (25), 'medium' (20), 'high' (15) o 'ultra' (cerca de 10). auto empieza en medium, baja cuando el flujo se atasca y sube tras unos 5 s limpios, nunca por encima de max.

• Error nuevo: no_page (estado 409), cuando data() o quality() vienen antes de page().

Por ahora solo el paquete de TypeScript (@miblo/status) tiene estos métodos; Python todavía no, pero la ruta POST /sdk/v1/screen/page (y screen/data y screen/quality) está en la referencia.

card()#

await screen.card({
  v: 1,
  title: 'Steps',
  icon: 'steps',
  items: [
    { t: 'big', value: '8,432', label: 'today' },
    { t: 'ring', value: 0.61, label: 'goal 14k', color: 'amber' },
  ],
});

screen.card({
    "v": 1,
    "title": "Steps",
    "icon": "steps",
    "items": [
        {"t": "big", "value": "8,432", "label": "today"},
        {"t": "ring", "value": 0.61, "label": "goal 14k", "color": "amber"},
    ],
})

Los campos de la tarjeta#

La tarjeta completa pesa como máximo 1024 bytes. Los campos desconocidos se descartan; un tipo de elemento desconocido rechaza la tarjeta.

Los elementos#

• label: hasta 16 caracteres.

• fx: una palabra, un efecto que el propio Miblo calcula (sin archivo, sin escritura en la flash). Una palabra que el elemento no acepta rechaza la tarjeta (bad_request). Lo que hace y cuesta cada uno, y los campos de mesh, están en la guía de Animaciones de pantalla (capítulo 5).

• id, range y live: un gráfico en vivo (Miblo 1.27), alimentado por push(): ver abajo.

• color: amber, blue, green, red, white o grey. Sin uno, cada tipo tiene el suyo (big blanco, ring coral, bar violeta, spark azul, text gris). No hay colores hexadecimales en la v1.

• icon: steps, heart, water, coffee, sun, moon, cloud, bolt, check, star, clock, calendar, chart, music, mail, code.

Cómo se trata el texto#

• Las secuencias de espacios se vuelven uno solo, se eliminan los caracteres invisibles, de control y bidi, se recortan los extremos y cada cadena se corta en su límite.

• Las frases de Miblo se rechazan (bad_request): una cadena que empieza como uno de los avisos de Miblo (approved:, phone:, miblo:, allow?, task: y sus formas en portugués) o que usa las frases de alerta del Miblo Desk ("NEEDS YOU", "Asked permission", "Asked a question" y sus traducciones). La pantalla de apps nunca se hace pasar por una alerta de Miblo.

• El campo con el problema llega en field, con una forma como items[1].items[0].value.

La vida de una tarjeta#

Una tarjeta vive en la memoria del Miblo Desk, no en su flash: cambiarla cada minuto no cuesta nada. Cuando el Miblo se reinicia, el puente envía la tarjeta de nuevo dentro de 15 minutos. Una tarjeta que no se actualiza durante 24 horas se descarta (la pantalla muestra "sem dados" con el nombre de tu programa).

Devuelve { ok, current, delivered, gadgets }: current dice si tu pantalla es la que está ahora en la pantalla de apps. Tarjetas: 2 por segundo, ráfagas de 5.

push()#

Un gráfico que cambia todo el tiempo (CPU, audio, un sensor) tiene dos modos desde Miblo 1.27. En casi tiempo real, el valor viaja con cada tarjeta y el fx del elemento anima el cambio en el Miblo: simple, pero cada tarjeta es una solicitud que le cuesta al Miblo Desk de 40 a 400 ms, y un elemento con un efecto llega a unos 10 fps en una tarjeta simple (5 bajo una animación). En el modo fluido, el elemento declara live y las muestras pasan por push(), a la tasa que quieras:

await screen.card({ v: 1, title: 'CPU', items: [
  { t: 'ring', id: 'cpu', value: 0.4, range: [0, 100], label: 'now', live: { hz: 10, seconds: 3 } },
  { t: 'spark', id: 'hist', range: [0, 100], label: 'last 6 s', live: { hz: 10, seconds: 3 } },
] });
screen.push('cpu', 42.5);                // or screen.push({ cpu: 42.5, hist: 42.5 })

screen.push("cpu", 42.5)                 # or screen.push(cpu=42.5, hist=42.5)

El paquete guarda las muestras con su hora y las envía al puente cada 500 ms (o cada 32 muestras). El puente las reúne en lotes de seconds (3 s): remuestrea la ventana a hz × seconds valores, cuantiza cada uno dentro del range y envía una solicitud por lote al Miblo, que reproduce el lote con su propio reloj, a 24 a 30 fps, redibujando solo el rectángulo del gráfico.

El búfer es necesario: el Miblo solo reproduce cuando tiene un lote completo y el siguiente ya viene en camino. Cuesta un retraso de 3 s, y eso se compensa porque el siguiente lote se carga en segundo plano mientras se muestra el actual: la reproducción nunca espera a la red. Un lote tardío mantiene la última muestra (late); dos lotes en la cola descartan el más antiguo.

• live: { hz, seconds }: hz de 1 a 30 (por defecto 10), seconds de 1 a 5 (por defecto 3). Solo en spark, ring y bar, y como máximo 2 elementos en vivo por tarjeta (fuera o dentro de un row): un tercero se rechaza (live_too_many). El fx en un elemento en vivo se ignora.

• id: de 1 a 16 caracteres [a-z0-9_-], único en la tarjeta, obligatorio con live: es la clave que usa push().

• range: [min, max]: números finitos, min < max; obligatorio en un spark, [0, 1] por defecto en un ring y un bar. Las muestras se cuantizan dentro de él.

• Un lote por tarjeta: los elementos en vivo de una tarjeta comparten los mismos seconds (uno distinto se rechaza, field items[1].live.seconds), y sus hz × seconds suman 180 como máximo (dos elementos a 30 Hz × 3 s lo cumplen; 30 Hz × 5 s dos veces se rechaza).

• push() hasta 60 veces por segundo por id (más rápido se fusiona). El paquete envía lo que está esperando cada 500 ms o 32 muestras, como POST /sdk/v1/screen/live con 1 a 128 muestras, cada una de máximo 60 s de antigüedad; el puente acepta 10 de estas por segundo (ráfagas de 20) y responde { ok, accepted, unknown } (unknown: ids para los que tu tarjeta actual no tiene un elemento en vivo, descartados). Un lote por Miblo cada seconds, hasta 1 KB. Nada va a la flash.

• push() nunca lanza un error: un envío que el puente rechazó va a screen({ tool, onPushError }) (Python: screen(tool, on_push_error=...)), si no, se descarta. await screen.flush() envía lo que está esperando ahora y lanza lo que un envío en segundo plano habría reportado.

• screen.status() lleva live: una entrada por id, con i y r (su lugar en la tarjeta), hz, seconds, seq, value (la última muestra), buffered (lotes en mano, 0 a 2), playing, late y real: { fps, drawMs }, lo que mide el Miblo. stop(), clear() y una tarjeta nueva sin el id terminan el flujo.

La guía de Animaciones de pantalla tiene el capítulo "Gráficos en vivo: dos modos", con una receta y la tabla de cuál modo elegir; la app Demo ao vivo de la tienda de apps del Desk muestra ambos lado a lado.

frame()#

Una imagen de 240x240 en uno de los 4 espacios de la flash de Miblo.

import fs from 'node:fs';
await screen.frame(0, fs.readFileSync('background.png'));

with open("background.png", "rb") as f:
    screen.frame(0, f.read())

Lo que puedes enviar:

• un PNG (de 8 bits, RGB o RGBA, no entrelazado, hasta 4096 de lado y 4 millones de píxeles en total): se ajusta a 240x240 manteniendo sus proporciones;

• píxeles RGBA crudos: { rgba, w, h } (TS, con un Uint8Array) o {"rgba": bytes, "w": ..., "h": ...} (Python);

• un archivo MFRM1 listo (el formato de Miblo).

El paquete envía un PNG o píxeles RGBA como base64 dentro de una solicitud de máximo 1 MiB, así que en la práctica un archivo PNG debe quedar por debajo de unos 760 KB y el RGBA crudo por debajo de unos 196.000 píxeles (443x443); más allá la respuesta es too_large (413). Envía un PNG de 240x240 y nada de esto importa.

El computador convierte la imagen a como máximo 64 colores, la codifica por filas y lo verifica todo antes de enviar; no hace falta ningún otro software. Un SVG o HTML lo renderizas tú mismo (un canvas, sharp, resvg...) y envías el PNG. Un fondo de colores planos y texto pesa de 5 a 30 KB; una foto suele pasar de 60000 bytes tras la reducción y se rechaza con su tamaño (too_many_colours).

Devuelve { ok, slot, bytes, colours, delivered, gadgets }. Una subida puede tardar hasta 60 s (el archivo va a cada dispositivo en trozos).

La flash se desgasta#

La flash de Miblo admite un número limitado de escrituras, y un marco se escribe en ella en cada subida. Por eso:

• cada espacio admite 1 escritura cada 10 s y 100 al día (rate_limited con retryAfter, verificado en el computador antes de convertir o enviar nada); la cuenta sobrevive a un reinicio;

• lo que cambia va en la tarjeta, no en el marco. Una capa redibuja la tarjeta sin escribir nada;

• un marco dañado o incompleto se elimina, nunca se dibuja.

Los espacios son compartidos#

Los 4 espacios pertenecen a todos los programas. Un espacio es del programa que lo escribió hasta que lo suelta (removeFrame(), clear()) o su pantalla desaparece. Escribir en el espacio de otro programa da slot_taken, con el nombre del dueño en owner.

layer()#

La tarjeta dibujada sobre un marco: escribe el fondo una vez, luego envía solo tarjetas.

await screen.layer(0, { v: 1, title: 'Steps', items: [{ t: 'big', value: '8,432', label: 'today' }] });

screen.layer(0, {"v": 1, "title": "Steps", "items": [{"t": "big", "value": "8,432", "label": "today"}]})

Es card() con bg: "frame:0". Diseña el fondo dejando espacio para los elementos: el diseño de la tarjeta es fijo según la cantidad de elementos.

Una tarjeta se dibuja sobre un marco solo cuando lo dice (bg: "frame:N"): un marco en un espacio por sí solo no se muestra. Lo mismo vale para el run() de una app que devuelve un frame: el ejecutor escribe la imagen, y la tarjeta que devuelve necesita bg: "frame:N" con el mismo espacio.

show()#

Fija tu pantalla: se queda en la pantalla de apps (sin rotación) y el Miblo Desk se queda en la pantalla de apps, como miblo mode app. show(false) la suelta.

await screen.show(true);

screen.show(True)

Devuelve { ok, shown, delivered, gadgets }. Una vez cada 10 s, para todos los programas juntos.

Una fijación retiene la pantalla para todos: mientras tu pantalla está fijada, el animate() de otro programa recibe anim_taken (retryAfter 60). Suelta (show(false)) cuando termines, sobre todo entre dos ejemplos.

peek()#

"Mira ahora": la pantalla de apps pasa al frente por 1 a 10 segundos (por defecto 10), a menos que Miblo esté alertando. Para el momento que importa (el bitcoin se movió un 5 %, el build se rompió).

await screen.peek(10);

screen.peek(10)

• Necesita una tarjeta primero (no_card).

• Una vez cada 10 minutos por programa, y como máximo una cada 10 s (ráfagas de 3) para todos los programas juntos (rate_limited con retryAfter).

• Trae tu pantalla al frente primero, a menos que otra esté fijada.

Devuelve { ok, seconds, delivered, gadgets }.

request() y release()#

Desde Miblo 1.29. "Necesito la pantalla": tu programa pide la pantalla de apps por su propio tiempo (de 5 a 120 segundos; sin seconds, el tiempo que la persona le dio a la app, 15 s por defecto), para el momento que importa (un gol, una reunión en 5 minutos), solo si no está pasando nada importante: ninguna sesión de IA esperando a la persona (un permiso, una pregunta), ninguna alerta de Miblo ni de otra app en la pantalla. Una sesión que simplemente corre no estorba.

const r = await screen.request({ seconds: 30 });
if (!r.shown) console.log('no screen:', r.why);

r = screen.request(30)
if not r["shown"]:
    print("no screen:", r["why"])

La respuesta es honesta, nunca una suposición: { ok, shown: true, seconds, delivered, gadgets } cuando tu pantalla está en el Miblo, o { ok, shown: false, why, seconds, gadgets } con why:

• Necesita una tarjeta primero (no_card). Envía la tarjeta del momento, luego pide la pantalla.

• Una app a la vez; el mismo programa puede pedir de nuevo solo 60 s después de que terminó su última retención (rate_limited con retryAfter). Pedir mientras retienes la pantalla responde los segundos que quedan (held: true), nunca la extiende.

• La rotación espera; cuando se acaba el tiempo (o con release()), vuelve la app a la que le tocaba. screen.release() devuelve { ok, released }.

• Funciona sea lo que sea que la persona haya elegido, excepto solo cuando yo lo pida; con cuando una app pide la pantalla, es la única forma en que se muestran las apps.

• status() dice request: { seconds, until } mientras tu pantalla está ahí por una solicitud (null en otro caso).

clear(), removeFrame() y status()#

status() responde { card, frames, shown, current, area, allowed, rotation, request, anim, live, budget }:

• card: tu tarjeta como la guarda el puente (con tool), o null; frames: tus espacios, [{ slot, bytes, at }] (at en segundos epoch);

• shown: fijada; current: tu pantalla es la que está ahora en la pantalla de apps; rotation: los segundos que una app se muestra cuando no tiene tiempo propio;

• area: { y, h }, la parte de la pantalla de 240x240 que recibe tu contenido. Es { y: 0, h: 240 } a menos que la persona mantenga la franja de límites arriba ("Mostrar siempre los límites arriba"): diseña tu fondo dentro de ella;

• allowed: false cuando la persona apagó la pantalla de tu app ("Mostrar la pantalla en Miblo"). Tu app sigue corriendo para sus alertas, tu tarjeta se conserva pero nunca se muestra, y frame(), animate(), peek(), show() y request() responden 200 con hidden: true y nada entregado. Envía una alerta en vez de dibujar el momento;

• request: { seconds, until } mientras una solicitud tuya retiene la pantalla, si no null; anim: tu animación (con playing o queued), si no null; live: tus gráficos en vivo, arriba;

• budget: lo que tu pantalla le cuesta al Miblo en RAM, almacenamiento y procesamiento, cada uno en bandas (ok, attention, over) con consejos en portugués e inglés. La memoria de Miblo lo explica; miblo screen status lo imprime.

Qué hace el Miblo Desk con cada llamada#

Un Miblo Desk apagado u ocupado lo pone al día el puente más tarde por sí solo. En gadgets, cada Miblo responde por sí mismo: error es offline, unpaired, rejected, busy o rate_limited (su propio límite de flash). Miblo Hub y Miblo Remote dibujan la misma tarjeta, píxel por píxel, con el código propio del Miblo Desk.

Errores y qué hacer#

Un 200 con hidden: true no es un error: la persona apagó la pantalla de tu app (ver allowed arriba).

Las tasas, para todo el computador#

Ejemplo completo: una app de pasos#

Este ejemplo usa una tarjeta, la forma antigua y obsoleta (mira Apps del Desk de página para la nueva).

El fondo va una vez; luego, cada minuto, solo cambia el número (sin escrituras en la flash).

// MIBLO_TOKEN=$(miblo sdk token) node steps.mjs
import fs from 'node:fs';
import { MibloStatus } from '@miblo/status';

const screen = new MibloStatus().screen({ tool: 'steps' });
await screen.frame(0, fs.readFileSync(new URL('./steps-background.png', import.meta.url)));
await screen.show(true);                       // or: miblo mode app

let steps = 8432;
for (;;) {
  await screen.layer(0, { v: 1, title: 'Steps', icon: 'steps', items: [
    { t: 'big', value: steps.toLocaleString('en-US'), label: 'today' },
    { t: 'ring', value: Math.min(1, steps / 14000), label: 'goal 14k', color: 'amber' },
  ] });
  await new Promise((r) => setTimeout(r, 60_000));
  steps += Math.floor(Math.random() * 120);
}

# MIBLO_TOKEN=$(miblo sdk token) python3 steps.py
import os, random, time
from miblo_status import MibloStatus

screen = MibloStatus().screen("steps")
with open(os.path.join(os.path.dirname(__file__), "steps-background.png"), "rb") as f:
    screen.frame(0, f.read())
screen.show(True)                              # or: miblo mode app

steps = 8432
while True:
    screen.layer(0, {"v": 1, "title": "Steps", "icon": "steps", "items": [
        {"t": "big", "value": f"{steps:,}", "label": "today"},
        {"t": "ring", "value": min(1, steps / 14000), "label": "goal 14k", "color": "amber"},
    ]})
    time.sleep(60)
    steps += random.randint(0, 120)

El ejemplo de TypeScript y su imagen de fondo vienen dentro del paquete @miblo/status (examples/steps.mjs y examples/steps-background.png); la copia de allí tiene etiquetas en portugués (Passos, hoje), el mismo programa por lo demás. Hace un bucle infinito por diseño: deténlo con Ctrl+C, luego miblo screen clear (o screen.clear()) para sacar la pantalla.