Another year comes to an end; as always, it is an opportunity to reflect on the achievements of the past year and look forward to the next. It's been over 3.5 years since I embarked on my embedded Rust journey, and it only gets more exciting. This post will be a round-up of some of the main milestones in 2025 and what is planned for 2026.

I am always grateful for all the feedback and notes I keep receiving from the embedded & Rust community. If you have anything to add at any time please feel free to reach out on any social account or just email hi@theembeddedrustacean.com.

2025 Reflections 🪞

The goal remains to address more gaps in the embedded Rust educational ecosystem. A big part of it is attracting first-time embedded, curious users who are into Rust. More parts of the ecosystem are becoming stable, but there are still many moving parts. Here are some of the milestones in 2025:

• ⬆️ Simplified Embedded Rust Updates: Both the core library edition and standard library edition of Simplified Embedded Rust were updated twice in 2025. The changes accommodated Wokwi changes and the release of the no-std esp-hal 1.0.0, among others. The most recent update introduced a whole new project chapter that mimics a real-world product. Additionally, in May, the STM32 Blog Collection Edition was added to the book series. The new edition was created to collect all the STM32 blog posts from The Embedded Rustacean Blog in a single resource.

• 💵 Simplified Embedded Rust Pricing Model Update: Now that the esp-hal project is becoming more stable, the updates for the book are going to be less frequent, which warrants a change. As such, the subscription model was discontinued in September. The Simplified Embedded Rust adopted a pay once, receive updates forever model. This excludes the STM32 Blog Collection Edition, which can be obtained for free by subscribing to and sharing The Embedded Rustacean Newsletter.

• 📚 900+ Copies Sold: Since its launch in May 2024, Simplified Embedded Rust has sold over 900 copies in digital and print formats. This is around a 500-copy increase from the end of 2024.

• 🗞️ 61 Newsletter Editions: The Embedded Rustacean newsletter was launched in 2023 as a source for everything embedded Rust and is still going strong. While 2023 ended with nine editions, 2024 ended with 35, and now the newsletter is closing 2025 with 61 editions. The newsletter continued to operate twice a month throughout 2025.

• 🤓 5k+ Subscribers: The Embedded Rustacean Newsletter’s growth has been phenomenal. We ended 2024 with a little over 3k subscribers and now end 2025 with more than 5k. Maintaining the newsletter has also become much more challenging than the previous year. With the emergence of AI and LLMs, the internet has been flooded with technically inaccurate content, making it more time-consuming to filter through. The Embedded Rustacean thankfully maintained its high engagement rates, positioning itself as a trusted source.

• 🦀 uFerris Hardware Announcement: I've probably mentioned in the past that many Rustaceans have reached out with interest in content about real hardware. However, I was always wondering what the best format is to deliver more content with physical hardware. As such, in September of 2025, the uFerris hardware initiative was announced to The Embedded Rustacean subscribers. uFerris is meant to serve as companion hardware for Simplified Embedded Rust and as a beginner-friendly development board that supports multiple controllers. Subscribers were polled on whether they would be interested in uFerris, and more than 70% agreed it was a good fit for them. Ever since, the effort to create the uFerris hardware has been launched. Prototype boards were manufactured and sent to early access users for evaluation. You can learn more about uFerris here.

A Look Forward to 2026 🔮

What’s in Plan

Just like before, I do much of this work in my spare time. As a result, to continue offering the best-quality material, I try to focus on what would benefit the community most by listening to the feedback I receive.

• 📖 Simplified Embedded Rust Roadmap: While the esp-hal project is stabilizing, there are still a few planned updates in the book's short-term roadmap. One update involves adding support for esp-radio (formerly esp-wifi) in the no-std edition of the book. This ultimately depends on when esp-radio reaches stability, but hopefully an update will be out on or around Q2 of 2026. Another update would involve accommodating the uFerris hardware by complementing the existing book examples for uFerris.

• 🦀 uFerris Hardware: uFerris hardware is currently being evaluated, and another hardware iteration is planned before becoming available for pre-order. Pre-orders are expected to start around Q2 of 2026. To stay up to date with what’s happening on uFerris, make sure to subscribe to The Embedded Rustacean.

• 📖 Additional Educational Material? Beyond the material in the books, I reckon there should be additional material to help learners expand their knowledge into more advanced (or even different) concepts. This could take the form of another book, microcourses, blog posts, or similar content. The challenge stems from the ecosystem's dynamic nature, which makes it harder to maintain the material consistently. What I have in mind going forward is creating more uFerris-centric material, maybe even driving community efforts toward it. uFerris is meant to serve as a reference platform that can accommodate multiple controllers.

• 🌲 Expand Embedded Rust Reach & Continue Growing Newsletter: The newsletter has been a core part of giving back to the community. The efforts to grow it will continue, hopefully enabling me to provide high-quality content continuously.

• 🏟️ Conferences: In 2024, I was fortunate to talk at the Rust in Paris conference. You can find the video here. There is more I have planned for 2026, but it is yet to be confirmed. Stay tuned!

Acknowledgments 🙏

Finally, I would like to thank everybody who contributed to these accomplishments; without their effort, none of the above would have been possible.

Conclusion

2025 has been nothing less than spectacular for embedded Rust. Embedded educational material is in a much better place now, but there is still much to catch up on. There is still a gap between the ecosystem's updates and the supporting educational material. The dynamic nature of many projects is probably the primary contributor to that gap. However, we seem to be inching toward more stability, at least in some of the more significant projects. Hopefully, 2026 is the year when many of these gaps are closed.

Another year comes to an end, as such, this is an opportunity to reflect on the achievements of 2024 and look forward to 2025. It's been over 2.5 years since I embarked on my embedded Rust journey, and it remains as exciting as ever. If you’re interested in how the journey started, refer to the post from last year. This post will be a round-up of everything that happened in 2024 and what to expect in 2025.

I am forever grateful for all the feedback and notes I keep receiving from the embedded & Rust community. It has been the guiding light and fuel for all my efforts. If you have anything to note after reading this post or have any ideas to share, please feel free to reach out on any social account or just email hi@theembeddedrustacean.com

2024 Reflections 🪞

The goal was and remains to address the gaps in the embedded Rust educational ecosystem. A big part of it is to attract first-time embedded curious users who are into Rust. There was, and still is, a lot of ground to cover. In that regard, there were a lot of interesting and significant milestones in 2024, here they are:

• 📖 Simplified Embedded Rust Published: In May 2024, I successfully published Simplified Embedded Rust. Also, although what I had in plan was one book covering ESP devices, I ended up with a series including two editions: a core library edition and a standard library edition. The editions covered both frameworks that the Espressif ecosystem supports for embedded Rust.

• 📚 400+ Copies Sold: Since its launch in May 2024, Simplified Embedded Rust has sold over 400 copies in digital and print formats. The book's reception was beyond my expectations. I was overwhelmed by the messages of support and thanks I received.

• ✍️ 100+ Blog Posts: I started with blog posts in the Rust-embedded educational space, and it was an amazing journey. Rustaceans continuously ping me about how they find the blog posts useful and how they helped them with their own journeys. In 2024, I reached the milestone of 100 blog posts. However, my focus has shifted somewhat since. I will discuss this further below.

• 🛍️ Rebranding: In 2024, an effort was made to consolidate all activities under one brand: The Embedded Rustacean. For those that have been around for a bit, there was the former Apollo Labs brand that the blog was operating under and is no longer used. There are still some github repos that are yet to be consolidated though.

• 🗞️ 35 Newsletter Editions: The Embedded Rustacean newsletter was launched in 2023 as a source for everything embedded Rust. 2023 ended with nine editions. The newsletter continued to operate bi-monthly throughout 2024. In 2024, 26 newsletter editions regularly highlighted news, educational material, and jobs in the embedded and Rust ecosystem. Throughout the year, the ecosystem had many exciting advancements, with several new companies joining the adoption list. From how things look, we can expect a very exciting 2025 for embedded Rust.

• 🤓 3.7k+ Subscribers: The Embedded Rustacean’s growth has been phenomenal. From less than 900 subscribers at the end of 2023, it has now crossed the 3700 subscriber mark! Further, the newsletter has had high engagement rates, exceeding a 40% open rate and a 30% click-through rate. These numbers testify to the usefulness of the material it has been delivering.

• 🏟️ 2 Conferences: In 2024, I had the pleasure to participate in 2 conferences to talk about embedded Rust. In July, I participated in the UA Rust Conference with my talk “Standard vs. Core Library: An Embedded Perspective.“ Additionally, I participated in the Espressif DevCon in September with my talk “Redefining Embedded Learning with ESP & Rust Bridging the Gap Between Complexity.“ While the Espressif talk is currently public on YouTube, the UARust talk has not yet been published publicly.

A Look Forward to 2025 🔮

What I Have in Plan

In 2024, I switched jobs to one that required more of my time. Also, just like before, I am still doing much of this work in my spare time. As a result, to continue offering the best quality material, I will switch to an alternate strategy where I can deliver more efficiently.

• ⬇️ ✍️ ⬆️ 📖 Less Blog Posting, More Book Updating: It has been challenging to find the time to maintain The Embedded Rustacean Blog, the Simplified Embedded Rust book, and The Embedded Rustacean newsletter. Especially as the number of blog posts has been piling up, many have become outdated due to the dynamic ecosystem. This makes the posts quite challenging to maintain individually with each update. Consequently, I’ll be shifting most of my focus toward maintaining Simplified Embedded Rust to stay dated with the ecosystem changes as it is more central and self-contained. Blog posts will be less frequent but probably reserved for supplementing concepts not covered by the book.

• 🏗️ Projects: Some comments I have received regarding Simplified Embedded Rust suggest that it is similar to other embedded Rust educational resources in that it lacks a project (or projects) for practice. I will work on addressing this early in 2025.

• 🌲 Expand Embedded Rust Reach & Continue Growing Newsletter: The growth experienced by The Embedded Rustacean newsletter in 2024 was exceptional. In 2025, I will be investing more effort in growing the newsletter and expanding its reach further to encompass more embedded Rust enthusiasts.

• 🏟️ Conferences: I plan to continue attending Rust conferences as circumstances allow. For now, I plan to attend Rust in Paris in March 2025.

• 📚 Another Book? This is a bit of a long shot, but ever since publishing Simplified Embedded Rust, I’ve had several inquiries about whether I would write a more hardware-oriented book with advanced concepts, essentially expanding the Simplified Embedded Rust series. Additionally, I have been pinged before about expanding into different devices like the Raspberry Pi Pico or the nRFs. While I am still inclined to venture in that direction, it really depends on how much time I can dedicate. Ultimately, my plan is to create a streamlined learning flow, not necessarily in the form of a book.

Acknowledgments 🙏

Finally, I would like to thank everybody who contributed to these accomplishments; without their effort, none of the above would have been possible. In particular:

• All the book reviewers who dedicated the time to proofread Simplified Embedded Rust in their spare time and provide their comments.

• The Espressif DevCon and the UARust Conference organizers, thank you for your time revising and preparing the conference recordings.

Conclusion

The embedded Rust ecosystem is growing spectacularly. Last year, I highlighted a scarcity of embedded Rust educational material, though, at the end of this year, we are in a different place. A lot of new material has emerged, and even existing material has been updated and enhanced. Hopefully, this trend is expected to continue growing. Now that there is a material that addresses folks coming from a non-embedded background, maybe 2025 is the year to shift gears to introduce more intermediate to advanced material. While there are many “pure” Rust topics to tackle, there are also integration topics that might be of increased interest. For example, in 2024, we saw Rust integrated into the Zephyr framework, in addition to other efforts attempting to integrate Rust into existing codebases. 2025 might be the year where we see more effort for resources pouring into that direction.

On Friday, May 17th, 2024, the release of Simplified Embedded Rust was announced marking a new kind of book in the embedded Rust learning space. I'm happy to say that this book, designed to address the needs of learners, has been received with great excitement and enthusiasm. Following its release, I received an overwhelming number of responses and questions. Common queries included:

• 📚 When is the paperback going to be available?

• 💳 Why the subscription model?

• 📖 Which edition should I choose?

• 🦀 What's Rust?

• 🤔 How different is the book from The Embedded Rustacean blog posts?

In this post, I aim to address these questions and provide further insights into the motivations and goals behind the book.

Motivation Behind the Book 🎓

Curiosity is a vital component of learning 🐈. As educators, we strive to nurture this curiosity to help students discover their passion. However, without engaging and exciting material, we risk losing their interest and attention. Hands-on learning is crucial, but what is required to get started can vary significantly across different fields. Beginners are in some cases expected to deal with complex tools they encounter for the first time. For instance, coding used to require relatively involved setups, whereas now, it can be done in seconds on several web-based platforms. Embedded adds a twist to this -> hardware 😱.

Simplified Embedded Rust is as much about transforming the approach to embedded systems learning as it is about embedded Rust. Learning embedded systems can be daunting due to the complexities of toolchains and setups, especially for beginners. Rust, often seen as a challenging language, adds another layer of difficulty. This book rises to the challenge by simplifying Rust's introduction within the context of embedded systems.

Goals 🎯

The primary goal of Simplified Embedded Rust is to make embedded Rust accessible and straightforward. By lowering the barrier to entry, the book aims to increase accessibility and provide a coherent overview of embedded Rust, minimizing the challenges many of us faced early on. The book gradually builds up the necessary knowledge, making it easier for readers to grasp more complex concepts. Practical material for each peripheral is included, allowing readers to apply their learning effectively without needing physical hardware. Thanks to modern tools like Wokwi we can replicate the software learning experience in embedded more effectively. The book also supports programming any supported ESP device in Rust, leveraging the powerful Espressif crates.

Why Rust? 🦀

Rust is a modern systems programming language designed for performance, safety, and concurrency. Unlike many traditional languages, Rust provides memory safety without requiring a garbage collector, making it a great fit for low-level programming where direct hardware access and real-time constraints are crucial.

Key features of Rust include:

• Memory Safety: Rust ensures memory safety through its infamous borrow checker preventing common bugs such as null pointer dereferencing and buffer overflows by using a strict ownership system. 🔒

• Concurrency: Rust's concurrency model ensures that data races are caught at compile time, making it easier to write safe, concurrent code. 🏎️

• Performance: Rust's performance is comparable to C and C++, making it suitable for systems programming and other performance-critical applications. 🚀

• Tooling: Rust comes with a rich set of tools, including a package manager (Cargo), a build system, and integrated testing support. 🛠️

Rust's unique combination of memory-safety, performance, and modern tooling makes it an excellent choice for embedded systems programming, where reliability and efficiency are paramount.

Why ESP? 🌐

The choice of ESP was deliberate. ESP offers the lowest entry barrier and has official Rust support, making it an ideal starting point. Espressif was one of the first system-on-chip (SoC) hardware companies to announce official support for Rust. Espressif has also a dedicated Rust team that contributes to their open source project to support embedded crates for ESPs. Through this effort, and among many other things, espressif also supports Rust on Wokwi. The espressif Rust team was also instrumental in helping me bring this book to life.

The Review Process 🔍

Simplified Embedded Rust is self-published, but ensuring its technical accuracy and effectiveness was paramount. To achieve this, both editions of the book was sent for review by a diverse group of 20 reviewers, who provided invaluable feedback. The group included both experienced and beginner developers. Their insights were invaluable in helping ensure the book meets its goals and maintains technical correctness.

How is This Book Different from The Blog? ✍️

A question I received is how the book differs from the content on The Embedded Rustacean blog (formerly apollolabs tech blog). While Simplified Embedded Rust builds on several examples from the blog, it offers core differences that make it a more comprehensive learning resource. Unlike the blog, the book is self-contained with exercises, aims to be ESP agnostic, offers a clear flow, and provides a conceptual background on embedded systems and the Rust ecosystem. The book is also regularly updated and includes pre-wired exercises, ensuring readers have a seamless learning experience from start to finish.

What the Book Covers 📘

The book starts with a generic explanation of microcontroller systems that drive embedded systems, providing essential background knowledge for programming embedded systems. This is followed by an in-depth explanation of the ESP and Rust embedded ecosystems. The remainder of the book is programming-oriented, covering all core peripherals and how to code each in Rust on ESP. Each peripheral has its own chapter that includes:

1. Conceptual Background: An overview of the peripheral and how it operates.

2. Configuration and Coding Steps: Detailed steps to configure and program the peripheral.

3. Application Example(s): A practical example (or examples) to demonstrate the peripheral in action.

4. Exercises: Exercises to reinforce learning and provide hands-on experience.

Who is This Book For? 🌟

Simplified Embedded Rust is targeted at individuals familiar with Rust who are eager to explore embedded systems for the first time, as well as embedded developers at all experience levels who are new to Rust. Whether you're looking to expand your skills or embark on a new learning journey, this book aims to meet your needs and offer valuable insights into the world of embedded Rust.

Choosing the Right Edition 📚

Espressif offers two approaches for embedded development on their SoCs; std and no-std. std, also known as the standard library, which is based on the ESP-IDF framework. no-std, also known as the core library, which is for bare-metal development. For those seeking more details, please check a more detailed overview here. As such, the book is available in two editions supporting each approach: the standard library edition and the core library edition. The choice depends on the depth of knowledge you seek. The standard library edition is easier to start with especially if coming from a Rust background, while the core library edition delves a tad deeper. If still confused, the following table might help you decide:

To acquire the Core Edition click here.

To acquire the Standard Edition click here.

Why a Subscription Model? 💡

A frequent question is why the book is subscription-based. While this model might not be ideal for everyone, it reflects the ongoing effort required to keep the book current in a dynamic ecosystem. There is a significant amount of work that would be needed to keep the book up to date. For example, during the review process, significant changes occurred to the esp-hal which necessitated updates, delaying the publication to ensure that the book is up to date.

Still, for those who prefer a one-time purchase, there are two options:

1. Keep the subscription only if you want updates beyond the minimum duration. You can still purchase once and cancel anytime before renewal, maintaining access to the latest material until the end of the billing cycle. If you need an updated copy at any time later, simply resubscribe.

2. Wait for the paperback version, which will be available on Amazon within a month.

Upcoming Updates 🛠️

Although the book is published, I view this as a start rather than an end to an exciting journey. The ecosystem, as mentioned before, is evolving quickly. There are still a lot of exciting things to come that I hope to incorporate. Some short-term milestones include:

• Publishing additional formats. This includes Mobi, Epub, and Paperback. These formats should be available within a month.

• Since the book is meant to be ESP agnostic, pre-wired examples and templates for all other ESPs will be provided. Also, if necessary, the content would be modified to make it more overarching.

• Added projects. The idea is to incorporate projects for readers so that they can apply their knowledge from all peripherals.

• Added examples. Some peripherals might benefit from more examples. Also, some more peripherals might be added, notably SPI.

• Incorporate community crates. Some might notice that the core edition does not have a connectivity/networking chapter. This is because I am waiting on the crate involved, esp-wifi, to become more stable

If you have any ideas or suggestions, please feel free to submit a feature request to either of the book's GitHub repositories. You can submit here for the Standard edition and here for the Core edition.

Acknowledgments 🙏

Finally, this work would not have been possible without all the support that I have received. I extend my heartfelt thanks to many individuals and groups. This experience has underscored how special the Rust community is. I am grateful to the reviewers, the Espressif Rust team, and all my students who have been a constant source of inspiration. Thank you for your support and contributions to making Simplified Embedded Rust a reality.

Conclusion ✨

Simplified Embedded Rust is more than just a book—it's a gateway to a transformative journey to becoming an embedded Rust developer. Whether you're a seasoned developer or just starting your journey, this book aims to make embedded Rust accessible, engaging, and practical. I invite you to dive in, explore the world of embedded Rust, and start your transformation.

Thank you for your support, and I look forward to your feedback and contributions!

This post is the sixth of a multi-part series where I'm exploring the use of Bluetooth Low Energy along embedded Rust on the ESP32. Information in this post might rely on knowledge presented in past posts.

1. Embedded Rust Bluetooth on ESP: BLE Scanner

2. Embedded Rust Bluetooth on ESP: BLE Advertiser

3. Embedded Rust Bluetooth on ESP: BLE Server

4. Embedded Rust Bluetooth on ESP: BLE Client

5. Embedded Rust Bluetooth on ESP: Secure BLE Client

Introduction

In this post, we're going to build on the BLE Server post to instead create a secure BLE server. We're going to create a peripheral device that will assume the role of a server upon connection establishment. Afterward, the connection will be secured. Similar to past posts, the code will be built using the esp32-nimble crate.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with standard library development in Rust with the ESP.

• Basic knowledge of networking layering concepts/stacks (ex. OSI model).

• Basic knowledge of Bluetooth.

💾 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.

🛠 Hardware Setup

Materials

• ESP32-C3-DevKitM

  

  🔌 Connections

  No connections are required for this example.

👨‍🎨 Software Design

The steps in securing a channel were presented in last week's post where we secured the connection of a BLE Client. It was demonstrated how after a connection is established, it can be secured by encrypting the connection. The exact same idea applies whether the device is a server or a client. The terms pairing and bonding were also introduced. security information to quickly establish a secure connection.

We mentioned that after a connection is secured, we further have the option to secure particular attributes. This is captured through the attribute properties. The properties available related to security include a choice of authentication, authorization, or encryption. These all apply to both read and write operations. As such, a server may define permissions independently for each characteristic. The server may allow some characteristics to be accessed by any client, while limiting access to other characteristics to only authenticated or authorized clients.

Authentication guarantees that a message has originated from a trusted party while authorization is a confirmation by the user to continue with the procedure. Characteristics that require authentication cannot be accessed until the client has gone through an authenticated pairing method. Authorization, on the other hand, is typically handled by the application. The BLE stack would forward requests to the application to complete the process.

In this post, we'll be appending the code in the peripheral server post to make it's connection secure. As such, we'll be creating a secure peripheral server with one characteristic. In that context, the code will take the following steps:

1. (Added Step) Configure device security capabilities and connection method for pairing

2. (Modified Step) Create Secure Service & Characteristic

3. Configure Advertising Data & Start Advertising

4. Establish a connection

5. Read a characteristic value every second

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import delays.

• The esp_idf_sys crate since its needed.

• The esp32_nimble crate for the BLE abstractions.

use esp32_nimble::{enums::*, uuid128, BLEAdvertisementData, BLEDevice, NimbleProperties};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_sys as _;

🎛 Initialization/Configuration Code

1️⃣ Obtain a handle for the BLE device: Similar to the pattern we've seen in embedded Rust with peripherals, as part of the singleton design pattern, we first have to take ownership of the device peripherals. In this context, its the BLEDevice that we need to take ownership of. This is done using the take() associated method. Here I create a BLE device handler named ble_device as follows:

let ble_device = BLEDevice::take();

2️⃣ Configure Device Security: In this step we need to configure the device I/O capabilities for pairing and set the authorization mode. The authorization mode would determine the pairing method and whether bonding is required or not. The authorization mode is captured through several flags mentioned earlier configurable through the esp32_nimble::enums::AuthReq enum. To match the client from last week, we will choose the passkey entry method.

To configure security parameters, we first need to call the security method on the BLEDevice instance. This would return a BLESecurity type that renders access to the security configuration methods. The authorization mode is configured through the set_auth method where we pass a AuthReq enum choice. AuthReq::all means setting all the flags and implies the passkey entry method and bonding. We also need to set the IO capabilities through the set_io_cap method. For that, we need to pass a SecurityIOCap enum option which we pass DisplayOnly. Here's the code:

// Configure Device Security
ble_device
    .security()
    .set_auth(AuthReq::all())
    .set_passkey(123456)
    .set_io_cap(SecurityIOCap::DisplayOnly)
    .resolve_rpa();

Note the resolve_rpa method utilized. RPA stands for resolvable private address. RPA is required to establish a higher level of security which generates what is referred to as a Long Term Key (LTK). Without going into too much detail, this would be required if you want to test with certain devices, especially iOS ones.

3️⃣ Create an Advertiser Instance: After initializing the NimBLE stack we create an advertiser instance by calling get_advertising, this will create a &Mutex<BLEAdvertising> instance. Heres the code:

let ble_advertiser = ble_device.get_advertising();

4️⃣ Obtain Handle for Server: We create a server instance by calling get_server, this will create a BLEServer instance. Heres the code:

let server = ble_device.get_server();

5️⃣ Define Server Connect & Disconnect Behaviour: using the server instance there exists a on_connect method for BLEServer. on_connect has one argument which is a closure that passes a handle for a BLEServer and a BLEConnDesc that contains connection information. In the closure body, upon connect, we'll print the connection data to the console then update the connection parameters. To update connection parameters, the BLEServerupdate_conn_params method is used. Here's the code:

server.on_connect(|server, clntdesc| {
    // Print connected client data
    println!("{:?}", clntdesc);
    // Update connection parameters
    server
        .update_conn_params(clntdesc.conn_handle(), 24, 48, 0, 60)
        .unwrap();
});

Similar to on_connect theres an on_disconnect method. on_disconnect also has one argument which is a closure that passes a handle for a BLEConnDesc and a Result that contains the reason for disconnection. All were going to do is to print a message that our device disconnected.

server.on_disconnect(|_desc, _reason| {
    println!("Disconnected, back to advertising");
});

6️⃣ Define Services & Characteristics: In this example, only one characteristic will be defined with a read and notify properties. However, every characteristic has to be associated with (listed under) a service. To create a service, within BLEServer there exists a create_service method that takes a single BleUuid argument. BleUuid is an enum representing a Bluetooth UUID. To make things easier, the nimble crate provides a uuid128 macro to parse a 128 UUID from string literals at compile time. We only need to pass a UUID string literal and the macro would take care of the rest. We create a service as follows:

// Create a service with custom UUID
let my_service = server.create_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"));

Next, we need to create a characteristic. This is done using the BLEServicecreate_characteristic method which has two arguments; BlueUuid and NimbleProperties. NimbleProperties is a struct containing a collection of associated constants representing the different supported operations and required security levels. For this characteristic we will support encrypted READ through the NimbleProperties::READ_ENC property. create_characteristic will return a Arc<Mutex<BLECharacteristic>>. As such, we can set a starting value for the characteristic that we created using the BLECharacteristic set_value method. set_value takes a single &[u8] parameter. Here's the code:

// Create a characteristic to associate with created service
let my_service_characteristic = my_service.lock().create_characteristic(
    uuid128!("681285a6-247f-48c6-80ad-68c3dce18585"),
    NimbleProperties::READ | NimbleProperties::READ_ENC,
);

