Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

Añadir y reclamar dispositivos

Añade dispositivos a mano, deja que se registren solos con una clave de aprovisionamiento o reclama un dispositivo con licencia mediante su número de serie y su código de reclamación; libéralo para devolverlo al grupo.

Hay varias formas de añadir un dispositivo a tu organización. Esta página cubre las tres que más usas: añadir un dispositivo manualmente, dejar que los dispositivos se registren solos con la clave de aprovisionamiento del perfil y reclamar un dispositivo licenciado. Para archivos con muchos dispositivos, consulta Importar dispositivos en bloque; para sensores LoRaWAN, consulta Añadir un dispositivo OTAA.

FormaÚsalo paraRequiere
Añadir manualmenteAlgunos dispositivos que configuras tú mismoCrear dispositivos (Admin)
AutoaprovisionamientoMuchos dispositivos del mismo tipo que se registran solosGestionar el aprovisionamiento (Admin)
ReclamarDispositivos licenciados con identidad de fábricaReclamar dispositivos (Admin)

El cajón Nuevo dispositivo

Abre Dispositivos y selecciona Nuevo dispositivo. Cuando tu organización tiene varias formas de entrada, el cajón pregunta ¿Qué vas a añadir?:

OpciónAñade
La opción de dispositivo licenciado («Con el código de su página Cloud: escanéalo o escríbelo.»)Un router, gateway o controlador licenciado, reclamándolo
Cámara o grabadorUna cámara IP o grabador. Consulta Añadir una cámara o grabador.
Dispositivo de redUn agente SNMP u otro equipo que la plataforma consulta. Consulta Endpoints de protocolo.
Gateway LoRaWANUn gateway Basics Station. Consulta Añadir un gateway LoRaWAN.
Dispositivo LoRaWANUn sensor LoRaWAN. Consulta Añadir un dispositivo OTAA.
Otro dispositivoCualquier dispositivo que se conecte por sí mismo mediante MQTT o HTTP

Una opción aparece solo cuando su módulo está activado y tienes sus permisos. Elegir otra forma vuelve a la lista.

Añadir un dispositivo manualmente

  1. En el cajón, elige Otro dispositivo.
  2. Introduce un Nombre (único en tu organización, hasta 128 caracteres), una Etiqueta opcional y elige el Perfil de dispositivo (El perfil predeterminado si no eliges ninguno).
  3. Activa Este dispositivo es un gateway solo para un dispositivo que informa por otros dispositivos.
  4. Selecciona Crear dispositivo.
  5. Copia el token de acceso ahora: solo se muestra una vez. Selecciona Lo he guardado cuando termines, o Abrir dispositivo.

La configuración de dispositivos de tu organización decide si un dispositivo nuevo recibe un token de acceso de inmediato: Emitir un token de acceso para dispositivos nuevos (activado por defecto; Dispositivos > ⋯ > Configuración). Si tus dispositivos usan MQTT básico o X.509, desactívalo: el dispositivo se crea entonces sin credencial y la estableces mediante la API. Consulta Credenciales de dispositivo.

Autoaprovisionamiento con una clave de aprovisionamiento

El dispositivo conoce la clave y el secreto de aprovisionamiento de su perfil. En el primer arranque pide a Hermetry su propia credencial, así que no tienes que crear cada dispositivo de antemano.

Configurar el perfil

  1. Abre el perfil y su pestaña Aprovisionamiento.
  2. Elige la Estrategia de aprovisionamiento:
EstrategiaComportamiento
DesactivadaTodas las solicitudes fallan (strategy_disabled).
Permitir crear dispositivos nuevosHermetry crea un dispositivo con el nombre que envía el dispositivo y devuelve su credencial. El dispositivo empieza En cuarentena.
Solo dispositivos preaprovisionadosSolo pueden aprovisionarse los dispositivos que creaste antes (por nombre). Recomendado para dispositivos vendidos en volumen, porque una clave en el firmware puede extraerse.
  1. Guarda y, después, selecciona Crear clave en Claves de aprovisionamiento. Copia el secreto: «Copia el secreto ahora. No volverás a verlo.» Selecciona Lo he copiado.

La tabla de claves muestra cada Id de clave, su Estado (En uso, Antigua, aún aceptada, Revocada), Creada, Aceptada hasta y Último uso. Los botones de clave actúan de inmediato; no forman parte de Guardar cambios.

