TasmoR Lib

Primary repository: Codeberg — Please submit issues and pull requests there.

A modern, type-safe Rust library for controlling Tasmota IoT devices via MQTT and HTTP protocols.

Early Development: This project is in active development (v0.x.x). The API may change between versions. Not recommended for production use yet.

Tested with: Tasmota firmware v15.2.0

Features

• Type-safe API - Compile-time guarantees for valid commands and values
• Dual protocol support - Control devices via MQTT or HTTP with full feature parity
• Async/await - Built on Tokio for efficient async I/O
• Full device support - Lights (RGB/CCT), switches, relays, energy monitors
• Event-driven architecture - Subscribe to device state changes in real-time (MQTT)
• Well-tested - Comprehensive unit and integration tests (630+ tests)

Supported Capabilities

Installation

Add to your Cargo.toml:

[dependencies]
tasmor_lib = "0.10"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

System Requirements

The MQTT feature (enabled by default) links against the Eclipse Paho MQTT C library, which is compiled from source during cargo build.

Build-time dependencies (required when the mqtt feature is enabled):

Runtime dependencies (required in the final binary):

OpenSSL is present on most Linux/macOS systems. For minimal Docker images (e.g., debian:slim, alpine), add it explicitly:

# Debian/Ubuntu
RUN apt-get install -y libssl3

# Alpine
RUN apk add --no-cache openssl-libs-static

If you only use HTTP (default-features = false, features = ["http"]), none of these system dependencies apply.

Feature Flags

Both HTTP and MQTT protocols are enabled by default. To reduce compile time and binary size, you can enable only the protocol you need:

# HTTP only (no C dependencies, no OpenSSL requirement)
tasmor_lib = { version = "0.10", default-features = false, features = ["http"] }

# MQTT only (no HTTP dependencies)
tasmor_lib = { version = "0.10", default-features = false, features = ["mqtt"] }

Quick Start

Basic Switch Control

The simplest use case - controlling a smart switch or relay:

use tasmor_lib::{Device, Capabilities};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to a Tasmota switch via HTTP
    let (device, initial_state) = Device::http("192.168.1.100")
        .with_capabilities(Capabilities::basic())
        .build_without_probe()
        .await?;

    // Check current state
    println!("Power is {:?}", initial_state.power(1));

    // Toggle power and get the response
    let response = device.power_toggle().await?;
    println!("Power is now {:?}", response.power_state(1));

    Ok(())
}

MQTT Connection

For persistent connections with real-time updates:

use tasmor_lib::{MqttBroker, Capabilities};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to MQTT broker
    let broker = MqttBroker::builder()
        .host("192.168.1.50")
        .credentials("mqtt_user", "mqtt_password")
        .build()
        .await?;

    // Create device from broker
    let (device, initial_state) = broker.device("tasmota_switch")
        .with_capabilities(Capabilities::basic())
        .build_without_probe()
        .await?;

    println!("Power is {:?}", initial_state.power(1));
    device.power_on().await?;

    // Clean disconnect when done
    device.disconnect().await;
    broker.disconnect().await?;

    Ok(())
}

Building Devices

build() vs build_without_probe()

Both methods return (Device, DeviceState) - the device handle and its initial state.

// Auto-detection: queries the device to discover capabilities
let (device, state) = Device::http("192.168.1.100")
    .build()
    .await?;

// Manual: you specify the capabilities (no capability query)
let (device, state) = Device::http("192.168.1.100")
    .with_capabilities(Capabilities::rgbcct_light())
    .build_without_probe()
    .await?;

Both methods query the device for its current state (power, dimmer, energy, etc.) and return it as DeviceState.

Predefined Capabilities

use tasmor_lib::Capabilities;

Capabilities::basic()           // Simple switch (1 relay)
Capabilities::neo_coolcam()     // Smart plug with energy monitoring
Capabilities::rgbcct_light()    // Full RGB + CCT light bulb
Capabilities::rgb_light()       // RGB only light
Capabilities::cct_light()       // Color temperature only light

Custom Capabilities

use tasmor_lib::CapabilitiesBuilder;

let caps = CapabilitiesBuilder::new()
    .with_power_channels(2)           // Dual relay
    .with_dimmer_control()
    .with_energy_monitoring()
    .build();

Examples by Use Case

Light Control (RGB/CCT)

use tasmor_lib::{Device, Capabilities, ColorTemperature, Dimmer, HsbColor};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (device, _) = Device::http("192.168.1.100")
        .with_capabilities(Capabilities::rgbcct_light())
        .build_without_probe()
        .await?;

    // Power and brightness
    device.power_on().await?;
    device.set_dimmer(Dimmer::new(75)?).await?;

    // Color temperature (warm to cold)
    device.set_color_temperature(ColorTemperature::WARM).await?;

    // RGB color
    device.set_hsb_color(HsbColor::blue()).await?;

    // Custom HSB color (hue: 0-360, saturation: 0-100, brightness: 0-100)
    device.set_hsb_color(HsbColor::new(120, 80, 100)?).await?;

    Ok(())
}

