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 may 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

Quickstart

import asyncio

from ampio_mqtt import AmpioClient, ObjectUpdated, discover


async def main() -> None:
    candidates = await discover()  # mDNS lookup of ampio.local
    if not candidates:
        raise SystemExit("No Ampio M-SERV found on the LAN")
    host = candidates[0].address or candidates[0].host

    client = AmpioClient(host, username="user", password="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 AuthFailed and ConnectionDied signals (docs/events.md).
Discovery of the object and module catalogues on either account tier, 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 carries a tracking-issue link or a caveat naming 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.

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ampio_mqtt-0.21.0.tar.gz (132.7 kB view details)

Uploaded Aug 18, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ampio_mqtt-0.21.0-py3-none-any.whl (58.5 kB view details)

Uploaded Aug 18, 2026 Python 3

File details

Details for the file ampio_mqtt-0.21.0.tar.gz.

File metadata

Download URL: ampio_mqtt-0.21.0.tar.gz
Upload date: Aug 18, 2026
Size: 132.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ampio_mqtt-0.21.0.tar.gz
Algorithm	Hash digest
SHA256	`3bfe34931536875b6cf541ab70a388f7049e2d92f5e62d2ee94ce520ce6620e3`
MD5	`9fbcc352013b8d2672903fcb50e66d2d`
BLAKE2b-256	`3d7a47d8254c3603ef8994d625df2f634a333bf0c7ea6d628ecbbcc2bc6af073`

See more details on using hashes here.

Provenance

The following attestation bundles were made for ampio_mqtt-0.21.0.tar.gz:

Publisher: release.yml on pszypowicz/ampio-mqtt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: ampio_mqtt-0.21.0.tar.gz
- Subject digest: 3bfe34931536875b6cf541ab70a388f7049e2d92f5e62d2ee94ce520ce6620e3
- Sigstore transparency entry: 2505541570
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: pszypowicz/ampio-mqtt@8246c30bf5fa55228a505f7ff16ff54382385ba9
- Branch / Tag: refs/tags/v0.21.0
- Owner: https://github.com/pszypowicz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@8246c30bf5fa55228a505f7ff16ff54382385ba9
- Trigger Event: push