Skip to main content

python-mobius

A Python client for the Bluetooth protocol of "Mobius" aquarium devices: EcoTech Marine (VorTech and Vectra pumps, Radion lights), AquaIllumination (Prime, Hydra, Orbit, Axis), Neptune Systems and NYOS. Built on bleak.

Not affiliated with or endorsed by any of these companies. This is an independent implementation of the protocol for interoperability with hardware you own, based on reverse engineering of the Mobius app and public community research. The protocol is documented in documentation/, in enough detail to implement it in another language.

Features

  • Discovery without connecting: model, serial number and tank (pan_id) from BLE advertisements.
  • Lights: channels, schedules, and the current intensity computed the way the app does it (schedule intensity, lunar phases, acclimation, hyperdrive).
  • Pumps: speed, flow, motor power and other sensor values; schedules and the active mode; battery backup settings and whether the pump runs on battery.
  • Schedules: read and write, as editable JSON or as the app's .mob template files; light schedule groups are handled.
  • Scenes: list, start (whole tank) and cancel.
  • Settings and commands: advanced features (Local Control, LED auto dim, fan speed, fan shutdown), lunar phases, schedule intensity, time sync, reboot, restart all.
  • One connection per tank: every other device of the tank is reached through it over the Thread mesh (RelayedMobiusDevice).
  • Batched polling: everything a poll needs in one request.
  • Diagnostics: attribute dumps, firmware and hardware information, Thread and clock diagnostics.
  • Firmware update checks: which firmware images to ask the Mobius cloud about and parsing its replies and changelogs (installing is not supported).
  • mobius-scan command line tool.

Supported devices

PrimitiveType Devices Support
VisualV1 Radion, Prime, Hydra Tested
VorTechV1, TurtleV1 VorTech, Axis Tested
PumpV1, VectraV1, AlpacaV1 Nero, Vectra, Orbit Same format as the tested pumps; not tested
CoffeeV1 NYOS Quantum Experimental: decoded with the pump format, not tested
DoseV1 Versa dosers Container level, dosing state and schedule (read); container size and refill (write); not tested on real hardware by the maintainer
HotSauceV1 Sensors Identity only

See known gaps for what isn't covered or tested.

Install

pip install python-mobius
# recommended: more reliable connections
pip install "python-mobius[retry]"

Python 3.9 or newer.

Quick start

import asyncio
from mobius import scan_for_mobius_devices_with_info, group_by_pan_id, MobiusDevice

async def main():
    found = await scan_for_mobius_devices_with_info()
    for pan_id, members in group_by_pan_id(found).items():
        print(f"tank {pan_id:#06x}:")
        for device, info in members:
            print(f"  {info.serial}  {info.model.name if info.model else info.model_raw}")

    device, info = found[0]
    async with MobiusDevice(device, serial=info.serial) as d:
        print(await d.get_device_summary())

asyncio.run(main())

Reaching the rest of the tank through one connection:

from mobius import RelayedMobiusDevice

async with MobiusDevice(serial="00000000000002") as gateway:
    for peer in await gateway.discover_mesh_peers_auto():
        print(await RelayedMobiusDevice(gateway, peer).get_device_info())

Command line:

mobius-scan                                  # list devices by tank
mobius-scan --by-serial SERIAL --dump-schedule
mobius-scan --by-serial SERIAL --relay-target OTHER_SERIAL
mobius-scan --help

The full API and every CLI option are described in documentation/16-python-library.md.

Development

git clone https://code.r3pek.org/r3pek/python-mobius
cd python-mobius
pip install -e ".[dev]"
pytest

Tests use captured packets and advertisements from real devices where possible.

ha-mobius is a Home Assistant integration built on this library.

License

GPLv2, see LICENSE.

Acknowledgments

The Reef2Reef thread "Controlling Mobius enabled VorTech pump using 0-10V and BLE" and the danmrossi/MobiusControl project, whose work this builds on. The reverse engineering and implementation were done with substantial help from Claude (Anthropic).

Metadata

Release files for python-mobius 0.13.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 python-mobius 0.13.0
File Size Uploaded Provenance Actions
python_mobius-0.13.0.tar.gz 275.6 kB Without provenance Details for python_mobius-0.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-mobius 0.13.0
File Interpreter ABI Platform Actions
python_mobius-0.13.0-py3-none-any.whl Python 3 none any Details for python_mobius-0.13.0-py3-none-any.whl

Total release size: 399.4 kB

Release files / python_mobius-0.13.0.tar.gz

Download URL python_mobius-0.13.0.tar.gz
Size 275.6 kB
Tags Source
SHA-256 checksum
How to use checksums
853b0ee87449c3a394aae8a456dd7e439fa06d912d671fa09050cdb28f54d5c1
BLAKE2b-256 checksum
How to use checksums
f5abde60b3524674b57e1e89ded37a2a25a59e881296404c03207488a3a5781c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / python_mobius-0.13.0-py3-none-any.whl

Download URL python_mobius-0.13.0-py3-none-any.whl
Size 123.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b90dd071161705f107a362a3c6f5622421f6e4dc6ebd39415938abd027b5b4d6
BLAKE2b-256 checksum
How to use checksums
3ca50322015fcd6f4dcc9b5bd50785d2da970ed1c9bc44a42bcb47928613dc22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for python-mobius 0.13.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.13.0 This release

2 release files No 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