Multi-Relay Control

For devices with multiple relays (e.g., dual switch):

use tasmor_lib::{Device, CapabilitiesBuilder, PowerIndex, PowerState};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let caps = CapabilitiesBuilder::new()
        .with_power_channels(2)
        .build();

    let (device, state) = Device::http("192.168.1.100")
        .with_capabilities(caps)
        .build_without_probe()
        .await?;

    // Check each relay
    println!("Relay 1: {:?}", state.power(1));
    println!("Relay 2: {:?}", state.power(2));

    // Control individual relays
    device.set_power(PowerIndex::new(1)?, PowerState::On).await?;
    device.set_power(PowerIndex::new(2)?, PowerState::Off).await?;

    // Toggle a specific relay
    device.toggle_power(PowerIndex::new(2)?).await?;

    Ok(())
}

Energy Monitoring

use tasmor_lib::{Device, Capabilities};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (device, state) = Device::http("192.168.1.101")
        .with_capabilities(Capabilities::neo_coolcam())
        .build_without_probe()
        .await?;

    // Energy data is available in initial state
    println!("Power:     {:?} W", state.power_consumption());
    println!("Voltage:   {:?} V", state.voltage());
    println!("Current:   {:?} A", state.current());
    println!("Today:     {:?} kWh", state.energy_today());
    println!("Yesterday: {:?} kWh", state.energy_yesterday());
    println!("Total:     {:?} kWh", state.energy_total());

    // Reset total energy counter
    let updated = device.reset_energy_total().await?;
    if let Some(energy) = updated.energy() {
        println!("Reset! New total: {} kWh", energy.total);
    }

    Ok(())
}

Typed Responses

All commands return typed responses for reliable parsing:

use tasmor_lib::{Device, Capabilities, Dimmer};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (device, _) = Device::http("192.168.1.100")
        .with_capabilities(Capabilities::rgbcct_light())
        .build_without_probe()
        .await?;

    // PowerResponse
    let power_resp = device.power_on().await?;
    println!("Relay 1 state: {:?}", power_resp.power_state(1));
    println!("All relays: {:?}", power_resp.all_power_states());

    // DimmerResponse
    let dimmer_resp = device.set_dimmer(Dimmer::new(50)?).await?;
    println!("Dimmer level: {}", dimmer_resp.dimmer());

    // ColorTemperatureResponse
    let ct_resp = device.set_color_temperature(153u16.try_into()?).await?;
    println!("Color temp: {} mireds", ct_resp.color_temperature());

    // HsbColorResponse
    let hsb_resp = device.set_hsb_color((180u16, 100u8, 100u8).try_into()?).await?;
    println!("HSB: {:?}", hsb_resp.hsb_color());

    Ok(())
}

Real-Time Updates (MQTT Callbacks)

Subscribe to device state changes pushed via MQTT:

use tasmor_lib::{MqttBroker, Capabilities};
use tasmor_lib::subscription::Subscribable;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let broker = MqttBroker::builder()
        .host("192.168.1.50")
        .credentials("mqtt_user", "mqtt_pass")
        .build()
        .await?;

    let (device, _) = broker.device("tasmota_bulb")
        .with_capabilities(Capabilities::rgbcct_light())
        .build_without_probe()
        .await?;

    // Subscribe to power changes (triggered by external events)
    device.on_power_changed(|relay_index, power_state| {
        println!("Relay {} changed to {:?}", relay_index, power_state);
    });

    // Subscribe to dimmer changes
    device.on_dimmer_changed(|dimmer| {
        println!("Dimmer changed to {}", dimmer.value());
    });

    // Subscribe to all state changes
    device.on_state_changed(|change| {
        println!("State change: {:?}", change);
    });

    // Handle connection events
    device.on_disconnected(|| {
        println!("Connection lost!");
    });

    device.on_reconnected(|| {
        println!("Reconnected! Consider calling query_state() to refresh");
    });

    // Keep the application running to receive callbacks
    tokio::signal::ctrl_c().await?;

    device.disconnect().await;
    broker.disconnect().await?;
    Ok(())
}

Multi-Device Management

Multiple devices can share a single broker connection for efficiency:

