# Home Assistant

A integração oficial da Mapit para o Home Assistant coloca cada veículo no mapa como rastreador de dispositivo, com sensores para a bateria e para quando comunicou pela última vez.

> **Beta.** A API da Mapit em que se baseia é uma beta, gratuita por agora. Veja as [condições da beta](https://developers.mapit.me/pt/terms.md).

## Instalação

São necessários o Home Assistant 2026.10 ou posterior e uma conta Mapit com pelo menos um veículo. Com o [HACS](https://hacs.xyz/):

1. Adicionar `https://github.com/mapit-iot/home-assistant-mapit` como repositório personalizado, com a categoria Integração.
2. Instalar o **Mapit** e reiniciar o Home Assistant. O HACS instala a [última versão publicada](https://github.com/mapit-iot/home-assistant-mapit/releases/latest).
3. Ir a **Definições > Dispositivos e serviços > Adicionar integração** e escolher **Mapit**.
4. Iniciar sessão com a conta Mapit e assinalar **Permitir também a localização do veículo e o último estado comunicado pelo dispositivo**. Sem essa permissão, o Home Assistant não consegue mostrar os veículos.
5. À primeira vez, o `my.home-assistant.io` pede o URL do Home Assistant (sugere `http://homeassistant.local:8123`). Indicar o endereço com que o Home Assistant é aberto e carregar em **Link account** (associar conta). O endereço fica guardado apenas nesse navegador.
6. O Home Assistant abre uma janela **Name and assign** (nomear e atribuir) com todos os veículos, onde é possível escolher uma área para cada um. Também é possível carregar em **Skip and finish** (ignorar e concluir). Os veículos aparecem.

Sem o HACS, descarregar o código-fonte da [última versão publicada](https://github.com/mapit-iot/home-assistant-mapit/releases/latest), e não o de `main`, copiar a respetiva pasta `custom_components/mapit` para a pasta `config/custom_components` do Home Assistant e reiniciá-lo. Nesse primeiro reinício o Home Assistant descarrega o `aiomapit` do PyPI, pelo que precisa de acesso à internet. Depois continuar a partir do passo 3.

## O que se obtém

Cada veículo passa a ser um dispositivo com estas entidades:

| Entidade | O que mostra |
| --- | --- |
| Rastreador de dispositivo (o nome do veículo) | A última posição comunicada. Um veículo que nunca comunicou uma posição mostra _desconhecido_. |
| Bateria Mapit | A bateria do próprio rastreador, não a do veículo. |
| Última comunicação | Quando o rastreador comunicou algo pela última vez. |
| Última localização | Quando a posição foi comunicada. |
| Conta-quilómetros | A quilometragem guardada na Mapit. |
| Estado | O que o rastreador comunicou por último, como indicado abaixo. |
| Tensão do veículo | A alimentação do veículo vista pelo rastreador. Desativada por predefinição: pode ser ativada nas definições da entidade. |

Tudo é o último valor comunicado, não em direto. O estado mostra um destes valores, com as mesmas etiquetas que a aplicação Mapit:

- `at_rest`: **Em repouso**. O veículo está parado.
- `buzz`: **Vibração**. O rastreador sentiu vibração com o veículo parado.
- `moving`: **Em trajeto**. O veículo está em movimento.
- `no_comms`: **Sem conexão**. O rastreador não está a comunicar.
- `hibernation` e `hibernation_requested`: **Desligado**. Em hibernação ou prestes a entrar, para poupar bateria.
- `tilt_detected`: **Moto caída**. O veículo pode ter caído.

Um veículo que nunca comunicou, ou que comunica um estado que não consta da lista, mostra _desconhecido_.

## Como funciona

- **Sem palavra-passe no Home Assistant.** Iniciar sessão na página da Mapit e autorizar o Home Assistant, como com qualquer outra aplicação. O Home Assistant guarda um token, nunca a palavra-passe.
- **Escolher o que ele vê.** A localização é uma permissão à parte na página de autorização.
- **Desligar a partir da Mapit.** A ligação aparece na página de aplicações ligadas, onde pode ser terminada.
- **Leve.** Lê o estado de todos os veículos num só pedido, mais ou menos uma vez por minuto.

## Integrações que pedem a palavra-passe

Algumas integrações da comunidade iniciam sessão com o email e a palavra-passe Mapit. Guardam a palavra-passe e podem deixar de funcionar sempre que a aplicação Mapit muda. Recomenda-se passar a usar a integração oficial e depois alterar a palavra-passe Mapit.
