This blog post is the sixth of a multi-part series of posts where I explore various peripherals in the ESP32C3 using standard library embedded Rust and the esp-idf-hal. Please be aware that certain concepts in newer posts could depend on concepts in prior posts.
Prior posts include (in order of publishing):
Introduction
In last week's post, MQTT was used to subscribe to a topic published by another client. This was achieved in part using the mqtt
abstractions in the ESP Rust esp_idf_svc
crate. Using the same crate, we can leverage abstractions to publish MQTT topics as well. In this post, we're going to look at how to configure an ESP using Rust to publish a topic to an MQTT broker.
๐ Knowledge Pre-requisites
To understand the content of this post, you need the following:
Basic knowledge of coding in Rust.
Basic familiarity with WiFi & MQTT.
๐พ Software Setup
All the code presented in this post is available on the apollolabs ESP32C3 git repo. Note that if the code on the git repo is slightly different then it means that it was modified to enhance the code quality or accommodate any HAL/Rust updates.
Additionally, the full project (code and simulation) is available on Wokwi here.
๐ Hardware Setup
Materials
๐จโ๐จ Software Design
Note: The code in this post is largely similar to last week's post. Also please refer to the same section of the prior post for additional background.
In this post, we are going to configure the ESP to publish a topic to an MQTT broker. The steps include the following:
Configure and Connect to WiFi
Configure MQTT
Create Client Instance and Define Event Behaviour
Wait for Broker Connection
Publish a Topic
๐จโ๐ป Code Implementation
๐ฅ Crate Imports
In this implementation, the following crates are required:
The
anyhow
crate for error handling.The
esp_idf_hal
crate to import the peripherals.The
esp_idf_svc
crate to import the device services (wifi in particular).The
embedded_svc
crate to import the neededwifi
andmqtt::client service
traits.The
std::thread
andstd::time
for sleep behavior and time measurement.
use anyhow;
use embedded_svc::mqtt::client::Event;
use embedded_svc::mqtt::client::QoS;
use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration};
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::mqtt::client::{EspMqttClient, MqttClientConfiguration};
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::wifi::{BlockingWifi, EspWifi};
use std::{thread::sleep, time::Duration};
๐ Initialization/Configuration Code
1๏ธโฃ Obtain a handle for the device peripherals: Similar to all past blog posts, in embedded Rust, as part of the singleton design pattern, we first have to take the device peripherals. This is done using the take()
method. Here I create a device peripheral handler named peripherals
as follows:
let peripherals = Peripherals::take().unwrap();
2๏ธโฃ Configure and Connect to WiFi: this involves the same steps that were done in the wifi post.
3๏ธโฃ Create the MQTT Configuration Handle: Within esp_idf_svc::mqtt::Client
there exists an MqttClientConfiguration
abstraction. This is the abstraction needed to configure MQTT. MqttClientConfiguration
contains a default
method allowing us to configure MQTT with a default
configuration. Following that we create an mqtt_config
handle as follows:
let mqtt_config = MqttClientConfiguration::default();
Note that if you were to use MQTT with a more advanced configuration, then this is the abstraction you need to update. This includes things like adding certificates for secure connections, defining client IDs, hostnames, and passwords among other things. Refer to the documentation for the full list of members.
That's it for Configuration!
๐ฑ Application Code
1๏ธโฃ Create Client Instance and Define Event Behaviour: Within the EspMqttClient
abstraction, there is a new
method that is used to create an instance of EspMqttClient
. new
has the following signature:
pub fn new(
url: &str,
conf: &MqttClientConfiguration<'_>,
callback: impl for<'b> FnMut(&'b Result<Event<EspMqttMessage<'b>>, EspError>) + Send + 'a
) -> Result<Self, EspError>
Note there are three parameters a url
, a MqttClientConfiguration
configuration, and a callback
. The url
as would be expected is the url
of the broker and conf
is the configuration we created earlier. callback
is a closure where we would need to define Event
behavior. Meaning, every time there is a broker Event
, we need to know what it is and react accordingly. Event
is an enum with the following signature:
pub enum Event<M> {
BeforeConnect,
Connected(bool),
Disconnected,
Subscribed(MessageId),
Unsubscribed(MessageId),
Published(MessageId),
Received(M),
Deleted(MessageId),
}
We're not going to react to all of the events but rather only the ones we care about. Those would be Connected
that conveys that we are connected to a broker, Suscribed
which means we are successfully subscribed to a topic, and Recieved
that conveys we received a message from the broker. Other than that, we can simply print the message event.
For this application, we are going to use the HiveMQ broker service. The service broker url
is mqtt://
broker.mqttdashboard.com
. Before running this code, you would need to go to the HiveMQ page and click connect. While connected, on the same page, you can define a topic to publish and a message then click publish. This would publish the message for any subscriber to read.
Following all of the above, a client
handle is created as follows:
let mut client = EspMqttClient::new(
"mqtt://broker.mqttdashboard.com",
&mqtt_config,
move |message_event| {
match message_event.as_ref().unwrap() {
Event::Connected(state) => println!("Connected"),
Event::Subscribed(id) => println!("Subscribed to {} id", id),
Event::Received(msg) => {
if msg.data() != [] {
println!("Recieved {}", std::str::from_utf8(msg.data()).unwrap())
}
}
_ => println!("{:?}", message_event.as_ref().unwrap()),
};
},
)?;
Note how the match statement matches what we mentioned earlier. The only additional thing to mention here is how we are handling the received message. Recieve
wraps a EspMqttMessage
type. EspMqttMessage
has several methods to process the incoming message. One of the methods is data
that recovers the received data in a &[u8]
. To print it out the received message it needs to be converted to a string using std::str::from_utf8
.
2๏ธโฃ Subscribe to Topic: While we've defined the event behavior, we haven't subscribed to a topic yet. For that, we need to call the subscribe
method on client
that is of type EspMqttClient
. Here's the code:
client.subscribe("testtopic/1", QoS::AtLeastOnce)?;
testtopic/1
is the default topic on HiveMQ. If you modify the topic there then you need to update it here.
When running the code, don't forget to connect the broker and then hit publish to see messages received by the ESP.
3๏ธโฃ Publish a Topic: To publish a topic, we need to call the publish
method in client
that is of type EspMqttClient
. publish
has 4 parameters; a &str
topic parameter, a QoS
type qos parameter, a bool
retain parameter, and a &[u8]
payload parameter. In the code we can create a count
variable that is incremented and published under a topic mytopic/1
every second. Here's the code:
let mut count:u8 = 0;
loop {
let msg = format!("Counter {}", count);
// Keep waking up device to avoid watchdog reset
client.publish("mytopic/1", QoS::AtLeastOnce, true, msg.as_bytes())?;
count += 1;
sleep(Duration::from_millis(1000));
}
๐ฑFull Application Code
Here is the full code for the implementation described in this post. You can additionally find the full project and others available on the apollolabs ESP32C3 git repo. Also, the Wokwi project can be accessed here.
use anyhow;
use embedded_svc::mqtt::client::Event;
use embedded_svc::mqtt::client::QoS;
use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration};
use embedded_svc::mqtt::client::Connection;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::mqtt::client::{EspMqttClient, MqttClientConfiguration};
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::wifi::{BlockingWifi, EspWifi};
use std::{thread::sleep, time::Duration};
fn main() -> anyhow::Result<()> {
// It is necessary to call this function once. Otherwise some patches to the runtime
// implemented by esp-idf-sys might not link properly. See https://github.com/esp-rs/esp-idf-template/issues/71
esp_idf_sys::link_patches();
let peripherals = Peripherals::take().unwrap();
let sysloop = EspSystemEventLoop::take()?;
let nvs = EspDefaultNvsPartition::take()?;
let mut wifi = BlockingWifi::wrap(
EspWifi::new(peripherals.modem, sysloop.clone(), Some(nvs))?,
sysloop,
)?;
wifi.set_configuration(&Configuration::Client(ClientConfiguration {
ssid: "Wokwi-GUEST".into(),
bssid: None,
auth_method: AuthMethod::None,
password: "".into(),
channel: None,
}))?;
// Start Wifi
wifi.start()?;
// Connect Wifi
wifi.connect()?;
// Wait until the network interface is up
wifi.wait_netif_up()?;
// Print Out Wifi Connection Configuration
while !wifi.is_connected().unwrap() {
// Get and print connection configuration
let config = wifi.get_configuration().unwrap();
println!("Waiting for station {:?}", config);
}
println!("Wifi Connected");
// Set up handle for MQTT Config
let mqtt_config = MqttClientConfiguration::default();
// Create Client Instance and Define Behaviour on Event
let mut client = EspMqttClient::new(
"mqtt://broker.mqttdashboard.com",
&mqtt_config,
move |message_event| {
match message_event.as_ref().unwrap() {
Event::Connected(_) => println!("Connected"),
Event::Subscribed(id) => println!("Subscribed to {} id", id),
Event::Received(msg) => {
if msg.data() != [] {
println!("Recieved {}", std::str::from_utf8(msg.data()).unwrap())
}
}
_ => println!("{:?}", message_event.as_ref().unwrap()),
};
},
)?;
// Subscribe to MQTT Topic
client.subscribe("testtopic/1", QoS::AtLeastOnce)?;
let mut count:u8 = 0;
loop {
let msg = format!("Counter {}", count);
// Keep waking up device to avoid watchdog reset
client.publish("mytopic/1", QoS::AtLeastOnce,true,msg.as_bytes())?;
count += 1;
sleep(Duration::from_millis(1000));
}
}
Conclusion
MQTT is a popular protocol in IoT applications due to its lightweight nature. As such, there is widespread support for MQTT implementations in many embedded devices. This post introduced how to set up MQTT publisher on ESP using Rust and the esp_idf_svc
. Have any questions? Share your thoughts in the comments below ๐.