Nota

Un dispositivo creado con Permitir crear nuevos dispositivos espera en cuarentena: puede conectarse, pero sus datos se descartan hasta que un administrador lo active. Los dispositivos en cuarentena cuentan para su límite de dispositivos. Consulte Cuarentena para dispositivos autorregistrados.

Lo que envía el dispositivo

Conéctate por TLS con el usuario provision y contraseña vacía, suscríbete a v1/provision/res y, después, publica en v1/provision/req:

{"deviceName": "boiler-07", "provisionDeviceKey": "pk_8f3b2c1e9d4a7b60", "provisionDeviceSecret": "ps_1c9e7f2a4b6d8e03"}

La respuesta en v1/provision/res:

{"status": "SUCCESS", "credentialsType": "ACCESS_TOKEN", "credentialsValue": "aZ3…"}

Después, el dispositivo inicia sesión con su nueva credencial. Por HTTPS, envía el mismo cuerpo a POST /api/v1/provision sin cabecera bearer; un rechazo también responde 200, con "status": "FAILURE".

RechazoSignificado
device_existsExiste un dispositivo con este nombre. Hermetry nunca vuelve a emitir credenciales para un nombre existente.
provision_key_invalidClave desconocida o secreto incorrecto.
provision_key_revokedLa clave fue revocada o su periodo de gracia terminó.
strategy_disabledLa estrategia del perfil está Desactivada.
rate_limitedDemasiadas solicitudes (consulta los límites abajo).

Límites: aprovisionamientos correctos por clave y hora (60 por defecto), 5 solicitudes por nombre de dispositivo y hora, y 10 solicitudes por dirección de origen y minuto.

Sustituir o revocar una clave

  • Sustituir clave crea una nueva clave y un nuevo secreto. La clave antigua sigue aceptada durante Días que la clave antigua sigue funcionando (30 por defecto, de 0 a 365; 0 la detiene de inmediato) y, después, se revoca automáticamente. Los dispositivos que configures a partir de ahora necesitan la nueva clave.
  • Revocar detiene una clave de inmediato y de forma definitiva. Escribes el id de la clave y das un motivo («Por ejemplo: el secreto se compartió por error.»). Los dispositivos que ya se registraron siguen funcionando.

Reclamar un dispositivo licenciado

Los routers, gateways y controladores con licencia salen de fábrica con su propia identidad: un número de serie, un certificado y un secreto de reclamación. Antes de reclamar uno, no pertenece a ninguna organización, y Hermetry descarta sus datos.

Reclamarlo

  1. Inicia sesión en el panel local del dispositivo y abre su página Cloud. Activa la conexión en la nube si está desactivada; el dispositivo se conectará a Hermetry por sí mismo.
  2. Pulsa Abrir ventana de reclamación en la misma página. La ventana permanece abierta 15 minutos.
  3. En Hermetry, abre Dispositivos > Nuevo dispositivo y elige la opción de dispositivo licenciado.
  4. Elige cómo introducir el código:
    • Escanear el código de la pantalla del dispositivo: apunta la cámara del teléfono al QR de la página Cloud y copia en el campo el texto que muestra.
    • Escribir número de serie y código: escribe el Número de serie (de 6 a 32 letras, dígitos y guiones, por ejemplo RT420-2610-000123) y el Código de reclamación (20 caracteres, por ejemplo 7KQ2-M9XH-D4TB-6WRA-1NZC).
  5. Selecciona Comprobar. En Listo para añadir, introduce un Nombre del dispositivo (vacío = el número de serie).
  6. Selecciona Añadir dispositivo. «El dispositivo se ha añadido. Se conecta en pocos segundos cuando está en línea.»

El dispositivo se añade con una copia del perfil de su modelo y su credencial de certificado X.509. Su conexión se reinicia dentro de tu organización.

Nota

No hay etiqueta impresa de reclamación. El código QR y el código de reclamación solo se muestran en el panel local del dispositivo, detrás de su inicio de sesión.

Cuando una reclamación falla