use tasmor_lib::{MqttBroker, Capabilities, Dimmer};
use tasmor_lib::subscription::Subscribable;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to broker once
    let broker = MqttBroker::builder()
        .host("192.168.1.50")
        .credentials("mqtt_user", "mqtt_pass")
        .build()
        .await?;

    // Create multiple devices sharing the broker connection
    let (living_room, living_state) = broker.device("tasmota_living")
        .with_capabilities(Capabilities::rgbcct_light())
        .build_without_probe()
        .await?;

    let (bedroom, bedroom_state) = broker.device("tasmota_bedroom")
        .with_capabilities(Capabilities::rgbcct_light())
        .build_without_probe()
        .await?;

    // Initial states are immediately available
    println!("Living room: {:?}", living_state.power(1));
    println!("Bedroom: {:?}", bedroom_state.power(1));

    // Subscribe to changes on each device
    living_room.on_power_changed(|relay, state| {
        println!("Living room relay {} -> {:?}", relay, state);
    });

    bedroom.on_power_changed(|relay, state| {
        println!("Bedroom relay {} -> {:?}", relay, state);
    });

    // Control devices
    living_room.power_on().await?;
    living_room.set_dimmer(Dimmer::new(75)?).await?;
    bedroom.power_on().await?;

    // Clean disconnect
    living_room.disconnect().await;
    bedroom.disconnect().await;
    broker.disconnect().await?;

    Ok(())
}

MQTT Device Discovery

Automatically discover all Tasmota devices on an MQTT broker:

use tasmor_lib::MqttBroker;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to broker
    let broker = MqttBroker::builder()
        .host("192.168.1.50")
        .port(1883)
        .credentials("mqtt_user", "mqtt_pass")
        .build()
        .await?;

    // Discover devices (10 second timeout)
    let devices = broker.discover_devices(Duration::from_secs(10)).await?;

    println!("Found {} devices:", devices.len());
    for (device, state) in &devices {
        println!("  - Power: {:?}, Dimmer: {:?}", state.power(1), state.dimmer());
    }

    // Use discovered devices...
    for (device, _) in devices {
        device.power_toggle().await?;
    }

    broker.disconnect().await?;
    Ok(())
}

Command Routines

Execute multiple commands atomically using the Routine builder:

use std::time::Duration;
use tasmor_lib::{Device, Capabilities, Routine, Dimmer, HsbColor};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (device, _) = Device::http("192.168.1.100")
        .with_capabilities(Capabilities::rgbcct_light())
        .build_without_probe()
        .await?;

    // Build a routine with multiple commands
    let wakeup_routine = Routine::builder()
        .set_dimmer(Dimmer::new(10)?)
        .power_on()
        .delay(Duration::from_secs(5))
        .set_dimmer(Dimmer::new(50)?)
        .delay(Duration::from_secs(5))
        .set_dimmer(Dimmer::new(100)?)
        .build()?;

    // Execute all commands atomically
    device.run(&wakeup_routine).await?;

    // RGB color transition routine
    let color_routine = Routine::builder()
        .set_hsb_color(HsbColor::red())
        .delay(Duration::from_secs(2))
        .set_hsb_color(HsbColor::green())
        .delay(Duration::from_secs(2))
        .set_hsb_color(HsbColor::blue())
        .build()?;

    device.run(&color_routine).await?;

    Ok(())
}

Parsing External Telemetry

If you're using your own MQTT client and want to parse Tasmota messages:

use tasmor_lib::telemetry::{parse_telemetry, TelemetryMessage};

fn handle_mqtt_message(topic: &str, payload: &str) {
    if let Ok(msg) = parse_telemetry(topic, payload) {
        match msg {
            TelemetryMessage::State { device_topic, state } => {
                println!("[{}] Power: {:?}, Dimmer: {:?}",
                    device_topic, state.power(), state.dimmer());
            }
            TelemetryMessage::Sensor { device_topic, data } => {
                if let Some(energy) = data.energy() {
                    println!("[{}] Power: {} W", device_topic, energy.power);
                }
            }
            TelemetryMessage::LastWill { device_topic, online } => {
                println!("[{}] {}", device_topic, if online { "online" } else { "offline" });
            }
            _ => {}
        }
    }
}

Runnable Examples

The examples/ directory contains complete runnable examples:

cargo run --example bulb_test -- 192.168.1.50 tasmota_topic user pass
cargo run --example energy_test -- 192.168.1.50 tasmota_plug user pass
cargo run --example routine_test -- 192.168.1.50 tasmota_bulb user pass
cargo run --example discovery_test -- 192.168.1.50 user pass
cargo run --example uptime -- http 192.168.1.100 admin password
cargo run --example uptime -- mqtt 192.168.1.50 tasmota_device user pass

Documentation

• API Documentation - Full API reference
• Tasmota Commands Reference - Official Tasmota protocol

Roadmap

• Stabilize API for 1.0 release

Development

# Run tests
cargo test

# Run tests with serde feature
cargo test --features serde

# Check code coverage
cargo tarpaulin --out Stdout

# Full verification pipeline
cargo check && cargo build && cargo test && cargo fmt --check && cargo clippy -- -D warnings -W clippy::pedantic

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Development setup
• Code style and linting
• Testing requirements
• Commit message conventions
• Pull request process

License

Licensed under the Mozilla Public License 2.0 (MPL-2.0).

Credits

Built for controlling Tasmota open-source firmware.

Key dependencies:

• Tokio - Async runtime
• paho-mqtt - MQTT client (wraps Eclipse Paho C library)
• reqwest - HTTP client

Testing:

• wiremock - HTTP mocking