> 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/mioty-blueprints.md).
# Blueprints MIOTY
Decode payloads MIOTY no Kilo IoT com blueprints — catálogo de Sistema vs Personalizado e instantâneos por dispositivo.
Um blueprint é a especificação do descodificador para um endpoint MIOTY: um documento JSON, associado a um `typeEui`, que indica ao Kilo IoT Server como transformar um payload bruto em campos nomeados. A telemetria de um dispositivo MIOTY não é descodificada até ser selecionado um blueprint para ele — por isso, associar um blueprint é o que transforma um endpoint registado num dispositivo que produz dados utilizáveis.
Os blueprints estão organizados como um catálogo: **Fabricante → Modelo do dispositivo → Blueprint**. Um fabricante contém os seus modelos; um modelo contém as suas versões de blueprint. A Configuração do blueprint no formulário do dispositivo é onde pode escolher desse catálogo ou criar uma nova entrada.
## A ideia mais importante: instantâneos por dispositivo
Quando seleciona um blueprint para um dispositivo, ele é **copiado para esse dispositivo como um instantâneo independente**.
O dispositivo não é um ponteiro em tempo real para o catálogo. Tem a sua própria cópia do descodificador. O que significa:
* **Editar um blueprint do catálogo não altera os dispositivos já associados a ele.** Eles continuam a funcionar com a cópia com que foram comissionados.
* **Eliminar uma entrada do catálogo não quebra os dispositivos que já a estejam a usar.** Eles continuam a descodificar com o seu instantâneo; a entrada simplesmente desaparece do catálogo e já não pode ser escolhida para novos dispositivos.
* **Dois dispositivos do mesmo modelo podem executar blueprints diferentes.** Uma bateria piloto num descodificador corrigido e uma frota em produção no comprovado é um estado normal, não um conflito.
* **Uma nova versão chega a um dispositivo apenas quando a aplica explicitamente.** Nada de uma edição no catálogo se propaga por si só.
Este é o mesmo modelo que a plataforma usa para codecs LoRaWAN, e existe por uma razão específica: numa frota de vários milhares de endpoints, uma edição acidental do descodificador que reescrevesse silenciosamente a forma como cada unidade interpretava o seu payload seria uma falha que descobriria pelos seus painéis. A fronteira do instantâneo significa que o trabalho no catálogo e o comportamento em produção são preocupações separadas. Melhora um modelo livremente; implementa-o no momento que lhe convier.
## Catálogos System e Custom
O catálogo está dividido em dois, e os dois nunca são misturados numa única lista — alterna entre eles.
| Catálogo | Quem o pode ver e usar | Quem o pode alterar |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Sistema** | Todos — fabricantes, modelos e blueprints podem ser usados por qualquer organização | Apenas administradores. Criar, editar e eliminar entradas System requer um administrador. |
| **Personalizado** | A sua organização | À sua livre gestão — criar, editar e eliminar sem restrições |
Usar um blueprint System num dispositivo cria **apenas o instantâneo nesse dispositivo**. Nada é copiado para o seu catálogo Custom, e o seu catálogo Custom permanece exatamente como o construiu.
A divisão prática: System cobre o hardware que a plataforma já conhece. Custom é onde vivem os seus próprios descodificadores, as suas variantes específicas do fornecedor e as suas correções de revisões de firmware.
## Usar um blueprint existente
Este é o caminho para hardware já abrangido pelo catálogo.
1. No formulário do dispositivo, encontre **Configuração do blueprint**.
2. Ative **Usar blueprint existente** **ATIVADO**.
3. Selecione o catálogo — **Sistema** ou **Personalizado**.
4. Selecione o **Fabricante**.
5. Selecione o **Modelo do dispositivo**. A lista restringe-se aos modelos desse fabricante.
6. Selecione o **Versão do blueprint**.
A especificação do descodificador é apresentada só de leitura para revisão, e o **Type EUI** Type EUI é preenchido automaticamente no formulário do dispositivo e não é editável — vem do blueprint. Guarde o dispositivo, e o blueprint é instantaneizado nele.
Assim que isso acontece, o dispositivo é identificado como **Instantâneo fixado**, para que possa ver rapidamente que o que está a ler pertence a este dispositivo e não à entrada partilhada do catálogo. Se o blueprint do catálogo de que foi copiado tiver sido entretanto eliminado, a etiqueta lê-se **Instantâneo fixado (modelo de origem eliminado)** — o dispositivo não é afetado e continua a descodificar com a sua própria cópia, mas a etiqueta indica que já não existe uma entrada do catálogo por trás dele para comparação.
A **o primeiro blueprint criado para um modelo torna-se o predefinido para novos dispositivos desse modelo** — por isso, uma vez que um modelo esteja corretamente configurado, comissionar o resto da frota é uma questão de selecionar o modelo.
## Criar um novo blueprint
Siga este caminho quando o catálogo não cobrir o seu hardware, ou quando uma revisão de firmware descodificar de forma diferente da entrada existente.
1. Ative **Usar blueprint existente** **DESATIVADO**.
2. **Fabricante** — selecione um existente, ou clique em **+ Adicionar novo fabricante** e atribua-lhe um nome.
3. **Novo modelo de dispositivo** — introduza o nome do modelo. Se duplicar um modelo existente, o formulário assinala-o — verifique se, na verdade, pretende adicionar uma versão a esse modelo em vez disso.
4. **Versão do blueprint** — introduza uma versão, por exemplo `1.0.0`. Uma versão, de propósito e não por acaso; esta string é o que a sua equipa usará para distinguir dois descodificadores dentro de um ano.
5. **JSON do blueprint** — cole a especificação do descodificador. Tem de ser JSON válido e tem de conter um `typeEui` de exatamente 16 caracteres hexadecimais.
6. Quando a especificação é válida, um auxiliar mostra o valor analisado — **"Type EUI: …"** — confirmando a que o dispositivo ficará associado.
7. Clique em **Guardar blueprint**. Uma notificação confirma *"Blueprint criado"*, e o novo modelo, versão e Type EUI são preenchidos no formulário do dispositivo.
### Mensagens de validação
| Mensagem | O que significa |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **"A especificação do blueprint tem de ser JSON válido"** | O texto colado não é analisado. Verifique se há uma vírgula final, uma colagem truncada ou aspas tipográficas de um documento. |
| **"typeEui tem de ter 16 caracteres hexadecimais"** | A `typeEui` o campo está presente, mas não tem exatamente 16 caracteres hexadecimais. |
| Uma mensagem a indicar-lhe para **"Usar blueprint existente"** | A `typeEui` já é usado por um modelo existente. Esse tipo de payload já está no catálogo — selecione-o em vez de criar uma entrada concorrente. |
Essa última vale a pena compreender em vez de contornar. O `typeEui` identifica um tipo de payload. Se já existir, a ação correta é usar o modelo existente — e, se precisar de um descodificador diferente para ele, adicione uma versão a esse modelo.
## Pré-visualização da descodificação
Antes de guardar, use **Pré-visualização da descodificação** para executar o descodificador num payload de amostra e inspecionar os campos que ele produz.
Use-o. Um blueprint que é analisado como JSON não é o mesmo que um blueprint que descodifica corretamente — fatores de escala, ordem dos bytes e valores com sinal são os casos clássicos em que um descodificador está sintaticamente perfeito e semanticamente errado. Um payload de amostra com um valor conhecido leva um minuto na bancada e poupa-o de descobrir o problema como um gráfico de temperatura que parece plausível e está errado por um fator de dez. Tire um payload da documentação do próprio dispositivo, ou de uma unidade que já tenha comissionado.
## Aplicar uma nova versão
Como os dispositivos funcionam com instantâneos, uma nova versão do blueprint chega a um dispositivo apenas quando a aplica:
1. Crie a nova versão sob o mesmo fabricante e modelo.
2. Abra o dispositivo que pretende mover.
3. Em Configuração do blueprint, selecione o novo **Versão do blueprint**.
4. Salve.
Implemente primeiro num dispositivo e confirme os respetivos campos descodificados em relação ao payload em tempo real antes de mover a frota. O modelo de instantâneo é o que torna possível esta implementação faseada — o resto da frota não é afetado enquanto valida.
## Eliminação de entradas do catálogo
Eliminar o seu próprio blueprint, modelo ou fabricante do catálogo Custom é sempre permitido.
Se os dispositivos estiverem a usar a entrada, recebe um **aviso com uma contagem** dos dispositivos afetados. Esses dispositivos continuam a funcionar — estão nos seus instantâneos. O que muda é o catálogo: a entrada desaparece e já não pode ser escolhida para novos dispositivos.
Leia a contagem antes de confirmar. Não é um bloqueio, mas indica quantos registos de dispositivos passam agora a ter um descodificador que já não tem uma entrada no catálogo por trás — o que importa na próxima vez que alguém tentar comissionar uma unidade correspondente e não encontrar nada para selecionar.
Eliminar uma **Sistema** entrada requer um administrador.
## Sugestões
* **Crie uma vez, comissione muitas.** Para uma implementação em frota, acerte o blueprint numa unidade com a Pré-visualização da descodificação e depois deixe o predefinido do modelo tratar do resto.
* **Versão no firmware, não nas datas.** Quando um fornecedor lança uma revisão de firmware que altera o payload, isso é uma nova versão do blueprint. Dê-lhe um nome de modo que a ligação seja óbvia.
* **Prefira o System quando fizer sentido.** Se o catálogo System cobre o seu hardware, use-o — obtém o descodificador sem ficar responsável pela sua manutenção, e o seu dispositivo continua a obter o seu próprio instantâneo.
* **Mapeie métricas após a descodificação.** Um blueprint produz campos nomeados; os modelos de métricas normalizam esses campos para um vocabulário partilhado entre fabricantes. Veja [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md).
## O que vem a seguir
* **Comissione o endpoint** — a secção do formulário do dispositivo MIOTY, passo a passo. Veja [Dispositivos MIOTY](/kilo-docs-pt/kilo-iot-server/devices/mioty-devices.md).
* **Normalize os campos descodificados** — mapeie-os para o vocabulário de medições da sua implementação. Veja [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.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/mioty-blueprints.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.
