pythermacell

A modern, fully-typed async Python client for Thermacell IoT devices (LIV Hub) built on the ESP RainMaker API.

What It Does

pythermacell is an asynchronous Python library for controlling and monitoring Thermacell LIV mosquito-repellent devices through their cloud platform (Espressif ESP RainMaker). It handles authentication, device discovery, power and LED control, and status monitoring behind a clean, fully-typed API. It is the engine behind the Thermacell LIV Home Assistant integration, and is equally suitable for standalone scripts and other applications.

Features

• Fully asynchronous (aiohttp) with comprehensive type hints (strict mypy).
• Three-layer architecture: low-level API, coordinating client, stateful devices.
• Power control, RGB LED control (HSV), and refill/runtime/status monitoring.
• Optimistic updates with automatic rollback for instant UI responsiveness.
• State caching, optional background auto-refresh, and change listeners.
• Built-in resilience: circuit breaker, exponential backoff, and rate limiting.
• Session injection for sharing an aiohttp session (e.g. with Home Assistant).
• Custom exception hierarchy and high unit + integration test coverage.

Installation

See INSTALL.md for the complete guide.

pip install pythermacell
# or
uv add pythermacell

Requires Python 3.13+.

Quick Start

import asyncio

from pythermacell import ThermacellClient


async def main() -> None:
    async with ThermacellClient(
        username="your@email.com",
        password="your_password",
    ) as client:
        for device in await client.get_devices():
            print(f"{device.name} ({device.model}) online={device.is_online}")

            await device.turn_on()
            await device.set_led_color(hue=120, brightness=80)

            print(f"Refill life: {device.refill_life}%")


asyncio.run(main())

Usage

The most common workflow is: construct a ThermacellClient, enter its async context, fetch devices, then control or monitor them through ThermacellDevice objects. Device control methods apply optimistically (local state updates immediately, then the API call runs in the background and rolls back on failure).

device = (await client.get_devices())[0]

await device.turn_on()                              # power on (optimistic)
await device.set_led_color(hue=240, brightness=80)  # blue
await device.refresh()                              # pull latest state from API

print(device.is_powered_on, device.refill_life, device.system_status)

For depth — authentication, LED rules, monitoring, optimistic updates, auto-refresh and change listeners, session injection, resilience patterns, and full error handling — see the Usage Guide. Runnable scripts live in examples/.

API Reference

Full reference lives in docs/. Key entry points:

Endpoint-level details are documented under docs/api/.

Development

See docs/DEVELOPMENT.md. In short:

git clone https://github.com/joyfulhouse/pythermacell.git
cd pythermacell
uv sync
uv run pytest
uv run ruff check
uv run mypy

Support

• Join the JoyfulHouse Discord for support and discussion across all JoyfulHouse Home Assistant integrations and libraries.
• Issues: https://github.com/joyfulhouse/pythermacell/issues
• PyPI: https://pypi.org/project/pythermacell/

Support Development

If this library is useful to you, please consider supporting its development:

• GitHub Sponsors
• Ko-fi

License

This project is licensed under the MIT License — see LICENSE for details.

This is an unofficial library and is not affiliated with, endorsed by, or sponsored by Thermacell Repellents, Inc. All product names, logos, and brands are the property of their respective owners.

Related Projects

• Thermacell LIV — the Home Assistant integration built on this library.

_{Built with Omnigent — the open-source AI agent framework and meta-harness.}

Native Services and LAN Control

Version 0.3.1 adds capability-driven timers, schedules, reboot, timezone, cloud OTA, and encrypted RainMaker local transport. See verified contracts and examples. Native timers, power confirmation, and cloud services are validated on live hubs (firmware 5.4.7). LAN control is experimental: it is validated only against HTTP/protocol simulators because no tested firmware advertises local control; offline startup is unsupported (#76).