A modern, fully-typed async Python client for Thermacell IoT devices (LIV Hub) built on the ESP RainMaker API.
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.
- 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
aiohttpsession (e.g. with Home Assistant). - Custom exception hierarchy and high unit + integration test coverage.
See INSTALL.md for the complete guide.
pip install pythermacell
# or
uv add pythermacellRequires Python 3.13+.
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, saturation=100, brightness=80)
print(f"Refill life: {device.refill_life}%")
asyncio.run(main())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, saturation=100, 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/.
Full reference lives in docs/. Key entry points:
| Symbol | Description |
|---|---|
ThermacellClient |
High-level client: authentication, device discovery, caching |
ThermacellDevice |
Stateful device: power, LED, monitoring, listeners |
ThermacellAPI |
Low-level ESP RainMaker HTTP layer |
AuthenticationHandler |
JWT authentication and token refresh |
pythermacell.resilience |
Circuit breaker, backoff, rate limiter |
| Exceptions | ThermacellError hierarchy |
Endpoint-level details are documented under docs/api/.
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- 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/
If this library is useful to you, please consider supporting its development:
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.
- Thermacell LIV — the Home Assistant integration built on this library.
Built with Omnigent — the open-source AI agent framework and meta-harness.