> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md).
# Registo de Dispositivos
Registe um dispositivo no Kilo IoT via LNS, MIOTY, Tracker, MQTT ou o Emulador — construa o seu Digital Twin, perfil e mapeamentos de métricas.
Cada dispositivo registado no Kilo IoT Server torna-se um Digital Twin — uma representação digital completa que espelha o estado atual do dispositivo, a configuração, o histórico de telemetria e os padrões de comportamento. O Digital Twin persiste mesmo quando o dispositivo físico está offline, proporcionando uma visão operacional contínua de toda a sua implementação. Como a associação ao dispositivo físico é opcional, pode criar e configurar totalmente um perfil de dispositivo antes de o hardware estar ligado — assim, a configuração e a colocação em serviço do hardware não têm de acontecer ao mesmo tempo. Com o [Emulador](/kilo-docs-pt/kilo-iot-server/devices/emulated-devices.md), pode ir mais longe e fazer com que o dispositivo produza dados antes mesmo de o hardware existir.
O registo do dispositivo é o processo de criar este Digital Twin e ligá-lo a um dispositivo físico através de um conector. O fluxo de registo orienta-o ao dar nome ao dispositivo, associá-lo a um conector, configurar o seu perfil de comunicação e mapear as medições que ele reporta.
## Pré-requisitos
Antes de registar um dispositivo, precisa de:
* **Um conector** — pelo menos um conector LNS, Mioty, Tracker, MQTT (Cloud ou External) ou Emulator tem de estar configurado. Consulte a [Conectores](/kilo-docs-pt/kilo-iot-server/connectors.md) e a [documentação do Conector MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector.md) .
* **Identificadores do dispositivo** — para dispositivos LoRaWAN: o Device EUI e o AppKey (normalmente impressos no dispositivo ou na respetiva embalagem). Para endpoints MIOTY: o End Point EUI e a Network Session Key. Para dispositivos de rastreio: o Unique ID fornecido pelo fabricante. Para dispositivos MQTT: o segmento de tópico ao nível do dispositivo sob o qual o dispositivo publica, usado como Device ID no registo do dispositivo; tem de corresponder exatamente ao segmento publicado (os espaços em branco são removidos na entrada). **Os dispositivos emulado não precisam de nada disto** — o Device ID é escolhido por si.
* **Apenas para dispositivos MQTT — o dispositivo tem de estar a publicar antes de o mapeamento poder ser concluído.** A lista pendente Connector key no separador Mapping é preenchida a partir das chaves de payload efetivamente recebidas do dispositivo. Consulte a [secção de comportamento específico do MQTT](#mqtt-specific-behavior) abaixo para o fluxo de trabalho em duas passagens.
## Onde começar
Existem dois pontos de entrada para o registo de dispositivos — ambos abrem a mesma caixa de diálogo Gerir dispositivo:
1. **Dispositivos** — Clique **Dispositivos** na barra lateral. Esta página mostra todos os dispositivos de todos os conectores. Clique em **Adicionar dispositivo** no canto superior direito.
2. **Ação da linha do conector** — Na **Conectores** página, clique no botão **+ Adicionar dispositivo** em qualquer linha de conector. A caixa de diálogo abre com esse conector pré-selecionado.
O formulário do dispositivo está organizado tanto para ecrãs pequenos como para desktop, para que possa registar hardware a partir de um telefone enquanto está no local de instalação.
## Fase 1 — Criar o perfil do dispositivo
A caixa de diálogo abre em modo **Adicionar dispositivo** , mostrando apenas a secção **Informações do dispositivo** . Ainda não estão visíveis separadores ou navegação — o primeiro passo é simplesmente identificar o dispositivo.
* **Fotografias do dispositivo** — Opcionalmente, carregue fotografias do dispositivo físico para identificação visual.
* **Nome do dispositivo** — Introduza um nome descritivo (obrigatório). Use uma convenção de nomes que escale ao longo da sua implementação — por exemplo, incluindo a localização ou o tipo de dispositivo no nome.
Clique em **Guardar**. O Digital Twin é criado apenas com o nome e a fotografia opcional. A caixa de diálogo passa automaticamente para o modo de edição.
## Fase 2 — Configurar ligação, métricas e registos
Após a primeira gravação, a caixa de diálogo reabre com os separadores **Informações do dispositivo**, **Ligação**, **Mapping** e **Logs** e um botão **Seguinte** para navegar entre eles. É aqui que associa o dispositivo a um conector e configura os seus dados. Surgem mais dois separadores quando se aplicam: **Comandos e estados** num dispositivo que possa receber downlinks, e **Emulador** num dispositivo associado ao conector Emulator.
### Separador Ligação
Este separador associa o Digital Twin ao dispositivo que o alimenta através de um conector. A lista pendente mostra os conectores que a sua organização possui, por nome e tipo, e os campos abaixo alteram-se para corresponder ao que selecionar.
#### Para dispositivos LoRaWAN (conector LNS)
1. **Tipo de conector** — Selecione o conector LNS na lista pendente. Se existir apenas um conector LNS, este poderá já estar pré-selecionado.
2. **Device EUI** — Introduza o identificador LoRaWAN exclusivo do dispositivo (cadeia hexadecimal de 8 bytes, apresentada como `HH HH HH HH HH HH HH HH`). Normalmente está impresso na etiqueta ou embalagem do dispositivo. Depois de um dispositivo físico estar associado, este campo não pode ser alterado sem primeiro desvincular o dispositivo.
**Ler código QR** — Em vez de transcrever dezasseis caracteres hexadecimais de uma etiqueta, clique em **Ler código QR** e aponte a câmara do seu portátil ou telefone para o código QR no dispositivo ou na respetiva embalagem. O Device EUI é preenchido a partir do código e, quando o código também inclui o AppKey, esse campo também é preenchido. Este é o caminho mais rápido e seguro ao colocar dispositivos em funcionamento em massa — um único carácter trocado num DevEUI produz um dispositivo que, silenciosamente, nunca entra na rede.
Se o navegador não conseguir aceder a uma câmara, o scanner apresenta **"QR code scanner is not found. Please try again."** Verifique se existe uma câmara e se o navegador recebeu permissão para usar a câmara no site e tente novamente — ou introduza os identificadores manualmente.
3. **Usar modelos de perfil de dispositivo** — Marque esta opção para selecionar a partir de uma biblioteca de perfis de dispositivo conhecidos.
Os modelos de perfil de dispositivo são predefinições convenientes para dispositivos LoRaWAN conhecidos. Cada modelo inclui a classe LoRaWAN do dispositivo, a banda de frequência e um **codec** — a lógica de descodificação de payload que traduz os dados brutos de uplink binários do dispositivo em campos legíveis. Selecionar um modelo é um processo em duas etapas:
* **Marca** — Selecione o fabricante do dispositivo na lista de preenchimento automático.
* **Modelo** — Selecione o modelo do dispositivo. A lista é filtrada com base na marca selecionada.
* **Perfil** — Selecione o perfil de modelo para este dispositivo. As opções são derivadas das bandas regionais suportadas pelo modelo.
Depois de selecionar os três, o servidor obtém o modelo correspondente e aplica a sua configuração ao formulário: a classe LoRaWAN, a **classe**, **banda**, e **codec** são preenchidos automaticamente. Pode rever e ajustar estes valores antes de guardar.
Os modelos são fornecidos como auxiliares de conveniência. A descodificação correta do payload não é garantida para todas as versões de firmware ou revisões de hardware. Se o codec de um modelo produzir campos em falta ou incorretos, pode editar diretamente os **funções de código** campo (veja abaixo).
Se não usar um modelo, configure o perfil manualmente:
* **Classe** — Escolha a classe do dispositivo LoRaWAN:
* **Classe A** — O dispositivo entra em repouso entre transmissões e só abre janelas curtas de receção após cada uplink. Isto é extremamente eficiente em termos energéticos — a maioria dos sensores alimentados a bateria usa Classe A e pode funcionar durante anos com uma única bateria.
* **Classe C** — O dispositivo mantém o recetor aberto continuamente, permitindo-lhe receber comandos downlink do servidor em qualquer altura. Como o rádio está sempre a ouvir, os dispositivos Classe C consomem significativamente mais energia e normalmente são alimentados pela rede elétrica. Escolha Classe C para dispositivos que precisam de responder imediatamente a comandos, como atuadores, interruptores ou ecrãs.
* **Marca** e **Modelo** — Introduza o fabricante e o modelo do dispositivo como texto livre.
* **Banda** — Selecione a banda de frequência LoRaWAN para a sua região. A banda tem de corresponder à configuração da sua gateway e às regulamentações de rádio da sua região. Opções disponíveis: EU868 (Europa), US915 (EUA), AU915 (Austrália), AS923 (Ásia), KR920 (Coreia do Sul), IN865 (Índia), RU864 (Rússia), CN470 (China), CN779 (China), EU433 (Europa 433 MHz), ISM2400 (global 2,4 GHz). Para uma lista completa de bandas de frequência por país, consulte [Frequências LoRaWAN](/kilo-docs-pt/kilo-iot-server/connectors/lns-connector/lorawan-frequencies.md). Para uma introdução ao LoRaWAN, consulte [O que é LoRaWAN?](/kilo-docs-pt/kilo-iot-server/connectors/lns-connector/what-is-lorawan.md).
* **AppKey** — Introduza a chave de aplicação do dispositivo — a chave de encriptação LoRaWAN usada para ativação over-the-air (OTAA). Normalmente é fornecida pelo fabricante do dispositivo; verifique a embalagem do dispositivo ou a documentação oficial.
#### Adicionar ao Vault
Os credenciais do dispositivo têm o hábito de acabar num local pouco prático: um autocolante numa unidade que agora está montada a seis metros de altura num corredor de armazém. Clique em **Adicionar ao Vault** no formulário do dispositivo para guardar o Device EUI e o par de chaves do dispositivo no Key Vault, onde podem ser recuperados independentemente do hardware e da etiqueta. Para um dispositivo LoRaWAN, isto guarda o AppKey associado ao DevEUI.
Faça isto no registo, enquanto os credenciais estão à sua frente. Reconfigurar um dispositivo cujo AppKey já não tem arquivado significa voltar à própria unidade — e se a chave pode ser extraída dela nessa altura depende do fabricante, podendo exigir uma ligação com fios à placa. Consulte o [Key Vault](/kilo-docs-pt/kilo-iot-server/reports/key-vault.md).
#### Funções de código (codec)
A **funções de código** campo contém o codec do payload do dispositivo — lógica JavaScript que descodifica o payload bruto de uplink LoRaWAN do dispositivo em campos com nome. Estes campos descodificados tornam-se as **chaves do conector** visíveis no separador Mapping.
Quando seleciona um modelo de perfil de dispositivo, este campo é preenchido automaticamente com o codec do modelo. Se configurar manualmente, este campo começa vazio — poderá ser necessário colar um codec a partir da documentação do fabricante do dispositivo ou de um repositório comunitário de codecs.
Se a saída descodificada não corresponder ao que espera — por exemplo, se faltarem campos, os valores parecerem errados ou os nomes dos campos não corresponderem à documentação do seu sensor — pode editar o código diretamente. O editor é uma área de texto multilinha com formatação monoespaçada.
#### Intervalo de envio de dados
Um dispositivo transmite segundo um horário fixo — de poucos em poucos minutos, uma vez por dia, uma vez por mês — e esse horário é configurado **no próprio dispositivo**. Varia de fabricante para fabricante: alguns dispositivos são fornecidos com o intervalo já definido pelo fabricante, outros exigem que o configure quando põe o dispositivo em funcionamento. Seja como for, o horário é uma propriedade do dispositivo. O **Intervalo de envio de dados** campo é onde indica à plataforma qual é esse horário, para que saiba quando esperar dados.
Defina-o de acordo com a forma como o dispositivo está realmente configurado para transmitir. Se o dispositivo envia uma vez por dia, defina isto para **1 dia**; uma vez por mês, defina para **1 mês**. O campo começa em **1 hora** por predefinição apenas porque a plataforma precisa de um valor inicial — não tem forma de ler o horário real do dispositivo, por isso trate essa predefinição como um marcador a substituir.
Se nenhuma mensagem chegar dentro do intervalo configurado, o dispositivo é marcado como offline na lista de dispositivos e assinalado no cartão Devices da página Overview. Definir o intervalo para corresponder ao dispositivo é o que impede que um dispositivo saudável e de baixa frequência seja marcado como offline simplesmente porque está silencioso entre os relatórios agendados.
Escolha um número e uma unidade: **minuto**, **hora**, **dia**, **semana**, ou **mês**.
> **Os dispositivos emulados são a exceção.** Num dispositivo associado ao conector Emulator, este campo não é uma descrição de um horário que o hardware já segue — *é* o horário em que a plataforma emite. Consulte [Dispositivos emulados](/kilo-docs-pt/kilo-iot-server/devices/emulated-devices.md).
#### Para localizadores de veículos (conector Tracker)
1. **Tipo de conector** — Selecione o conector Tracker na lista pendente.
2. **Unique ID** — Introduza o identificador exclusivo do dispositivo do localizador.
3. **Modelo do dispositivo** — Procure e selecione a partir da biblioteca de modelos de localizadores. Comece a escrever para filtrar a lista.
4. **Url para localizador GPS** — Depois de selecionar um modelo, aparece um painel a mostrar o URL do endpoint. Clique no botão de copiar para o copiar e, em seguida, configure o seu localizador para enviar dados para este URL.
#### Para endpoints MIOTY (conector Mioty)
Selecione o conector Mioty na lista pendente e o formulário apresenta o conjunto de parâmetros MIOTY — End Point EUI, endereço curto, chave de sessão da rede e contadores. Estes campos, os respetivos intervalos válidos e o modelo que descodifica os payloads do endpoint estão documentados na íntegra em [Dispositivos MIOTY](/kilo-docs-pt/kilo-iot-server/devices/mioty-devices.md).
#### Para dispositivos emulados (conector Emulator)
Selecione o conector Emulator e o dispositivo gera a sua própria telemetria em vez de a receber — sem identificadores, sem credenciais, sem hardware. Dá-se-lhe um Device ID, escolhe-se o que mede (manual ou a partir de uma predefinição de dispositivo) e define-se com que frequência reporta. Um separador adicional **Emulador** permite então controlar os seus valores diretamente.
É assim que constrói uma implementação antes de os sensores chegarem e troca o mesmo dispositivo por hardware real quando chegarem. Consulte [Dispositivos emulados](/kilo-docs-pt/kilo-iot-server/devices/emulated-devices.md).
### Separador Mapping
Este separador mapeia os dados brutos do sensor do dispositivo para definições de medição normalizadas. Se houver modelos de métricas configurados para o tipo de dispositivo, os mapeamentos podem ser preenchidos automaticamente. Caso contrário, pode atribuir modelos de métricas manualmente.
#### Chaves do conector — veja o que o dispositivo envia
Assim que o dispositivo estiver ligado e a transmitir, o separador Mapping apresenta uma **tabela de chaves do conector** mostrando cada campo no payload bruto do dispositivo. Cada linha mostra o nome do campo (exatamente como o dispositivo o envia — por exemplo, `t`, `temp1`, `humidity_pct`), o respetivo valor atual e o carimbo de data/hora da última atualização. Este é o payload em tempo real do dispositivo, atualizado em tempo real.
Regresse a esta tabela sempre que precisar de saber o que um dispositivo reporta e em que formato — para escrever uma condição de regra, ou definir o valor esperado num comando. Consulte [Decodificação de payload e chaves do conector](/kilo-docs-pt/kilo-iot-server/devices/payload-decoding.md).
#### Mapear campos brutos para modelos de métricas
É aqui que transforma a saída enigmática do dispositivo em medições significativas e rotuladas. Quando mapeia uma chave bruta do conector (como `t`) para um modelo de métrica (como "Temperature", unidade: °C, tipo: Float), está a dar a esse campo bruto uma identidade legível por humanos. A partir daí, painéis, regras de automação, alertas e consultas históricas mostram todos "Temperature (°C)" — e não o nome bruto do campo que o firmware do dispositivo envia.
Para normalizar um campo bruto:
1. **Adicionar uma métrica** — Clique **Adicionar chave** e selecione um modelo de métrica na lista pendente (por exemplo, "Temperature", unidade: °C, tipo: Float). As colunas Unit, Type e Data type são preenchidas automaticamente a partir do modelo. Se o modelo de que precisa não existir, crie um em [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md) primeiro.
2. **Selecione a chave do conector** — Na lista pendente **Chave do conector** para essa métrica, escolha o nome do campo bruto que corresponde a esta medição (por exemplo, selecione `t` para um dispositivo que envia a temperatura como `t`).
3. **Guardar** — O mapeamento entra em vigor imediatamente. Os dados normalizados fluem através de painéis, regras de automação, avaliações de alarmes e consultas históricas.
Se a Chave do conector não estiver preenchida, os dados dessa métrica serão ignorados.
Repita para cada medição que o dispositivo reporta. Várias métricas podem ser mapeadas numa única sessão.
#### Qualquer dispositivo, qualquer formato de payload
Este fluxo de trabalho aceita dados de qualquer dispositivo que o servidor possa receber — incluindo hardware de protótipo com esquemas de payload em evolução, sensores de fabricantes de nicho com formatos de telemetria não documentados e equipamento de campo legado que transmite identificadores codificados em vez de nomes de campo legíveis por humanos. Se o dispositivo envia dados, a tabela de chaves do conector apresenta-os e pode mapeá-los.
Para detalhes sobre a configuração de modelos de métricas, consulte [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md).
#### Comportamento específico do MQTT
Para dispositivos ingeridos através do [conector MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector.md), aplicam-se duas especificidades do fluxo de registo:
* **A lista pendente Chave do conector fica vazia até chegar a primeira publicação.** A lista pendente é preenchida a partir das chaves de payload efetivamente recebidas do dispositivo, e não de uma entrada de texto livre. Para um registo MQTT novo, isto requer uma gravação em duas passagens: adicione uma linha por métrica com a chave normalizada selecionada e o Data type definido, deixe a Chave do conector vazia, guarde, confirme que o dispositivo está a publicar, reabra o registo do dispositivo — a lista pendente Chave do conector está agora preenchida, faça a correspondência de cada linha, guarde novamente.
* **Coluna Value do separador Mapping vs. histórico do separador Logs.** A coluna Value é uma captura em tempo real do payload mais recente (atualiza em cada publicação aceite, independentemente de as Chaves do conector estarem preenchidas). O separador Logs é o histórico por sensor (preenchido apenas por publicações que chegam *após* as Chaves do conector serem guardadas). Depois de concluir a segunda passagem, gere uma nova publicação para preencher o separador Logs — publicações mais antigas não são normalizadas retroativamente.
* **O mapeamento é iterativo.** O registo inicial raramente capta todas as chaves de payload úteis. Depois de os dados em tempo real terem chegado durante um período representativo, reabra o registo do dispositivo, reveja a lista pendente Chave do conector e a coluna Value para ver o que está realmente a ser publicado, adicione linhas de Mapping para quaisquer campos adicionais que pretenda acompanhar, guarde e desencadeie uma nova publicação para que o separador Logs comece a registar histórico para os novos mapeamentos.
Veja [Tópicos e roteamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) para o fluxo de trabalho completo de registo específico do MQTT.
### Separador Logs
O separador Logs está inicialmente vazio. Depois de o dispositivo começar a enviar dados, este separador apresenta o registo bruto de eventos com carimbos de data/hora e detalhes do payload.
Clique em **Guardar** novamente para guardar a configuração de ligação e métricas.
## Após guardar
O dispositivo aparece nas listas de dispositivos em todo o servidor — na tabela de dispositivos do conector, em Devices e em quaisquer painéis ou regras de automação que o referenciem.
Para dispositivos LoRaWAN, os dados começam a fluir assim que o dispositivo físico envia um pedido de join e o servidor o aceita. Para dispositivos de rastreio, os dados começam a fluir assim que o localizador começa a enviar dados para o endpoint URL configurado.
Registar um dispositivo aqui não faz com que ele faça join. Um dispositivo LoRaWAN junta-se a uma rede de cada vez, por isso uma unidade que foi anteriormente colocada em funcionamento noutro local — devolvida de outro site, comprada em segunda mão ou usada noutra plataforma — permanece associada a essa rede até ser reiniciada e enviar um novo pedido de join. Hardware recém-saído de fábrica faz join por si só; qualquer dispositivo com histórico normalmente precisa primeiro de um reset. Consulte [Antes de qualquer coisa chegar: aderir à rede](/kilo-docs-pt/kilo-iot-server/devices/device-diagnostics.md#before-anything-arrives-joining-the-network).
Se o dispositivo estiver registado mas não estiver a chegar nenhum dado, abra o respetivo separador **Ligação** e leia o estado de receção — este informa se o dispositivo chegou à rede, se as mensagens estão a ser recebidas e se os valores nelas estão a ser armazenados, com o próximo passo específico para cada caso. Consulte [Diagnóstico do dispositivo](/kilo-docs-pt/kilo-iot-server/devices/device-diagnostics.md).
## O que vem a seguir
* **Configurar modelos de métricas** antes ou depois do registo para controlar como os dados brutos são normalizados. Consulte [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md).
* **Editar propriedades do dispositivo** a qualquer momento através da mesma caixa de diálogo. Consulte [Gestão de dispositivos](/kilo-docs-pt/kilo-iot-server/devices/device-management.md).
* **Diagnosticar um dispositivo silencioso** a partir do seu separador Ligação. Consulte [Diagnóstico do dispositivo](/kilo-docs-pt/kilo-iot-server/devices/device-diagnostics.md).
* **Registar um endpoint MIOTY** e os respetivos campos específicos do protocolo. Consulte [Dispositivos MIOTY](/kilo-docs-pt/kilo-iot-server/devices/mioty-devices.md).
* **Começar sem hardware** e mudar para o dispositivo real quando ele chegar. Consulte [Dispositivos emulados](/kilo-docs-pt/kilo-iot-server/devices/emulated-devices.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