// Set a starting value for the characteristic
my_service_characteristic.lock().set_value(b"Start Value");

6️⃣ Configure Advertiser Data: This step is similar to what was done in the BLE Advertiser post. A small difference is that here we are also attaching the service to the advertisement data. This is done using the add_service_uuid method. Note that the UUID being advertised is the same service UUID created earlier.

// Configure Advertiser Data
ble_advertiser
    .lock()
    .set_data(
        BLEAdvertisementData::new()
            .name("ESP32 Server")
            .add_service_uuid(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1")),
    )
    .unwrap();

That's it for configuration!

📱 Application Code

Start Advertising: Now we have to start the advertising process. This is done by calling the BLEAdvertising start method.

ble_advertiser.lock().start().unwrap();

Update Characteristic: All we have to do now is keep updating the characteristic by calling the set_value method again. Here, the my_service_characteristic value keeps getting updated every one every second by incrementing its contents.

let mut val = 0;

loop {
    FreeRtos::delay_ms(1000);
    my_service_characteristic.lock().set_value(&[val]).notify();
    val = val.wrapping_add(1);
}

🧪 Testing

In order to test this code, you can use nRF connect mobile app or the bluefruit connect mobile app. In either app you would be able to connect to the ESP and poll the server data.

📱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.

use esp32_nimble::{enums::*, uuid128, BLEAdvertisementData, BLEDevice, NimbleProperties};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_sys as _;

fn main() {
    esp_idf_sys::link_patches();

    // Take ownership of device
    let ble_device = BLEDevice::take();

    // Obtain handle for peripheral advertiser
    let ble_advertiser = ble_device.get_advertising();

    // Configure Device Security
    ble_device
        .security()
        .set_auth(AuthReq::all())
        .set_passkey(123456)
        .set_io_cap(SecurityIOCap::DisplayOnly)
        .resolve_rpa();

    // Obtain handle for server
    let server = ble_device.get_server();

    // Define server connect behaviour
    server.on_connect(|server, clntdesc| {
        // Print connected client data
        println!("{:?}", clntdesc);
        // Update connection parameters
        server
            .update_conn_params(clntdesc.conn_handle(), 24, 48, 0, 60)
            .unwrap();
    });

    // Define server disconnect behaviour
    server.on_disconnect(|_desc, _reason| {
        println!("Disconnected, back to advertising");
    });

    // Create a service with custom UUID
    let my_service = server.create_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"));

    // Create a characteristic to associate with created service
    let my_service_characteristic = my_service.lock().create_characteristic(
        uuid128!("681285a6-247f-48c6-80ad-68c3dce18585"),
        NimbleProperties::READ | NimbleProperties::READ_ENC ,
    );

    // Modify characteristic value
    my_service_characteristic.lock().set_value(b"Start Value");

    // Configure Advertiser Data
    ble_advertiser
        .lock()
        .set_data(
            BLEAdvertisementData::new()
                .name("ESP32 Server")
                .add_service_uuid(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1")),
        )
        .unwrap();

    // Start Advertising
    ble_advertiser.lock().start().unwrap();

    // (Optional) Print dump of local GATT table
    // server.ble_gatts_show_local();

    // Init a value to pass to characteristic
    let mut val = 0;

    loop {
        FreeRtos::delay_ms(1000);
        my_service_characteristic.lock().set_value(&[val]).notify();
        val = val.wrapping_add(1);
    }
}

Conclusion

This post introduced how to create a secure BLE server on the ESP32-C3 with Rust. This was by using the esp32-nimble crate in a standard library development environment using the esp-idf-hal . In this post, the ESP32-C3 was configured as a secure peripheral device advertising a service. The device also assumes a server role after a connection is established and secures the connection with a passkey. Have any questions? Share your thoughts in the comments below 👇.

This post is the fourth of a multi-part series where I'm exploring the use of Bluetooth Low Energy along embedded Rust on the ESP32. Information in this post might rely on knowledge presented in past posts.

1. Embedded Rust Bluetooth on ESP: BLE Scanner

2. Embedded Rust Bluetooth on ESP: BLE Advertiser

3. Embedded Rust Bluetooth on ESP: BLE Server

4. Embedded Rust Bluetooth on ESP: BLE Client

Introduction

In this post, we're going to build on the previous post to instead create a secure BLE client. We're going to create a central device that will assume the role of a client upon connection establishment. Afterward, the connection will be secured. Similar to past posts, the code will be built using the esp32-nimble crate.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with standard library development in Rust with the ESP.

• Basic knowledge of networking layering concepts/stacks (ex. OSI model).

• Basic knowledge of Bluetooth.

💾 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.

🛠 Hardware Setup

Materials

• ESP32-C3-DevKitM

  

  🔌 Connections

  No connections are required for this example.

👨‍🎨 Software Design

After a connection is established is can be secured by encrypting the connection. This is such that data exchanged is not in plain text. Encryption requires that keys are exchanged as part of the process in securing a connection. There are two terms involved in this process, pairing and bonding. Pairing refers to the process of exchanging and keys for encryption purposes. Bonding on the other hand is in reference to encryption for future reconnections. Additionally, bonding always happens after pairing is completed.

There are several steps that a BLE connection goes through to secure a channel:

1. Establish I/O Capabilities: As part of the pairing process both devices have to establish what their I/O capabilities are. In addition, among other things, devices exchange supported security features and whether or not bonding is requested. I/O capabilites include the following options:

   • DisplayOnly: The peer only has a display

   • DisplayYesNo: The peer has a display and the option to select “yes” or “no”

   • KeyboardOnly: The peer has keyboard only

   • NoInputNoOutput: The peer has no input and no output capabilities

   • KeyboardDisplay: The peer has keyboard and display capabilities

2. Choose Pairing Method: In order to complete pairing, devices need to agree on a pairing method to exchange keys. The pairing method chosen is decided based on a Out of Bound (OOB) flag, the Man-In-The-Middle (MITM) flag, and the I/O capability chosen earlier. Pairing methods include (least secure to most secure):

   • Just Works: This method is the simplest and most convenient, where devices automatically exchange keys without any user interaction. However, it provides the lowest level of security and is vulnerable to man-in-the-middle attacks.

   • Passkey Entry: In this method, one device displays a randomly generated passkey, and the user must enter the same passkey on the other device. This ensures that the devices are physically present and aware of each other during the pairing process.

   • Out-of-Band (OOB): OOB pairing involves using an external channel, such as NFC or QR codes, to exchange pairing information securely. This method provides a high level of security by leveraging an additional communication channel.

   • Numeric Comparison: Numeric Comparison pairing provides a high level of security by ensuring that both devices are aware of each other's identities. This method also makes sure that there is no interception or tampering during the pairing process. It requires active participation from the users to verify the displayed numeric values, which adds an extra layer of security against unauthorized access. In this method, the devices display a 6-digit number and the user selects “yes” or “no” to confirm the display.

3. Bonding (Optional): After successful pairing, the devices have the option to enter into a bonding relationship. This involves securely storing the security information exchanged during pairing, such as the encryption keys and device identities, in persistent memory. As such, when the devices come into proximity again, they can use the stored security information to quickly establish a secure connection.

Now that the connection is secured, we further have the option to secure particular attributes. In the BLE Server post, GATT operations were explained in which the supported operations by an attribute were defined through its properties. As such, there are additional properties available related to security for choice of authentication, authorization, and encryption. Authentication guarantees that a message has originated from a trusted party while authorization is a confirmation by the user to continue with the procedure. These attribute properties, however, are set by a server as the client would be accessing the attributes remotely.

Note that attributes can be associated with different levels of security. The level of security associated with an attribute, like GATT operations, is captured through its properties. This is something we'll be demonstrating in a secure server example in next week's post. This means that there could be several attributes available applying different security levels. A client in turn would only be able to access the attributes matching (or less than) the level of security is achieves.

In this post, we'll be appending the code in the central client post to make it's connection secure. As such, we'll be creating a secure central client with one characteristic. In that context, the code will take the following steps:

1. (Added Step) Configure device security capabilities and connection method for pairing

2. Scan and find a particular advertiser

3. Establish a connection

4. (Added Step) Secure the connection

5. Read a characteristic value every second

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import delays and blocking abstractions.

• The esp_idf_sys crate since its needed.

• The esp32_nimble crate for the BLE abstractions.

use esp32_nimble::{enums::*, uuid128, BLEClient, BLEDevice};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_hal::task::block_on;
use esp_idf_sys as _;

🎛 Initialization/Configuration Code

1️⃣ Obtain a handle for the BLE device: Similar to the pattern we've seen in embedded Rust with peripherals, as part of the singleton design pattern, we first have to take ownership of the device peripherals. In this context, its the BLEDevice that we need to take ownership of. This is done using the take() associated method. Here I create a BLE device handler named ble_device as follows:

let ble_device = BLEDevice::take();

2️⃣ Configure Device Security: In this step we need to configure the device I/O capabilities for pairing and set the authorization mode. The authorization mode would determine the pairing method and whether bonding is required or not. The authorization mode is captured through several flags mentioned earlier configurable through the esp32_nimble::enums::AuthReq enum. From what it seems, the NimBLE crate supports at most the passkey entry method.

To configure security parameters, we first need to call the security method on the BLEDevice instance. This would return a BLESecurity type that renders access to the security configuration methods. The authorization mode is configured through the set_auth method where we pass a the AuthReq enum choice. AuthReq::all means setting all the flags and implies the passkey entry method and and bonding. We also need to set the IO capabilities through the set_io_cap method. For that, we need to pass a SecurityIOCap enum option which we pass KeyboardOnly. Now although we do not have a keyboard, there exists a method we'll see later where we can pass a passkey that we will hardcode. Here's the code:

// Configure Device Security
ble_device
    .security()
    .set_auth(AuthReq::all())
    .set_io_cap(SecurityIOCap::KeyboardOnly);

3️⃣ Create a Scan Instance: After initializing the NimBLE stack we create a scan instance by calling get_scan, this will create a BLEScan instance. This instance would allow us to start looking for advertising servers. Heres the code:

let ble_scan = ble_device.get_scan();

4️⃣ Configure Scan Parameters and Callback: Now that we have a scan instance we can configure the scan parameters as done previously in the past BLE scanner post. One difference here is that the on_result method has been replaced by a find_device async method. In this case, to make things easier, rather than printing all advertising devices, we're going to look for and connect one particular peripheral device. find_device has two parameters; a ms duration defining how long to look for a particular device, and a closure passing a BLEAdvertisedDevice as a token. In this closure, we are extracting the advertising device names to see if they match the name we're looking for. DEVICE_NAME is a const defined earlier in the code reflecting the &str name.

Upon completion of the scan process, note that the device would be a handle for a BLEAdvertisedDevice type wrapped in an Option. Note also how the scan interval chosen is 100ms and the scan window is 99ms.

let device = ble_scan
    .active_scan(true)
    .interval(100)
    .window(99)
    .find_device(10000, |device| device.name() == DEVICE_NAME)
    .await
    .unwrap();

5️⃣ Instantiate Client and Define Behaviour On Connection to a Peripheral: Upon identifying a device to connect to the Option should return a Some wrapping a BLEAdvertisedDevice . For the obtained device, we need to instantiate the Client and define connection behavior. We instantiate a client using the BLEClientnew method.

Using the client instance there exists a on_connect method for BLEClient. on_connect has one argument which is a closure that passes a handle for a BLEClient that contains the connected client information. In the closure body, upon connect, we'll print that we are connected and update the connection parameters. To update connection parameters, the BLEClient update_conn_params method is used. Here's the code:

if let Some(device) = device {
    // Create Client Handle
    let mut client = BLEClient::new();

    // Define Connect Behaviour
    client.on_connect(|client| {    
    // Update Connect Parameters on Connect
        client.update_conn_params(120, 250, 0, 60).unwrap();
        println!("Connected to {}", DEVICE_NAME);
    });

   // Remainder of code
}

6️⃣ Establish a Connection: Now that we've identified the device we want to connect to and the connection behavior, we can establish the connection. This is done by calling the connect method for the identified device. All we need to do is pass the device address as an argument which can be accessed using the BLEAdvertisedDeviceaddr method.

if let Some(device) = device {
    // Prior code from step 4

   // Connect to advertising device using its address
   client.connect(device.addr()).await.unwrap();

   // Remainder of code
}

7️⃣ Secure the Connection: After connection establishment, we need to secure the connection. To secure the connection we need to provide the passkey that will be entered in the process. This is done through the on_passkey_request method where a 6-digit passkey needs to be provided. This passkey should match the key entered at the other peer. Afterward, secure_connection an async method is called to establish a secure connection:

// Enter 123456 passkey on request
client.on_passkey_request(|| 123456);

// Secure Connection
client.secure_connection().await.unwrap();

That's it for configuration!

📱 Application Code

The code in this section is identical to what has been developed in the BLE Client example. However, note what differs is that the remote characteristic security level can be different depending on its properties. To be able to access the characteristic, our client would need to have a matching security level.

Identify Services and Characteristics available: Since we are operating as a Client, we need to get the "remote" services and characteristics that are available at the server. The UUIDs for these services should be known beforehand. Meaning, the client should be familiar with the services the server offers and their UUIDs to identify them.

In the first step, we need to obtain a service and then follow it by obtaining the characteristic(s) corresponding to that service. For the connected client of BLEClient type, there exists a get_service method that takes a UUID as a parameter. get_service is an async method returning a Result wrapping a BLERemoteService. In turn, BLERemoteService has a get_characteristic method with a similar signature that returns a BLERemoteCharacteristic. Heres the corresponding code:

// Seek and Create Handle for the BLE Remote Server Service corresponding to the UUID
let service = client
        .get_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"))
        .await
        .unwrap();

// Seek and Create Handle for the BLE Remote Server Characteristic corresponding to the UUID
let uuid = uuid128!("681285a6-247f-48c6-80ad-68c3dce18585");
let characteristic = service.get_characteristic(uuid).await.unwrap();

Read From Characteristic(s): Now that we have access to the remote characteristic through the characteristic handle, we can perform any supported GATT operations. For this case, for a server we create we know that the characteristic would at least support a read operation. Using the BLERemoteCharacteristicread_value method we receive a Result wrapping a Vec<u8>. As indicated earlier we mentioned that we want to update the read value every 1 sec as follows:

loop {
    // Read & Print Characteristic Value
    let value = characteristic.read_value().await.unwrap();
    println!("Read Value: {:?}", value);

    // Wait 1 second before reading again
    FreeRtos::delay_ms(1000);
}

📝 Note: While not incorporated in this code, it would be beneficial to identify the supported GATT operations for a characteristic beforehand. For that, there exists BLERemoteCharacteristic methods like can_read, can_notify, can_write, and so on that return a bool indicating if the operation is supported.

🧪 Testing

In order to test this code, you can use nRF connect mobile app or the bluefruit connect mobile app. In either app, you will be able to create an advertising peripheral as a server and define services and characteristics. Be mindful that the services you create need to have the same UUID defined in our code.

📝 Note: When testing, make sure to change DEVICE_NAME accordingly.

📱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.

use esp32_nimble::{enums::*, uuid128, BLEClient, BLEDevice};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_hal::task::block_on;
use esp_idf_sys as _;

const DEVICE_NAME: &str = "iPhone";

fn main() {
    esp_idf_sys::link_patches();

    block_on(async {
        // Acquire BLE Device Handle
        let ble_device = BLEDevice::take();

        // Configure Device Security
        ble_device
            .security()
            .set_auth(AuthReq::all())
            .set_io_cap(SecurityIOCap::KeyboardOnly);

        // Acquire Scan Handle
        let ble_scan = ble_device.get_scan();

        // Scan and Find Device/Server
        let device = ble_scan
            .active_scan(true)
            .interval(100)
            .window(99)
            .find_device(10000, |device| device.name() == DEVICE_NAME)
            .await
            .unwrap();

        if let Some(device) = device {
            // Create Client Handle
            let mut client = BLEClient::new();

            // Define Connect Behaviour
            client.on_connect(|client| {
                // Update Connect Parameters on Connect
                client.update_conn_params(120, 250, 0, 60).unwrap();
                println!("Connected to {}", DEVICE_NAME);
            });

            // Connect to advertising device using its address
            client.connect(device.addr()).await.unwrap();

            // Enter 123456 passkey on request
            client.on_passkey_request(|| 123456);

            // Secure Connection
            client.secure_connection().await.unwrap();

            // Seek and Create Handle for the BLE Remote Server Service corresponding to the UUID
            let service = client
                .get_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"))
                .await
                .unwrap();

            // Seek and Create Handle for the BLE Remote Server Characteristic corresponding to the UUID
            let uuid = uuid128!("681285a6-247f-48c6-80ad-68c3dce18585");
            let characteristic = service.get_characteristic(uuid).await.unwrap();

            loop {
                // Read & Print Characteristic Value
                let value = characteristic.read_value().await.unwrap();
                println!("Read Value: {:?}", value);

                // Wait 1 second before reading again
                FreeRtos::delay_ms(1000);
            }
        }
    });
}

Conclusion

This post introduced how to create a secure BLE client on the ESP32-C3 with Rust. This was by using the esp32-nimble crate in a standard library development environment using the esp-idf-hal . In this post, the ESP32-C3 was configured as a secure central device scanning for a peripheral server device containing a service. The device also assumes a client role after a connection is established and secures the connection with a passkey. Have any questions? Share your thoughts in the comments below 👇.

This post is the fourth of a multi-part series where I'm exploring the use of Bluetooth Low Energy along embedded Rust on the ESP32. Information in this post might rely on knowledge presented in past posts.

1. Embedded Rust Bluetooth on ESP: BLE Scanner

2. Embedded Rust Bluetooth on ESP: BLE Advertiser

3. Embedded Rust Bluetooth on ESP: BLE Server

Introduction

In this post, we're going to build on the previous post to instead create a BLE client. We're going to create a central device that will assume the role of a client upon connection establishment. Similar to past posts, the code will be built using the esp32-nimble crate.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with standard library development in Rust with the ESP.

• Basic knowledge of networking layering concepts/stacks (ex. OSI model).

• Basic knowledge of Bluetooth.

💾 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.

🛠 Hardware Setup

Materials

• ESP32-C3-DevKitM

  

  🔌 Connections

  No connections are required for this example.

👨‍🎨 Software Design

In our example, we'll be creating a central client with one characteristic that can be read from. In that context, after configuring our device, the code will take the following steps:

1. Scan and find a particular advertiser

2. Establish a connection

3. Read the characteristic value every second

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import delays and blocking abstractions.

• The esp_idf_sys crate since its needed.

• The esp32_nimble crate for the BLE abstractions.

use esp32_nimble::{uuid128, BLEClient, BLEDevice};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_hal::task::block_on;
use esp_idf_sys as _;

🎛 Initialization/Configuration Code

1️⃣ Obtain a handle for the BLE device: Similar to the pattern we've seen in embedded Rust with peripherals, as part of the singleton design pattern, we first have to take ownership of the device peripherals. In this context, its the BLEDevice that we need to take ownership of. This is done using the take() associated method. Here I create a BLE device handler named ble_device as follows:

let ble_device = BLEDevice::take();

2️⃣ Create a Scan Instance: After initializing the NimBLE stack we create a scan instance by calling get_scan, this will create a BLEScan instance. This instance would allow us to start looking for advertising servers. Heres the code:

let ble_scan = ble_device.get_scan();

3️⃣ Configure Scan Parameters and Callback: Now that we have a scan instance we can configure the scan parameters as done previously in the past BLE scanner post. One difference here is that the on_result method has been replaced by a find_device async method. In this case, to make things easier, rather than printing all advertising devices, we're going to look for and connect one particular peripheral device. find_device has two parameters; a ms duration defining how long to look for a particular device, and a closure passing a BLEAdvertisedDevice as a token. In this closure, we are extracting the advertising device names to see if they match the name we're looking for. DEVICE_NAME is a const defined earlier in the code reflecting the &str name.

Upon completion of the scan process, note that the device would be a handle for a BLEAdvertisedDevice type wrapped in an Option. Note also how the scan interval chosen is 100ms and the scan window is 99ms.

let device = ble_scan
    .active_scan(true)
    .interval(100)
    .window(99)
    .find_device(10000, |device| device.name() == DEVICE_NAME)
    .await
    .unwrap();

4️⃣ Instantiate Client and Define Behaviour On Connection to a Peripheral: Upon identifying a device to connect to the Option should return a Some wrapping a BLEAdvertisedDevice . For the obtained device, we need to instantiate the Client and define connection behavior. We instantiate a client using the BLEClient new method.

Using the client instance there exists a on_connect method for BLEClient. on_connect has one argument which is a closure that passes a handle for a BLEClient that contains the connected client information. In the closure body, upon connect, we'll print that we are connected and update the connection parameters. To update connection parameters, the BLEClient update_conn_params method is used and has the following signature:

pub fn update_conn_params(
    &mut self,
    min_interval: u16,
    max_interval: u16,
    latency: u16,
    timeout: u16
) -> Result<(), BLEError>

min_interval is a value for the minimum connection interval in ms, max_interval is a value for the maximum connection interval in ms, latency is expressed as the number of intervals to skip if theres no data to transmit, and timeout is the supervision timeout time in 10ms units. Here's the code:

if let Some(device) = device {
    // Create Client Handle
    let mut client = BLEClient::new();

    // Define Connect Behaviour
    client.on_connect(|client| {    
    // Update Connect Parameters on Connect
        client.update_conn_params(120, 250, 0, 60).unwrap();
        println!("Connected to {}", DEVICE_NAME);
    });

   // Remainder of code
}

5️⃣ Establish a Connection: Now that we've identified the device we want to connect to and the connection behavior, we can establish the connection. This is done by calling the connect method for the identified device. All we need to do is pass the device address as an argument which can be accessed using the BLEAdvertisedDevice addr method.

if let Some(device) = device {
    // Prior code from step 4

   // Connect to advertising device using its address
   client.connect(device.addr()).await.unwrap();

   // Remainder of code
}

That's it for configuration!

📱 Application Code

Identify Services and Characteristics available: Since we are operating as a Client, we need to get the "remote" services and characteristics that are available at the server. The UUIDs for these services should be known beforehand. Meaning, the client should be familiar with the services the server offers and their UUIDs to identify them.

In the first step, we need to obtain a service and then follow it by obtaining the characteristic(s) corresponding to that service. For the connected client of BLEClient type, there exists a get_service method that takes a UUID as a parameter. get_service is an async method returning a Result wrapping a BLERemoteService. In turn, BLERemoteService has a get_characteristic method with a similar signature that returns a BLERemoteCharacteristic. Heres the corresponding code:

// Seek and Create Handle for the BLE Remote Server Service corresponding to the UUID
let service = client
        .get_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"))
        .await
        .unwrap();

// Seek and Create Handle for the BLE Remote Server Characteristic corresponding to the UUID
let uuid = uuid128!("681285a6-247f-48c6-80ad-68c3dce18585");
let characteristic = service.get_characteristic(uuid).await.unwrap();

Read From Characteristic(s): Now that we have access to the remote characteristic through the characteristic handle, we can perform any supported GATT operations. For this case, for a server we create we know that the characteristic would at least support a read operation. Using the BLERemoteCharacteristic read_value method we receive a Result wrapping a Vec<u8>. As indicated earlier we mentioned that we want to update the read value every 1 sec as follows:

loop {
    // Read & Print Characteristic Value
    let value = characteristic.read_value().await.unwrap();
    println!("Read Value: {:?}", value);

    // Wait 1 second before reading again
    FreeRtos::delay_ms(1000);
}

📝 Note: While not incorporated in this code, it would be beneficial to identify the supported GATT operations for a characteristic beforehand. For that, there exists BLERemoteCharacteristic methods like can_read, can_notify, can_write, and so on that return a bool indicating if the operation is supported.

🧪 Testing

In order to test this code, you can use nRF connect mobile app or the bluefruit connect mobile app. In either app, you will be able to create an advertising peripheral as a server and define services and characteristics. Be mindful that the services you create need to have the same UUID defined in our code.

📝 Note: When testing, make sure to change DEVICE_NAME accordingly.

📱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.

use esp32_nimble::{uuid128, BLEClient, BLEDevice};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_hal::task::block_on;
use esp_idf_sys as _;

const DEVICE_NAME: &str = "Device Name";

fn main() {
    esp_idf_sys::link_patches();

    block_on(async {
        // Acquire BLE Device Handle
        let ble_device = BLEDevice::take();
        // Acquire Scan Handle
        let ble_scan = ble_device.get_scan();
        // Scan and Find Device/Server
        let device = ble_scan
            .active_scan(true)
            .interval(100)
            .window(99)
            .find_device(10000, |device| device.name() == DEVICE_NAME)
            .await
            .unwrap();

        if let Some(device) = device {
            // Create Client Handle
            let mut client = BLEClient::new();

            // Define Connect Behaviour
            client.on_connect(|client| {
                // Update Connect Parameters on Connect
                client.update_conn_params(120, 250, 0, 60).unwrap();
                println!("Connected to {}", DEVICE_NAME);
            });

            // Connect to advertising device using its address
            client.connect(device.addr()).await.unwrap();

            // Seek and Create Handle for the BLE Remote Server Service corresponding to the UUID
            let service = client
                .get_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"))
                .await
                .unwrap();

            // Seek and Create Handle for the BLE Remote Server Characteristic corresponding to the UUID
            let uuid = uuid128!("681285a6-247f-48c6-80ad-68c3dce18585");
            let characteristic = service.get_characteristic(uuid).await.unwrap();

            loop {
                // Read & Print Characteristic Value
                let value = characteristic.read_value().await.unwrap();
                println!("Read Value: {:?}", value);

                // Wait 1 second before reading again
                FreeRtos::delay_ms(1000);
            }
        }
    });
}

Conclusion

This post introduced how to create a BLE client on the ESP32-C3 with Rust. This was by using the esp32-nimble crate in a standard library development environment using the esp-idf-hal . In this post, the ESP32-C3 was configured as a central device scanning for a peripheral server device containing a service. The device also assumes a client role after a connection is established. Have any questions? Share your thoughts in the comments below 👇.

This post is the third of a multi-part series where I'm exploring the use of Bluetooth Low Energy along embedded Rust on the ESP32. Information in this post might rely on knowledge presented in past posts.

1. Embedded Rust Bluetooth on ESP: BLE Scanner

2. Embedded Rust Bluetooth on ESP: BLE Advertiser

Introduction

In the first two posts of this series, we've dealt with activities conducted pre-connection establishment. This included a central device scanning for advertising peripheral devices (BLE Scanner) and a peripheral device advertising its presence to central devices (BLE Advertiser). In this post, we want to transition to the post-connection phase. This means that a connection needs to be established first, and then the connected devices assume the roles of server and client when exchanging data. In this case the devices can start exchanging data in the form of what is known as attributes.

In this post, we're going to create a peripheral device that will assume the role of a server upon connection establishment. Similar to past posts, the code will be built using the esp32-nimble crate.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with standard library development in Rust with the ESP.

• Basic knowledge of networking layering concepts/stacks (ex. OSI model).

• Basic knowledge of Bluetooth.

💾 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.

🛠 Hardware Setup

Materials

• ESP32-C3-DevKitM

  

  🔌 Connections

  No connections are required for this example.

👨‍🎨 Software Design

🔗 Connection Establishment & Management

Once a central decides to connect to a peripheral, it would send a connection request to the peripheral. The peripheral would in turn accept the connection and establish a bi-directional communication channel between the two devices. Once a new connection is established, new connection settings/parameters are involved to manage the connection. Notice how in terms of connection management, we are still using the peripheral and central roles. Some important settings include the following:

1. Connection Interval: Recall scan intervals in the pre-connection phase. This is a similar concept, albeit post-connection. The connection interval defines how often the central device communicates with the peripheral device. A shorter connection interval allows for more frequent communication, resulting in lower latency but higher power consumption. Conversely, a longer connection interval reduces the frequency of communication, resulting in higher latency but lower power consumption. The lower power consumption is a result of the devices going to sleep after all needed packets are exchanged.

   The connection interval is typically negotiated during the establishment of a connection, but can also be updated during a connection. It is specified in units of 1.25 milliseconds, with allowable values ranging from 7.5 ms to 4,000 ms (or 7.5 ms to 4 seconds).

   Within a connection interval, there also exists connection events. A connection event, triggered by a central sending a packet, marks the exchange of data between devices to either synchronize their clocks and/or communicate data.

2. Peripheral Latency: This allows the peripheral device to skip a certain number of connection events (intervals) if it has no data to transmit. This also allows the peripheral to conserve power by entering a low-power mode between connection events. One way of viewing this is extending the connection interval when theres no data to share.

3. Supervision Timeout: This limits the duration of inactivity before the connection is considered lost. If the peripheral has no data to transmit for a prolonged period exceeding the supervision timeout, the connection may be terminated by either the peripheral or the central device.

🔃 Data Exchange

This is the phase where the devices assume client and server roles. The meaning of these roles is similar to the context of regular networking. A server is a data provider and a client is a data requestor. While a central role often aligns with a client role and a peripheral roles often aligns with a server role, thats not always the case. Pre-connection roles are not tied to post-connection data exchange roles. Meaning that a peripheral or central device can dynamically switch between data exchange roles, allowing a device to act either as a client or a server as needed.

In a BLE connection, all data is exchanged through attributes. An attribute itself is a data structure and is the basic building block forming larger data structures defined by the GATT layer like services and characteristics (more next). An attribute can simply be viewed as a shared variable between two devices that both can modify. Why is this necessary? one might wonder. Meaning that, we could have exchanged data purely through attributes. Interoperability is one of the main reasons. By defining standardized services and characteristics, BLE devices from different manufacturers can communicate and interoperate seamlessly. This promotes compatibility and allows for the creation of diverse ecosystems of BLE devices and applications.

There are several GATT layer operations that can modify attributes. These operations are split into client-initiated and server-initiated, depending on the source triggering a data exchange operation. Here are the main GATT operations:

1. Read: This is a client-initiated operation. This operation allows a client device to retrieve the value of a characteristic from a server device. The client sends a read request to the server, and the server responds with the current value of the characteristic.

2. Write: This is a client-initiated operation. This operation allows a client device to set the value of a characteristic on a server device. The client sends a write request containing the new value, and the server updates the characteristic value accordingly.

3. Write Without Response: This is a client-initiated operation. Similar to the write operation, this operation allows a client device to set the value of a characteristic on a server device. However, unlike the write operation, the write without response operation does not require an acknowledgment from the server. This can be used for faster data transmission when acknowledgment is not necessary.

4. Notify: This is a server-initiated operation. This operation allows a server device to send notifications to a client device when the value of a characteristic changes. The client subscribes to notifications for a specific characteristic, and the server sends notifications whenever the characteristic value is updated.

5. Indicate: This is a server-initiated operation. Similar to notifications, this operation allows a server device to send indications to a client device when the value of a characteristic changes. However, indications require acknowledgment from the client, ensuring reliable delivery of data.

🛎️ Services & Characteristics

As mentioned earlier, the basic building block in BLE is an attribute. As such, both services and characteristics are special types of attributes reserved to provide some structure in the data exchange process.

Services are a type of attribute that represent a collection of related data or functionalities offered by a BLE device. Each service is identified by a unique 16-bit or 128-bit Universally Unique Identifier (UUID). Services typically contain one or more characteristics and define the capabilities of the device. Services act as containers for characteristics and provide a logical grouping for related functionality.

Characteristics are another type of attribute that represent individual data elements within a service. Each characteristic has its own unique 16-bit or 128-bit UUID as well within the context of its parent service. Characteristics define specific pieces of data or operations that can be performed, such as reading a sensor value or writing a configuration parameter. Characteristics have properties that define how they can be accessed and manipulated, such as read, write, notify, and indicate (GATT Operations).

There also exists descriptors which are additional attributes that provide metadata or additional information about a characteristic. Descriptors are optional and can be used to specify characteristics' properties, permissions, and user-friendly descriptions. Descriptors like all other attributes also have their own unique 16-bit or 128-bit UUID. Descriptors provide context and additional details about characteristics, enhancing their usability and interoperability.

Lets take an example. Say we want to create a BLE-enabled fitness tracker which part of it tracks the heart rate. One service could be a heart rate service that would encompass heart rate-related functionalities. This type of service could have several characteristics, one could be a heart rate measurement characteristic and another would be a body sensor location characteristic.

The BLE standard provides a lot of standard services for common applications to leverage in designs. However, we are not mandated to use any of them. We can actually create our own services and characteristics to exchange data which is what we'll be doing in our example. To exchange data though, a device should have at least one service that encompasses at least one characteristic.

In our example we'll be creating a peripheral server with one characteristic that can be read from or written to.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import delays.

• The esp_idf_sys crate since its needed.

• The esp32_nimble crate for the BLE abstractions.

use esp32_nimble::{uuid128, BLEAdvertisementData, BLEDevice, NimbleProperties};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_sys as _;

🎛 Initialization/Configuration Code

1️⃣ Obtain a handle for the BLE device: Similar to the pattern we've seen in embedded Rust with peripherals, as part of the singleton design pattern, we first have to take ownership of the device peripherals. In this context, its the BLEDevice that we need to take ownership of. This is done using the take() associated method. Here I create a BLE device handler named ble_device as follows:

let ble_device = BLEDevice::take();

2️⃣ Create an Advertiser Instance: After initializing the NimBLE stack we create an advertiser instance by calling get_advertising, this will create a &Mutex<BLEAdvertising> instance. Heres the code:

let ble_advertiser = ble_device.get_advertising();

3️⃣ Obtain Handle for Server: We create a server instance by calling get_server, this will create a BLEServer instance. Heres the code:

let server = ble_device.get_server();

4️⃣ Define Server Connect & Disconnect Behaviour: using the server instance there exists a on_connect method for BLEServer. on_connect has one argument which is a closure that passes a handle for a BLEServer and a BLEConnDesc that contains connection information. In the closure body, upon connect, we'll print the connection data to the console then update the connection parameters. To update connection parameters, the BLEServerupdate_conn_params method is used and has the following signature:

pub fn update_conn_params(
    &mut self,
    conn_handle: u16,
    min_interval: u16,
    max_interval: u16,
    latency: u16,
    timeout: u16
) -> Result<(), BLEError>

conn_handle is the connection handle of the client, min_interval is a value for the minimum connection interval in ms, max_interval is a value for the maximum connection interval in ms, latency is expressed as the number of intervals to skip if theres no data to transmit, and timeout is the supervisiontimeout time in 10ms units. Here's the code:

server.on_connect(|server, clntdesc| {
    // Print connected client data
    println!("{:?}", clntdesc);
    // Update connection parameters
    server
        .update_conn_params(clntdesc.conn_handle(), 24, 48, 0, 60)
        .unwrap();
});

Similar to on_connect theres an on_disconnect method. on_disconnect also has one argument which is a closure that passes a handle for a BLEConnDesc and a Result that contains the reason for disconnection. All were going to do is to print a message that our device disconnected.

server.on_disconnect(|_desc, _reason| {
    println!("Disconnected, back to advertising");
});

5️⃣ Define Services & Characteristics: In this example, only one characteristic will be defined with a read and notify properties. However, every characteristic has to be associated with (listed under) a service. To create a service, within BLEServer there exists a create_service method that takes a single BleUuid argument. BleUuid is an enum representing a Bluetooth UUID. To make things easier, the nimble crate provides a uuid128 macro to parse a 128 UUID from string literals at compile time. We only need to pass a UUID string literal and the macro would take care of the rest. We create a service as follows:

// Create a service with custom UUID
let my_service = server.create_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"));

The UUID used is a custom UUID generated using an online generator tool. create_service also returns a Arc<Mutex<BLEService>>.

Next, we need to create a characteristic. This is done using the BLEServicecreate_characteristic method which has two arguments; BlueUuid and NimbleProperties. NimbleProperties is a struct containing a collection of associated constants representing the different GATT operations. These constants can be or'ed together to define the operations that can modify the characteristic. Our characteristic will support READ and NOTIFY operations. create_characteristic will return a Arc<Mutex<BLECharacteristic>>. As such, we can set a starting value for the characteristic that we created using the BLECharacteristicset_value method. set_value takes a single &[u8] parameter. Here's the code:

// Create a characteristic to associate with created service
let my_service_characteristic = my_service.lock().create_characteristic(
    uuid128!("681285a6-247f-48c6-80ad-68c3dce18585"),
    NimbleProperties::READ | NimbleProperties::NOTIFY,
);

// Set a starting value for the characteristic
my_service_characteristic.lock().set_value(b"Start Value");

6️⃣ Configure Advertiser Data: This step is similar to what was done in the BLE Advertiser post. A small difference is that here we are also attaching the service to the advertisement data. This is done using the add_service_uuid method. Note that the UUID being advertised is the same service UUID created earlier.

// Configure Advertiser Data
ble_advertiser
    .lock()
    .set_data(
        BLEAdvertisementData::new()
            .name("ESP32 Server")
            .add_service_uuid(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1")),
    )
    .unwrap();

That's it for configuration!

📱 Application Code

Start Advertising: Now we have to start the advertising process. This is done by calling the BLEAdvertisingstart method.

ble_advertiser.lock().start().unwrap();

Update Characteristic: All we have to do now is keep updating the characteristic by calling the set_value method again. Here, the my_service_characteristic value keeps getting updated every one every second by incrementing its contents.

let mut val = 0;

loop {
    FreeRtos::delay_ms(1000);
    my_service_characteristic.lock().set_value(&[val]).notify();
    val = val.wrapping_add(1);
}

🧪 Testing

In order to test this code, you can use nRF connect mobile app or the bluefruit connect mobile app. In either app you would be able to connect to the ESP and poll the server data.

📱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.

use esp32_nimble::{uuid128, BLEAdvertisementData, BLEDevice, NimbleProperties};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_sys as _;

fn main() {
    esp_idf_sys::link_patches();

    // Take ownership of device
    let ble_device = BLEDevice::take();

    // Obtain handle for peripheral advertiser
    let ble_advertiser = ble_device.get_advertising();

    // Obtain handle for server
    let server = ble_device.get_server();

    // Define server connect behaviour
    server.on_connect(|server, clntdesc| {
        // Print connected client data
        println!("{:?}", clntdesc);
        // Update connection parameters
        server
            .update_conn_params(clntdesc.conn_handle(), 24, 48, 0, 60)
            .unwrap();
    });

    // Define server disconnect behaviour
    server.on_disconnect(|_desc, _reason| {
        println!("Disconnected, back to advertising");
    });

    // Create a service with custom UUID
    let my_service = server.create_service(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1"));

    // Create a characteristic to associate with created service
    let my_service_characteristic = my_service.lock().create_characteristic(
        uuid128!("681285a6-247f-48c6-80ad-68c3dce18585"),
        NimbleProperties::READ | NimbleProperties::NOTIFY,
    );

    // Modify characteristic value
    my_service_characteristic.lock().set_value(b"Start Value");

    // Configure Advertiser Data
    ble_advertiser
        .lock()
        .set_data(
            BLEAdvertisementData::new()
                .name("ESP32 Server")
                .add_service_uuid(uuid128!("9b574847-f706-436c-bed7-fc01eb0965c1")),
        )
        .unwrap();

    // Start Advertising
    ble_advertiser.lock().start().unwrap();

    // (Optional) Print dump of local GATT table
    // server.ble_gatts_show_local();

    // Init a value to pass to characteristic
    let mut val = 0;

    loop {
        FreeRtos::delay_ms(1000);
        my_service_characteristic.lock().set_value(&[val]).notify();
        val = val.wrapping_add(1);
    }
}

Conclusion

This post introduced how to create a BLE server on the ESP32-C3 with Rust. This was by using the esp32-nimble crate in a standard library development environment using the esp-idf-hal . In this post, the ESP32-C3 was configured as a peripheral device advertising a service. The device also assumes a server role after a connection is established. Have any questions? Share your thoughts in the comments below 👇.

This post is the second of a multi-part series where I'm exploring the use of Bluetooth Low Energy along embedded Rust on the ESP32. Information in this post might rely on knowledge presented in past posts.

1. Embedded Rust Bluetooth on ESP: BLE Scanner

Introduction

In last week's post, some BLE foundations were introduced where the difference between central and peripheral devices was explained. Central devices initiate connections and request data or services from peripheral devices. Peripheral devices, on the other end, were ones that advertise their presence and provide services to central devices. Additionally, these terms were associated with devices before a connection was established. In that context, the ESP32-C3 was configured to run as a central device to perform a scan for advertising BLE peripheral devices.

In this post, we're going to remain in the pre-connection phase but do the opposite. We're going to configure the ESP32-C3 to run as an advertising peripheral device. The code will be built using the esp32-nimble crate.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with standard library development in Rust with the ESP.

• Basic knowledge of networking layering concepts/stacks (ex. OSI model).

• Basic knowledge of Bluetooth.

💾 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.

🛠 Hardware Setup

Materials

• ESP32-C3-DevKitM

  

  🔌 Connections

  No connections are required for this example.

👨‍🎨 Software Design

The idea of advertising is for a peripheral device to "advertise" its presence and services. However, a peripheral device does not necessarily have to establish a connection with a central device to provide data. An application example is beacons. Beacons are peripheral devices that broadcast data but do not establish connections with central devices. In this post, we are going to program the ESP as an advertising peripheral device. Key settings include the following:

Advertisment Type

There are several advertisement types including the following:

• Not connectable: This means that a central device cannot connect to the peripheral device.

• Directed connectable: This means that the peripheral device advertisement packets are targeted to a specific central scanner. This type is meant for cases where the peripheral already knows the central and wants to allow for a quick reconnection.

• Undirected connectable: This means that the peripheral device advertisement packets are not targeted to a specific scanner.

Scan Response

Advertising peripherals can choose to accept what is referred to as scan requests. Central devices can choose to send scan requests to advertisers. If a scan request is accepted, the peripheral device would respond with additional information in a scan response. In that context, a peripheral can be either scannable or non-scannable. A scannable peripheral is one that accepts scan requests from a central scanner.

Recall from last week's post, in the central device, scan requests were defined through the scan type. The scan type could be configured as active or passive. Active scanning meant that the central would send scan requests. Additionally, the scan type was configured using the active_scan method.

Discoverable Mode

The discoverable mode refers to the state in which a BLE device actively broadcasts its presence to nearby devices. There are two main discoverable modes:

1. General Discoverable Mode: In this mode, the BLE device continuously broadcasts advertising packets to advertise its presence to nearby devices.

2. Limited Discoverable Mode: Limited discoverable mode is similar to general discoverable mode but with a limited duration. This mode is typically used when the device only needs to be discoverable for a short time to establish connections with nearby devices. This mode is useful in cases relative to conserving power.

The peripheral that will be configured in this post, will only advertise its presence. As such, it will not advertise any services, will be non-connectable and non-scannable (doesn't support scan requests).

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import delay abstractions.

• The esp32_nimble crate for the necessary BLE abstractions.

• The esp_idf_sys crate since its needed by the esp32_nimble crate.

use esp32_nimble::{
    enums::{ConnMode, DiscMode},
    BLEAdvertisementData, BLEDevice,
};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_sys as _;

🎛 Initialization/Configuration Code

1️⃣ Obtain a handle for the BLE device: Similar to the pattern we've seen in embedded Rust with peripherals, as part of the singleton design pattern, we first have to take ownership of the device peripherals. In this context, its the BLEDevice that we need to take ownership of. This is done using the take() associated method. Here I create a BLE device handler named ble_device as follows:

let ble_device = BLEDevice::take();

Although not obvious, note that take not only provides ownership, but behind the scenes also initializes the NimBLE stack.

2️⃣ Create an Advertiser Instance: After initializing the NimBLE stack we create an advertiser instance by calling get_advertising, this will create a &Mutex<BLEAdvertising> instance. Heres the code:

let ble_advertiser = ble_device.get_advertising();

Note how BLEAdvertising is wrapped in a Mutex. This means that every time we want to access it, we need to obtain a lock.

3️⃣ Configure Device Advertising Data: In this example, we are not going to advertise any specific data. However, at minimum we need to define what our advertiser name is. To do this, there exists the set_data method for BLEAdvertising that takes a single argument of BLEAdvertisementData. For that we need to create an instance of BLEAdvertisementData using it's new method, then specify a name using the name method. The name method takes a single &str argument.

 // Specify Advertiser Name
 let mut ad_data = BLEAdvertisementData::new();
 ad_data.name("ESP32-C3 Peripheral");

 // Configure Advertiser with Specified Data
 ble_advertiser.lock().set_data(&mut ad_data).unwrap();

4️⃣ Configure Advertiser Settings: With advertiser instance we created we can now configure the advertiser parameters discussed earlier; advertisement type, discoverable mode, and scan response. These parameters can all be configured by calling BLEAdvertising methods on the ble_advertiser instance we created.

To set the advertisement type, there exists the advertisement_type method that takes a single ConnMode enum argument that specifies the connection mode. We are going to choose the Non option which means that our device is non-connectable. This is because we don't want any central devices to connect to us.

To set the discoverable mode there exists the disc_mode method that takes a single DiscMode enum argument specifying the discoverable mode. We are going to choose the Gen option which means that our device is in general discoverable mode. This means our device will continuously broadcasts advertising packets to advertise its presence to nearby devices.

Finally, we can specify if we will allow scan responses. This is done using the scan_response method which takes a single bool argument. We'll simply set this to false. Note that if we were to allow scan responses we would have needed to specify the data that would result from a scan response. For that we could have used the set_raw_scan_response_data method that is part of BLEAdvertising. Here's the code for our configuration:

ble_advertiser
    .lock()
    .advertisement_type(ConnMode::Non)
    .disc_mode(DiscMode::Gen)
    .scan_response(false);

That's it for configuration!

📱 Application Code

Start Advertising: All we have to do now is start the advertising process. This is done by calling the BLEAdvertising start method. start doesn't take any parameters. After that we enter a loop to keep the application running. A delay is included in the loop to avoid the watchdog from triggering due to lack of activity.

// Start Advertising
ble_advertiser.lock().start().unwrap();
println!("Advertisement Started");
loop {
    // Keep Advertising
    // Add delay to prevent watchdog from triggering
    FreeRtos::delay_ms(10);
}

📱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.

use esp32_nimble::{
    enums::{ConnMode, DiscMode},
    BLEAdvertisementData, BLEDevice,
};
use esp_idf_hal::delay::FreeRtos;
use esp_idf_sys as _;

fn main() {
    esp_idf_svc::sys::link_patches();

    // Take ownership of device
    let ble_device = BLEDevice::take();
    // Obtain handle for advertiser
    let ble_advertiser = ble_device.get_advertising();

    // Specify Advertiser Name
    let mut ad_data = BLEAdvertisementData::new();
    ad_data.name("ESP32-C3 Peripheral");

    // Configure Advertiser with Specified Data
    ble_advertiser.lock().set_data(&mut ad_data).unwrap();

    // Make Advertiser Non-Connectable
    // Set Discovery Mode to General
    // Deactivate Scan Responses
    ble_advertiser
        .lock()
        .advertisement_type(ConnMode::Non)
        .disc_mode(DiscMode::Gen)
        .scan_response(false);

    // Start Advertising
    ble_advertiser.lock().start().unwrap();
    println!("Advertisement Started");
    loop {
        // Keep Advertising
        // Add delay to prevent watchdog from triggering
        FreeRtos::delay_ms(10);
    }
}

Conclusion

This post introduced how to start working with BLE on the ESP32-C3 with Rust. This was by using the esp32-nimble crate in a standard library development environment using the esp-idf-hal . In this post, the ESP32-C3 was configured as a peripheral device as an advertising BLE device. Have any questions? Share your thoughts in the comments below 👇.

This post is a start of a new series where I'll be exploring the use of Bluetooth Low Energy along embedded Rust on the ESP32.

Introduction

Bluetooth is a wireless communication technology that enables data exchange over short distances between devices, allowing for convenient connectivity in various applications such as audio streaming, file transfer, and device synchronization. Bluetooth can take a while to wrap your head around. Other than understanding the protocol and its stack, there's more than one flavor. There's Bluetooth Classic and there's Bluetooth Low Energy or what is commonly known as BLE. Bluetooth Classic and BLE share some common components but are not compatible. This means that a BLE radio can't connect to a Bluetooth radio unless that Bluetooth radio supports BLE. This is referred to as dual mode. The focus of this post is BLE.

BLE, introduced as part of Bluetooth 4.0, extends the capabilities of traditional Bluetooth by providing energy-efficient communication for devices with low-power requirements, making it ideal for applications like wearable technology, IoT devices, and wireless sensors. BLE enables long battery life and reduced power consumption while maintaining compatibility with existing Bluetooth devices, opening up new possibilities for connected devices in diverse industries.

BLE incorporates several terms and quite an involved stack. However, to work with BLE one does not need to intimately dig into each layer, however, some terms are necessary to understand. In this post, I'll try to simplify some of these concepts and explain the necessary terms. In this code, I'm going to demonstrate how to perform a scan using the ESP as a central device. What these terms mean will be explained in more detail soon.

The code will be built using the esp32-nimble crate. The esp32-nimble crate is a wrapper for the ESP32 NimBLE Bluetooth stack. The crate is inspired by the NimBLE-Arduino project. NimBLE is an open source BLE stack fully compliant with the Bluetooth specification providing both host and controller functionalities. NimBLE is also part of the Apache MyNewt project. The ESP-IDF supports only a port of the NimBLE host stack and provides a different controller implementation.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with standard library development in Rust with the ESP.

• Basic knowledge of networking layering concepts/stacks (ex. OSI model).

• Basic knowledge of Bluetooth.

💾 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.

🛠 Hardware Setup

Materials

• ESP32-C3-DevKitM

  

  🔌 Connections

  No connections are required for this example.

👨‍🎨 Software Design

Its always confused me how Bluetooth seems to have two parallel stacks and several roles. Though looking at the stack and roles from device connection state would help simplify understanding. In that context, lets consider two main states; pre-connection and post-connection. Let's keep that in mind as we inspect the layers and device roles.

The figure below shows the BLE stack. Note how there is a host part and controller part. The controller layers lie in the hardware and handle the low level physical aspects of communication, such as radio frequencies, modulation, packet encoding, packet transmission, and packet reception. The host layers lie in the software and are responsible for higher-level protocol handling, including connection management, security, and data processing. The host and the controller interact with each other through an interface often referred to as the host controller interface of (HCI). This can be simply a serial interface like UART. You can potentially think of the controller and the host as two different ICs that exchange data with each other.

There are parallels to be drawn from computer network systems to help understand. You've probably seen network interface controllers (NICs), or network cards. Some NICs for example would enable connecting to an ethernet network or WiFi from one end and a computer mother board from another end. The motherboard connection could be something like a PCI interface. This is equivalent to the HCI in BLE context.

The BLE protocol stack is composed of several layers, each serving distinct functions in facilitating communication between BLE-enabled devices. These layers include:

1. Physical Layer (PHY): This layer of is responsible for converting digital data into radio waves and vice versa for transmission.

2. Link Layer (LL): This layer among several tasks, manages the connection establishment, data packet format, and error handling.

3. Host Controller Interface (HCI): The HCI layer provides an interface between the Host and the Controller. It standardizes communication between the Host (typically a microprocessor running higher-level protocols) and the Controller (responsible for low-level radio operations).

4. Logical Link Control and Adaptation Protocol (L2CAP): L2CAP is a protocol layer that provides segmentation and reassembly of data packets, multiplexing of multiple logical connections, and quality of service (QoS) negotiation.

5. Security Manager (SM): This layer is responsible for establishing and managing security features in BLE connections.

6. Attribute Profile (ATT) and Generic Attribute Profile (GATT): These layers define a hierarchical data structure used to organize data exchanged between BLE devices. They enables devices to expose services, characteristics, and descriptors, allowing for standardized communication and interoperability.

7. Generic Access Profile (GAP): This layer is responsible for managing the basic aspects of device interaction in a BLE network. Things like discovery, advertising, and connection establishment.

Note how in the figure, the layers on the left hand side are pre connection layers (SM and GAP). This is because the tasks they perform are pre connection tasks; advertising, authenticating, discovery...etc.. The right hand side, on the other hand, includes the post connection layers (ATT and GATT) performing post connection tasks mainly to do with data exchange.

🤹‍♂️ Device Roles

There are four main terms that float around with device roles in BLE; Central, Peripheral, Server, and Client. Just like the stack layers, we can look at the roles from a pre/post connection perspective.

1. Pre Connection Roles:

   • Central: The "central" is a device that typically initiates connections and requests data or services from peripheral devices. Central devices can scan for nearby peripherals, establish connections, and exchange data with them.

   • Peripheral: The "peripheral" is a device that advertises its presence and provides services to central devices.

2. Post Connection Roles :

   • Client: The "client" is a device that consumes data or services provided by a "server."

   • Server: The "server" is a device that provides data or services to clients.

In this post, we are going to program the ESP as a central device scanning for other devices. When scanning there are several scan settings available and depend on what the application desires. Factors considered include device discovery frequency, power consumption, and connection reliability. In this post we're not going to use them all, but its beneficial to know what is available. Key settings include the following:

1. Scan Interval: As shown in the figure below, the scan interval determines the time interval between successive scans performed by the BLE device. It affects how frequently the device scans for nearby devices. Shorter scan intervals result in more frequent scanning but may consume more power. A good practice is to set a relatively short scan interval, so that the scanning process is more likely to receive the advertising packets. The scanning interval can go up to seconds but is typically specified in milliseconds.

2. Scan Window: The scan window specifies the duration within each scan interval during which the device actively listens for advertising packets. It affects the duration of each scanning cycle and impacts the likelihood of discovering nearby devices. Adjusting the scan window allows balancing between power consumption and device discovery frequency.

3. Scan Duration: The scan duration determines the total duration of a single scanning cycle, including both the scanning interval and scan window. It affects how long the device spends actively scanning for nearby devices before entering an idle state. Longer scan durations increase the likelihood of discovering nearby devices but may consume more power.

4. Scan Type: The scan type specifies whether the scanning process is passive or active. In passive scanning, the device only listens for advertising packets from nearby devices. In active scanning, the device sends out scan requests to nearby devices, prompting them to respond with advertising packets.

5. Filter Policies: Filter policies define which advertising packets the device filters or ignores during the scanning process. They can filter devices based on specific criteria such as device address, advertising data, or signal strength. Filter policies help optimize the scanning process by focusing on relevant advertising packets.

Understanding the above terms would make our job quite straight forward using the esp32-nimble crate.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import the task::block_on function.

• The esp_idf_sys crate since its needed.

• The esp32_nimble crate for the BLE abstractions.

use esp32_nimble::BLEDevice;
use esp_idf_hal::task::block_on;
use esp_idf_sys as _;

🎛 Initialization/Configuration Code

1️⃣ Obtain a handle for the BLE device: Similar to the pattern we've seen in embedded Rust with peripherals, as part of the singleton design pattern, we first have to take ownership of the device peripherals. In this context, its the BLEDevice that we need to take ownership of. You might have guessed it already, this is done using the take() associated method. Here I create a BLE device handler named ble_device as follows:

let ble_device = BLEDevice::take();

Although not obvious, note that take not only provides ownership, but behind the scenes also initializes the NimBLE stack.

2️⃣ Create a Scan Instance: After initializing the NimBLE stack we create a scan instance by calling get_scan, this will create a BLEScan instance. This instance would allow us to start looking for advertising servers. Heres the code:

let ble_scan = ble_device.get_scan();

3️⃣ Configure Scan Parameters and Callback: Now that we have a scan instance we can configure the scan parameters discussed earlier; scan type, interval, and window. Additionally, we need to configure the behaviour on the return of a scan result. These parameters can all be configured by calling BLEScan methods on the ble_scan instance we created.

To set the scan type, there exists the active_scan method that takes a single bool type argument. To set the interval there exists the interval method that takes a single u32 type argument representing the interval in ms. To set the window there exists the window method that takes a single u32 type argument representing the window in ms.

Finally, whenever our central device detects an advertising device, the behaviour needs to be identified. This is done using the on_result method. The on_result parameter is a callback that is called when a new scan result is detected. The first parameter is a reference to ble_scan instance itself, and the second is a reference to a detected device of BLEAdvertisedDevice type. BLEAdvertisedDevice contains alot of data about the advertiser device obtained by various methods. At a minimum, we're going to retrieve the name, address and rssi of a advertising device. This is demonstrated in the following code:

ble_scan
    .active_scan(true)
    .interval(100)
    .window(50)
    .on_result(|_scan, param| {
        println!(
            "Advertised Device Name: {:?}, Address: {:?} dB, RSSI: {:?}",
            param.name(),
            param.addr(),
            param.rssi()
        );
    });

Note that the scan interval chosen is 100ms and the scan window is 50ms.

That's it for configuration!

📱 Application Code

Start the Scan: All we have to do now is start the scan process. This is done by calling the BLEScan start method. start takes one parameter which specifies a scan duration in milliseconds. Note though how start is an async function that returns a Future. This means that it would defer execution until the scan is completed. For that, note in the full application how the code is wrapped in a async block inside a block_on function. This serves to block execution until the scan process is completed.

ble_scan.start(5000).await.unwrap();
println!("Scan finished");

📱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.

use esp32_nimble::BLEDevice;
use esp_idf_hal::task::block_on;
use esp_idf_sys as _;

fn main() {
    esp_idf_svc::sys::link_patches();

    block_on(async {
        let ble_device = BLEDevice::take();
        let ble_scan = ble_device.get_scan();
        ble_scan
            .active_scan(true)
            .interval(100)
            .window(50)
            .on_result(|_scan, param| {
                println!(
                    "Advertised Device Name: {:?}, Address: {:?} dB, RSSI: {:?}",
                    param.name(),
                    param.addr(),
                    param.rssi()
                );
            });
        ble_scan.start(5000).await.unwrap();
        println!("Scan finished");
    });
}

Conclusion

This post introduced how to start working with BLE on the ESP32-C3 with Rust. This was by using the esp32-nimble crate in a standard library development environment using the esp-idf-hal . In this post, the ESP32-C3 was configured as a central device to perform a scan for advertising BLE devices. Have any questions? Share your thoughts in the comments below 👇.

Ever since creating the WiFi post, I received several inquiries about using a custom SSID and password. In that past post, I had hardcoded the WiFi SSID and password. I figured its a sign for updating the code to demonstrate how to enter a custom access point SSID and password.

In this post, I will be updating the past WiFi post application code to accommodate custom network SSID entry. UART will be used to acquire user entry from the terminal.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• WiFi Blog Post.

• UART Blog Post.

💾 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

• ESP32-C3-DevKitM

  

👨‍🎨 Software Design

In the past example, the ESP32 was configured in station mode in the following steps:

1. Configure WiFi

2. Start WiFi

3. Connect WiFi

4. (Optional) Confirm Connection and Check Connection Configuration

Ahead of these steps we'll need to capture the user entry and use it in the WiFi configuration. These are the additional steps that need to be taken ahead of connecting to WiFi:

1. Instantiate and Configure UART

2. Ask user for SSID

3. Read and store SSID

4. Ask user for password

5. Read and store password

After that we can proceed to configure WiFi with the stored entries.

👨‍💻 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 necessary for WiFi.

• The heapless crate for the heapless String and Vec types.

use esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::wifi::{AuthMethod, BlockingWifi, ClientConfiguration, Configuration, EspWifi};
use heapless::{String, Vec};
use std::fmt::Write;

🎛 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 & Instantiate UART: UART needs to be instantiated to use the same pins used for terminal logging. These are pins 20 and 21. This is similar to how UART was configured in the UART post:

// Configure UART
// Create handle for UART config struct
let config = config::Config::default().baudrate(Hertz(115_200));

// Instantiate UART
let mut uart = UartDriver::new(
    peripherals.uart0,
    peripherals.pins.gpio21,
    peripherals.pins.gpio20,
    Option::<gpio::Gpio0>::None,
    Option::<gpio::Gpio1>::None,
    &config,
)
.unwrap();

3️⃣ Acquire User Input: Following the UART configuration, the user is prompted to enter the SSID as shown below. Following that, the SSID is captured by entering a loop where a character is read one at a time using the UART driver read method. Note the following:

• Each character entered is echoed to the console using the write method. This is so that the user has visual confirmation that the intended character is entered. In the case of password entry, an asterisk (ascii value 42) is echoed instead of the actual entry.

• Each character that is acquired is appended/buffered in the ssid and password vectors using the extend_from_slice Vec method.

• Every time a character is read, the code checks if its a carriage return (ascii value 13). If it is then the code breaks out of the loop.

• Both ssid and password are heapless::Vec types.

uart.write_str("Enter Network SSID: ").unwrap();

// Read and Buffer SSID
let mut ssid = Vec::<u8, 32>::new();
loop {
    let mut buf = [0_u8; 1];
    uart.read(&mut buf, BLOCK).unwrap();
    uart.write(&buf).unwrap();
    if buf[0] == 13 {
        break;
    }
    ssid.extend_from_slice(&buf).unwrap();
}

uart.write_str("\nEnter Network Password: ").unwrap();

// Read and Buffer Password
let mut password = Vec::<u8, 64>::new();
loop {
    let mut buf = [0_u8; 1];
    uart.read(&mut buf, BLOCK).unwrap();
    uart.write(&[42]).unwrap();
    if buf[0] == 13 {
        break;
    }
    password.extend_from_slice(&buf).unwrap();
}

4️⃣ Adjust Buffered Types: Both ssid and password are Vec types. The WiFi configuration however accepts a heapless::String type. As such, the acquired values need to be adjusted such that the types are compatible as follows:

let ssid: String<32> = String::from_utf8(ssid).unwrap();
let password: String<64> = String::from_utf8(password).unwrap();

5️⃣ Obtain handle for WiFi: this involves the same steps that were done in the WiFi post.

let sysloop = EspSystemEventLoop::take()?;
let nvs = EspDefaultNvsPartition::take()?;
let mut wifi = EspWifi::new(peripherals.modem, sysloop, Some(nvs))?;

6️⃣ Configure the WiFi Driver: now that we have the ssid and password we can proceed to configure the wifi driver as follows:

wifi.set_configuration(&Configuration::Client(ClientConfiguration {
    ssid: ssid,
    bssid: None,
    auth_method: AuthMethod::None,
    password: password,
    channel: None,
}))?;

This is it for configuration! Let's now jump into the application code.

📱 Application Code

Start and Connect Wifi: Now that wifi is configured, all we need to do is start it and then connect to a network:

// Start Wifi
wifi.start()?;

// Connect Wifi
wifi.connect()?;

// Wait until the network interface is up
wifi.wait_netif_up()?;

println!("Wifi Connected");

loop {}

This is it!

📱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 esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::wifi::{AuthMethod, BlockingWifi, ClientConfiguration, Configuration, EspWifi};
use heapless::{String, Vec};
use std::fmt::Write;

fn main() -> anyhow::Result<()> {
    // Take Peripherals
    let peripherals = Peripherals::take().unwrap();
    let sysloop = EspSystemEventLoop::take()?;
    let nvs = EspDefaultNvsPartition::take()?;

    // Configure UART
    // Create handle for UART config struct
    let config = config::Config::default().baudrate(Hertz(115_200));

    // Instantiate UART
    let mut uart = UartDriver::new(
        peripherals.uart0,
        peripherals.pins.gpio21,
        peripherals.pins.gpio20,
        Option::<gpio::Gpio0>::None,
        Option::<gpio::Gpio1>::None,
        &config,
    )
    .unwrap();

    let mut wifi = BlockingWifi::wrap(
        EspWifi::new(peripherals.modem, sysloop.clone(), Some(nvs))?,
        sysloop,
    )?;

    // This line is for Wokwi only so that the console output is formatted correctly
    uart.write_str("\x1b[20h").unwrap();

    uart.write_str("Enter Network SSID: ").unwrap();

    // Read and Buffer SSID
    let mut ssid = Vec::<u8, 32>::new();
    loop {
        let mut buf = [0_u8; 1];
        uart.read(&mut buf, BLOCK).unwrap();
        uart.write(&buf).unwrap();
        if buf[0] == 13 {
            break;
        }
        ssid.extend_from_slice(&buf).unwrap();
    }

    uart.write_str("\nEnter Network Password: ").unwrap();

    // Read and Buffer Password
    let mut password = Vec::<u8, 64>::new();
    loop {
        let mut buf = [0_u8; 1];
        uart.read(&mut buf, BLOCK).unwrap();
        uart.write(&[42]).unwrap();
        if buf[0] == 13 {
            break;
        }
        password.extend_from_slice(&buf).unwrap();
    }

    let ssid: String<32> = String::from_utf8(ssid).unwrap();
    let password: String<64> = String::from_utf8(password).unwrap();

    wifi.set_configuration(&Configuration::Client(ClientConfiguration {
        ssid: ssid,
        bssid: None,
        auth_method: AuthMethod::None,
        password: password,
        channel: None,
    }))?;

    // Start Wifi
    wifi.start()?;

    // Connect Wifi
    wifi.connect()?;

    // Wait until the network interface is up
    wifi.wait_netif_up()?;

    println!("Wifi Connected");

    loop {}
}

Conclusion

This post introduced how to configure and connect ESP Wifi in station mode using Rust and the esp_idf_svc crate. This code is modified from a past WiFi example allowing a user to enter an SSID and password instead of hardcoding them. This avoids having to recompile the code every time the WiFi station needs to be changed. Have any questions? Share your thoughts in the comments below 👇.

In this week's post, we're going to add the remainder of the features to the CLI app last week. This includes capturing options from users, supporting host names, and printing statistics.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Knowledge in DNS is helpful.

• ESP Embedded Rust: Ping CLI Part 1

💾 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, 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

• ESP32-C3-DevKitM

  

👨‍🎨 Software Design

I'm going to make a small modification to the program options to ease the development a bit. Here's the modified version of the help:

Ping is a utility that sends ICMP Echo Request packets to a specified network host 
(either identified by its IP address or hostname) to test connectivity and measure round-trip time.

Usage: ping [options] <hostname/IP>

Options:
  --count=<number>     Number of ICMP Echo Request packets to send (default is 4).
  --interval=<seconds> Set the interval between successive ping packets in seconds.
  --timeout=<seconds>  Specify a timeout value for each ping attempt.
  --size=<bytes>       Set the size of the ICMP packets.

Examples:
  ping 192.168.1.1          # Ping the IP address 192.168.1.1
  ping example.com          # Ping the hostname 'example.com'
  ping --count=10 google.com     # Send 10 ping requests to google.com
  ping --interval=0.5 --size=100 example.com  # Ping with interval of 0.5 seconds and packet size of 100 bytes to 'example.com'

In last week's code there were three steps:

1. Setup CLI Root Menu & Callback

2. CLI Start-Up

3. Create Ping App Logic

Here are the areas that need to be updated:

• The root menu in step 1 needs to be updated with items to incorporate the command options.

• The app logic in step 3 needs to incorporate the logic to acquire the optional parameters, process the parameters, and adjust the printed output.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation the crates required are as follows:

• The esp_idf_hal crate to import the needed device hardware abstractions.

• menu to provide the menu CLI structs and abstractions.

• std::fmt to import the Write trait.

use esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use menu::*;
use std::fmt::Write;

📝 Updating the Root Menu

We need to update the ROOT_MENU ping command Item to accommodate the options shown in the help output earlier. This includes count, interval, timeout, and size. In the parameter list, these all need to be of type Parameter::NamedValue since they are all named parameters with an argument (link to menu crate documentation). Here's the updated Item :

&Item {
    item_type: ItemType::Callback {
        function: ping_app,
        parameters: &[Parameter::Mandatory {
            parameter_name: "hostname/IP",
            help: Some("IP address or hostname"),
        },
        Parameter::NamedValue {
            parameter_name: "count",
            argument_name: "cnt",
            help: Some("Packet count"),
        },
        Parameter::NamedValue {
            parameter_name: "interval",
            argument_name: "int",
            help: Some("Interval between counts"),
        },
        Parameter::NamedValue {
            parameter_name: "timeout",
            argument_name: "to",
            help: Some("timeout for each ping attempt"),
        },
        Parameter::NamedValue {
            parameter_name: "size",
            argument_name: "sz",
            help: Some("Set the size of the packet"),
        },],
    },
    command: "ping",
    help: Some("
    Ping is a utility that sends ICMP Echo Request packets to a specified network host 
    (either identified by its IP address or hostname) to test connectivity and measure round-trip time.

    Usage: ping [options] <hostname/IP>

    Options:
      --count=<number>     Number of ICMP Echo Request packets to send (default is 4).
      --interval=<seconds> Set the interval between successive ping packets in seconds.
      --timeout=<seconds>  Specify a timeout value for each ping attempt.
      --size=<bytes>       Set the size of the ICMP packets.
      --help               Display this help message and exit.

    Examples:
      ping 192.168.1.1          # Ping the IP address 192.168.1.1
      ping example.com          # Ping the hostname 'example.com'
      ping -count=10 google.com     # Send 10 ping requests to google.com
      ping -interval=0.5 -size=100 example.com  # Ping with interval of 0.5 seconds and packet size of 100 bytes to 'example.com'
    "),
},

👨‍💻 Acquire and Process Parameters

🌐 Acquiring and Processing a Hostname

In the last post, in the ping app CLI ping_app callback function, we supported pinging only raw IP addresses using the Ipv4Addrfrom_str method. Meaning if we wanted to ping a hostname like www.google.com, we wouldn't be able to. To support hostnames, we'd need an abstraction that can parse the acquired string and resolve the hostname to an IP. std::net::ToSocketAddrs provides such abstractions. Heres the updated code:

// Read terminal input
let ip_str = argument_finder(item, args, "hostname/IP").unwrap().unwrap();

// Resolve IP Address
let addresses = (ip_str, 0)
    .to_socket_addrs()
    .expect("Unable to resolve domain")
    .next()
    .unwrap();

// Convert to IP v4 type address
let addr = match addresses {
    std::net::SocketAddr::V4(a) => *a.ip(),
    std::net::SocketAddr::V6(_) => {
        writeln!(context, "Address not compatible, try again").unwrap();
        return;
    }
};

I'm going to broadly explain what is happening here and would recommend referring to the std::net::ToSocketAddrs documentation for detail. The first part of the code is similar to before where we read the terminal input. In the second part, to_socket_addrs is being used to parse and resolve an address from the user entry. to_socket_addrs returns a collection of possible addresses in which only the first one is being used.

The addresses returned by to_socket_addrs are of IpAddr type that could be either a IPv4 or IPv6 address. As such, the second part of the code makes sure that its an IPv4 address that is being used since thats what EspPing supports.

📝 Acquiring and Processing Options

We earlier added four command options the user can enter. These options would need to update the ping_configEspPing configuration struct. As such, a default instance of ping_config is created first such that if the user doesn't enter any options to update a member then we opt for a default configuration. Here's the code:

// Setup Default Ping Config
let mut ping_config = PingConfiguration::default();

// Obtain CLI Options and Modify Default Configuration Accordingly
ping_config.count = 1;
let mut ping_attempts = 4;

match argument_finder(item, args, "count") {
    Ok(arg) => match arg {
        Some(cnt) => ping_attempts = FromStr::from_str(cnt).unwrap(),
        None => (),
    },
    Err(_) => (),
}

match argument_finder(item, args, "interval") {
    Ok(arg) => match arg {
        Some(inter) => {
            ping_config.interval = Duration::from_secs(FromStr::from_str(inter).unwrap())
        }
        None => (),
    },
    Err(_) => (),
}

match argument_finder(item, args, "timeout") {
    Ok(arg) => match arg {
        Some(to) => ping_config.timeout = Duration::from_secs(FromStr::from_str(to).unwrap()),
        None => (),
    },
    Err(_) => (),
}

match argument_finder(item, args, "size") {
    Ok(arg) => match arg {
        Some(sz) => ping_config.data_size = FromStr::from_str(sz).unwrap(),
        None => (),
    },
    Err(_) => (),
}

Note how ping_config.count is set to 1. This is because if it's anything other than 1 then it would send multiple byte_size packets per attempt. Additionally, we'd want to print each ping attempt individually a number of times that the user defines. For that, the ping_attempts variable is introduced with a default of 4.

📝 Note:count is used in two different contexts. count that is provided as a user option is essentially what we are calling the number of ping attempts. On the other hand, while ping_config.count also refers to the number of attempts, it refers to attempts done in one ping operation. This means we wouldn't be able to print every attempt individually. To circumvent this, ping_config.count is always set to 1 and ping_attempts controls how many times an EspPing is performed.

👨‍💻 Adjust the Printed Output

In the first part of the printed output, we need to adjust it to reflect the input the user provided. Additionally, we need to introduce some variables to collect information for printing the statistics later. These are summary, times, and rx_count. Here is the adjusted output:

// Update CLI
// Pinging {IP} with {x} bytes of data
writeln!(
    context,
    "Pinging {} [{:?}] with {} bytes of data\n",
    ip_str, addr, ping_config.data_size
)
.unwrap();

let mut summary = Summary::default();
let mut times: Vec<u128> = Vec::new();
let mut rx_count = 0;

// Ping 4 times and print results in following format:
// Reply from {IP}: bytes={summary.recieved} time={summary.time} TTL={summary.timeout}
for _n in 1..=ping_attempts {
    summary = ping.ping(addr, &ping_config).unwrap();

    writeln!(
        context,
        "Reply from {:?}: bytes = {}, time = {:?}, TTL = {:?}",
        addr, ping_config.data_size, summary.time, ping_config.timeout
    )
    .unwrap();

    // Update values for statistics
    times.push(summary.time.as_millis());
    if summary.transmitted == summary.received {
        rx_count += 1;
    }
}

Afterward, the ping stats are appended with the following commands:

// Print ping statistics in following format:
// Ping statistics for {IP}:
//      Packets: Sent = {sent}, Received  = {rec}, Lost = {loss} <{per}% Loss>
// Approximate round trip times in milliseconds:
//      Minimum = {min}ms, Maximum = {max}ms, Average = {avg}ms
writeln!(context, "\nPing Statistics for {:?}", addr).unwrap();
writeln!(
    context,
    "     Packets: Sent = {}, Received  = {}, Lost = {} <{}% loss>",
    ping_attempts,
    rx_count,
    ping_attempts - rx_count,
    ((ping_attempts - rx_count) / ping_attempts) * 100
)
.unwrap();
writeln!(context, "Approximate round trip times in milliseconds:").unwrap();
writeln!(
    context,
    "     Minimum = {} ms, Maximum = {} ms, Average = {} ms",
    times.iter().min().unwrap(),
    times.iter().max().unwrap(),
    times.iter().sum::<u128>() / times.len() as u128,
)
.unwrap();

That's it for code!

📱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 esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::ping::{Configuration as PingConfiguration, EspPing, Summary};
use esp_idf_svc::wifi::{AuthMethod, BlockingWifi, ClientConfiguration, Configuration, EspWifi};
use menu::*;
use std::fmt::Write;
use std::net::ToSocketAddrs;
use std::str::FromStr;
use std::time::Duration;

// CLI Root Menu Struct Initialization
const ROOT_MENU: Menu<UartDriver> = Menu {
    label: "root",
    items: &[
        &Item {
            item_type: ItemType::Callback {
                function: hello_name,
                parameters: &[Parameter::Mandatory {
                    parameter_name: "name",
                    help: Some("Enter your name"),
                }],
            },
            command: "hw",
            help: Some("This is the help for the hello, name hw command!"),
        },
        &Item {
            item_type: ItemType::Callback {
                function: ping_app,
                parameters: &[Parameter::Mandatory {
                    parameter_name: "hostname/IP",
                    help: Some("IP address or hostname"),
                },
                Parameter::NamedValue {
                    parameter_name: "count",
                    argument_name: "cnt",
                    help: Some("Packet count"),
                },
                Parameter::NamedValue {
                    parameter_name: "interval",
                    argument_name: "int",
                    help: Some("Interval between counts"),
                },
                Parameter::NamedValue {
                    parameter_name: "timeout",
                    argument_name: "to",
                    help: Some("timeout for each ping attempt"),
                },
                Parameter::NamedValue {
                    parameter_name: "size",
                    argument_name: "sz",
                    help: Some("Set the size of the packet"),
                },],
            },
            command: "ping",
            help: Some("
            Ping is a utility that sends ICMP Echo Request packets to a specified network host 
            (either identified by its IP address or hostname) to test connectivity and measure round-trip time.

            Usage: ping [options] <hostname/IP>

            Options:
              --count=<number>     Number of ICMP Echo Request packets to send (default is 4).
              --interval=<seconds> Set the interval between successive ping packets in seconds.
              --timeout=<seconds>  Specify a timeout value for each ping attempt.
              --size=<bytes>       Set the size of the ICMP packets.
              --help               Display this help message and exit.

            Examples:
              ping 192.168.1.1          # Ping the IP address 192.168.1.1
              ping example.com          # Ping the hostname 'example.com'
              ping -count=10 google.com     # Send 10 ping requests to google.com
              ping -interval=0.5 -size=100 example.com  # Ping with interval of 0.5 seconds and packet size of 100 bytes to 'example.com'
            "),
        },
    ],
    entry: None,
    exit: None,
};

fn main() -> anyhow::Result<()> {
    // Take Peripherals
    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".try_into().unwrap(),
        bssid: None,
        auth_method: AuthMethod::None,
        password: "".try_into().unwrap(),
        channel: None,
    }))?;

    // Start Wifi
    wifi.start()?;

    // Connect Wifi
    wifi.connect()?;

    // Wait until the network interface is up
    wifi.wait_netif_up()?;

    println!("Wifi Connected");

    // Configure UART
    // Create handle for UART config struct
    let config = config::Config::default().baudrate(Hertz(115_200));

    // Instantiate UART
    let mut uart = UartDriver::new(
        peripherals.uart0,
        peripherals.pins.gpio21,
        peripherals.pins.gpio20,
        Option::<gpio::Gpio0>::None,
        Option::<gpio::Gpio1>::None,
        &config,
    )
    .unwrap();

    // This line is for Wokwi only so that the console output is formatted correctly
    uart.write_str("\x1b[20h").unwrap();

    // Create a buffer to store CLI input
    let mut clibuf = [0u8; 64];
    // Instantiate CLI runner with root menu, buffer, and uart
    let mut r = Runner::new(ROOT_MENU, &mut clibuf, uart);

    loop {
        // Create single element buffer for UART characters
        let mut buf = [0_u8; 1];
        // Read single byte from UART
        r.context.read(&mut buf, BLOCK).unwrap();
        // Pass read byte to CLI runner for processing
        r.input_byte(buf[0]);
    }
}

// Callback function for hw command
fn hello_name<'a>(
    _menu: &Menu<UartDriver>,
    item: &Item<UartDriver>,
    args: &[&str],
    context: &mut UartDriver,
) {
    // Print to console passed "name" argument
    writeln!(
        context,
        "Hello, {}!",
        argument_finder(item, args, "name").unwrap().unwrap()
    )
    .unwrap();
}

// Callback function for ping command
fn ping_app<'a>(
    _menu: &Menu<UartDriver>,
    item: &Item<UartDriver>,
    args: &[&str],
    context: &mut UartDriver,
) {
    // Retreieve CLI Input
    let ip_str = argument_finder(item, args, "hostname/IP").unwrap().unwrap();

    // Resolve IP Address
    let addresses = (ip_str, 0)
        .to_socket_addrs()
        .expect("Unable to resolve domain")
        .next()
        .unwrap();

    // Convert to IP v4 type address
    let addr = match addresses {
        std::net::SocketAddr::V4(a) => *a.ip(),
        std::net::SocketAddr::V6(_) => {
            writeln!(context, "Address not compatible, try again").unwrap();
            return;
        }
    };

    // Create EspPing instance
    let mut ping = EspPing::new(0_u32);

    // Setup Default Ping Config
    let mut ping_config = PingConfiguration::default();

    // Obtain CLI Options and Modify Default Configuration Accordingly
    ping_config.count = 1;
    let mut ping_attempts = 4;

    match argument_finder(item, args, "count") {
        Ok(arg) => match arg {
            Some(cnt) => ping_attempts = FromStr::from_str(cnt).unwrap(),
            None => (),
        },
        Err(_) => (),
    }

    match argument_finder(item, args, "interval") {
        Ok(arg) => match arg {
            Some(inter) => {
                ping_config.interval = Duration::from_secs(FromStr::from_str(inter).unwrap())
            }
            None => (),
        },
        Err(_) => (),
    }

    match argument_finder(item, args, "timeout") {
        Ok(arg) => match arg {
            Some(to) => ping_config.timeout = Duration::from_secs(FromStr::from_str(to).unwrap()),
            None => (),
        },
        Err(_) => (),
    }

    match argument_finder(item, args, "size") {
        Ok(arg) => match arg {
            Some(sz) => ping_config.data_size = FromStr::from_str(sz).unwrap(),
            None => (),
        },
        Err(_) => (),
    }

    println!("{:?}", ping_config);

    // Update CLI
    // Pinging {IP} with {x} bytes of data
    writeln!(
        context,
        "Pinging {} [{:?}] with {} bytes of data\n",
        ip_str, addr, ping_config.data_size
    )
    .unwrap();

    let mut summary = Summary::default();
    let mut times: Vec<u128> = Vec::new();
    let mut rx_count = 0;

    // Ping 4 times and print results in following format:
    // Reply from {IP}: bytes={summary.recieved} time={summary.time} TTL={summary.timeout}
    for _n in 1..=ping_attempts {
        summary = ping.ping(addr, &ping_config).unwrap();

        writeln!(
            context,
            "Reply from {:?}: bytes = {}, time = {:?}, TTL = {:?}",
            addr, ping_config.data_size, summary.time, ping_config.timeout
        )
        .unwrap();

        // Update values for statistics
        times.push(summary.time.as_millis());
        if summary.transmitted == summary.received {
            rx_count += 1;
        }
    }

    // Print ping statstics in following format:
    // Ping statistics for {IP}:
    //      Packets: Sent = {sent}, Recieved  = {rec}, Lost = {loss} <{per}% Loss>
    // Approximate round trip times in milliseconds:
    //      Minimum = {min}ms, Maximum = {max}ms, Average = {avg}ms
    writeln!(context, "\nPing Statistics for {:?}", addr).unwrap();
    writeln!(
        context,
        "     Packets: Sent = {}, Recieved  = {}, Lost = {} <{}% loss>",
        ping_attempts,
        rx_count,
        ping_attempts - rx_count,
        ((ping_attempts - rx_count) / ping_attempts) * 100
    )
    .unwrap();
    writeln!(context, "Approximate round trip times in milliseconds:").unwrap();
    writeln!(
        context,
        "     Minimum = {} ms, Maximum = {} ms, Average = {} ms",
        times.iter().min().unwrap(),
        times.iter().max().unwrap(),
        times.iter().sum::<u128>() / times.len() as u128,
    )
    .unwrap();
}

Conclusion

In this post, a ping CLI application replica was built on an ESP32C3 using Rust and the supporting std library crates. The current version is an updated version of a CLI presented in a previous post. In the application in this post, hostnames and options are supported. Additionally, ping statistics are reported as part of the output. Have any questions? Share your thoughts in the comments below 👇.

In the last blog post, I demonstrated the basic usage of ping::EspPing. Also in the post of the week before that, I went through the process of creating a command line interface over UART. I figured, why not combine both to create a Ping CLI app replica?! As a result, in this post, a replica of a CLI ping application will be created. So that it's not overwhelming, the process is going to be broken up into two posts. In the first post, the basic framework of the app will be created. Next week, in the second post, more features will be added.

📚 Knowledge Pre-requisites

The content of this post is heavily dependent on the following past posts:

• ESP Embedded Rust: Command Line Interface

• Edge IoT with Rust on ESP: Ping!

• Edge IoT with Rust on ESP: Connecting WiFi

💾 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

• ESP32-C3-DevKitM

  

👨‍🎨 Software Design

This is a description of the app we're going to build:

Ping is a utility that sends ICMP Echo Request packets to a specified network host 
(either identified by its IP address or hostname) to test connectivity and measure round-trip time.

Usage: ping [options] <hostname/IP>

Options:
  -c, --count <number>     Number of ICMP Echo Request packets to send (default is 4).
  -i, --interval <seconds> Set the interval between successive ping packets in seconds.
  -t, --timeout <seconds>  Specify a timeout value for each ping attempt.
  -s, --size <bytes>       Set the size of the ICMP packets.

Examples:
  ping 192.168.1.1          # Ping the IP address 192.168.1.1
  ping example.com          # Ping the hostname 'example.com'
  ping -c 10 google.com     # Send 10 ping requests to google.com
  ping -i 0.5 -s 100 example.com  # Ping with interval of 0.5 seconds and packet size of 100 bytes to 'example.com'

This description is what will appear when help ping is entered. Also, the following is the type of output we want to recreate:

To create the application, the following steps are followed:

🐾 Step 1: Setup CLI Root Menu & Callback

In this first step, the following tasks will be accomplished:

1. The ping command Item needs to be added to the root menu Menu struct.

2. The callback function for ping setup.

🐾 Step 2: CLI Start-Up

The following are the actions that the application needs to take before spawning the CLI interface and invoking any commands:

1. Configure, Instantiate, and Connect to WiFi.

2. Configure and Instantiate UART

3. Instantiate and run the CLI runner with the root menu.

🐾 Step 3: Create Ping App Logic

The app logic will be contained in the ping command callback function. This is the logic that will be executed when the ping command is invoked. The following are the app logic steps:

1. Retrieve & Process CLI input

2. Instantiate EspPing

3. Setup EspPing Configuration

4. Perform ping and update CLI

For this week's post, in step 1, the only input that will be processed is the ip address. Hostname and option processing capability will be added in the next post. Additionally, ping stats printing will be added next week.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import the peripherals needed for uart.

• The esp_idf_svc crate to import the device services needed for wifi and ping.

• The menu crate for creating the CLI.

• The std::str crate to import the FromStr abstraction.

use esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::ipv4::Ipv4Addr;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::ping::{Configuration as PingConfiguration, EspPing};
use esp_idf_svc::wifi::{AuthMethod, BlockingWifi, ClientConfiguration, Configuration, EspWifi};
use menu::*;
use std::fmt::Write;
use std::str::FromStr;

🐾 Step 1: Setup CLI Root Menu & Callback

1️⃣ Add thepingcommandItemto root menu: similar to what was done in the CLI post with the hw command for the hello app, a new &Item is added for ping in the ROOT_MENU. Note that the callback function name is ping_app also there's only one parameter_name that will be recognized which is "hostname/IP" . Also, the help message details how the command will work. Be mindful that the options are included in the description although not supported yet.

&Item {
    item_type: ItemType::Callback {
        function: ping_app,
        parameters: &[Parameter::Mandatory {
            parameter_name: "hostname/IP",
            help: Some("IP address or hostname"),
     }],
    },
    command: "ping",
    help: Some("
    Ping is a utility that sends ICMP Echo Request packets to a specified network host 
    (either identified by its IP address or hostname) to test connectivity and measure round-trip time.

    Usage: ping [options] <hostname/IP>

    Options:
      -c, --count <number>     Number of ICMP Echo Request packets to send (default is 4).
      -i, --interval <seconds> Set the interval between successive ping packets in seconds.
      -t, --timeout <seconds>  Specify a timeout value for each ping attempt.
      -s, --size <bytes>       Set the size of the ICMP packets.
      -h, --help               Display this help message and exit.

    Examples:
      ping 192.168.1.1          # Ping the IP address 192.168.1.1
      ping example.com          # Ping the hostname 'example.com'
      ping -c 10 google.com     # Send 10 ping requests to google.com
      ping -i 0.5 -s 100 example.com  # Ping with interval of 0.5 seconds and packet size of 100 bytes to 'example.com'
     "),
}

2️⃣ Create the callback function: The callback function named ping_app for the ping command specified in the ROOT_MENUItem is implemented as follows:

fn ping_app<'a>(
    _menu: &Menu<UartDriver>,
    item: &Item<UartDriver>,
    args: &[&str],
    context: &mut UartDriver,
) {
    // App code goes here
}

We're going to keep it empty for now, and fill in the logic implementation in the last step.

🐾 Step 2: CLI Start-Up

1️⃣ Configure, Instantiate, and Connect to WiFi: This involves the same steps taken in the wifi post to connect to WiFi. Inside the main function, the following code is added:

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".try_into().unwrap(),
    bssid: None,
    auth_method: AuthMethod::None,
    password: "".try_into().unwrap(),
    channel: None,
}))?;

