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.0may 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.value),
of=ObjectUpdated,
)
await client.start() # connect, subscribe, run discovery
rooms = await client.fetch_rooms()
for obj_id, room in rooms.items():
print(f"object {obj_id} -> {room}")
await asyncio.sleep(30)
await client.stop()
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, capped-backoff
reconnect, and one typed event stream that includes 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 lights, covers with stop and tilt, the
regulator setpoint, scenes, and bus events, plus a raw escape hatch for the
rest of the verb vocabulary (
docs/protocol.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, 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 list and the low-latency raw input topics.
Bus events are the exception on both tiers, since 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. If something misbehaves on an older server, upgrade the M-SERV
first.
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. If your install meets the baseline, works, and you are happy with it, stay on your current versions and 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, because any account can raise any event (see Choosing an account).
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ampio_mqtt-0.36.1.tar.gz.
File metadata
- Download URL: ampio_mqtt-0.36.1.tar.gz
- Upload date:
- Size: 185.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ad8ca814ac8b2aa820ee41f549473f954519c5571c870d24e0fdee6b79ea44aa
|
|
| MD5 |
c60398c0f12418cec9c970a0a3458c53
|
|
| BLAKE2b-256 |
0238a3446adea95225aff13351c335a5facc307641dd9506ea8b20cda88ae550
|
Provenance
The following attestation bundles were made for ampio_mqtt-0.36.1.tar.gz:
Publisher:
release.yml on pszypowicz/ampio-mqtt
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ampio_mqtt-0.36.1.tar.gz -
Subject digest:
ad8ca814ac8b2aa820ee41f549473f954519c5571c870d24e0fdee6b79ea44aa - Sigstore transparency entry: 2618273142
- Sigstore integration time:
-
Permalink:
pszypowicz/ampio-mqtt@fbbec66616b52f757278d0fbd4172e12745ae056 -
Branch / Tag:
refs/tags/v0.36.1 - Owner: https://github.com/pszypowicz
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fbbec66616b52f757278d0fbd4172e12745ae056 -
Trigger Event:
push
-
Statement type:
File details
Details for the file ampio_mqtt-0.36.1-py3-none-any.whl.
File metadata
- Download URL: ampio_mqtt-0.36.1-py3-none-any.whl
- Upload date:
- Size: 68.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
36419bb4657fd812ce2e10a27c9669b2b8b03a587fa27d372b54033d7c4bf558
|
|
| MD5 |
ac07bfbffd272ae53ae62c70ba50f481
|
|
| BLAKE2b-256 |
0c7e88ee5e7e75521afb14906418ee5b20f4126f4a45fc217a29d833dfcf4e08
|
Provenance
The following attestation bundles were made for ampio_mqtt-0.36.1-py3-none-any.whl:
Publisher:
release.yml on pszypowicz/ampio-mqtt
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ampio_mqtt-0.36.1-py3-none-any.whl -
Subject digest:
36419bb4657fd812ce2e10a27c9669b2b8b03a587fa27d372b54033d7c4bf558 - Sigstore transparency entry: 2618273149
- Sigstore integration time:
-
Permalink:
pszypowicz/ampio-mqtt@fbbec66616b52f757278d0fbd4172e12745ae056 -
Branch / Tag:
refs/tags/v0.36.1 - Owner: https://github.com/pszypowicz
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@fbbec66616b52f757278d0fbd4172e12745ae056 -
Trigger Event:
push
-
Statement type:
