ampio-mqtt

Beta - 0.x.x. This library exists to back the home-assistant/core ampio integration currently in development. Anything below 1.0.0 is unstable by design: the public surface (dataclass fields, exported names, method signatures) can and will change between any two 0.x.x releases without migration shims. 1.0.0 is reserved for the moment the integration PR is accepted upstream; until then, breaking changes are expected and pins should be exact.

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; the library itself is Home Assistant agnostic.

Account tiers. Any Ampio account works; what the library can see is decided by the account's administrator bit. Per-user app permissions do not change it (live-verified with a standard account granted every app permission):

  • Administrator - the full catalogue: every DB object, the module list (AmpioClient.modules with names, models, firmware), and the global raw-channel topics that deliver input events with minimal latency.
  • Standard user (the recommended shape for a dedicated Home Assistant account) - the app-sync surface: the objects the administrator granted the account in the Ampio app, with names, classification metadata, visibility flags, rooms, and the server identity (AmpioClient.server_info). No module list (so mserv_id stays None) and no raw input topics - input events arrive about 100-140 ms later, through the per-object republish.

AmpioClient.access_tier reports the detected tier once discovery completes. docs/account-tiers.md has the full capability table, the measured latency difference, and when an administrator account is worth it.

The grant bounds reads and writes alike. An account can only read and only command the objects it was granted in the app; a command aimed at anything else is dropped, and no state for it reaches the account's namespace. A dedicated standard account is therefore a real privilege boundary, not just a narrower view.

Status

Beta, iterated alongside the home-assistant/core ampio integration (see the stability note above). Currently supports:

  • TCP connection to the Ampio MQTT broker with username/password auth and auto-reconnect with capped exponential backoff and jitter,
  • discovery of physical modules and logical DB objects from the M-SERV,
  • two-tier discovery: administrator accounts read the full config catalogue; standard accounts fall back to the app-sync data surface (grant-filtered objects with full metadata, plus the params_devices visibility table). The detected tier is exposed as AmpioClient.access_tier,
  • replacement-stable per-object identity via AmpioObject.stable_key (the Designer leafId), identical on both tiers - see docs/identity.md,
  • live push of object state changes via per-object MQTT topics, plus a bulk states snapshot at startup,
  • classification of sensor objects (temperature and M-SENS environmental channels) with Home-Assistant-compatible device/state class hints,
  • M-SERV identification (mac, firmware versions, local IP),
  • per-module health on the admin tier (AmpioModule.supply_voltage, temperature) from each module's own diagnostics broadcast, with add_module_listener() for updates,
  • best-effort LAN discovery via discover() (explicit multicast DNS A-record lookup of ampio.local driven by python-zeroconf, followed by a TCP probe of the resolved address). Home Assistant integrations can pass their shared AsyncZeroconf instance via discover(zeroconf=...).
  • per-object room mapping via AmpioClient.fetch_rooms() ({object_id: room_name}), backed by the M-SERV's MQTT data/groups + data/group_devices endpoints. Intended for a Home Assistant integration to forward as DeviceInfo.suggested_area at first import; reassignment is the user's call after that.
  • per-module capability classification on AmpioModule.capabilities (a frozenset[Capability]): DIGITAL_OUTPUT, DIGITAL_INPUT, ANALOG_INPUT, TEMPERATURE_INPUT, ENV_SENSOR, ROLLER_OUTPUT, RGBW_OUTPUT, IR_OUTPUT, UI_PANEL, BRIDGE, HUB, ALARM, AUDIO_VIDEO. Most modules carry several flags (e.g. M-OC-4s = {DIGITAL_OUTPUT, ANALOG_INPUT, RGBW_OUTPUT}). Drives HA platform selection and bundle/split decisions in the integration.
  • object control via AmpioClient.command() plus typed helpers (turn_on, turn_off, toggle, set_value, set_color, open_cover, close_cover, set_cover_position, set_cover_tilt). Works on both account tiers - see docs/protocol.md,
  • output-object classification via classify() / OutputKind (AmpioObject.output_kind, is_output, supports_tilt): relays, dimmers, RGBW lights, and the three cover types, each flagged with the command verbs it answers so a consumer picks a platform without its own type table. Tilt-capable blinds also report their slat angle as AmpioObject.tilt_position,
  • input-object classification via classify() / InputKind (AmpioObject.input_kind, is_input, is_on): flags map to a generic boolean, motion detection to binary_sensor.motion. Live flag/button events are delivered with minimal latency through the same add_object_listener() pipeline by routing the decoded raw per-channel topics (which fire ahead of the per-object republish) to the owning object.

