> 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/dashboards/adding-widgets/map-widget.md).
# Widget de Mapa
Coloque ativos com GPS num mapa interativo com o widget Mapa — posição atual, métrica em tempo real e histórico de rota.
O widget Mapa coloca um ativo que reporta GPS num mapa interativo real ao ar livre. O marcador mostra a posição atual do ativo e o valor atual de **uma métrica selecionada** de cada vez — velocidade, temperatura da carga, estado de ligado/desligado do motor, nível da bateria ou qualquer outro sensor que o dispositivo transmita.
Qualquer dispositivo que transmita coordenadas GPS funciona — um rastreador de veículo via o conector Tracker, uma etiqueta GPS LoRaWAN via LNS ou um dispositivo de campo ligado por MQTT. O widget deteta a localização a partir de campos de sensor chamados `lat`/`latitude` e `lon`/`longitude`/`lng`. Se esses campos existirem no dispositivo, ele aparece no mapa.
Isto é diferente do [Widget de imagem](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/image-widget.md), que funciona com qualquer imagem estática que você carregue. O widget Mapa é para ativos que se movem — veículos, equipamento móvel, dispositivos de campo.
Coloque o widget Mapa num painel operacional juntamente com os widgets Últimos dados e Gráfico para dar aos despachantes e supervisores uma perceção situacional imediata: localização do ativo, estado atual da métrica e histórico recente de rota, tudo numa única vista. Os controlos de intervalo de datas permitem aos operadores rever o histórico da rota sem sair do painel.
## Configurar um widget Mapa
### Passo 1 — Selecione Mapa no seletor de widgets
Clique em **Mapa** no seletor. (Consulte [Adicionar widgets](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets.md) para saber como abrir o modo de edição e chegar ao seletor.) O painel de definições abre com dois separadores: **Origem de dados** e **Aparência**.
### Passo 2 — Separador Fonte de dados: selecione um dispositivo e uma métrica
O separador Origem de dados tem o título **"Configuração do mapa"** com o subtítulo **"Configure os últimos dados e as origens de dados."**
1. Clique no seletor de dispositivo para escolher um rastreador ou dispositivo equipado com GPS. O seletor não pré-filtra dispositivos que já tenham dados de localização — você pode escolher qualquer dispositivo.
2. Depois de selecionar um dispositivo, o widget procura automaticamente sensores cujos nomes correspondam a `lat` ou `latitude` para latitude e `lon`, `longitude`, ou `lng` para longitude. Se forem encontrados sensores correspondentes, o marcador aparece no mapa.
3. Os sensores não relacionados com localização do dispositivo selecionado ficam disponíveis para adicionar como uma **métrica adicional**. Escolha uma para mostrar o valor atual no marcador do mapa — velocidade, temperatura da carga, nível da bateria, nível de combustível ou qualquer campo numérico que o dispositivo transmita.
4. O widget Mapa suporta **exatamente uma métrica adicional**. Depois de selecionada, a opção Adicionar métrica desaparece.
A cor do marcador reflete quaisquer condições configuradas na métrica adicional. Se as condições marcarem a temperatura da carga a vermelho acima de 12°C, o marcador fica vermelho no marcador do painel assim que esse limite é atingido.
### Passo 3 — Separador Aparência: nome e estilo
**Nome do widget** *(obrigatório)* — O cabeçalho exibido acima do mapa.
**Descrição** — Subtítulo opcional.
**Tema** — **Claro** ou **Escuro** esquema de cores dos mosaicos do mapa. Independente do tema do painel — escolha o que for mais legível para os operadores que o irão usar.
**Legenda dos dados exibidos** — Alternar para mostrar uma legenda que identifique a métrica exibida.
### Passo 4 — Guardar
Clique em **Salvar** para adicionar o widget ao painel.
## Depois de colocar o widget
O mapa é renderizado com a última posição conhecida do ativo. O marcador mostra o valor da métrica selecionada e usa cor baseada em condições, se as condições estiverem configuradas. À medida que o dispositivo transmite novas posições, o marcador é atualizado automaticamente.
## Controlos do histórico da rota
* **Histórico** — Clique para mudar para uma vista de intervalo de datas.
* **Botão de intervalo de datas** — Mostra o período selecionado como **DD.MM.AAAA - DD.MM.AAAA**. Clique para alterar o intervalo.
* **Limpar intervalo de dados** — Regressa à vista da posição atual.
Quando um intervalo de datas está ativo, o widget traça as localizações registadas do dispositivo como uma linha tracejada que liga todas as posições registadas durante esse período. Até **500 pontos de posição GPS** são renderizados por intervalo de datas.
## Resolução de Problemas
**Sem marcador no mapa:** O widget deteta a localização procurando sensores chamados `lat`/`latitude` e `lon`/`longitude`/`lng`. Se o dispositivo usar nomes diferentes para os seus sensores de localização, o widget não consegue encontrar dados de localização. Abra a página de detalhes do dispositivo e verifique os nomes dos sensores — alinhe-os com os padrões esperados para resolver isto.
**Rota vazia para o intervalo de datas selecionado:** O dispositivo não estava a transmitir durante esse período, ou o GPS não tinha fixação. Experimente um intervalo de datas maior. Se o dispositivo nunca tiver reportado dados de localização, não haverá rota disponível.
**Valor da métrica não aparece no marcador:** O dispositivo ainda não transmitiu esse campo desde que o widget foi configurado. Abra a página do dispositivo para confirmar se a métrica tem valores recentes.
## Exemplos operacionais
**Monitorização de veículos da frota:** Um veículo de entregas transmite posição GPS e velocidade. Um widget Mapa no painel operacional do depósito mostra a localização atual do veículo com a velocidade atual no marcador — ou altere a métrica selecionada para o estado de ligado/desligado do motor para ver se o veículo está em funcionamento enquanto estacionado numa paragem. Condições na métrica de velocidade podem assinalar o veículo a amarelo ou vermelho se exceder um limite. O histórico da rota permite à equipa operacional rever o trajeto completo das entregas do dia depois do expediente.
**Despacho de técnicos de campo:** Uma equipa de gestão de instalações acompanha técnicos de assistência por todo um grande campus. Um widget Mapa no painel NOC mostra a posição atual de cada técnico com o nível da bateria no marcador — assim os coordenadores sabem quem está por perto e disponível quando surge uma nova tarefa, sem ligar para cada técnico.
**Conformidade no transporte refrigerado:** Um veículo de carga refrigerada transmite a posição GPS e a temperatura do compartimento de carga. O widget Mapa mostra a temperatura da carga no marcador com cor baseada em condições: verde para conformidade (2–8°C), vermelho para violação. Os despachantes podem ver de relance se a carga está dentro das especificações sem entrar nas páginas de cada dispositivo. Se o marcador ficar vermelho, sabem simultaneamente a localização e a temperatura.
**Auditoria de rota de entrega:** Um supervisor de logística usa os controlos de intervalo de datas para rever a rota de um veículo num dia anterior — verificando se a rota correspondeu ao percurso planeado, procurando paragens inesperadas e confirmando as janelas de entrega.
## Ver também
* [Condições](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/conditions.md) — Regras de cor para a métrica do marcador
* [Adicionar widgets](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets.md) — Modo de edição e seletor de widgets
---
# 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/dashboards/adding-widgets/map-widget.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.
