mqtt_async_embedded/
lib.rs

1//! # Async MQTT Client for Embedded Systems
2//!
3//! `mqtt-async-embedded` is a `no_std` compatible, asynchronous MQTT client designed for embedded
4//! systems, built upon the [Embassy](https://embassy.dev/) async ecosystem.
5//!
6//! ## Core Features
7//!
8//! - **`no_std` & `no_alloc`:** Designed to run on bare-metal microcontrollers without requiring a
9//!   standard library or dynamic memory allocation. Buffers are managed using `heapless`.
10//! - **Fully Async:** Built with `async/await` and leverages the Embassy ecosystem for timers
11//!   and networking, ensuring non-blocking operations.
12//! - **Rust 2024 Edition:** Uses native `async fn` in traits, removing the need for `async-trait`.
13//! - **MQTT v3.1.1 and v5 Support:** Supports both major versions of the MQTT protocol, selectable
14//!   via feature flags.
15//! - **Transport Agnostic:** A flexible `MqttTransport` trait allows the client to run over any
16//!   reliable, ordered, stream-based communication channel, including TCP, UART, or SPI.
17//! - **QoS 0 & 1:** Implements "at most once" and "at least once" delivery guarantees.
18//!
19//! ## Usage
20//!
21//! To use the client, you need to provide a transport implementation, configure the client options,
22//! and then run the `poll` method continuously to handle keep-alives and incoming messages.
23//!
24//! ```no_run
25//! # use mqtt_async_embedded::client::{MqttClient, MqttOptions};
26//! # use mqtt_async_embedded::packet::QoS;
27//! # use mqtt_async_embedded::transport::MqttTransport;
28//! # use core::future::Future;
29//! #
30//! # struct MyTransport;
31//! # impl MqttTransport for MyTransport {
32//! #     type Error = ();
33//! #     async fn send(&mut self, buf: &[u8]) -> Result<(), Self::Error> { Ok(()) }
34//! #     async fn recv(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error> { Ok(0) }
35//! # }
36//! #
37//! # async fn run() -> Result<(), mqtt_async_embedded::error::MqttError<()>> {
38//! let transport = MyTransport;
39//! let options = MqttOptions::new("my-device-id", "mqtt.broker.com", 1883);
40//! let mut client = MqttClient::<_, 5, 256>::new(transport, options);
41//!
42//! client.connect().await?;
43//! client.publish("sensors/temperature", b"25.3", QoS::AtLeastOnce).await?;
44//!
45//! loop {
46//!     // Poll the client to process incoming messages and send keep-alives.
47//!     if let Some(event) = client.poll().await? {
48//!         // Handle incoming publish packets, ACKs, etc.
49//!         println!("Received event: {:?}", event);
50//!     }
51//! }
52//! # Ok(())
53//! # }
54//! ```
55
56#![no_std]
57// The `async_fn_in_trait` feature is now stable in the 2024 edition, so this is no longer needed.
58
59pub mod client;
60pub mod error;
61pub mod packet;
62pub mod transport;
63pub mod util;
64
65// Re-export key types for easier access at the crate root.
66pub use client::{MqttClient, MqttOptions};
67pub use packet::QoS;
68
mqtt_async_embedded/lib.rs

mqtt_async_embedded/
lib.rs