Protocol reference notes live under docs/; src/ampio_mqtt/const.py remains the canonical source for the topic helpers.

Installation

pip install ampio-mqtt

discover() resolves ampio.local over multicast DNS from inside the process via python-zeroconf, which is a hard runtime dependency. The lookup works identically on macOS, HAOS, plain Linux, and Docker - no dependency on nss-mdns/avahi being configured on the host.

Usage

import asyncio

from ampio_mqtt import AmpioClient, discover


async def main() -> None:
    # Find the M-SERV on the LAN via mDNS.
    candidates = await discover()
    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.add_object_listener(lambda obj: print(obj.id, obj.kind, obj.value))
    await client.start()  # connects, subscribes, requests discovery

    # Per-object room map. A Home Assistant integration would forward each
    # value as `DeviceInfo.suggested_area` at first device creation.
    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())

License

MIT

Project links

Data verified by PyPI on Aug 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.58.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for pszypowicz from gravatar.com pszypowicz

Credits

Author: pszypowicz

GitHub Statistics

Data verified by PyPI on Aug 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT

Requires

Python >=3.13

Provides Extra

test

Tags

ampio home-assistant mqtt smart-home

Report project as malware

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.10.0.tar.gz (80.4 kB view details)

Uploaded Source

Built Distribution

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

ampio_mqtt-0.10.0-py3-none-any.whl (40.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: ampio_mqtt-0.10.0.tar.gz
  • Upload date:
  • Size: 80.4 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.10.0.tar.gz
Algorithm Hash digest
SHA256 ac941b75c4990f54dbd21bba76f0a087bc9c7c5db785b773c511aa26e8cfea0f
MD5 83b5baef55dcd5893a55402371fcface
BLAKE2b-256 de86678845e5b7070374ea1052ee16bf9d5380f4ec3999643db2e3ad3c816a24

See more details on using hashes here.

Provenance

The following attestation bundles were made for ampio_mqtt-0.10.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.

File details

Details for the file ampio_mqtt-0.10.0-py3-none-any.whl.

File metadata

  • Download URL: ampio_mqtt-0.10.0-py3-none-any.whl
  • Upload date:
  • Size: 40.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ampio_mqtt-0.10.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6bf7b7630c67e870ea2a9a0c7175a7827b5215334ef2c0f8d37397c0ce963df4
MD5 cc83ff1d0e0874820b651279c62f9186
BLAKE2b-256 fc4e00442e4a36c163082bdf9a4f0a718728f024013e3b65b8cd4ce0207dd222

See more details on using hashes here.

Provenance

The following attestation bundles were made for ampio_mqtt-0.10.0-py3-none-any.whl:

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.

Release history Release notifications | RSS feed

0.58.0

2 files

0.57.0

2 files

0.56.0

2 files

0.55.0

2 files

0.54.1

2 files

0.54.0

2 files

0.53.0

2 files

0.52.0

2 files

0.51.0

2 files

0.50.0

2 files

0.49.0

2 files

0.48.0

2 files

0.47.0

2 files

0.46.0

2 files

0.45.0

2 files

0.44.0

2 files

0.43.0

2 files

0.42.0

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.1

2 files

0.36.0

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.0

2 files

0.31.0

2 files

0.30.0

2 files

0.29.0

2 files

0.28.0

2 files

0.27.0

2 files

0.26.1

2 files

0.26.0

2 files

0.25.0

2 files

0.24.0

2 files

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.0

2 files

0.18.0

2 files

0.17.0

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.0

2 files

This release

0.10.0 This release

2 files

0.9.0

2 files

0.8.0

2 files

0.7.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

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