// Start Wifi
wifi.start()?;

// Connect Wifi
wifi.connect()?;

// Wait until the network interface is up
wifi.wait_netif_up()?;

println!("Wifi Connected");

2️⃣ Configure and Instantiate UART: This and the following step are identical to what was accomplished in the CLI post. Here is the code associated with this step:

// Configure UART
// Create handle for UART config struct
let config = config::Config::default().baudrate(Hertz(115_200));

// Instantiate UART
let mut uart = UartDriver::new(
    peripherals.uart0,
    peripherals.pins.gpio21,
    peripherals.pins.gpio20,
    Option::<gpio::Gpio0>::None,
    Option::<gpio::Gpio1>::None,
    &config,
)
.unwrap();

3️⃣ Instantiate and run the CLI runner with the root menu: Again, following the the CLI post, this is the associated code:

// Create a buffer to store CLI input
let mut clibuf = [0u8; 64];
// Instantiate CLI runner with root menu, buffer, and uart
let mut r = Runner::new(ROOT_MENU, &mut clibuf, uart);

loop {
    // Create single element buffer for UART characters
    let mut buf = [0_u8; 1];
    // Read single byte from UART
    r.context.read(&mut buf, BLOCK).unwrap();
    // Pass read byte to CLI runner for processing
    r.input_byte(buf[0]);
}

