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, HotSauceV1 Dosers, 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.12.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.12.0
File Size Uploaded Provenance Actions
python_mobius-0.12.0.tar.gz 259.1 kB Without provenance Details for python_mobius-0.12.0.tar.gz

Built distribution (wheel)

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

Total release size: 374.8 kB

Release files / python_mobius-0.12.0.tar.gz

Download URL python_mobius-0.12.0.tar.gz
Size 259.1 kB
Tags Source
SHA-256 checksum
How to use checksums
4975d115aabe619491dea463e2d81a285bfffc3367d79cf5954677fd6a074b83
BLAKE2b-256 checksum
How to use checksums
7dd99f2050b3feb344b83fe09d49b83e9e5e9de873c28bd7e69dc95f766c418c
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.12.0-py3-none-any.whl

Download URL python_mobius-0.12.0-py3-none-any.whl
Size 115.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fc9fb8beed060a8f42685e0e28a5596bd47a8190379dae7c583c4c0994bd4e33
BLAKE2b-256 checksum
How to use checksums
d4876fc958f29cc1101ff8575d5f8c2902f89069aa446a92922f0641af656593
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.12.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.12.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