Tutorial del primer dispositivo

Esta es la página que te lleva por todo el camino: de un tenant vacío a un dispositivo cuya telemetry se almacena, se transmite en vivo y se prueba en la blockchain — usando únicamente curl y la vía de ingesta HTTP. Síguela de arriba abajo y tendrás un dispositivo funcional y anclado al final.

Cada comando es real y ejecutable por copiar y pegar. Reemplaza los marcadores (<...>) y los IDs de ejemplo con los valores que vayas obteniendo conforme avanzas.

Lo que construirás

flowchart LR
  A["1. Iniciar sesión<br/>(JWT)"] --> B["2. Profile"]
  B --> C["3. Clave de provisioning"]
  C --> D["4. Reclamar dispositivo<br/>(device_id + api_key)"]
  D --> E["5. Enviar telemetry"]
  E --> F["6. Verlo en vivo"]
  F --> G["7. Anclado + verificado"]

Requisitos previos

Un tenant de CORE-M y un login de admin del tenant (email + contraseña).
curl y jq (opcional, para una salida bonita).
La URL base de la API. Usamos https://api.kronoxdata.com; la ingesta de telemetry está en el puerto 8080.

Tutorial

Inicia sesión y obtén un token de admin del tenant.

El login del panel intercambia tus credenciales por un JWT (un token de acceso firmado con Ed25519). Lo usarás como bearer token para cada llamada de admin en este tutorial — crear profiles, keys y leer el estado de anchoring.
Ventana de terminal
```
curl -X POST https://api.kronoxdata.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "<your-password>"
  }'
```
```
{
  "access_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
Guárdalo para reutilizarlo:
Ventana de terminal
```
export COREM_JWT="eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
```
Si tu tenant requiere MFA, el login devuelve un desafío MFA en lugar de un token; completa el paso TOTP y recibirás el token de acceso. Consulta Seguridad y cumplimiento.

Crea un device profile.

Un profile contiene los valores por defecto que un dispositivo hereda — tags, política de anchoring, esquema de telemetry y política OTA. Puedes omitir esto y usar los valores por defecto de tu tenant, pero crear uno ahora hace que el dispositivo arranque configurado. Mantén el esquema permisivo para tu primer dispositivo.

curl -X POST https://api.kronoxdata.com/api/v1/profiles \
  -H "Authorization: Bearer $COREM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temperature Sensor v2",
    "type": "temp-sensor",
    "default_tags": { "region": "eu" },
    "anchoring_policy": { "mode": "merkle_batch" }
  }'

{ "profile_id": "prof_temp_v2", "name": "Temperature Sensor v2" }

Crea una clave de provisioning (plantilla).

Una plantilla de provisioning emite una provision key de un solo uso que un dispositivo presenta para reclamar su propia identidad en campo. Referencia el profile del paso 2 y puede restringir qué hardware_ids pueden reclamarla y cuándo expira la key.

curl -X POST https://api.kronoxdata.com/api/v1/provisioning/templates \
  -H "Authorization: Bearer $COREM_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "factory-batch",
    "profile_id": "prof_temp_v2",
    "hardware_id_pattern": "HW-*",
    "one_time": true,
    "expires_in_seconds": 86400
  }'

{
  "template_id": "tmpl_5d1a",
  "provision_key": "pk_live_Td9vQ2sR... (shown once)"
}

La provision_key se muestra una vez — este es el secreto que flasheas en, o entregas a, el dispositivo. Guárdala:

export PROVISION_KEY="pk_live_Td9vQ2sR..."

Desde el “dispositivo”, reclámalo.

Ahora actúa como el dispositivo. El dispositivo presenta su provision key, un nombre legible por humanos y su hardware_id estable. CORE-M deriva el tenant de la key (nunca de un campo del cliente), crea el registro del dispositivo y emite su API key de larga duración — devuelta exactamente una vez.
Ventana de terminal
```
curl -X POST https://api.kronoxdata.com/api/v1/provision \
  -H "Content-Type: application/json" \
  -d "{
    \"provision_key\": \"$PROVISION_KEY\",
    \"device_name\": \"Lobby sensor\",
    \"hardware_id\": \"HW-001\"
  }"
```
```
{
  "device_id": "dev_8f3a",
  "api_key": "sk_live_9Qk3pR2wXn7vJ4mB..."
}
```
Esa api_key (prefijo sk_live_) es la credencial del dispositivo. Guarda ambas:
Ventana de terminal
```
export DEVICE_ID="dev_8f3a"
export DEVICE_KEY="sk_live_9Qk3pR2wXn7vJ4mB..."
```
El provisioning es idempotente por hardware_id. Reclamar de nuevo con HW-001 devuelve el mismo device_id y una api_key vacía — el dispositivo debería seguir usando la key que obtuvo la primera vez. Si la perdiste, rota una nueva (consulta Rotación de credenciales).
Envía tu primer punto de telemetry.

Autentícate con la key del dispositivo y haz POST de un TelemetryPoint al endpoint de ingesta en el puerto 8080. El timestamp es RFC 3339; todo lo medido va en numeric_values, los estados en string_values.
Ventana de terminal
```
curl -X POST https://api.kronoxdata.com:8080/api/v1/telemetry \
  -H "Authorization: Bearer $DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"points\": [{
      \"device_id\": \"$DEVICE_ID\",
      \"timestamp\": \"2026-05-29T14:30:00Z\",
      \"numeric_values\": { \"temperature\": 22.5, \"humidity\": 65 },
      \"string_values\":  { \"status\": \"ok\" }
    }]
  }"