🐾 Step 3: Create Ping App Logic

1️⃣ Retrieve & Process CLI input: In the ping_app callback function, the first order of action will be to recover the user input. This is done using the argument_finder function in the menu crate. For now, the only entry supported is an IP address. Given that the retrieved IP address entry is a &str type, it needs to be converted to an EspPing compatible Ipv4Addr type using the from_str associated method which returns a Result. Finally, in case the user enters incorrect input, this can be handled by doing a pattern match on the from_strResult. Here is the code:

// Retreieve CLI Input
let ip_str = argument_finder(item, args, "hostname/IP").unwrap().unwrap();

// Process Input - Convert &str type to Ipv4Addr
let ip = Ipv4Addr::from_str(ip_str);

// Process Input - Make sure address formant is correct
let addr = match ip {
    Ok(addr) => addr,
    Err(_) => {
        writeln!(context, "Address error, try again").unwrap();
        return;
    }
};

2️⃣ InstantiateEspPing: This is a single-line action same to what was done before:

let mut ping = EspPing::new(0_u32);

3️⃣ SetupEspPingConfiguration: for this post, a default configuration is going to be used. In next week's post, the configuration will be modified to accommodate any user-entered options.

let ping_config = &PingConfiguration::default();

4️⃣ Performpingand update CLI: This is the part where the output of the ping app is replicated. First, we need to print Pinging [IP address] with [bytes sent] bytes of data . The IP address is the one entered by the user and the number of bytes sent is inside the ping_config struct.

