# Home Assistant

Mapit's own Home Assistant integration puts each of your vehicles on the map as a device tracker, with sensors for its battery and when it last reported.

> **Beta.** The Mapit API behind it is a beta, free for now. See the [beta terms](https://developers.mapit.me/terms.md).

## Install

You need Home Assistant 2026.10 or newer, and a Mapit account with at least one vehicle. With [HACS](https://hacs.xyz/):

1. Add `https://github.com/mapit-iot/home-assistant-mapit` as a custom repository, with the category Integration.
2. Install **Mapit** and restart Home Assistant. HACS installs the [latest release](https://github.com/mapit-iot/home-assistant-mapit/releases/latest).
3. Go to **Settings > Devices & services > Add integration** and pick **Mapit**.
4. Sign in with your Mapit account and tick **Also allow vehicle location and last reported device status**. Home Assistant cannot show your vehicles without it.
5. The first time, `my.home-assistant.io` asks for your Home Assistant URL (it suggests `http://homeassistant.local:8123`). Enter the address you open Home Assistant at and press **Link account**. The address is stored only in that browser.
6. Home Assistant opens a **Name and assign** dialog that lists every vehicle, where you can choose an area for each. **Skip and finish** is fine too. Your vehicles appear.

Without HACS, download the source of the [latest release](https://github.com/mapit-iot/home-assistant-mapit/releases/latest), not `main`, copy its `custom_components/mapit` folder into your Home Assistant `config/custom_components` folder, and restart Home Assistant. Home Assistant downloads `aiomapit` from PyPI on that first restart, so it needs internet access. Then continue from step 3.

## What you get

Each vehicle becomes a device with these entities:

| Entity | What it shows |
| --- | --- |
| Device tracker (the vehicle's name) | The last position reported. A vehicle that never reported a position shows _unknown_. |
| Mapit battery | The tracker's own battery, not the vehicle's. |
| Last communication | When the tracker last reported anything. |
| Last location | When the position was reported. |
| Odometer | The mileage stored in Mapit. |
| Status | What the tracker last reported, as listed below. |
| Vehicle voltage | The vehicle's supply seen by the tracker. Disabled by default: turn it on in the entity settings. |

Everything is last reported, not live. The status shows one of these values, with the same labels as the Mapit app:

- `at_rest`: **At rest**. The vehicle is parked.
- `buzz`: **Vibration**. The tracker felt vibration while parked.
- `moving`: **In transit**. The vehicle is moving.
- `no_comms`: **Offline**. The tracker is not communicating.
- `hibernation` and `hibernation_requested`: **Off**. Hibernating or about to, to save battery.
- `tilt_detected`: **Fall detection**. The vehicle may have fallen.

A vehicle that never reported, or reports a status not listed here, shows _unknown_.

## How it works

- **No password in Home Assistant.** You sign in on Mapit's page and approve Home Assistant, as you would for any other app. Home Assistant keeps a token, never your password.
- **You choose what it sees.** Location is a separate permission on the approval page.
- **Disconnect from Mapit.** The connection appears on your connected apps page, where you can end it.
- **Light.** It reads every vehicle's status in one request, about once a minute.

## Integrations that ask for your password

Some community integrations sign in with your Mapit email and password. They hold your password, and they can stop working whenever the Mapit app changes. We recommend moving to the official integration and then changing your Mapit password.