```
```
{ "accepted": 1, "rejected": 0 }
```
accepted: 1 significa que el punto pasó la auth, se emparejó con un dispositivo conocido y pasó la validación de esquema. Detrás de ese ack se actualizó el last_seen del dispositivo, este cambió de offline → online, y el punto se enriqueció, se hizo doble escritura en los stores hot y cold, se hizo fan-out en vivo y se puso en cola para anchoring. Consulta Envío de telemetry para la forma completa y las demás codificaciones.
Míralo en vivo.

El punto ya está en el panel. Abre el panel de tu tenant y el tile del dispositivo para Lobby sensor muestra temperature: 22.5 actualizándose en tiempo real — estos tiles leen el store hot y el fan-out en vivo.

Para consumir el mismo stream de forma programática, suscríbete por WebSocket. El dashboard-bff envía cada punto validado de un dispositivo que estés observando:
Ventana de terminal
```
# Subscribe to live telemetry for one device (WebSocket)
wscat -c "wss://api.kronoxdata.com/ws?token=$COREM_JWT" \
  -x '{"subscribe":"telemetry.live","device_id":"dev_8f3a"}'
```
Cada punto aceptado llega en telemetry.live.{tenant}.{device} en cuestión de milisegundos desde la ingesta.
Confirma que se ancla — y verifica la proof.

Esta es la parte que hace que CORE-M sea CORE-M. El hash de tu punto se une a un Merkle batch, la raíz del batch se compromete en la blockchain BSV en una transacción, y puedes verificar este punto exacto contra ese compromiso on-chain.

Tu punto en cola se une a un Merkle batch, que se vacía tras 1000 puntos o 30 segundos. Puedes observar cómo se forman los batches en el feed de anchors:
Ventana de terminal
```
curl "https://api.kronoxdata.com/api/v1/anchors" \
  -H "Authorization: Bearer $COREM_JWT"
```
Luego pídele al verificador una proof portable de este punto exacto. El verificador recalcula el hash canónico a partir de los campos que envías y lo busca — así que los valores deben coincidir exactamente con lo que enviaste. Mientras el punto sigue pendiente devuelve NOT_FOUND; una vez que el batch se ancla y se confirma, devuelve el Merkle path más una proof SPV/BEEF de inclusión en bloque:
Ventana de terminal
```
curl -X POST "https://api.kronoxdata.com/api/v1/verify/raw" \
  -H "Authorization: Bearer $COREM_JWT" \
  -H "Content-Type: application/json" \
  -d "{
    \"device_id\": \"$DEVICE_ID\",
    \"timestamp\": \"2026-05-29T14:30:00Z\",
    \"numeric_values\": { \"temperature\": 22.5, \"humidity\": 65 },
    \"string_values\":  { \"status\": \"ok\" }
  }"
```
```
{
  "verified": true,
  "txid": "4f3b9a...c1d0",
  "merkle_root": "a1b2c3...",
  "merkle_path": [{ "hash": "…", "is_right": false }, { "hash": "…", "is_right": true }],
  "block_height": 871234,
  "beef_hex": "0100beef..."
}
```
verified: true significa que el verificador recalculó el hash canónico de tu punto (SHA256(device_id || timestamp_seconds_be || jcs_payload)), recorrió el Merkle path hasta la raíz y confirmó que esa raíz reside en la transacción de blockchain nombrada. Tu primera lectura es ahora demostrable ante cualquiera, para siempre. Consulta Anchoring y Merkle proofs para toda la maquinaria.

Resolución de problemas

accepted: 0 / el punto nunca aparece. La causa más común es un dispositivo desconocido — el punto no coincidió con ningún registro de dispositivo y se descartó silenciosamente (telemetry_dropped_total{reason="unknown_device"}). Comprueba que hiciste POST con el device_id correcto del paso 4 (el valor dev_..., no el hardware_id), y que el provisioning realmente tuvo éxito.

401 / UNAUTHENTICATED. Credencial errónea o expirada. La telemetry debe usar la api_key del dispositivo (sk_live_...), no el JWT de admin. Las llamadas de admin (profiles, provisioning, estado de anchoring) deben usar el JWT. Los JWTs expiran — vuelve a ejecutar el paso 1 si el tuyo ha caducado.

INVALID_ARGUMENT en la telemetry. El telemetry_schema de tu profile requiere una métrica que tu punto omite. O bien inclúyela o relaja el esquema en el profile.

A dónde ir después

Elige un protocolo más rico

Resumen de conexión de dispositivos Mueve este dispositivo a MQTT, CoAP/DTLS, LwM2M o detrás de un gateway — sin necesidad de reaprovisionar.

Opera el dispositivo

Device RPC y comandos Envía comandos a tu dispositivo — fijar config, leer estado, reiniciar — y correlaciona respuestas.

Actualizaciones OTA Distribuye firmware verificado en un rollout escalonado, controlado por canary, con rollback.

Rotación de credenciales Rota la api_key del dispositivo con una ventana de solapamiento, o revócala de inmediato.

Prueba los datos

Anchoring Cómo los hashes de los puntos de telemetry se convierten en Merkle batches comprometidos on-chain.

Verificación Recalcula el hash, recorre el Merkle path y confirma la inclusión en bloque — sin confianza.