// Update CLI
// Pinging {IP} with {x} bytes of data
writeln!(
    context,
    "Pinging {} with {} bytes of data\n",
    ip_str, ping_config.data_size
)
.unwrap();

Afterward, a ping needs to be performed 4 times and the output of each ping is reported in the format Reply from [IP Address]: bytes=[bytes received] time=[response duration] TTL=[timeout duration]. Here's the associated code:

// Ping 4 times and print results
for _n in 1..=4 {
    let summary = ping.ping(addr, ping_config).unwrap();

    writeln!(
        context,
        "Reply from {}: bytes = {}, time = {:?}, TTL = {:?}",
        ip_str, summary.received, summary.time, ping_config.timeout
    )
    .unwrap();
}

Thats it!

🧪 Testing

Since the current version supports only IP addresses, for the sake of testing, local network addresses can be pinged if using physical hardware. If you desire to test with internet addresses or on Wokwi some possible addresses to ping include the following:

• OpenDNS: 208.67.222.222 and 208.67.220.220

• Cloudflare: 1.1.1.1 and 1.0.0.1

• Google DNS: 8.8.8.8 and 8.8.4.4

📱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 esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::ipv4::Ipv4Addr;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::ping::{Configuration as PingConfiguration, EspPing};
use esp_idf_svc::wifi::{AuthMethod, BlockingWifi, ClientConfiguration, Configuration, EspWifi};
use menu::*;
use std::fmt::Write;
use std::str::FromStr;

// CLI Root Menu Struct Initialization
const ROOT_MENU: Menu<UartDriver> = Menu {
    label: "root",
    items: &[
        &Item {
            item_type: ItemType::Callback {
                function: hello_name,
                parameters: &[Parameter::Mandatory {
                    parameter_name: "name",
                    help: Some("Enter your name"),
                }],
            },
            command: "hw",
            help: Some("This is the help for the hello, name hw command!"),
        },
        &Item {
            item_type: ItemType::Callback {
                function: ping_app,
                parameters: &[Parameter::Mandatory {
                    parameter_name: "hostname/IP",
                    help: Some("IP address or hostname"),
                }],
            },
            command: "ping",
            help: Some("
            Ping is a utility that sends ICMP Echo Request packets to a specified network host 
            (either identified by its IP address or hostname) to test connectivity and measure round-trip time.

            Usage: ping [options] <hostname/IP>

            Options:
              -c, --count <number>     Number of ICMP Echo Request packets to send (default is 4).
              -i, --interval <seconds> Set the interval between successive ping packets in seconds.
              -t, --timeout <seconds>  Specify a timeout value for each ping attempt.
              -s, --size <bytes>       Set the size of the ICMP packets.
              -h, --help               Display this help message and exit.

            Examples:
              ping 192.168.1.1          # Ping the IP address 192.168.1.1
              ping example.com          # Ping the hostname 'example.com'
              ping -c 10 google.com     # Send 10 ping requests to google.com
              ping -i 0.5 -s 100 example.com  # Ping with interval of 0.5 seconds and packet size of 100 bytes to 'example.com'
            "),
        },
    ],
    entry: None,
    exit: None,
};

fn main() -> anyhow::Result<()> {
    // Take Peripherals
    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".try_into().unwrap(),
        bssid: None,
        auth_method: AuthMethod::None,
        password: "".try_into().unwrap(),
        channel: None,
    }))?;

    // Start Wifi
    wifi.start()?;

    // Connect Wifi
    wifi.connect()?;

    // Wait until the network interface is up
    wifi.wait_netif_up()?;

    println!("Wifi Connected");

    // Configure UART
    // Create handle for UART config struct
    let config = config::Config::default().baudrate(Hertz(115_200));

    // Instantiate UART
    let mut uart = UartDriver::new(
        peripherals.uart0,
        peripherals.pins.gpio21,
        peripherals.pins.gpio20,
        Option::<gpio::Gpio0>::None,
        Option::<gpio::Gpio1>::None,
        &config,
    )
    .unwrap();

    // This line is for Wokwi only so that the console output is formatted correctly
    uart.write_str("\x1b[20h").unwrap();

    // Create a buffer to store CLI input
    let mut clibuf = [0u8; 64];
    // Instantiate CLI runner with root menu, buffer, and uart
    let mut r = Runner::new(ROOT_MENU, &mut clibuf, uart);

    loop {
        // Create single element buffer for UART characters
        let mut buf = [0_u8; 1];
        // Read single byte from UART
        r.context.read(&mut buf, BLOCK).unwrap();
        // Pass read byte to CLI runner for processing
        r.input_byte(buf[0]);
    }
}

// Callback function for hw command
fn hello_name<'a>(
    _menu: &Menu<UartDriver>,
    item: &Item<UartDriver>,
    args: &[&str],
    context: &mut UartDriver,
) {
    // Print to console passed "name" argument
    writeln!(
        context,
        "Hello, {}!",
        argument_finder(item, args, "name").unwrap().unwrap()
    )
    .unwrap();
}

// Callback function for ping command
fn ping_app<'a>(
    _menu: &Menu<UartDriver>,
    item: &Item<UartDriver>,
    args: &[&str],
    context: &mut UartDriver,
) {
    // Retreieve CLI Input
    let ip_str = argument_finder(item, args, "hostname/IP").unwrap().unwrap();

    // Process Input - Convert &str type to Ipv4Addr
    let ip = Ipv4Addr::from_str(ip_str);

    // Process Input - Make sure address formant is correct
    let addr = match ip {
        Ok(addr) => addr,
        Err(_) => {
            writeln!(context, "Address error, try again").unwrap();
            return;
        }
    };

    // Create EspPing instance
    let mut ping = EspPing::new(0_u32);

    // Setup Ping Config
    let ping_config = &PingConfiguration::default();

    // Update CLI
    // Pinging {IP} with {x} bytes of data
    writeln!(
        context,
        "Pinging {} with {} bytes of data\n",
        ip_str, ping_config.data_size
    )
    .unwrap();

    // Ping 4 times and print results
    // Reply from {IP}: bytes={summary.recieved} time={summary.time} TTL={summary.timeout}
    for _n in 1..=4 {
        let summary = ping.ping(addr, ping_config).unwrap();

        writeln!(
            context,
            "Reply from {}: bytes = {}, time = {:?}, TTL = {:?}",
            ip_str, summary.received, summary.time, ping_config.timeout
        )
        .unwrap();
    }
}

Conclusion

In this post, a ping CLI application replica was built on a ESP32C3 using Rust and the supporting std library crates. The current version is limited to pinging IP addresses only. In the next blog post, hostnames and options support will be added. Additionally, ping statistics will be reported as part of the output. Have any questions? Share your thoughts in the comments below 👇.

This blog post is the seventh of a multi-part series of posts where I explore various peripherals in the ESP32C3 using standard library embedded Rust and the esp-idf-svc. Please be aware that certain concepts in newer posts could depend on concepts in prior posts.

Prior posts include (in order of publishing):

1. Edge IoT with Rust on ESP: Connecting WiFi

2. Edge IoT with Rust on ESP: HTTP Client

3. Edge IoT with Rust on ESP: HTTP Server

4. Edge IoT with Rust on ESP: NTP

5. Edge IoT with Rust on ESP: MQTT Subscriber

6. Edge IoT with Rust on ESP: MQTT Publisher

Introduction

Ping is a networking utility used to test the reachability of a host on an Internet Protocol (IP) network and to measure the round-trip time for messages sent from the originating host to a destination computer and back. Essentially, it sends a small packet of data to a specified address and waits for a response. If the destination host is reachable, it sends a response back, allowing the sender to determine the status and latency of the connection. Ping is widely used for troubleshooting network connectivity issues and measuring network performance.

The esp-idf-svc provides an EspPing abstraction to perform ping operations. In this post, a simple ping application will be created using ping::EspPing. I'll be pinging the Google DNS IP.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Basic familiarity with the network stack.

💾 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

• ESP32-C3-DevKitM

  

👨‍🎨 Software Design

Ping utilizes the Internet Control Message Protocol (ICMP) in the network layer of the network stack. ICMP is a protocol used by network devices, like routers and servers, to communicate error messages and operational information back to the sender. Ping uses ICMP Echo Request and Echo Reply messages to determine the reachability and latency of a target host.

When you initiate a ping from your device, it constructs an ICMP Echo Request packet containing a small amount of data and sends it to the destination IP address. The destination device, if reachable, receives the packet and responds with an ICMP Echo Reply packet, indicating that it has received the ping request. This exchange of ICMP messages allows ping to determine if the destination host is reachable and measure the round-trip time (RTT) it takes for the packet to travel to the destination and back.

In this post, we are going to configure the ESP to ping the Google DNS IP (8.8.8.8). The steps include the following:

1. Configure and Connect to WiFi.

2. Configure and perform a Ping.

3. Print Results.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The esp_idf_hal crate to import the peripherals.

• The esp_idf_svc crate to import the device services (wifi in particular).

• The std::str crate to import the FromStr abstraction.

use std::str::FromStr;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::ipv4::Ipv4Addr;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::ping::{Configuration as PingConfiguration, EspPing};
use esp_idf_svc::wifi::{AuthMethod, BlockingWifi, ClientConfiguration, Configuration, EspWifi};

🎛 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 Handle and Configure Ping: Within esp_idf_svc::ping::EspPing there exists an new abstraction. new takes a single interface_index parameter that is a u32 type. interface_index represents the Netif index. Passing a value of 0 means that is no interface index (click here for more about ESP Netif). Following that we create an ping handle as follows:

let mut ping = EspPing::new(0_u32);

That's it for Configuration!

📱 Application Code

1️⃣ Perform a Ping: Within the EspPing abstraction, there is a ping method with the following signature:

pub fn ping(
    &mut self,
    ip: Ipv4Addr,
    conf: &Configuration
) -> Result<Summary, EspError>

There are two arguments that need to be passed, an IP address of type Ipv4Addr and and configuration. Ipv4Addr has a from_str associated method that allows the passing of a slice using the dot decimal notation. Configuration on the other hand is a struct containing the configuration parameters and is defined as follows:

pub struct Configuration {
    pub count: u32,
    pub interval: Duration,
    pub timeout: Duration,
    pub data_size: u32,
    pub tos: u8,
}

where count is the number of probes/messages to be sent, interval is the Duration between probes, timeout defines the wait Duration to wait for an echo, data_size is the size of each message, and tos defines the type of service where 0 defines normal service also referred to as best effort. In this post, the defaultConfiguration will be used. Consequently, a ping is initiated as follows:

let ping_res = ping.ping(
    Ipv4Addr::from_str("8.8.8.8").unwrap(),
    &PingConfiguration::default(),
);

2️⃣ Process the Ping Response: from the signature shown earlier, ping returns a Result wrapped in a Summary. Summary has the following members:

pub struct Summary {
    pub transmitted: u32,
    pub received: u32,
    pub time: Duration,
}

Consequently, the Result is processed as follows:

match ping_res {
    Ok(summary) => println!(
        "Transmitted: {}, Recieved: {} Time: {:?}",
        summary.transmitted, summary.received, summary.time
    ),
    Err(e) => println!("{:?}", e),
}

Thats it!

📱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 std::str::FromStr;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::ipv4::Ipv4Addr;
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::ping::{Configuration as PingConfiguration, EspPing};
use esp_idf_svc::wifi::{AuthMethod, BlockingWifi, ClientConfiguration, Configuration, EspWifi};

fn main() -> anyhow::Result<()> {
    // Take Peripherals
    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".try_into().unwrap(),
        bssid: None,
        auth_method: AuthMethod::None,
        password: "".try_into().unwrap(),
        channel: None,
    }))?;

    println!("Connecting to WiFi");

    // Start Wifi
    wifi.start()?;

    // Connect Wifi
    wifi.connect()?;

    // Wait until the network interface is up
    wifi.wait_netif_up()?;

    // This line is for Wokwi only so that the console output is formatted correctly
    println!("\x1b[20h");

    println!("Wifi Connected");

    println!("Pinging Google DNS (8.8.8.8)");

    let mut ping = EspPing::new(0_u32);

    let ping_res = ping.ping(
        Ipv4Addr::from_str("8.8.8.8").unwrap(),
        &PingConfiguration::default(),
    );

    match ping_res {
        Ok(summary) => println!(
            "Transmitted: {}, Recieved: {} Time: {:?}",
            summary.transmitted, summary.received, summary.time
        ),
        Err(e) => println!("{:?}", e),
    }

    loop {}
}

Conclusion

Ping is a popular tool used by network devices to determine device reachability and latency information. This post introduced how to set up Ping on a ESP32C3 using Rust and the esp_idf_svc. Have any questions? Share your thoughts in the comments below 👇.

Command line interfaces (CLI) in embedded applications are probably not as common as non-embedded ones. One reason is that embedded applications do not often require direct user input from a terminal, but rather through some other physical interface. As such, if a CLI is required in embedded there are different considerations.

In a typical non-embedded CLI, there is an underlying operating system (OS) with a CLI (in a shell) meant for accepting user input and passing commands to the OS itself. The OS in turn processes the input appropriately. As such, a command signifies a precompiled executable stored in some directory followed by a collection of arguments. The passed arguments are then processed by the named program when the OS executes it. The arguments are also typically allocated to dynamic memory.

In case a CLI is needed in embedded, things take a different turn. First, an underlying OS with a shell interface doesn't necessarily exist, but rather an already running application or RTOS. Second, the interface itself could be on another host device. Third, dynamic allocation is not desirable. This means that to create a CLI, logic is incorporated within an existing running application. This comes in the form of accepting commands over some logging interface like UART and processing them in the board.

In this post, I'm going to create a simple embedded CLI interface on an ESP32C3 device. However, the CLI logic not going to be created from scratch, but rather leveraging an existing crate. There are several no-std CLI crates that I encountered including; terminal-cli , embedded-cli , light-cli , and menu . Looking at each of the crates, they all had friendly abstractions and great features. I ended up going for menu based on the number of downloads since it seemed to be the most popular.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with UART and how to set it up for the ESP32C3.

💾 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, 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

• ESP32-C3-DevKitM

  

