cosalette 0.2.0

an opinionated Python framework for building IoT-to-MQTT bridge applications

cosalette

An opinionated Python framework for building IoT-to-MQTT bridge applications.

Documentation · Quickstart · API Reference

---

What is cosalette?

cosalette lets you build IoT-to-MQTT bridge daemons in Python with minimal boilerplate. You define devices (telemetry pollers or command handlers), register hardware adapters, and the framework handles MQTT wiring, structured logging, health reporting, error publishing, and graceful lifecycle management.

Key Features

• Declarative device registration — @app.command(), @app.device(), and @app.telemetry() decorators (guide)
• Hexagonal architecture — protocol-based ports with swappable adapters (concept)
• Structured JSON logging — per-device context, configurable levels (concept)
• Health & heartbeats — LWT crash detection, periodic JSON heartbeats, per-device availability (concept)
• Structured error publishing — domain errors published to MQTT with type mapping (concept)
• Pydantic settings — type-safe configuration from env vars and .env files (guide)
• CLI for free — --dry-run, --version, --log-level, --env-file via Typer (reference)
• Test-friendly — MockMqttClient, FakeClock, pytest fixtures included (guide)

Quick Example

import cosalette

app = cosalette.App(name="weather2mqtt", version="0.1.0")

@app.telemetry("sensor", interval=5.0)
async def sensor() -> dict[str, object]:
    return {"temperature": 21.5, "humidity": 55.0}

if __name__ == "__main__":
    app.run()

See the full Quickstart for a complete walkthrough.

Installation

pip install cosalette

Or with uv:

uv add cosalette

Contributing

See CONTRIBUTING.md for development setup, commands, project structure, and code quality standards.

Documentation

Full documentation is published at ff-fab.github.io/cosalette.

Section	What you'll find
Getting Started	Installation, quickstart tutorial
Concepts	Architecture, MQTT topics, lifecycle, hexagonal design
How-To Guides	Step-by-step guides for each feature
Reference	API docs, CLI options, payload schemas
ADRs	Architecture Decision Records

License

MIT License. See LICENSE for details.