---
icon: material/hammer-wrench
---

# How-To Guides

Step-by-step instructions for common tasks.

These guides assume you've read the [Getting Started](../getting-started/index.md)
section and are familiar with the basic [concepts](../concepts/index.md).

<div class="grid cards" markdown>

-   **Telemetry Device**

    ---

    Build a sensor-polling device with optional publish strategies.

    [:octicons-arrow-right-24: Telemetry Device](telemetry-device.md)

-   **Command & Control Device**

    ---

    Build a device that receives commands via MQTT.

    [:octicons-arrow-right-24: Command Device](command-device.md)

-   **Configuration**

    ---

    Extend Settings, use `.env` files, override via CLI.

    [:octicons-arrow-right-24: Configuration](configuration.md)

-   **Hardware Adapters**

    ---

    Register adapters: direct, lazy import, dry-run swapping.

    [:octicons-arrow-right-24: Adapters](adapters.md)

-   **Share State Between Handlers**

    ---

    Use adapters-as-state to share data between command and telemetry handlers.

    [:octicons-arrow-right-24: Shared State](shared-state.md)

-   **Lifespan**

    ---

    Run startup and shutdown code with the lifespan context manager.

    [:octicons-arrow-right-24: Lifespan](lifespan.md)

-   **Testing**

    ---

    Use `cosalette.testing`, AppHarness, and pytest fixtures.

    [:octicons-arrow-right-24: Testing](testing.md)

-   **Custom Error Types**

    ---

    Map domain exceptions to structured error payloads.

    [:octicons-arrow-right-24: Error Types](error-types.md)

-   **Build a Full App** :material-star:{ .star }

    ---

    Capstone guide — combines everything above into a complete application.

    [:octicons-arrow-right-24: Full App Guide](full-app.md)

</div>