👨‍🎨 Software Design

💻 The Application

For this post, I'm going to create a simple application called hello with a command hw. hw takes one argument and its a person's name. The application would then print hello followed by the name given. Here's a sample:

> hw Omar
Hello, Omar!

Also, the application would support a help command to provide a summary of commands the terminal supports. Also there is a help option for each command providing the user with information about the command.

📦 The menu Crate

The menu crate consists of four main components:

1. The Menu struct: Each Menu has a name or label , optional functions to call on entry and exit of the Menu and, most importantly, a collection of Items.

2. The Item struct: Items can be viewed as command buckets within a Menu. Item members include an ItemType which specifies the type of the Item , a command string, and a help message associated with the command. ItemType is also a struct that specifies whether the Item opens up another sub Menu, or calls a function upon the invocation of the command.

3. The Runner struct: This is the struct that handles all incoming input. When our application is executing incoming byte characters will be passed to an instantiation of this struct for processing. Obviously, in Runner instantiation, the the Menu would be required in addition to a source for the incoming bytes (Ex. UART channel).

4. The Callback Functions: These are the functions that are called upon the invocation of a command. In these functions the logic associated with each command will be executed.

👣 Implementation Steps

Following the earlier description, these are the steps we need to take:

1. Define the Root Menu

2. Implement any Callback functions

3. Configure peripherals in main

4. Instantiate the Runner in main

5. Create the Application loop

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation the crates required are as follows:

• The esp_idf_hal crate to import the needed device hardware abstractions.

• menu to provide the menu CLI structs and abstractions.

• std::fmt to import the Write trait.

use esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use menu::*;
use std::fmt::Write;

📝 Define the Root Menu

Before implementing the logic, we need to define our root Menu. Since this this a simple application, the Menu will have one Item that contains the hw command. Menu has the following definition:

pub struct Menu<'a, T>
where
    T: 'a,
{
    pub label: &'a str,
    pub items: &'a [&'a Item<'a, T>],
    pub entry: Option<MenuCallbackFn<T>>,
    pub exit: Option<MenuCallbackFn<T>>,
}

label is the label of the menu, entry and exit specify functions to call on entry and exit of the Menu , and items is an array of Item s. Also each Item has the following definition:

pub struct Item<'a, T>
where
    T: 'a,
{
    pub command: &'a str,
    pub help: Option<&'a str>,
    pub item_type: ItemType<'a, T>,
}

where command is the command text for a particular Item , help is the help message associated with command, and item_type is an enum that specifies what the type of the item is. ItemType is defined as follows:

pub enum ItemType<'a, T>
where
    T: 'a,
{
    Callback {
        function: ItemCallbackFn<T>,
        parameters: &'a [Parameter<'a>],
    },
    Menu(&'a Menu<'a, T>),
    _Dummy,
}

One can see that Item can be either a Callback that would call a function on the invocation of an Item command, and parameters that are passed to that command. Alternatively, an Item could be another Menu which specifies a sub-menu.

Given the above, for our application, we define a const Menu called ROOT_MENU as follows:

// CLI Root Menu Struct Initialization
const ROOT_MENU: Menu<UartDriver> = Menu {
    label: "root",
    items: &[&Item {
        item_type: ItemType::Callback {
            function: hello_name,
            parameters: &[Parameter::Mandatory {
                parameter_name: "name",
                help: Some("Enter your name"),
            }],
        },
        command: "hw",
        help: Some("This is an embedded CLI terminal. Check the summary for the list of supported commands"),
    }],
    entry: None,
    exit: None,
};

Note here that ROOT_MENU is given a label "root". Additionally, our application would have only one Item with command text "hw" that, when entered by the user, would invoke a function called hello_name .The application Item also takes only one parameter defined as name . Also I've decided to not call any functions on entry and exit of the root Menu. The associated help messages are also defined at the Menu and Item level.

👨‍💻 Implement the Callback Function

Given the earlier step, we now need to define the behaviour when the callback function hello_name associated with hw is called. However, we still need to know what are the arguments that will be passed to this function. As such, the menu crate defines the signature of the callback function ItemCallbackFn as follows:

pub type ItemCallbackFn<T> = fn(menu: &Menu<'_, T>, item: &Item<'_, T>, args: &[&str], context: &mut T);

Following this signature, we implement the function hello_name as follows:

fn hello_name<'a>(
    _menu: &Menu<UartDriver>,
    item: &Item<UartDriver>,
    args: &[&str],
    context: &mut UartDriver,
) {
    // Print to console passed "name" argument
    writeln!(
        context,
        "Hello, {}!",
        argument_finder(item, args, "name").unwrap().unwrap()
    )
    .unwrap();
}

Note that all the function is doing is using the writeln macro to print to the console. writeln accepts a ‘writer’, a format string, and a list of arguments. Arguments will be formatted according to the specified format string and the result will be passed to the writer. The writer is any type that implements the Write trait in which case its the UartDriver type for the context thats being passed to hello_name by the runner. Note how for the list of arguments and argument_finder function is being used. argument_finder is a menu crate function and it looks for the named parameter in the parameter list of the Item, then finds the correct argument. Note how argument_finder takes three arguments, the Item we want to look for an argument in, the list of arguments that have been passed to the CLI (args), and the argument we want to look for ("name").

🎛 Configure Peripherals

In the main the following code is used to instantiate and configure UART:

// Take Peripherals
let peripherals = Peripherals::take().unwrap();

// Configure UART
// Create handle for UART config struct
let config = config::Config::default().baudrate(Hertz(115_200));

// Instantiate UART
let mut uart = UartDriver::new(
    peripherals.uart0,
    peripherals.pins.gpio21,
    peripherals.pins.gpio20,
    Option::<gpio::Gpio0>::None,
    Option::<gpio::Gpio1>::None,
    &config,
)
.unwrap();

The detail behind how this code works has been covered in a prior post here. If anything seems unclear I recommend referring back to the past post. Only thing to note here is that uart0 is used with gpio21 and gpio20 for Tx and Rx pins. This is because this is the peripheral and the pins used to connect to a host on the ESP32-C3-DevKitM.

🏃‍♂️ Instantiate the Runner

In the menu crate documentation, Runner has a new method with the following signature:

pub fn new(menu: Menu<'a, T>, buffer: &'a mut [u8], context: T) -> Runner<'a, T>

The first parameter is a root Menu (defined in the first step!), the second is a buffer that the Runner can use (clibuf), finally, context could be any type that implements Write (this is our instantiated uart handle) As a result, the runner is instantiated with the following code:

// Create a buffer to store CLI input
let mut clibuf = [0u8; 64];
// Instantiate CLI runner with root menu, buffer, and uart
let mut r = Runner::new(ROOT_MENU, &mut clibuf, uart);

📝 Note: The generic type T that appears in all prior structs seen earlier is defined by the context object that the Runner carries around. In our case its the UartDriver type.

🔄 The Main Loop

In the main loop, all that needs to be done is read one byte at a time from the UART channel. Remember that the UART channel is now part of the runner context. This is done using the UART read method (again, for a refresher check out this post). Every read byte is passed to the instantiated runner using the input_byte runner method.

loop {
    // Create single element buffer for UART characters
    let mut buf = [0_u8; 1];
    // Read single byte from UART
    r.context.read(&mut buf, BLOCK).unwrap();
    // Pass read byte to CLI runner for processing
    r.input_byte(buf[0]);
}

That's it for code!

📱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 esp_idf_hal::delay::BLOCK;
use esp_idf_hal::gpio;
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_hal::prelude::*;
use esp_idf_hal::uart::*;
use menu::*;
use std::fmt::Write;

// CLI Root Menu Struct Initialization
const ROOT_MENU: Menu<UartDriver> = Menu {
    label: "root",
    items: &[&Item {
        item_type: ItemType::Callback {
            function: hello_name,
            parameters: &[Parameter::Mandatory {
                parameter_name: "name",
                help: Some("Enter your name"),
            }],
        },
        command: "hw",
        help: Some("This is an embedded CLI terminal. Check the summary for the list of supported commands"),
    }],
    entry: None,
    exit: None,
};

fn main() {
    // Take Peripherals
    let peripherals = Peripherals::take().unwrap();

    // Configure UART
    // Create handle for UART config struct
    let config = config::Config::default().baudrate(Hertz(115_200));

    // Instantiate UART
    let mut uart = UartDriver::new(
        peripherals.uart0,
        peripherals.pins.gpio21,
        peripherals.pins.gpio20,
        Option::<gpio::Gpio0>::None,
        Option::<gpio::Gpio1>::None,
        &config,
    )
    .unwrap();

    // This line is for Wokwi only so that the console output is formatted correctly
    uart.write_str("\x1b[20h").unwrap();

    // Create a buffer to store CLI input
    let mut clibuf = [0u8; 64];
    // Instantiate CLI runner with root menu, buffer, and uart
    let mut r = Runner::new(ROOT_MENU, &mut clibuf, uart);

    loop {
        // Create single element buffer for UART characters
        let mut buf = [0_u8; 1];
        // Read single byte from UART
        r.context.read(&mut buf, BLOCK).unwrap();
        // Pass read byte to CLI runner for processing
        r.input_byte(buf[0]);
    }
}

// Callback function for hw commans
fn hello_name<'a>(
    _menu: &Menu<UartDriver>,
    item: &Item<UartDriver>,
    args: &[&str],
    context: &mut UartDriver,
) {
    // Print to console passed "name" argument
    writeln!(
        context,
        "Hello, {}!",
        argument_finder(item, args, "name").unwrap().unwrap()
    )
    .unwrap();
}

Conclusion

This post showed how to create a simple embedded command line interface over a UART channel. In the post, the application was created on the ESP32C3 using the menu crate. The application also leveraged the esp-idf-hal asbtractions. Have any questions? Share your thoughts in the comments below 👇.

This blog post is the eleventh of a multi-part series of posts where I explore various peripherals in the ESP32C3 using embedded Rust at the HAL level. Please be aware that certain concepts in newer posts could depend on concepts in prior posts.

Prior posts include (in order of publishing):

1. ESP32 Embedded Rust at the HAL: GPIO Button Controlled Blinking

2. ESP32 Embedded Rust at the HAL: Button-Controlled Blinking by Timer Polling

3. ESP32 Embedded Rust at the HAL: UART Serial Communication

4. ESP32 Embedded Rust at the HAL: PWM Buzzer

5. ESP32 Embedded Rust at the HAL: Timer Ultrasonic Distance Measurement

6. ESP32 Embedded Rust at the HAL: Analog Temperature Sensing using the ADC

7. ESP32 Embedded Rust at the HAL: GPIO Interrupts

8. ESP32 Embedded Rust at the HAL: SPI Communication

9. ESP32 Embedded Rust at the HAL: Random Number Generator

10. ESP32 Embedded Rust at the HAL: Remote Control Peripheral

Introduction

I2C is a popular serial communication protocol in embedded systems. Another common name used is also Two-Wire Interface (TWI), since, well, it is. I2C is commonly found in sensors and interface boards as it offers a compact implementation with decent speeds reaching Mbps. Counter to UART, I2C allows multiple devices (up to 127) to tap into the same bus. As a result, it becomes often useful if there is a way to scan for devices that are connected.

In this post, I will be configuring and setting up I2C communication for the ESP32C3 to scan the bus for devices. The code would detect if there is a device connected to a particular address. The retrieved results will also be printed on the console.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Familiarity with the basic template for creating embedded applications in Rust.

• Familiarity with I2C communication basics.

💾 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

• ESP32-C3-DevKitM

  

• Any I2C-based device (Ex. Adafruit DS1307 Real-Time Clock).

🔌 Connections

Connections include the following:

• Gpio2 wired to the SCL pin of all I2C devices.

• Gpio3 wired to the SDA pin of all I2C devices.

• Power and Gnd wired to all I2C devices on the bus.

👨‍🎨 Software Design

I2C communication involves a master device initiating communication with a slave device through a start condition, followed by sending the slave's address and a read/write bit. The slave responds with an acknowledgment, and data transfer occurs with subsequent acknowledgment or non-acknowledgment after each byte. Finally, the communication is concluded with a stop condition. Furthermore, the address field of an I2C frame is 7-bits wide which supports up to 127 devices on a connected single bus.

Note how after a slave address is sent, a slave device has to respond with an acknowledgment. If a slave does not respond, it means that it does not exist on the bus. As such, to create an I2C scanner the following steps need to be taken:

1. Initialize address to 0.

2. Send a read frame to address

3. If ack received, record that device detected at address , otherwise, record that no device is connected.

4. Increment address .

5. If address< 127 Go back to step 2. Otherwise, terminate the application.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation the crates required are as follows:

• The esp32c3_hal crate to import the ESP32C3 device hardware abstractions.

• The esp_backtrace crate to define the panicking behavior.

• The esp_println crate to provide println! implementation.

use esp32c3_hal::{clock::ClockControl, 
    i2c::I2C, 
    peripherals::Peripherals, 
    prelude::*, 
    IO,
};
use esp_backtrace as _;
use esp_println::println;

🎛 Peripheral Configuration Code

1️⃣ Obtain a handle for the device peripherals: In embedded Rust, as part of the singleton design pattern, we first have to take the PAC-level device peripherals. This is done using the take() method. Here I create a device peripheral handler named dp as follows:

let peripherals = Peripherals::take();

2️⃣ Instantiate and obtain handle to system clocks: The system clocks need to be configured as they are needed in setting up the I2C peripheral. To set up the system clocks we need to first make the SYSTEM struct compatible with the HAL using the split method (more insight on this here). After that, the system clock control information is passed to boot_defaults in ClockControl. ClockControl controls the enablement of peripheral clocks providing necessary methods to enable and reset specific peripherals. Finally, the freeze() method is applied to freeze the clock configuration. Note that freezing the clocks is a protection mechanism by the HAL to avoid the clock configuration changing during runtime.

    let system = peripherals.SYSTEM.split();
    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

3️⃣ Instantiate and Create Handle for IO: When creating an instance for I2C, we'll be required to pass it instances of the SDA and SCL pins. As such, we'll need to create an IO struct instance. The IO struct instance provides a HAL-designed struct that gives us access to all gpio pins thus enabling us to create handles/instances for individual pins. We do this like prior posts, by calling the new() instance method on the IO struct as follows:

let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);

Note how the new method requires passing two parameters; the GPIO and IO_MUX peripherals.

4️⃣ Configure and Obtain Handle for the I2C peripheral: To create an instance of an I2C peripheral we need to use the new instance method in i2c::I2c in the esp32c3-hal:

pub fn new<SDA, SCL>(
    i2c: impl Peripheral<P = T> + 'd,
    sda: impl Peripheral<P = SDA> + 'd,
    scl: impl Peripheral<P = SCL> + 'd,
    frequency: Rate<u32, 1, 1>,
    clocks: &Clocks<'_>
) -> I2C<'d, T>
where
    SDA: OutputPin + InputPin,
    SCL: OutputPin + InputPin,

The i2c parameter expects and instance of an i2c peripheral, the sda and scl parameters expect instances of pins configured as input/output, frequency is the desired bus frequency, and clocks is an instance of the system clocks. As such, I create an instance for the pulse handle as follows:

let mut i2c0 = I2C::new(
    peripherals.I2C0,
    io.pins.gpio3,
    io.pins.gpio2,
    100u32.kHz(),
    &clocks,
);

I've chosen I2C0 wth gpio3 for SDA, gpio2 for SCL, and 100kHz for the bus frequency.

Off to the application!

📱 Application Code

In the application, we are going to run a scan once for all possible addresses from 1 to 127. As such, a for loop can be utilized. In each iteration, we're first going to print the address being scanned followed by doing a i2c read. The I2C read method takes two parameters, a u8 address and a &[u8] buffer to store the read data. Also, in our case, we don't really care about any data received.

read returns a Result, in which case, if the Result is Ok that means that a device was found. Otherwise, if the Result is Err, it means that an ACK was not received and a device was not found. The following is the application code:

// Start Scan at Address 1 going up to 127
for addr in 1..=127 {
    println!("Scanning Address {}", addr as u8);

    // Scan Address
    let res = i2c0.read(addr as u8, &mut [0]);

    // Check and Print Result
    match res {
        Ok(_) => println!("Device Found at Address {}", addr as u8),
        Err(_) => println!("No Device Found"),
    }
}

Finally, since the main returns a !, then an empty loop is required.

loop{}

📱 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.

#![no_std]
#![no_main]
#![feature(type_alias_impl_trait)]

use esp32c3_hal::{clock::ClockControl, i2c::I2C, peripherals::Peripherals, prelude::*, IO};
use esp_backtrace as _;
use esp_println::println;

#[entry]
fn main() -> ! {
    let peripherals = Peripherals::take();
    let system = peripherals.SYSTEM.split();
    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

    // Obtain handle for GPIO
    let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);

    // Initialize and configure I2C0
    let mut i2c0 = I2C::new(
        peripherals.I2C0,
        io.pins.gpio3,
        io.pins.gpio2,
        100u32.kHz(),
        &clocks,
    );

    // This line is for Wokwi only so that the console output is formatted correctly
    esp_println::print!("\x1b[20h");

    // Start Scan at Address 1 going up to 127
    for addr in 1..=127 {
        println!("Scanning Address {}", addr as u8);

        // Scan Address
        let res = i2c0.read(addr as u8, &mut [0]);

        // Check and Print Result
        match res {
            Ok(_) => println!("Device Found at Address {}", addr as u8),
            Err(_) => println!("No Device Found"),
        }
    }

    // Loop Forever
    loop {}
}

Conclusion

In this post, a I2C scanner application was created leveraging the I2C peripheral for the ESP32C3. The I2C code was created at the HAL level using the Rust no-std esp32c3-hal. Have any questions/comments? Share your thoughts in the comments below 👇.

This blog post is the fifth of a multi-part series of posts where I will explore various peripherals of the ESP32 using the embedded Rust embassy framework.

Prior posts include (in order of publishing):

1. Embassy on ESP: Getting Started

2. Embassy on ESP: GPIO

3. Embassy on ESP: UART Transmitter

4. Embassy on ESP: UART Echo

Introduction

Hardware timers while relatively simple circuits are really effective in several applications in embedded. Timer peripherals are effective in timing both software and hardware events. Timers also have features that allow the generation of hardware waveforms (Ex. PWM). In this post, I'll use embassy to measure the width of the pulse for two different signals. The resulting pulse width value will be printed on the console.

The square waves used in this post will be generated using the Wokwi custom external block. In general, this type of measurement would be useful as it emulates the behavior of applications that include tachometers or anemometers. Tachometers and anemometers generate square wave signals that are proportional to the speed of rotation. With some calculations, and depending on the application, the provided code can be expanded to provide frequency and/or rpm values.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

💾 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

• ESP32-C3-DevKitM

  

• Square Wave Generator/Pulse Generator: This can take many forms in real hardware though since I'm using Wokwi, there is the custom chip feature that allows me to generate square waves.

  

🔌 Connections

📝 Note

All connection details are also shown in the Wokwi example.

Connections include the following:

• Gpio0 wired to the top pin of the breakout custom chip.

• Gpio1 wired to the bottom pin of the breakout custom chip.

👨‍🎨 Software Design

The square wave signal is going to be fed into the ESP32 as an input. For the purpose of this post, the code will measure the widths of the pulses in each square wave. The custom chip is designed such that one wave generates pulses that are 10ms wide and another that are 25ms wide. To measure the pulse width, the algorithm in this post needs to determine the time elapsed between every positive edge and the negative edge that follows.

Following the configuration of the pins and the device, for each pin the follow steps are taken:

1. await a positive edge transition.

2. Capture timer instant.

3. await negative edge transition.

4. Calculate then print the duration of the pulse.

5. Go back to step 1

Let's now jump into implementing this logic.

🚨 Important Note

The custom chip block in Wokwi has its own internal code that generates the square waves/pulses. There is a tab in the project where one can look at the source code. However, how to create and code a custom block is not part of this post. For the interested in creating custom chips in Wokwi I recommend checking out the chips api documentation.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation, the following crates are required:

• The embassy_executor crate to import the embassy executor.

• The esp32c3-hal crate to import the necessary ESP32C3 abstractions.

• The esp_backtrace crate needed to define panic behavior.

• The embassy_time crate to obtain timer abstractions.

• The embedded_hal_async crate to obtain digital pin Wait abstractions.

• The esp_backtrace crate needed to define panic behavior.

use embassy_executor::Spawner;
use embassy_time::Instant;
use embedded_hal_async::digital::Wait;
use esp32c3_hal::gpio::{AnyPin, Input, PullUp};
use esp32c3_hal::{clock::ClockControl, embassy, peripherals::Peripherals, prelude::*, IO};
use esp_backtrace as _;

💓 The Pulse Timer Task

There are two pulse timer tasks, one for each pin. Both will replicate the same behavior except for two different pins. The pulse timer task is expected to await for pin edges to time the pulse width. These are the required steps:

1️⃣ Create a Pulse Timer Task: Tasks are marked by the #[embassy_executor::task] macro followed by a async function implementation. The task created is referred to as pulse1_timer task defined as follows:

#[embassy_executor::task]
async fn pulse1_timer(mut pin: AnyPin<Input<PullUp>>) {

There is a similar task that will have the exact same code called pulse2_timer .

🔁 Task Loop

1️⃣ Wait for rising edge on pin: The first thing we need to do is await the incoming pulse to become high. For that, there exists a wait_for_high method implementation for the Wait trait in the embedded-hal-async. wait_for_high is an async function that resolves into a Future if its waiting on a condition. Otherwise, we get a Result . We call wait_for_high on pin as follows:

pin.wait_for_high().await.unwrap();

2️⃣ Capture the time instant: now that the signal turned high, a timer needs to be started to time the duration of the pulse. Using the new method from the Instant abstraction in the embassy-time crate allows the capture of the current time instant. We can bind the captured instant to an inst variable as follows:

let inst = Instant::now();

3️⃣ Wait for falling edge on pin: Now all we need to do is await the incoming signal to become low marking the end of the pulse. Now instead we use a wait_for_low method implementation for the Wait trait in the embedded-hal-async. We call wait_for_low on pin as follows:

pin.wait_for_low().await.unwrap();

4️⃣ Calculate and print duration: To calculate the Duration, Instant has a checked_duration_since method that takes two Instants and calculates a Duration. As such, we have to calculate the difference between the current Instant (after falling edge) and inst that was captured after a rising edge. Also using the as_millis Duration method, we can extract the time in milliseconds and print as follows:

// Calculate Duration
let pwidth = Instant::checked_duration_since(&Instant::now(), inst).unwrap();
// Print Duration
esp_println::println!("Sq Wave 1 Pulse Width is {}ms", pwidth.as_millis());

📱 The Main Task

The start of the main task is marked by the following code:

#[embassy_executor::main]
async fn main(spawner: Spawner)

The following steps will mark the tasks performed in the main task.

1️⃣ Obtain a handle for the device peripherals & system clocks: 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 , a system peripheral handler system, and a system clock handler clocks as follows:

let peripherals = Peripherals::take();
let system = peripherals.SYSTEM.split();
let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

2️⃣ Initialize Embassy Timers for the ESP32C3: In embassy, there exists an init function that takes two parameters. The first is system clocks and the second is an instance of a timer. Under the hood, what this function does is initialize the embassy timers. As such, we can initialize the embassy timers as follows:

embassy::init(
    let timer_group0 = esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks);
    embassy::init(&clocks, timer_group0.timer0);

3️⃣ Instantiate and Create Handle for IO: We need to configure the signal input pins as inputs and obtain handlers for them. Before we can obtain any handles we need to create an IO struct instance. The IO struct instance provides a HAL-designed struct that gives us access to all gpio pins thus enabling us to create handles for individual pins. This is similar to the concept of a split method used in other HALs (more detail here). We do this by calling the new() instance method on the IO struct as follows:

let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);

Note how the new method requires passing the GPIO and IO_MUX peripherals.

4️⃣ Obtain a handle and configure the signal input pins: The signal inputs are connected to pins 0 and 1 (gpio0 and gpio1) as stated earlier. Additionally, since the pin is driven by an external signal that has known states it can be configured as floating. A floating input can be configured for the pin using the into_floating_input() method as follows:

let del_but = io.pins.gpio2.into_floating_input().degrade();

Note that we are using the degrade method which "degrades" the pin type into a generic AnyPin type that is required to pass to the button_press task.

5️⃣ Spawn Pulse Timer Tasks: now that configuration is done, we can kick off both the pulse1_timer and pulse2_timer tasks. This is done using the spawn method as follows:

spawner.spawn(pulse1_timer(pulse1)).ok();
spawner.spawn(pulse2_timer(pulse2)).ok();

📱 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.

#![no_std]
#![no_main]
#![feature(type_alias_impl_trait)]

use embassy_executor::Spawner;
use embassy_time::{Instant, Duration};
use embedded_hal_async::digital::Wait;
use esp32c3_hal::gpio::{AnyPin, Input, Floating};
use esp32c3_hal::{clock::ClockControl, embassy, peripherals::Peripherals, prelude::*, IO};
use esp_backtrace as _;

#[embassy_executor::task]
async fn pulse1_timer(mut pin: AnyPin<Input<Floating>>) {
    loop {
        // Wait for rising edge
        pin.wait_for_high().await.unwrap();
        // Capture time instant at rising edge
        let inst = Instant::now();
        // Wait for falling edge
        pin.wait_for_low().await.unwrap();
        // Calculate Duration
        let pwidth = Instant::checked_duration_since(&Instant::now(), inst).unwrap();
        // Print Duration
        esp_println::println!("Sq Wave 1 Pulse Width is {}ms", pwidth.as_millis());
        // Uncomment below line to reduce console print frequency
        // Timer::after(Duration::from_millis(1000)).await;
    }
}

#[embassy_executor::task]
async fn pulse2_timer(mut pin: AnyPin<Input<Floating>>) {
    loop {
        // Wait for rising edge
        pin.wait_for_high().await.unwrap();
        // Capture time instant at rising edge
        let inst = Instant::now();
        // Wait for falling edge
        pin.wait_for_low().await.unwrap();
        // Calculate Duration
        let pwidth = Instant::checked_duration_since(&Instant::now(), inst).unwrap();
        // Print Duration
        esp_println::println!("Sq Wave 1 Pulse Width is {}ms", pwidth.as_millis());
        // Uncomment below line to reduce console print frequency
        // Timer::after(Duration::from_millis(1000)).await;
    }
}

