Skip to main content

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.0 can break between any two releases without migration shims, so pin exact versions. 1.0.0 is 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 AuthFailed and ConnectionDied signals (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 /api verb (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.68.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ampio-mqtt 0.68.0
File Size Uploaded Provenance Actions
ampio_mqtt-0.68.0.tar.gz 294.4 kB With provenance Details for ampio_mqtt-0.68.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ampio-mqtt 0.68.0
File Interpreter ABI Platform Actions
ampio_mqtt-0.68.0-py3-none-any.whl Python 3 none any Details for ampio_mqtt-0.68.0-py3-none-any.whl

Total release size: 394.6 kB

Release files / ampio_mqtt-0.68.0.tar.gz

Download URL ampio_mqtt-0.68.0.tar.gz
Size 294.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7593a01e31cdc39bc9078f3d62e4042b216ed8c0a523f6aee0c550d29359cffa
BLAKE2b-256 checksum
How to use checksums
240c01933638105072a80f66c10c44c43081a9efdfc41db3de96abacbb4925cf
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 15, 2026.

Transparency log

Release files / ampio_mqtt-0.68.0-py3-none-any.whl

Download URL ampio_mqtt-0.68.0-py3-none-any.whl
Size 100.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a9f4b981b97f1f9bac1347fcb04da5e796deafc1776289a9394d725b2a9864e7
BLAKE2b-256 checksum
How to use checksums
0890a56e71606495ff4723cea4ac76dbaf708314d615bf9f5194254a2ea72c95
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 15, 2026.

Transparency log

Security for ampio-mqtt 0.68.0

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.

Select from 2 files

Attestation for ampio_mqtt-0.68.0.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 15, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

0.68.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page