Crate tasmor_lib 

TasmoR Lib - A Rust library to control Tasmota devices.

This library provides async APIs to interact with Tasmota-powered devices via both HTTP and MQTT protocols.

Supported Features

• Power control: Turn devices on/off, toggle, blink
• Light control: Dimmer, color temperature, HSB colors, fade effects
• Status queries: Device status, network info, firmware version
• Energy monitoring: Power consumption, voltage, current readings

Supported Modules

• Generic (Module 18): Flexible GPIO configuration
• Neo Coolcam (Module 49): Smart plugs with energy monitoring

Feature Flags

This library supports optional features to reduce compile time and binary size:

• http - Enables HTTP protocol support (enabled by default)
• mqtt - Enables MQTT protocol support (enabled by default)

Both features are enabled by default. To use only one protocol:

# HTTP only
tasmor_lib = { version = "0.5", default-features = false, features = ["http"] }

# MQTT only
tasmor_lib = { version = "0.5", default-features = false, features = ["mqtt"] }

Quick Start

HTTP Device with Auto-Detection

use tasmor_lib::Device;

#[tokio::main]
async fn main() -> tasmor_lib::Result<()> {
    // Create device with automatic capability detection
    // Returns (device, initial_state) tuple
    let (device, _initial_state) = Device::http("192.168.1.100")
        .build()
        .await?;

    // Basic power control
    device.power_on().await?;

    // Check capabilities before using features
    if device.capabilities().supports_dimmer_control() {
        device.set_dimmer(tasmor_lib::Dimmer::new(75)?).await?;
    }

    Ok(())
}

HTTP Device with Manual Capabilities

use tasmor_lib::{Device, Capabilities};

#[tokio::main]
async fn main() -> tasmor_lib::Result<()> {
    // Create device without probing (faster startup)
    // Returns (device, initial_state) tuple
    let (device, _initial_state) = Device::http("192.168.1.100")
        .with_capabilities(Capabilities::rgbcct_light())
        .build_without_probe()
        .await?;

    device.power_on().await?;
    Ok(())
}

MQTT Device

use tasmor_lib::MqttBroker;

#[tokio::main]
async fn main() -> tasmor_lib::Result<()> {
    // Connect to MQTT broker
    let broker = MqttBroker::builder()
        .host("192.168.1.50")
        .build()
        .await?;

    // Create device - returns (device, initial_state) tuple
    let (device, _initial_state) = broker.device("tasmota_switch")
        .build()
        .await?;

    device.power_toggle().await?;

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

MQTT Device with Callbacks (Event Subscriptions)

MQTT devices support real-time event subscriptions via callbacks:

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

#[tokio::main]
async fn main() -> tasmor_lib::Result<()> {
    let broker = MqttBroker::builder()
        .host("192.168.1.50")
        .build()
        .await?;

    let (device, _initial_state) = broker.device("tasmota_switch")
        .build()
        .await?;

    // Subscribe to power state changes
    device.on_power_changed(|relay_idx, state| {
        println!("Relay {} is now {:?}", relay_idx, state);
    });

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

    device.power_toggle().await?;

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

HTTP vs MQTT: Choosing a Protocol

This library supports two protocols for communicating with Tasmota devices. Each has distinct characteristics suited to different use cases.

Feature Comparison

Feature	HTTP	MQTT
Connection type	Stateless (request/response)	Persistent (pub/sub)
Real-time events	❌ Not supported	✅ Full support
Event subscriptions	❌ Compile-time error	✅ Subscribable trait
Connection overhead	New connection per command	Single persistent connection
Network requirements	Direct device access	MQTT broker required
Firewall friendly	✅ Standard HTTP/HTTPS	May require port forwarding
Multi-device efficiency	One connection per device	Shared broker connection
Device topic	N/A	✅ device.topic()
Explicit disconnect	N/A	✅ device.disconnect()

When to Use HTTP

• Simple scripts: One-off commands or automation scripts
• Direct device access: No MQTT broker available
• Firewall constraints: Only HTTP ports are open
• Low-frequency control: Occasional commands without state tracking

use tasmor_lib::Device;

// HTTP: Simple, direct control
let (device, _) = Device::http("192.168.1.100").build().await?;
device.power_on().await?;

When to Use MQTT

• Real-time monitoring: React to device state changes instantly
• Home automation: Integration with existing MQTT infrastructure
• Multi-device setups: Efficiently manage many devices via one broker
• State synchronization: Keep local state in sync with device state

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

// MQTT: Real-time events and state tracking
let broker = MqttBroker::builder()
    .host("192.168.1.50")
    .build()
    .await?;

let (device, _initial_state) = broker.device("tasmota_plug")
    .build()
    .await?;

// React to external changes (physical button, other apps, etc.)
device.on_power_changed(|idx, state| {
    println!("Relay {idx} changed to {state:?}");
});

// MQTT-specific methods
println!("Device topic: {}", device.topic());

// Clean disconnect when done
device.disconnect().await;
assert!(device.is_disconnected());

Type Safety

The protocol choice is encoded in the type system. Attempting to use subscription methods on an HTTP device results in a compile-time error:

use tasmor_lib::{Device, subscription::Subscribable};

let (device, _) = Device::http("192.168.1.100").build().await?;

// This will NOT compile - HTTP devices don't implement Subscribable
device.on_power_changed(|idx, state| {
    println!("Power changed");
});

Re-exports

pub use error::DeviceError;

pub use error::Error;

pub use error::ParseError;

pub use error::ProtocolError;

pub use error::Result;

pub use error::ValueError;

pub use state::DeviceState;

pub use state::StateChange;

pub use state::SystemInfo;

pub use protocol::HttpConfig;

pub use protocol::MqttBroker;

pub use protocol::MqttBrokerBuilder;

pub use command::Routine;

pub use command::RoutineBuilder;

pub use response::ColorTemperatureResponse;

pub use response::DimmerResponse;

pub use response::EnergyResponse;

pub use response::FadeDurationResponse;

pub use response::FadeResponse;

pub use response::HsbColorResponse;

pub use response::PowerResponse;

pub use response::RgbColorResponse;

pub use response::RoutineResponse;

pub use response::SchemeResponse;

pub use response::StartupFadeResponse;

pub use response::StatusResponse;

pub use response::WakeupDurationResponse;

pub use subscription::Subscribable;

pub use subscription::SubscriptionId;

pub use types::ColorTemperature;

pub use types::DateTimeParseError;

pub use types::Dimmer;

pub use types::FadeDuration;

pub use types::HsbColor;

pub use types::PowerIndex;

pub use types::PowerState;

pub use types::RgbColor;

pub use types::Scheme;

pub use types::TasmotaDateTime;

pub use types::WakeupDuration;

Modules

command

Tasmota command definitions.

discovery

MQTT device auto-discovery for Tasmota devices.

error

Error types for the TasmoR library.

protocol

Protocol implementations for communicating with Tasmota devices.

response

Response parsing for Tasmota JSON responses.

state

Device state management types.

subscription

Subscription system for device state changes.

telemetry

Telemetry message parsing for Tasmota MQTT messages.

types

Value types for Tasmota device control.

Structs

Capabilities

Capabilities of a Tasmota device.

CapabilitiesBuilder

Builder for creating custom capabilities.

Device

A Tasmota device that can be controlled via HTTP or MQTT.