#[main]
async fn main(spawner: Spawner) {
    let peripherals = Peripherals::take();
    let system = peripherals.SYSTEM.split();
    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

    // Initialize Embassy with needed timers
    let timer_group0 = esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks);
    embassy::init(&clocks, timer_group0.timer0);

    // This line is for Wokwi only so that the console output is formatted correctly
    esp_println::print!("\x1b[20h");

    // Inititalize and configure pins
    // Acquire Handle to IO
    let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
    // Configure pins as pull up input and degrade
    let pulse1 = io.pins.gpio0.into_floating_input().degrade();
    let pulse2 = io.pins.gpio1.into_floating_input().degrade();

    // Spawn pulse measurement tasks
    spawner.spawn(pulse1_timer(pulse1)).ok();
    spawner.spawn(pulse2_timer(pulse2)).ok();
}

Conclusion

In this post, a timer application measuring square wave pulse durations was created. The application leverages the Timer peripherals for the ESP32C3 microcontroller. The code was created leveraging the embassy framework. Have any questions? Share your thoughts in the comments below 👇.

This blog post is the fourth of a multi-part series of posts where I will explore various peripherals of the ESP32 using the embedded Rust embassy framework.

Prior posts include (in order of publishing):

1. Embassy on ESP: Getting Started

2. Embassy on ESP: GPIO

3. Embassy on ESP: UART Transmitter

Introduction

It is probably more common that UART is used in simplex one-direction communication Ex. to log device messages. As such, there might be less mention of UART receiver functionality. With receive functionality UART can be set up to receive and process incoming messages. For embedded applications, it can be useful if one wants to enable user input from a serial terminal. In this post, using embassy and the ESP32C3, I will be expanding on the last UART Transmitter post to include receive functionality as well. In the example in this post, I will create a UART echo application. The application will receive user input from the terminal and "echo" it back to the terminal.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Knowledge of how the embassy executor works.

• Basic knowledge of UART Communication.

💾 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

• ESP32-C3-DevKitM

  

🔌 Connections

No special connections are required for this implementation. The UART lines on the ESP32-C3 in DevKitM are connected on-board to the UART bridge.

🗒️ Note: The ESP uses the UART0 peripheral for esp_println . Be mindful of that if you want to modify the code in this example.

👨‍🎨 Software Design

In the application developed in this post, the ESP will wait for user input from the serial monitor and echo it back to the monitor. As such, the ESP will wait for incoming messages on the UART receiver end. Once a new message is entered, the ESP will keep buffering input characters until a valid end of transmission (EOT) character is received. After that the ESP will send the same buffered characters back to the monitor using its transmitter.

For this functionality there will be two tasks, a uart_reader (receive) task and a uart_writer (transmit) task. In between the tasks there will be a shared character (u8) buffer that I'll call DATAPIPE.

On a read event (incoming characters from monitor/terminal), the uart_reader task executes in taking the following steps:

1. read characters from UART receive buffer until a valid EOT character.

2. On the successful completion of a read, share the received characters with the uart_writer task by writing them to DATAPIPE.

The uart_writer task will kick in once new data appears in DATAPIPE taking the following steps:

1. write the DATAPIPE contents to the UART write buffer.

2. Transmit a new line (carriage return 0x0D followed by line feed 0x0A characters)

3. Flush the transmit buffer.

Let's now jump into the implementation.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation the crates required are as follows:

• The embassy_sync crate to import Pipe, a special abstraction needed for synchronization.

• The embassy_executor crate to import the embassy executor.

• The esp32c3-hal crate to import the necessary ESP32C3 abstractions.

• The esp_backtrace crate needed to define panic behavior.

use embassy_executor::Spawner;
use embassy_sync::{blocking_mutex::raw::CriticalSectionRawMutex, pipe::Pipe};
use esp32c3_hal::{
    clock::ClockControl,
    embassy,
    peripherals::{Peripherals, UART0},
    prelude::*,
    uart::{config::AtCmdConfig, UartRx, UartTx},
    Uart,
};
use esp_backtrace as _;

🌍 Global Variables & Constants

In the application at hand, there will be two tasks that share a character buffer. The uart_reader task will write to the shared buffer and the uart_writer task will read from this buffer. As such, we can create a global buffer DATAPIPE to "pipe" the characters are going to be passed around. We declare DATAPIPE as static and define it as follows:

static DATAPIPE: Pipe<CriticalSectionRawMutex, READ_BUF_SIZE> = Pipe::new();

📝 Note: Global variables shared among tasks in Rust could be a sticky topic. This is because sharing global data is unsafe since it can cause race conditions. You can read more about it here. Embassy offers several synchronization primitives that provide safe abstractions depending on what needs to be accomplished. There is a prior post where I go into detail about these primitives here.

In addition to the above, it would be convenient to define the following constants:

// Read Buffer Size
const READ_BUF_SIZE: usize = 64;
// End of Transmission Character (Carrige Return -> 13 or 0x0D in ASCII)
const AT_CMD: u8 = 0x0D;

READ_BUF_SIZE will be used to define the sizes of the buffers we declare. Additionally AT_CMD defines the character that we will use for detecting an EOT sequence.

🤓 The UART Reader Task

The UART reader task is expected to accept a UART instance as input and loop constantly check/await if MYSIGNAL gets updated. Though ahead of the loop it might be beneficial to indicate that the task has started. These are the required steps:

1️⃣ Create a UART Reader Task: Tasks are marked by the #[embassy_executor::task] macro followed by a async function implementation. The task created is referred to as uart_reader task defined as follows:

#[embassy_executor::task]
async fn uart_reader(mut tx: UartRx<'static, UART0>)

UartRx marks a UART receiver type that is configured with an instance of UART0. This means when spawning the task, we need pass a handle for a UART reciever configured with an instance of UART0. This will be done in the main task before spawning the uart_reader task.

2️⃣ Declare a Read Buffer: Before entering the task loop, we need to declare read buffer rbuf to store characters that will be received. rbuf will later store characters written to DATAPIPE .

let mut rbuf: [u8; READ_BUF_SIZE] = [0u8; READ_BUF_SIZE];

🔁 Task Loop

1️⃣ Read Characters from Monitor/Terminal into Buffer:

As part of the embedded_io_async crate we can use the read implementation of the Read trait to asynchronously read a message. read has the following signature:

async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>

As such, we need to pass a mutable reference of a type (UartRx in our case) that implements Read and our message as a slice of u8. Since read is an async function, the program needs to await for the read operation to complete. Using read we can receive characters into our buffer rbuf as follows:

 let r = embedded_io_async::Read::read(&mut rx, &mut rbuf[0..]).await;

read will keep on reading characters into rbuf until reaching a valid EOT character. The EOT character will be defined later in out main when we configure the UART0 peripheral. read also returns a Result that contains the amount of characters that were read.

2️⃣ Write Buffered Characters to Pipe: The Pipe we need to write to is DATAPIPE. For that, we need to write all of the characters in rbuf to DATAPIPE There exists a write_all method for the Pipe type that has the following signature:

pub async fn write_all(&self, buf: &[u8])

write_all will write all bytes from buf into the Pipe. This results in the following code for us:

match r {
    Ok(len) => {
        // If read succeeds then write recieved characters to pipe
        DATAPIPE.write_all(&rbuf[..len]).await;
    }
    Err(e) => esp_println::println!("RX Error: {:?}", e),
}

The match is used to process the Result returned from the read method. If a receive error occurs, then esp_println is used to log the error.

🕹️ The UART Writer Task

The UART writer task is expected to accept a UART instance as input and loop constantly check/await if DATAPIPE has new data. These are the required steps:

1️⃣ Create a UART Writer Task: Tasks are marked by the #[embassy_executor::task] macro followed by a async function implementation. The task created is referred to as uart_writer task defined as follows:

#[embassy_executor::task]
async fn uart_writer(mut tx: UartTx<'static, UART0>)

UartTx marks a UART transmitter type that is configured with an instance of UART0. This means when spawning the task, we need pass a handle for a UART transmitter configured with an instance of UART0. This will be done in the main task before spawning the uart_writer task.

2️⃣ Declare a Write Buffer: Before entering the task loop, we need to declare write buffer wbuf to store characters that will be transmitted. wbuf will later store characters read from DATAPIPE .

let mut wbuf: [u8; READ_BUF_SIZE] = [0u8; READ_BUF_SIZE];

🔁 Task Loop

1️⃣ Read Characters from Pipe into Write Buffer: In the task loop, the first thing we need to do is await a change on DATAPIPE. For that, there exists a read method for the Pipe type. read has the following signature:

pub fn read<'a>(&'a self, buf: &'a mut [u8]) -> ReadFuture<'a, M, N>

read will read a nonzero amount of bytes from the pipe into buf. If it is not possible to read a nonzero amount of bytes because the pipe’s buffer is empty, this method will wait until it isn’t. Consequently, we'll read DATAPIPE contents into wbuf as follows:

DATAPIPE.read(&mut wbuf).await;

2️⃣ Complete Write Operations:

As part of the embedded_io_async crate we can use the write implementation of the Write trait to asynchronously write a message. write has the following signature:

async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

As such, we need to pass a mutable reference of a type (UartTx in our case) that implements Write and our message as a slice of u8. Since write is an async function, the program needs to await for the write operation to complete. Using write we'll need to transmit the buffer contents, transmit a new line, and flush the transmit buffer. This results in the following code:

// Transmit Buffer Contents
embedded_io_async::Write::write(&mut tx, &wbuf)
    .await
    .unwrap();
// Transmit a new line
embedded_io_async::Write::write(&mut tx, &[0x0D, 0x0A])
    .await
    .unwrap();
// Flush transmit buffer
embedded_io_async::Write::flush(&mut tx).await.unwrap();

flush will flush the output stream and ensure that all the buffer contents reach their destination.

📝 Note: I could have easily also used esp_println which provides more convenient abstractions to print to the console. While in this context it does not make much difference, I did this for two reasons. First, since this is a UART example, we need to demonstrate how to use UART abstractions. Second, the previous code is a good demonstration of the use of the embedded-io-async traits. Using the embedded-io-async traits allows for more portable code in some contexts.

📱 The Main Task

The start of the main task is marked by the following code:

#[main]
async fn main(spawner: Spawner)

As the documentation states: "The main entry point of an Embassy application is defined using the #[main] macro. The entry point is also required to take a Spawner argument." As we'll see, Spawner is what will allow us to spawn or kick-off the uart_writer task.

The following steps will mark the tasks performed in the main task.

1️⃣ Obtain a handle for the device peripherals & system clocks: In embedded Rust, as part of the singleton design pattern, we first have to take the PAC-level device peripherals. This is done using the take() method. Here I create a device peripheral handler named peripherals , a system peripheral handler system, and a system clock handler clocks as follows:

let peripherals = Peripherals::take();
let system = peripherals.SYSTEM.split();
let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

2️⃣ Initialize Embassy Timers for the ESP32C3:

In embassy, there exists an init function that takes two parameters. The first is system clocks and the second is an instance of a timer. Under the hood, what this function does is initialize the embassy timers. As such, we can initialize the embassy timers as follows:

embassy::init(
    let timer_group0 = esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks);
    embassy::init(&clocks, timer_group0.timer0);

📝 Note: At the time of writing this post, I couldn't really locate the init function docs.rs documentation. It didn't seem easily accessible through any of the current HAL implementation documentation. Nevertheless, I reached the signature of the function through the source here.

3️⃣ Obtain Handle and Configure UART: to create an instance of UART0, there exists a new instance method under esp32c3_hal::Uart that requires two parameters; a UART peripheral type and a Clocks type. There also exists a split method that allows us to "split" the uart0 instance into separate transmitter and receiver instances with handles tx and rx. split returns a tuple with two instances. We also will be using UART methods set_at_cmd and set_rx_fifo_full_threshold to configure the AT_CMD character and the read buffer size.

let uart0 = Uart::new(peripherals.UART0, &clocks);
uart0.set_at_cmd(AtCmdConfig::new(None, None, None, AT_CMD, None));
uart0
    .set_rx_fifo_full_threshold(READ_BUF_SIZE as u16)
    .unwrap();
let (tx, rx) = uart0.split();

Note the following:

• UART0 is chosen since it is the one that ties to the UART logging pins on board. Additionally, new configures UART with the default 8N1 setup.

• set_at_cmd takes a AtCmdConfig parameter that is a struct with configuration options for the AT-CMD detection functionality. We only need to configure the EOT character. The rest of the members can be viewed in the documentation.

4️⃣ Spawn UART Reader and Writer Tasks: before entering the button press loop, we're going to need to kick off our uart_writer and uart_reader tasks. This is done using the spawn method as follows:

spawner.spawn(uart_writer(tx)).unwrap();\
spawner.spawn(uart_reader(tx)).unwrap();

Next, we can move on to the task loop.

This concludes the code for the full application.

📱 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.

#![no_std]
#![no_main]
#![feature(type_alias_impl_trait)]

use embassy_executor::Spawner;
use embassy_sync::{blocking_mutex::raw::CriticalSectionRawMutex, pipe::Pipe};
use esp32c3_hal::{
    clock::ClockControl,
    embassy,
    peripherals::{Peripherals, UART0},
    prelude::*,
    uart::{config::AtCmdConfig, UartRx, UartTx},
    Uart,
};
use esp_backtrace as _;

// Read Buffer Size
const READ_BUF_SIZE: usize = 64;

// End of Transmission Character (Carrige Return -> 13 or 0x0D in ASCII)
const AT_CMD: u8 = 0x0D;

// Declare Pipe sync primitive to share data among Tx and Rx tasks
static DATAPIPE: Pipe<CriticalSectionRawMutex, READ_BUF_SIZE> = Pipe::new();

#[embassy_executor::task]
async fn uart_writer(mut tx: UartTx<'static, UART0>) {
    // Declare write buffer to store Tx characters
    let mut wbuf: [u8; READ_BUF_SIZE] = [0u8; READ_BUF_SIZE];
    loop {
        // Read characters from pipe into write buffer
        DATAPIPE.read(&mut wbuf).await;
        // Transmit/echo buffer contents over UART
        embedded_io_async::Write::write(&mut tx, &wbuf)
            .await
            .unwrap();
        // Transmit a new line
        embedded_io_async::Write::write(&mut tx, &[0x0D, 0x0A])
            .await
            .unwrap();
        // Flush transmit buffer
        embedded_io_async::Write::flush(&mut tx).await.unwrap();
    }
}

#[embassy_executor::task]
async fn uart_reader(mut rx: UartRx<'static, UART0>) {
    // Declare read buffer to store Rx characters
    let mut rbuf: [u8; READ_BUF_SIZE] = [0u8; READ_BUF_SIZE];
    loop {
        // Read characters from UART into read buffer until EOT
        let r = embedded_io_async::Read::read(&mut rx, &mut rbuf[0..]).await;
        match r {
            Ok(len) => {
                // If read succeeds then write recieved characters to pipe
                DATAPIPE.write_all(&rbuf[..len]).await;
            }
            Err(e) => esp_println::println!("RX Error: {:?}", e),
        }
    }
}

#[main]
async fn main(spawner: Spawner) {
    let peripherals = Peripherals::take();
    let system = peripherals.SYSTEM.split();
    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

    // Initialize Embassy with needed timers
    let timer_group0 = esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks);
    embassy::init(&clocks, timer_group0.timer0);

    // Initialize and configure UART0
    let mut uart0 = Uart::new(peripherals.UART0, &clocks);
    uart0.set_at_cmd(AtCmdConfig::new(None, None, None, AT_CMD, None));
    uart0
        .set_rx_fifo_full_threshold(READ_BUF_SIZE as u16)
        .unwrap();
    // Split UART0 to create seperate Tx and Rx handles
    let (tx, rx) = uart0.split();

    // Spawn Tx and Rx tasks
    spawner.spawn(uart_reader(rx)).ok();
    spawner.spawn(uart_writer(tx)).ok();
}

Conclusion

In this post, a UART application receiving and transmitting from/to a host was created for the ESP32C3 microcontroller. The code leveraged the Pipe synchronization primitive with the embassy async framework to enable a UART echo application. Have any questions? Share your thoughts in the comments below 👇.

Inspired by James Munns's call, and as 2023 is coming to an end, I figure it's a good opportunity to reflect and look forward to 2024. It's been a bit over 1.5 years since I embarked on my embedded Rust journey and it's been nothing less than exciting since. So here it goes.

The Beginnings 👶

It all started through a habit I have of reading job descriptions, particularly in the embedded space, to understand market trends. Back in 2021, alongside the usual suspects of C and C++, I recall seeing Rust as a preferred skill and having no clue what it was. After that, the more I got into Rust, the more I figured that it makes the most sense for embedded going forward.

Rust is stereotyped as a language that is hard to learn. My perspective is that what makes it feel hard is that it requires an adapted mindset. Because the thing is, once you get used to Rust, you start feeling that it's easier to deal with compared to other languages. For me, at this point, I find it hard sometimes to adapt my mindset back to languages like C. Though regardless, huge strides have been made in teaching the language. At this point, there is no shortage of free and paid educational material, and resources are only increasing. This is also impacted by the sheer number of people adopting Rust.

In the embedded Rust space, things were (and still are somewhat) a bit reversed. What I mean by this is that it is harder to get started with embedded Rust than Rust itself, yet, there probably isn't nearly as much guidance/resources. There is a growing gap between the quickly evolving ecosystem and the limited educational resources. There is a good number of options/combinations to get started with from choices of HALs, PACs, Embassy, RTIC, std, no-std....etc. This is apart from existing challenges for embedded beginners like identifying a controller/dev board and setting up a toolchain. Many ways to get started, without necessarily a clear path add intimidation and confusion factors. This can be an obstacle to increased adoption which is needed to facilitate more (and thus faster) growth.

I might be naive in thinking this, but the formula in my mind is simple; easy access leads to faster adoption. For a newbie, comparing Rust to embedded Rust, it's two contrasting experiences. It literally takes a few seconds to get started with Rust while with embedded, well, it varies. It varies with the level of experience and platform, but it probably ranges from seconds to hours.

The Gaps 🕳️

I subscribe to the belief that increasing educational resources is a crucial part of increased adoption. As a result, after gaining some footing I set out myself with a focus on embedded Rust education. Some of the gaps I realized included:

1. Material Focus: Many educational resources take the approach of focusing on what Rust brings to embedded, rather than how embedded works with Rust. For example, if you grab any traditional embedded book, the material assumes knowledge of C/C++ and explains embedded concepts with C as a tool. This is not something that I found to be the case with Rust-embedded material (but was an expectation of mine). This might not be ideal for one starting with embedded and Rust. Why? because embedded context is assumed to exist. I felt at the time there was somewhat of a community mindset focused on convincing familiar users that Rust is good for embedded. Now though I think the evolving mindset needs to be that Rust is here to stay and this is how embedded is done using Rust. Thinking of it, one who knows how good Rust is would only want to try it in a different context. This made it one of my goals to get more non-embedded Rustaceans into the field.

2. Incomplete Documentation: Going through existing resources at the time, I always had thoughts of "what about if I wanted to do x or y?". For that, existing learning material only would give a flavor. So I dived into the world of embedded crate documentation and a long dive it was. I recall how navigating and interpreting documentation was quite a challenging experience at the start. Also while there were many abstractions there were several methods without descriptions. Some methods were self-explanatory, others were not. I often had to dig into the source to figure out certain things. A reverse engineering task. I even published several posts since trying to address this gap. Also while the documentation part remains an issue, I feel it is recognized within the community.

3. Missing Context: Code examples are great, which many HAL repositories include, though I don't think raw examples are beginner material. The biggest issue is that many of the examples miss context or explanation. As a result, figuring out what the example does becomes another reverse engineering task. I recall instances that I had to figure out from the code example what particular device/sensor is being interacted with. The examples might have not targeted beginners, but they must do so with time. Maybe supplemented with more comments or associated with explanatory material.

4. Unnoticed Work: There are a lot of great contributions done by the Rust community that I felt might be going unnoticed. Many members have invested incredible time in contributing toward different projects and creating material but I felt they might not have gotten the deserved exposure.

2023 Reflections 🪞

In the content I've been producing and the contributions I make, my goal was always and still is to address the gaps I mentioned earlier. A big part of it is to attract first-time embedded curious users who love Rust. At least in the educational space, there's a lot of ground to cover, and I had hoped to do much more, but I am doing this mostly in my spare time. However, at least in 2023, here are some of the milestones I reached and accomplishments I achieved:

• ✍️ 88 Blog Posts: These blog posts have been mostly Rust-embedded tutorials that I publish weekly. The idea or focus was to help beginners get started with tutorial posts. Each post is also associated with a template project to provide a starting point. Out of the 88 Posts, there were focused series including the following:

  • STM32 HAL Series

  • STM32 PAC Series

  • STM32 Embassy Series

  • Building Drivers with Rust

  • no-std ESP32

  • std ESP32

  • ESP32 IoT Series

  • (On Going) ESP32 Embassy Series

• 📰 The Embedded Rustacean Newsletter: This was an effort I established to help bring more focus on different parts of embedded Rust. The space is moving fast and having a resource summarizing activities periodically helps community members stay up to date. This includes; highlighting projects, educational material, industry trends, Rust adoptions, and jobs among others. Since launching the newsletter, several individuals have expressed how there is much more going on in embedded Rust than they perceived.

• 🛰️ AeroRust Space Conference: Part of this conference was a 1-day workshop on embedded Rust that I contributed to. The workshop material targets embedded space enthusiasts who want to build with Rust. The workshop included the building of a pseudo-nano satellite platform using Embassy and ESP. For the interested, the material is all open-sourced here. The learners got to tinker with real hardware building a small nanosatellite and also programming it.

• 📖 Embedded Electronics Book: While this is not embedded Rust-focused, it was inspired by community beginner struggles. Many new learners get lost in the early electronic configurations of microcontrollers. I figured a resource like this would help fill in some gaps.

A Look Forward to 2024 🔮

What I Have in Plan

• A Book on Embedded Rust: The electronics book was actually a distraction from another book project I was working on. This new book aligns with filling one of the earlier gaps mentioned; A book with material that covers embedded foundations with Rust.

• More & More Blog Posts: With upcoming posts, I hope to fill in more educational gaps. I notice there is a lot of interest within the community in Embassy. I have also gotten notes for creating tutorials on additional devices like the Raspberry Pi Pico and the nRF series of devices. I'd personally also like to highlight exciting projects like Shuttle and Ockam that I find have a lot of potential. Even work with several driver crates.

• Expand Embedded Rust Reach: I hope to do this by expanding the reach of the newsletter. Highlight embedded trends and opportunities as they come along. Also, keep the community informed of activities that are going on and give exposure to the work that is being done. This would be hopefully a vehicle to attract more embedded enthusiasts into the Rust space as well.

What I'd Hope to See

These are things that are probably better suited as community efforts:

• Plug and Play: This goes to the goal of being able to get started with embedded Rust in seconds. A self-contained solution including hardware with a preconfigured toolchain and a project template to get started developing embedded Rust in a jiffy. Maybe the best way to explain this is to have an Arduino-like model. This includes embedded Rust-branded development boards integrating controllers that the community identifies/adopts. Along with a VSCode extension like PlatformIO or even a lightweight IDE like Arduino to spawn preconfigured projects quickly. All this can bring more community focus on developing examples and crates around the Rust boards. Having boards also answer a beginner's big question of "What hardware should I buy?". I would say from my viewpoint that the current effort that looks closest to this is the ecosystem Espressif is building around ESPs with Rust.

• More Wokwi Integration: Wokwi is an amazing embedded simulator and is great for getting started quickly. For a learner, there's no need for toolchain setup or even the purchase of hardware. There are many features as well that make it quite a flexible tool supporting a lot of features right from the browser. Users can also vote for more features. Still maybe at some point, one might want to tinker with physical hardware. However, at that point, they would have gained some confidence first. Currently, only ESP boards are supported with Rust on Wokwi. I hope for the variety to expand soon.

Acknowledgments 🙏

None of this work would have been possible without community support. I always thought that even had Rust sucked, I would probably stick around because of the community. I would like to give special thanks to the following people:

• Juraj Michalek and Sergio Gasquez of Espressif Systems for embracing my work, helping integrate me into community meetings, proofreading my book, and offering different means of support.

• Aissata Maiga of Ferrous Systems in her support proofreading my book and providing invaluable input. Also as one of the community members to recognize my work early on.

• Lachezar Lechev of AeroRust for inviting me to become part of the AeroRust space conference. Also for being a great host during my time at the conference.

• Jeremy Lempereur of Apollo GraphQL for sponsoring my trip to the AeroRust space conference.

Conclusion

I think that a core driver to accelerated Embedded Rust adoption is the production of more educational material. Those interested in embedded Rust do not all necessarily come from an embedded background. Creating educational material comes with the challenge of simplifying concepts and providing a quick way to start. It's easy for a regular practitioner to get caught up with what they think is easy though it's different for a beginner. Strides have been made in this context for embedded Rust but more work remains. 2023 was an exciting year for embedded Rust in that regard, I only look forward to what's to come in 2024.

This blog post is the third of a multi-part series of posts where I will explore various peripherals of the ESP32 using the embedded Rust embassy framework.

Prior posts include (in order of publishing):

1. Embassy on ESP: Getting Started

2. Embassy on ESP: GPIO

Introduction

Setting up UART serial communication remains useful for several types of device-to-device (point-to-point) communication. One of the common examples is interacting with a host PC. UART implementations are also still found in some industrial and wireless applications. In this post, using embassy and the ESP32C3, I will be configuring and setting up UART communication with a host PC. UART will be configured as a transmitter where the application will detect and send button press counts over the communication channel.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Knowledge of how the embassy executor works.

• Basic knowledge of UART Communication.

💾 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

• ESP32-C3-DevKitM

  

🔌 Connections

No special connections are required for this implementation. The UART lines on the ESP32-C3 in DevKitM are connected on-board to the UART bridge.

👨‍🎨 Software Design

In the application developed in this post, button presses will be detected and counted. The button press count will be sent over UART to the host PC. A button press input will be configured for interrupts and increment a count each time the button is pressed. Consequently, every time a button press is detected the UART interface will transmit the count. The button press logic and the UART logic will each be implemented in their own tasks.

Figure 1 below expresses the states/logic of the button press task. Additionally, Figure 2 expresses the states/logic the UART task will alternate between. The button task will be implemented in the main task. Note that both tasks are being observed as independent each running their own logic. In reality, each will treated by the embassy executor as such. However, the UART task is dependent on a count variable being updated by the button press state machine. For that, we will need to use a special abstraction that allows safe exchange of data among tasks.

Let's now jump into implementing this algorithm.

👨‍💻 Code Implementation

📥 Crate Imports

In this implementation the crates required are as follows:

• The embassy_sync crate to import Signal, a special abstraction needed for synchronization.

• The embassy_executor crate to import the embassy executor.

• The embedded-hal-async crate to import the GPIO abstractions to detect button presses.

• The esp32c3-hal crate to import the needed ESP32C3 abstractions.

• The esp_backtrace crate needed to define panic behavior.

use embassy_executor::Spawner;
use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::signal::Signal;
use embedded_hal_async::digital::Wait;
use esp32c3_hal::{
    clock::ClockControl,
    embassy, interrupt,
    peripherals::{Interrupt, Peripherals, UART0},
    prelude::*,
    Uart, UartTx, IO,
};
use esp_backtrace as _;

🌍 Global Variables

In the application at hand, there will be two tasks that share a count value. The button press detection task will increment a count the UART writer task will use it. As such, we can create a global variable MYSIGNAL to "signal" the count value that is going to be passed around. We declare MYSIGNAL as static and define it as follows:

static MYSIGNAL: Signal<CriticalSectionRawMutex, u32> = Signal::new();

📝 Note: Global variables shared among tasks in Rust is a very sticky topic. This is because sharing global data is unsafe since it can cause race conditions. You can read more about it here. Embassy offers several synchronization primitives that provide safe abstractions depending on what needs to be accomplished. There is a prior post where I go into detail about these primitives here.

🕹️ The UART Writer Task

The UART writer task is expected to accept a UART instance as input and loop constantly check/await if MYSIGNAL gets updated. Though ahead of the loop it might be beneficial to indicate that the task has started. These are the required steps:

1️⃣ Create a UART Writer Task: Tasks are marked by the #[embassy_executor::task] macro followed by a async function implementation. The task created is referred to as uart_writer task defined as follows:

#[embassy_executor::task]
async fn uart_writer(mut tx: UartTx<'static, UART0>)

UartTx marks a UART transmitted type that is configured with an instance of UART0. This means when spawning the task, we need pass a handle for a UART transmitter configured with an instance of UART0. This will be done in the main task before spawning the uart_writer task.

2️⃣ Print a Message: As part of the embedded_io_async crate we can use the write implementation in the Write trait to asynchronously write a message. write has the following signature:

async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

As such, we need to pass a mutable reference of a type (UartTx in our case) that implements Write and our message as a slice of u8. Since write is an async function, the program needs to await for the write operation to complete. This results in the following code:

embedded_io_async::Write::write(
    &mut tx,
    b"UART Task Spawned. Waiting for Button Press...\r\n",
)
.await
.unwrap();

📝 Note: I could have easily also used esp_println which provides more convenient abstractions to print to the console. While in this context it does not make much difference, I did this for two reasons. First, since this is a UART example, we need to demonstrate how to use UART abstractions. Second, the previous code is a good demonstration of the use of the embedded-io-async traits. Using the embedded-io-async traits allows for more portable code in some contexts.

3️⃣ Define the task loop: Next enter the task loop. The first thing we need to do is await a change on MYSIGNAL. For that, there exists a wait method for the Signal type. wait_for_rising_edge is an async function that resolves into a Future if its waiting on a signal. Once the Future resolves, we get back a value corresponding to the press_count. We then print the press_count:

loop {
    let press_count = MYSIGNAL.wait().await;
    esp_println::println!("Button Pressed {} time(s)", press_count);
}

📱 The Main Task

The start of the main task is marked by the following code:

#[main]
async fn main(spawner: Spawner)

As the documentation states: "The main entry point of an Embassy application is defined using the #[main] macro. The entry point is also required to take a Spawner argument." As we'll see, Spawner is what will allow us to spawn or kick-off the button_press task.

The following steps will mark the tasks performed in the main task.

1️⃣ Obtain a handle for the device peripherals & system clocks: In embedded Rust, as part of the singleton design pattern, we first have to take the PAC-level device peripherals. This is done using the take() method. Here I create a device peripheral handler named peripherals , a system peripheral handler system, and a system clock handler clocks as follows:

let peripherals = Peripherals::take();
let system = peripherals.SYSTEM.split();
let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

2️⃣ Initialize Embassy Timers for the ESP32C3:

In embassy, there exists an init function that takes two parameters. The first is system clocks and the second is an instance of a timer. Under the hood, what this function does is initialize the embassy timers. As such, we can initialize the embassy timers as follows:

embassy::init(
    &clocks,
    esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks).timer0,
);

📝 Note: At the time of writing this post, I couldn't really locate the init function docs.rs documentation. It didn't seem easily accessible through any of the current HAL implementation documentation. Nevertheless, I reached the signature of the function through the source here.

3️⃣ Instantiate and Create Handle for IO: We need to configure the LED pins as a push-pull output and obtain a handler for the pin so that we can control it. Similarly, we need to obtain a handle for the button input pin. Before we can obtain any handles for the LEDs and the button we need to create an IO struct instance. The IO struct instance provides a HAL-designed struct that gives us access to all gpio pins thus enabling us to create handles for individual pins. This is similar to the concept of a split method used in other HALs (more detail here). We do this by calling the new() instance method on the IO struct as follows:

let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);

