Skip to content

Getting Started

Welcome to cosalette — a Python framework for building MQTT device daemons.

cosalette handles the infrastructure (MQTT connectivity, configuration, logging, health reporting, error handling) so you can focus on your device's domain logic.

What You'll Build

cosalette is FastAPI for MQTT daemons. If you've ever written a Python script that reads a sensor, formats JSON, publishes to an MQTT broker, and runs in a while True loop — cosalette replaces all the boilerplate around that loop.

You declare your devices with decorators, and the framework handles:

  • MQTT connectivity — connection, reconnection, Last Will & Testament
  • Configuration — environment variables and .env files via pydantic-settings
  • Structured logging — JSON or text, with device-scoped correlation
  • Health reporting — per-device availability, LWT crash detection, online/offline status
  • Error isolation — one device crashing doesn't take down the others
  • Graceful shutdown — SIGTERM/SIGINT handling, orderly teardown
  • Testing — first-class test doubles and a harness for integration tests

A minimal cosalette app looks like this:

import cosalette

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

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

app.run()

That's a fully operational MQTT daemon — with structured logging, health reporting, graceful shutdown, and a CLI with --dry-run, --log-level, and --version flags — all from 7 lines of code.

  • AI-Assisted Development

    Install the packaged cosalette instruction file into your app repo and use local CLI help topics for deeper framework context.

    AI-Assisted Development

  • Quickstart

    Build your first cosalette app step by step — from zero to a working telemetry daemon with tests.

    Quickstart

Installation

cosalette is published on PyPI.

uv add cosalette

pip install cosalette

Using GitHub Copilot or another coding agent?

Run cosalette ai init in your app repository after installation. This installs .github/instructions/cosalette.instructions.md, which Copilot can discover automatically. See AI-Assisted Development.

Alternative: install from Git

To install the latest development version directly from the repository:

uv add "cosalette @ git+https://github.com/ff-fab/cosalette.git"

Or for a local editable install:

git clone https://github.com/ff-fab/cosalette.git
cd cosalette
uv pip install -e packages/

Requirements

  • Python 3.14+
  • An MQTT broker (e.g. Mosquitto)

Next Steps

Once you have cosalette installed:

  1. AI-Assisted Development — Install the packaged instruction file and learn the local CLI help commands for deeper framework context.
  2. Quickstart — Build a telemetry daemon from scratch, add configuration, and write your first test.
  3. Router & Composition — Organize multi-module apps using Router for testable boundaries.
  4. Architecture — Understand the composition-root pattern and how the framework orchestrates your devices.
  5. Device Archetypes — Learn about telemetry, command, and device patterns.