MensajeSignificado
«La ventana de reclamación del dispositivo está cerrada. …»Pulsa Abrir ventana de reclamación en la página Cloud y vuelve a intentarlo en menos de 15 minutos.
«Este dispositivo pertenece a otra cuenta. …»Pide al vendedor o al propietario anterior que lo libere y, después, vuelve a intentarlo.
«El número de serie o el código de reclamación no es correcto. …»Revisa ambos en la página Cloud del dispositivo.
«Demasiados intentos por ahora. Espera una hora y vuelve a intentarlo.»Las reclamaciones fallidas están limitadas a 5 por número de serie, 20 por usuario y 30 por dirección y hora.
«Se ha alcanzado el límite de dispositivos de tu plan. …»Retire un dispositivo o actualiza primero el plan.
«Este dispositivo se está añadiendo ahora mismo. …»Espera un momento y revisa la lista de dispositivos.
«Este dispositivo ya está en esta cuenta.»No hay nada que hacer.

Reclamar por API

POST/tenant/{tenantId}/api/iot/claim

Reclama un dispositivo con licencia mediante su número de serie y su código de reclamación. Opcional: name para el nuevo dispositivo, iotAssetId para colocarlo de inmediato y dryRun para comprobar qué se reclamaría sin reclamarlo (una simulación cuenta para el límite de intentos igual que una reclamación real). El código de reclamación nunca se muestra en la respuesta. Un rechazo incluye uno de not_claimable, bad_secret, press_claim_button, device_limit o rate_limited en details.reason.

Cuerpo de la solicitud application/json

{
    "serial": "RT420-2610-000123",
    "secret": "7KQ2M9XHD4TB6WRA1NZC",
    "name": "Pump house router"
}

Ejemplo curl

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/claim' \
  -H 'Content-Type: application/json' \
  -d '{"serial":"RT420-2610-000123","secret":"7KQ2M9XHD4TB6WRA1NZC","name":"Pump house router"}'

Respuestas

201Created
{
    "status": "claimed",
    "serial": "RT420-2610-000123",
    "deviceId": "…",
    "model": "…",
    "profileId": "…"
}
200OK
{
    "status": "claimable",
    "serial": "RT420-2610-000123",
    "model": "…",
    "type": "…",
    "hw": "…"
}
400Bad Request
{
    "message": "The serial or claim code is not correct.",
    "code": "VALIDATION_ERROR",
    "details": {
        "reason": "bad_secret"
    }
}
403Forbidden
{
    "message": "…",
    "code": "FEATURE_NOT_AVAILABLE",
    "details": {
        "reason": "device_limit"
    }
}
409Conflict
{
    "message": "Open the claim window on the device's Cloud page (it stays open for 15 minutes), then try again.",
    "code": "CONFLICT",
    "details": {
        "reason": "press_claim_button"
    }
}
429Too Many Requests
{
    "message": "…",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
        "reason": "rate_limited"
    }
}

La respuesta 200 con "status": "claimable" corresponde a una simulación. Una reclamación de un dispositivo que tu organización ya posee responde 200 con "status": "claimed" y "alreadyOwned": true. Una reclamación en curso responde {"status": "in_progress", "serial": "…"}. 409 con not_claimable significa que el número de serie es desconocido, está retirado o pertenece a otra cuenta.

La pestaña Propiedad y la liberación de un dispositivo

La pestaña Propiedad de un dispositivo reclamado muestra su Número de serie, su Modelo, su Certificado (válido hasta) y la fecha en que se Añadió a esta cuenta. Un dispositivo creado en tu cuenta en lugar de reclamado indica No es un dispositivo de fábrica.

Para ceder un dispositivo con licencia a otro propietario, selecciona Liberar dispositivo en la pestaña Propiedad. El cuadro de diálogo ¿Liberar este dispositivo? explica:

  • El dispositivo sale de esta cuenta y su conexión se cierra.
  • Sus datos permanecen en el historial de esta cuenta.
  • El siguiente propietario necesita acceso físico al dispositivo para añadirlo.
  • Restablecer de fábrica el dispositivo no lo libera: solo lo hace esta acción.

Escribe el número de serie para confirmar y, opcionalmente, indica un motivo. El dispositivo vuelve al grupo de fábrica.

Un dispositivo también puede liberarse con el botón Liberar de su propia página de la nube. Entonces recibirás un aviso «Un dispositivo se ha liberado solo de tu cuenta». Si nadie de tu equipo lo hizo, contacta con soporte.

Relacionado