Note how the new method requires passing the GPIO and IO_MUX peripherals.

4️⃣ Obtain a handle and configure the input button: The push button is connected to pin 2 (gpio2) as stated earlier. Additionally, in the pressed state, the button pulls to ground. Consequently, for the button unpressed state, a pull-up resistor needs to be included so the pin goes high. An internal pull-up can be configured for the pin using the into_pull_up_input() method as follows:

let mut button = io.pins.gpio2.into_pull_up_input();

5️⃣ Obtain Handle and Configure UART: to create an instance of UART0, there exists a new instance method under esp32c3_hal::Uart that requires two parameters; a UART peripheral type and a Clocks type. Since we need only an instance of a UART transmitted, there also exists a split method that allows us to "split" the uart0 instance into separate transmitter and receiver instances. split returns a tuple with two instances. Since we don't need the receiver instance an underscore _ is used.

let uart0 = Uart::new(peripherals.UART0, &clocks);
let (tx, _) = uart0.split();

UART0 is chosen since it is the one that ties to the UART logging pins on board. Additionally, new configures UART with the default 8N1 setup.

6️⃣ Enable GPIO Interrupts: At this point, the button instance is just an input pin. In order to make the device respond to push button events, interrupts need to be enabled for button. This results in the following lines of code:

esp32c3_hal::interrupt::enable(
    esp32c3_hal::peripherals::Interrupt::GPIO,
    esp32c3_hal::interrupt::Priority::Priority1,
)

4️⃣ Spawn UART Writer Task: before entering the button press loop, we're going to need to kick off our uart_writer task. This is done using the spawn method as follows:

spawner.spawn(uart_writer(tx)).unwrap();

Next, we can move on to the task loop.

🔁 Main Task Loop

Following the design described earlier, in the main task (button press task), we will await a button press to occur. Once a press has occurred, press_count is incremented and signaled. Here's the code:

let mut press_count = 0;
loop {
    // Await Button Press
    button.wait_for_rising_edge().await.unwrap();
    // Increment Count
    press_count += 1;
    // Signal Press Count
    MYSIGNAL.signal(press_count);
}

Note here the use of the signal method on MYSIGNAL to update its value and "signal" it to the uart_writer task.

This concludes the code for the full application.

📱 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.

#![no_std]
#![no_main]
#![feature(type_alias_impl_trait)]

use embassy_executor::Spawner;
use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::signal::Signal;
use embedded_hal_async::digital::Wait;
use esp32c3_hal::{
    clock::ClockControl,
    embassy, interrupt,
    peripherals::{Interrupt, Peripherals, UART0},
    prelude::*,
    Uart, UartTx, IO,
};
use esp_backtrace as _;

static MYSIGNAL: Signal<CriticalSectionRawMutex, u32> = Signal::new();

#[embassy_executor::task]
async fn uart_writer(mut tx: UartTx<'static, UART0>) {
    embedded_io_async::Write::write(
        &mut tx,
        b"UART Task Spawned. Waiting for Button Press...\r\n",
    )
    .await
    .unwrap();
    loop {
        let press_count = MYSIGNAL.wait().await;
        esp_println::println!("Button Pressed {} time(s)", press_count);
    }
}

#[main]
async fn main(spawner: Spawner) {
    let peripherals = Peripherals::take();
    let system = peripherals.SYSTEM.split();
    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

    // Initilize Embassy Timers
    embassy::init(
        &clocks,
        esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks).timer0,
    );

    // Configure UART
    let uart0 = Uart::new(peripherals.UART0, &clocks);
    let (tx, _) = uart0.split();

    // Configure GPIO
    let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
    let mut button = io.pins.gpio2.into_pull_up_input();

    // Enable Interrupts for GPIO
    interrupt::enable(Interrupt::GPIO, interrupt::Priority::Priority1).unwrap();

    spawner.spawn(uart_writer(tx)).ok();

    let mut press_count = 0;
    loop {
        // Detect and Count Button Presses
        button.wait_for_rising_edge().await.unwrap();
        press_count += 1;
        // Signal Press Count
        MYSIGNAL.signal(press_count);
    }
}

Conclusion

In this post, a UART application transmitting to a host was created for the ESP32C3 microcontroller. The code combined the use of Signals, GPIO, and interrupts with the embassy async framework. Have any questions? Share your thoughts in the comments below 👇.

This blog post is the second of a multi-part series of posts where I will explore various peripherals of the ESP32 using the embedded Rust embassy framework.

Prior posts include (in order of publishing):

1. Embassy on ESP: Getting Started

Introduction

In the first post from last week, a basic application was built in embassy on the ESP32C3. This was mainly to introduce basic operations and also a template to build on. One of the things that is amazing about embassy and async is how much easier it is to implement interrupt-driven code. There are two prior blog posts that you can compare to for ESP. Both for std and no-std implementation of interrupts. I recommend revisiting those prior posts to draw comparisons.

In this post, we'll get to start experimenting with GPIO interrupts in embassy. We'll see how we can configure GPIO, read inputs, and manipulate output. We'll be developing an application that uses a 10 LED bar graph to circulate a light at different speeds. The speed is altered by a button press.

📚 Knowledge Pre-requisites

To understand the content of this post, you need the following:

• Basic knowledge of coding in Rust.

• Knowledge of how the embassy executor works

💾 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

• ESP32-C3-DevKitM

  

• 10 Segment LED Bar Graph

• Pushbutton

🔌 Connections

📝 Note

All connection details are also shown in the Wokwi example.

Connections include the following:

• LED Bar Graph Anode A10 to gpio1 on the devkit.

• LED Bar Graph Anode A9 to gpio10 on the devkit.

• LED Bar Graph Anode A8 to gpio19 on the devkit.

• LED Bar Graph Anode A7 to gpio18 on the devkit.

• LED Bar Graph Anode A6 to gpio4 on the devkit.

• LED Bar Graph Anode A5 to gpio5 on the devkit.

• LED Bar Graph Anode A4 to gpio6 on the devkit.

• LED Bar Graph Anode A3 to gpio7 on the devkit.

• LED Bar Graph Anode A2 to gpio8 on the devkit.

• LED Bar Graph Anode A1 to gpio9 on the devkit.

• All LED Bar Graph Cathodes C1-C10 are connected to each other and the devkit GND.

• On one end, the button pin should be connected to gpio3 of the devkit. The gpio3 pin will be configured as input. On the same button end, the other pin of the switch will be connected to the devkit GND.

👨‍🎨 Software Design

In the application developed in this post, I want to cycle through turning on LEDs on an LED bar. A button will also be used to change how fast the light is cycling. Meaning, that every time I press the button, I want to see the LED cycling at a different speed. Obviously, the device pins would need to be configured first, which I will cover in the next section. In this section, I will focus on the design of the application algorithm.

The design will use interrupts to detect button press events. The button press will modify a delay variable shared with the main task. We can consider that the application has two tasks, an LED cycling task and a button-press task. Both applications share a del variable that is adjusted according to button presses.

In the LED cycling (main) task, starting with the first LED in the sequence on the LED bar, here are the steps the algorithm would go through:

1. Turn on LED.

2. await for a delay of del to expire.

3. Turn off the LED.

4. await for a delay of 100ms to expire.

5. Repeat steps 1-5 for the next LED in sequence.

6. Once all LEDs are done, loop back to the first LED in sequence.

In the button-pressed task, here are the steps the algorithm would go through:

1. await for a button press to occur (ex. rising edge to occur).

2. Adjust del

3. Go back to step 1.

Note that every time we have an await the task is yielding to the executor to determine what to do next.

For the delay adjusting procedure in the button-pressed task, the delay value is changed so that the rate of LED cycling decreases. However, we need to make sure that the new delay value does not go negative. As such, if the del drops below a certain threshold we'd want to reset it to the original value we started with.

For step 4 in the main task, note the 100 ms delay. This is to make sure that the current LED is off (visually) before turning on the next one in the sequence. You can experiment with this and see that if removed, you would notice an effect that the previous LED is still on when the current one turns on. You could probably live with a smaller delay as long as your eye does not notice it, I just used 100ms to stay on the safe side.

Let's now jump into implementing this algorithm.

👨‍💻 Code Implementation

📝 Although I followed the documentation to set up my first project, it wasn't all smooth sailing. It was mainly had to do with configurations/settings of configuration (toml) files. I figure this has to do with embassy still being considered to be experimental. Set up I managed to get working is available up in my git repo.

📥 Crate Imports

In this implementation the crates required are as follows:

• The core::sync::atomic and portable_atomic crates to import Atomic and Ordering that will be needed for syncronization.

• The embassy_executor crate to import the embassy executor.

• The embassy_time crate to import Timer abstractions for delays.

• The embedded-hal-async crate to import the GPIO abstractions to detect button presses.

• The esp32c3-hal crate to import the needed ESP32C3 abstractions.

• The esp_backtrace crate needed to define panic behavior.

use core::sync::atomic::Ordering;
use portable_atomic::AtomicU32;
use embassy_executor::Spawner;
use embassy_time::{Duration, Timer};
use embedded_hal_async::digital::Wait;
use esp32c3_hal::{clock::ClockControl, embassy, peripherals::Peripherals, prelude::*, IO};
use esp32c3_hal::gpio::{AnyPin, Input, PullUp};
use esp_backtrace as _;

🌍 Global Variables

In the application at hand, there will be two tasks that share a delay value. The button press detection task will adjust the delay and the LED control task will use it. As such, we can create a global variable BLINK_DELAY to carry the delay value that is going to be passed around. Here the AtomicU32 type is used which is an integer type that can be safely shared between threads. The AtomicU32 type has the same in-memory representation as the underlying integer type, u32 but is considered safe to share between threads.

static BLINK_DELAY: AtomicU32 = AtomicU32::new(200_u32);

📝 Note: Global variables shared among tasks in Rust is a very sticky topic. This is because sharing global data is unsafe since it can cause race conditions. You can read more about it here. Embassy offers several synchronization primitives that provide safe abstractions depending on what needs to be accomplished. There is a prior post about these primitives here.

🕹️ The Button Press Task

The button press task is expected to accept a GPIO pin as input and loop forever checking if the button is pressed. These are the required steps:

1️⃣ Create a blinking task and handle for the button: Tasks are marked by the #[embassy_executor::task] macro followed by a async function implementation. The task created is referred to as press_button task defined as follows:

#[embassy_executor::task]
async fn press_button(mut button: AnyPin<Input<PullUp>>)

AnyPin marks a generic pin type that is configured as a PullUp Input. This means we need to obtain a handle for the button pin and configure it to an input with a pull-up. This will be done in the main task before spawning the button_press task

2️⃣ Define the task loop: Next enter the task loop. The first thing we need to do is await a button press. For that, there exists a wait_for_rising_edge method implementation for the Wait trait in the embedded-hal-async. wait_for_rising_edge is an async function that resolves into a Future if its waiting on a condition. Otherwise, we get a Result . We call wait_for_rising_edge on button as follows:

button.wait_for_rising_edge().await.unwrap();

Using embassy, async events from interrupts or otherwise are managed through Futures. This means that execution can be yielded using await to allow other code to progress until the event attached to a Future occurs. The executor manages all of this in the background and more detail about it is provided in the embassy documentation.

3️⃣ Retrieve the delay: Next we load the delay value from the global context as follows:

let del = BLINK_DELAY.load(Ordering::Relaxed);

load is a method part of the AtomicU32 synchronization abstraction.

4️⃣ Adjust the Delay: This is the final step in the task and involves adjusting the delay according to our desired logic. Here we are doing decrements of 50 ms and if we reach a value less than 50, we reset back to the starting value of 200.

if del <= 50_u32 {
  BLINK_DELAY.store(200_u32,Ordering::Relaxed);
  esp_println:: println!("Delay is now 200ms");
} else {
  BLINK_DELAY.store(del - 50_u32,Ordering::Relaxed);
  esp_println:: println!("Delay is now {}ms", del - 50_u32);
}

📱 The Main Task (LED Cycling Task)

The start of the main task is marked by the following code:

#[embassy_executor::main]
async fn main(spawner: Spawner)

As the documentation states: "The main entry point of an Embassy application is defined using the #[embassy_executor::main] macro. The entry point is also required to take a Spawner argument." As we've seen in last week's post, Spawner is what will allow us to spawn or kick-off button_task.

As indicated before, the main task will also be where we manage the LED cycling logic. The following steps will mark the tasks performed in the main task.

1️⃣ Obtain a handle for the device peripherals & system clocks: In embedded Rust, as part of the singleton design pattern, we first have to take the PAC-level device peripherals. This is done using the take() method. Here I create a device peripheral handler named peripherals , a system peripheral handler system, and a system clock handler clocks as follows:

let peripherals = Peripherals::take();
let system = peripherals.SYSTEM.split();
let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

2️⃣ Initialize Embassy Timers for the ESP32C3:

In embassy, there exists an init function that takes two parameters. The first is system clocks and the second is an instance of a timer. Under the hood, what this function does is initialize the embassy timers. As such, we can initialize the embassy timers as follows:

embassy::init(
    &clocks,
    esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks).timer0,
);

📝 Note: At the time of writing this post, I couldn't really locate the init function docs.rs documentation. It didn't seem easily accessible through any of the current HAL implementation documentation. Nevertheless, I reached the signature of the function through the source here.

3️⃣ Instantiate and Create Handle for IO: We need to configure the LED pins as a push-pull output and obtain a handler for the pin so that we can control it. Similarly, we need to obtain a handle for the button input pin. Before we can obtain any handles for the LEDs and the button we need to create an IO struct instance. The IO struct instance provides a HAL-designed struct that gives us access to all gpio pins thus enabling us to create handles for individual pins. This is similar to the concept of a split method used in other HALs (more detail here). We do this by calling the new() instance method on the IO struct as follows:

let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);

Note how the new method requires passing the GPIO and IO_MUX peripherals.

4️⃣ Obtain a handle and configure the input button: The push button is connected to pin 2 (gpio2) as stated earlier. Additionally, in the pressed state, the button pulls to ground. Consequently, for the button unpressed state, a pull-up resistor needs to be included so the pin goes high. An internal pull-up can be configured for the pin using the into_pull_up_input() method as follows:

let del_but = io.pins.gpio2.into_pull_up_input().degrade();

Note that as opposed to the LED outputs, the button handle here does not need to be mutable since we will only be reading it. Additionally, here we are using the degrade method which "degrades" the pin type into a generic AnyPin type that is required to pass to the button_press task.

5️⃣ Obtain handles for the LEDs and configure them to output: We have 10 LEDs that we need to activate individually. One approach is to configure each separately and activate it separately. However, in order to make things efficient, we can combine the LED pin handles all in one array. This will allow us to iterate over the individual pins using a for loop. However, there is a challenge here. Each pin will have a different type and arrays require that all elements are of a similar type. This is another good example for usage of degrade. Using degrade we can make all the pins of the same AnyPin type. This is how it looks like:

let mut leds = [
    io.pins.gpio1.into_push_pull_output().degrade(),
    io.pins.gpio10.into_push_pull_output().degrade(),
    io.pins.gpio19.into_push_pull_output().degrade(),
    io.pins.gpio18.into_push_pull_output().degrade(),
    io.pins.gpio4.into_push_pull_output().degrade(),
    io.pins.gpio5.into_push_pull_output().degrade(),
    io.pins.gpio6.into_push_pull_output().degrade(),
    io.pins.gpio7.into_push_pull_output().degrade(),
    io.pins.gpio8.into_push_pull_output().degrade(),
    io.pins.gpio9.into_push_pull_output().degrade(),
];

3️⃣ Enable GPIO Interrupts: At this point, the button instance is just an input pin. In order to make the device respond to push button events, interrupts need to be enabled for button. In the interrupt module in the esp32c3-hal, there exists an enable method that allows the enabling of different interrupts. The enable method has the following signature:

pub fn enable(interrupt: Interrupt, level: Priority) -> Result<(), Error>

interrupt expects an Interrupt type which is an enumeration of all interrupts for the esp32c3. Also level expects a priority which is also an enumeration of all priorites. This results in the following line of code:

esp32c3_hal::interrupt::enable(
    esp32c3_hal::peripherals::Interrupt::GPIO,
    esp32c3_hal::interrupt::Priority::Priority1,
)

I chose a priority of one since there are no other interrupts. this would only make a difference when you have several interrupts that might compete for processor time.

4️⃣ Spawn Button Press Task: before entering the LED cycling loop, we're going to need to kick off our button_press task. Then button_press task can be kicked off using the spawn method as follows:

spawner.spawn(press_button(del_but)).unwrap();

Next, we can move on to the application Loop.

🔁 Main Task Loop

Following the design described earlier, in the main task, we will cycle through turning on and off LEDs. Along the way we should await a BLINK_DELAY amount of time before going to the next LED. Since we packaged all LEDs in an array this is done in a for loop as follows:

loop {
    for led in &mut leds {
        led.set_high().unwrap();
        Timer::after(Duration::from_millis(BLINK_DELAY.load(Ordering::Relaxed) as u64)).await;
        led.set_low().unwrap();
        Timer::after(Duration::from_millis(100)).await;
    }
}

Note the usage of Timer that comes from the embassy_time crate. after is a Timer instance method that accepts a Duration and returns a Future. As such, await allows us to yield execution to the executor such that the task can be polled later to check if the delay expired. Note that we are delaying BLINK_DELAY amount of delay after setting the LED to high. This is the shared value that is adjusted by the button_press task.

This concludes the code for the full application.

📱 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.

#![no_std]
#![no_main]
#![feature(type_alias_impl_trait)]

use core::sync::atomic::Ordering;
use portable_atomic::AtomicU32;
use embassy_executor::Spawner;
use embassy_time::{Duration, Timer};
use embedded_hal_async::digital::Wait;
use esp32c3_hal::{clock::ClockControl, embassy, peripherals::Peripherals, prelude::*, IO};
use esp32c3_hal::gpio::{AnyPin, Input, PullUp};
use esp_backtrace as _;

// Global Variable to Control LED Rotation Speed
static BLINK_DELAY: AtomicU32 = AtomicU32::new(200_u32);

#[main]
async fn main(spawner: Spawner) {
    // Take Peripherals
    let peripherals = Peripherals::take();
    let system = peripherals.SYSTEM.split();
    let clocks = ClockControl::boot_defaults(system.clock_control).freeze();

    // Initilize Embassy Timers
    embassy::init(
        &clocks,
        esp32c3_hal::timer::TimerGroup::new(peripherals.TIMG0, &clocks).timer0,
    );

    // Acquire Handle to IO
    let io = IO::new(peripherals.GPIO, peripherals.IO_MUX);
    // Configure Delay Button to Pull Up input
    let del_but = io.pins.gpio2.into_pull_up_input().degrade();
    // Configure LED Array Pins to Output & Store in Array
    let mut leds = [
        io.pins.gpio1.into_push_pull_output().degrade(),
        io.pins.gpio10.into_push_pull_output().degrade(),
        io.pins.gpio19.into_push_pull_output().degrade(),
        io.pins.gpio18.into_push_pull_output().degrade(),
        io.pins.gpio4.into_push_pull_output().degrade(),
        io.pins.gpio5.into_push_pull_output().degrade(),
        io.pins.gpio6.into_push_pull_output().degrade(),
        io.pins.gpio7.into_push_pull_output().degrade(),
        io.pins.gpio8.into_push_pull_output().degrade(),
        io.pins.gpio9.into_push_pull_output().degrade(),
    ];
    // Enable GPIO Interrupts
    esp32c3_hal::interrupt::enable(
        esp32c3_hal::peripherals::Interrupt::GPIO,
        esp32c3_hal::interrupt::Priority::Priority1,
    )
    .unwrap();
    // Spawn Button Press Task
    spawner.spawn(press_button(del_but)).unwrap();

    // This line is for Wokwi only so that the console output is formatted correctly
    esp_println::print!("\x1b[20h");

    // Enter Application Loop Blinking on LED at a Time
    loop {
        for led in &mut leds {
            led.set_high().unwrap();
            Timer::after(Duration::from_millis(BLINK_DELAY.load(Ordering::Relaxed) as u64)).await;
            led.set_low().unwrap();
            Timer::after(Duration::from_millis(100)).await;
        }
    }
}


#[embassy_executor::task]
async fn press_button(mut button: AnyPin<Input<PullUp>>) {
    loop {
      // Wait for Button Press
      button.wait_for_rising_edge().await.unwrap();
      esp_println:: println!("Button Pressed!");
      // Retrieve Delay Global Variable
      let del = BLINK_DELAY.load(Ordering::Relaxed);
      // Adjust Delay Accordingly
      if del <= 50_u32 {
        BLINK_DELAY.store(200_u32,Ordering::Relaxed);
        esp_println:: println!("Delay is now 200ms");
      } else {
        BLINK_DELAY.store(del - 50_u32,Ordering::Relaxed);
        esp_println:: println!("Delay is now {}ms", del - 50_u32);
      } 
    }
}

Conclusion

In this post, an LED control application was created leveraging the GPIO peripheral for the ESP32C3 microcontroller. The code was created using interrupts and the embassy async framework. It shows how embassy really simplifies the development of interrupt-based code. Have any questions? Share your thoughts in the comments below 👇.