ampio-mqtt
Async Python client for the Ampio Smart Home local MQTT protocol exposed by the Ampio M-SERV controller. Built to back a Home Assistant integration while staying Home Assistant agnostic itself.
Beta. Everything below
1.0.0can break between any two releases without migration shims, so pin exact versions.1.0.0is reserved for the release that accompanies the home-assistant/core integration being accepted upstream.
Installation
pip install ampio-mqtt
LAN discovery (discover()) needs the discovery extra
(pip install ampio-mqtt[discovery]), which pulls in zeroconf. Home Assistant
ships zeroconf itself, so the integration needs no extra.
Quickstart
import asyncio
from ampio_mqtt import AmpioClient, ObjectUpdated, discover
async def main() -> None:
found = await discover() # mDNS lookup of ampio.local
if found is None:
raise SystemExit("No Ampio M-SERV found on the LAN")
client = AmpioClient(found.address, "user", "secret")
client.subscribe(
lambda e: print(e.object.id, e.object.kind, e.object.state),
of=ObjectUpdated,
)
await client.connect() # connect, subscribe, request the catalogues
rooms = await client.fetch_rooms()
for obj_id, room in rooms.items():
print(f"object {obj_id} -> {room}")
await asyncio.sleep(30)
await client.disconnect()
asyncio.run(main())
What it does
Each area is one page under docs/, and the docstrings carry
the API detail.
- A maintained broker connection with QoS 1 on every leg but the retained raw
state tree, and a capped-backoff reconnect. One typed event stream carries
every update and the terminal
AuthFailedandConnectionDiedsignals (docs/events.md). - Discovery of the object catalogue on either account tier (the module catalogue
is admin-only), with the detected tier exposed for setup flows
(
docs/account-tiers.md). - Classification of every object into a sensor, input, output, or thermostat
kind with Home-Assistant-compatible hints
(
docs/classification.md). - Replacement-stable identity for objects and modules, so a hardware swap keeps
its entities (
docs/identity.md). - Commands for relays, dimmers, RGBW and color-temperature lights, covers with
stop and tilt with the roller lock, the regulator setpoint, scenes, and bus
events. A push notification to the install's mobile app rides the same
surface. The M-DOT panel buzzer, its touch field colours and touch lock, and
the module identify LED are admin-only. The
command()escape hatch sends any other/apiverb (docs/commands.md). - A low-latency input bridge from the raw per-channel topics on the admin tier
(
docs/raw-channel-bridge.md). - Room mapping, per-module health, reported capabilities, touch panel settings and cover travel parameters, eviction events for server-side deletions, and connection diagnostics for a consumer's report blob.
- LAN discovery of the M-SERV by multicast DNS, self-contained in the process
(
docs/discovery-flow.md).
Choosing an account
A dedicated standard account is the recommended shape for Home Assistant. It
sees exactly the objects granted in the Ampio app and can command only those. An
administrator account adds the module catalogue, the low-latency raw tree, the
module diagnostics, and the CAN write surfaces (panel LEDs and colours, the
buzzer, the touch lock, and the identify LED). Bus events are the exception on
both tiers. Any account can raise any event number, and the logic behind an
event runs with full authority. docs/account-tiers.md
has the capability table and the measured latency difference.
Supported M-SERV versions
The library is developed and live-tested against an M-SERV self-reporting
serverVersion 1865 (serverRevision 409, mqttVersion 5.133.11). That
baseline is the compatibility floor. Wire behavior documented in this repo is
verified against that install unless marked otherwise in place - an open claim
says exactly what is unverified. Older servers are not supported, and the
library logs a warning when the connected server reports a lower or missing
serverVersion.
Ampio does not guarantee the stability of these wire surfaces. A server update or a module firmware update can change or remove behavior this library depends on, without notice. Breaking changes by Ampio are a known pattern. The author of an earlier Ampio integration stopped maintenance for exactly this reason.
Upgrade rules
- If something misbehaves on an older server, upgrade the M-SERV first.
- If your install meets the baseline and works, stay on your current versions. Do not chase the latest ones.
- If you decide to update anyway, make a full backup first - ideally a full image of the M-SERV's microSD card.
Disclaimer
This library is an independent, best-effort project and has no affiliation with Ampio. Use it at your own risk. It commands real hardware, and a wrong command moves real devices.
The M-SERV itself guarantees the safety of a standard account. The broker limits such an account to the objects granted in the Ampio app, and it denies the raw CAN surfaces on the wire. A defect in this library cannot widen that boundary. Bus events are the one exception (see Choosing an account).
Development tests
Install the development dependencies with uv sync --group dev. Run the unit
tests with uv run pytest.
The MQTT integration tests start temporary Mosquitto processes on loopback
addresses. They use synthetic replies and credentials and need no Ampio
hardware. Install Mosquitto with brew install mosquitto on macOS or
sudo apt-get install mosquitto on Debian or Ubuntu. Make sure that mosquitto
and mosquitto_passwd are on PATH, then run uv run pytest --mqtt -m mqtt.
Run uv run pytest --mqtt to include both suites. Without --mqtt, pytest
skips the broker tests. With --mqtt, missing broker executables fail the
suite. CI runs both suites on each supported Python version.
License
MIT
Metadata
Release files for ampio-mqtt 0.70.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ampio_mqtt-0.70.1.tar.gz | 297.8 kB | With provenance | Details for ampio_mqtt-0.70.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ampio_mqtt-0.70.1-py3-none-any.whl | Python 3 | none | any | Details for ampio_mqtt-0.70.1-py3-none-any.whl |
Total release size: 398.3 kB
Release files / ampio_mqtt-0.70.1.tar.gz
| Download URL | ampio_mqtt-0.70.1.tar.gz |
|---|---|
| Size | 297.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18bc841742128ee9af559a6ec8871f02836d6a7d7c9b89c49f824e75a91c464c
|
|
BLAKE2b-256 checksum How to use checksums |
c14696aaab5ff6e86268ffcc53fcf013827c8d7092b3c6e9615d331ebedca9b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / ampio_mqtt-0.70.1-py3-none-any.whl
| Download URL | ampio_mqtt-0.70.1-py3-none-any.whl |
|---|---|
| Size | 100.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc2710ae5521f5d521d3ea7b6d9fd100cf60d61bbf1cd3e6c9abe8a37fc4d7f3
|
|
BLAKE2b-256 checksum How to use checksums |
c821d40da44a75edc010e5dd074ee8c8a85be6f9515b4ecc1a32f263be496778
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logSecurity for ampio-mqtt 0.70.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ampio_mqtt-0.70.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.