DEV Community: Omar Hiari

From Zero to Rust: Simplified Embedded Systems Programming

Omar Hiari — Mon, 20 May 2024 20:43:35 +0000

Introduction 🚀

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.

If Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter & get 10% off the book:

Subscribe Now to The Embedded Rustacean

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:

Conceptual Background: An overview of the peripheral and how it operates.
Configuration and Coding Steps: Detailed steps to configure and program the peripheral.
Application Example(s): A practical example (or examples) to demonstrate the peripheral in action.
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:

Embedded Systems Knowledge	Rust Programming Knowledge	Recommended Edition
Intermediate/Advanced	Intermediate/Advanced	Core
Intermediate/Advanced	Beginner	Core or Standard
Beginner	Intermediate/Advanced	Standard
Beginner	Beginner	Standard

Click Here to Acquire the Core Edition

Click Here to Acquire the Standard Edition

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:

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

Embedded Rust Bluetooth on ESP: Secure BLE Server

Omar Hiari — Mon, 15 Apr 2024 20:25:39 +0000

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.

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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:

(Added Step) Configure device security capabilities and connection method for pairing
(Modified Step) Create Secure Service & Characteristic
Configure Advertising Data & Start Advertising
Establish a connection
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 👇.

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

Embedded Rust Bluetooth on ESP: Secure BLE Client

Omar Hiari — Tue, 09 Apr 2024 05:57:30 +0000

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.

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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

🛠 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 capabilities 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 a 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:

(Added Step) Configure device security capabilities and connection method for pairing
Scan and find a particular advertiser
Establish a connection
(Added Step) Secure the connection
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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

Embedded Rust Bluetooth on ESP: BLE Client

Omar Hiari — Mon, 01 Apr 2024 09:00:00 +0000

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.

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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

🛠 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:

Scan and find a particular advertiser
Establish a connection
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

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.

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.

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

// 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

📝 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 👇.

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

Embedded Rust Bluetooth on ESP: BLE Server

Omar Hiari — Mon, 25 Mar 2024 09:00:00 +0000

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.

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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

🛠 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:

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.

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

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

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 BLEServer update_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>

where 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 supervision timeout 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();
});

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 BLEService create_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 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::NOTIFY,
);

// Set a starting value for the characteristic
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();

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.

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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

Embedded Rust Bluetooth on ESP: BLE Advertiser

Omar Hiari — Sat, 16 Mar 2024 06:05:52 +0000

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.

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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

🛠 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:

General Discoverable Mode: In this mode, the BLE device continuously broadcasts advertising packets to advertise its presence to nearby devices.
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

let ble_device = BLEDevice::take();

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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

Embedded Rust Bluetooth on ESP: BLE Scanner

Omar Hiari — Sun, 10 Mar 2024 14:45:06 +0000

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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:

Physical Layer (PHY): This layer of is responsible for converting digital data into radio waves and vice versa for transmission.
Link Layer (LL): This layer among several tasks, manages the connection establishment, data packet format, and error handling.
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).
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.
Security Manager (SM): This layer is responsible for establishing and managing security features in BLE connections.
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.
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.

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

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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

Edge IoT with Rust on ESP: WiFi Revisited

Omar Hiari — Sat, 02 Mar 2024 20:31:26 +0000

Introduction

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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

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:

Configure WiFi
Start WiFi
Connect WiFi
(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:

Instantiate and Configure UART
Ask user for SSID
Read and store SSID
Ask user for password
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 👇.

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

ESP Embedded Rust: Ping CLI App Part 2

Omar Hiari — Sat, 24 Feb 2024 11:08:11 +0000

Introduction

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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:

Setup CLI Root Menu & Callback
CLI Start-Up
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 Ipv4Addr from_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_config EspPing 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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

ESP Embedded Rust: Ping CLI App Part 1

Omar Hiari — Sat, 17 Feb 2024 11:36:49 +0000

Introduction

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 Knowledge Pre-requisites

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

💾 Software Setup

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:

The ping command Item needs to be added to the root menu Menu struct.
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:

Configure, Instantiate, and Connect to WiFi.
Configure and Instantiate UART
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:

Retrieve & Process CLI input
Instantiate EspPing
Setup EspPing Configuration
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 the ping command Item to 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_MENU Item 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_str Result. 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️⃣ Instantiate EspPing: This is a single-line action same to what was done before:

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

3️⃣ Setup EspPing Configuration: 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️⃣ Perform ping and 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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

Edge IoT with Rust on ESP: Ping!

Omar Hiari — Sat, 10 Feb 2024 18:07:12 +0000

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.

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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

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:

Configure and Connect to WiFi.
Configure and perform a Ping.
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

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 default Configuration 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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

ESP Embedded Rust: Command Line Interface

Omar Hiari — Sat, 03 Feb 2024 20:05:32 +0000

Introduction

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.

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

📚 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:

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.
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.
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).
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:

Define the Root Menu
Implement any Callback functions
Configure peripherals in main
Instantiate the Runner in main
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

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

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Subscribe Now to The Embedded Rustacean

DEV Community: Omar Hiari

From Zero to Rust: Simplified Embedded Systems Programming

Introduction 🚀

If Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter & get 10% off the book:

Motivation Behind the Book 🎓

Goals 🎯

Why Rust? 🦀

Why ESP? 🌐

The Review Process 🔍

How is This Book Different from The Blog? ✍️

What the Book Covers 📘

Who is This Book For? 🌟

Choosing the Right Edition 📚

Why a Subscription Model? 💡

Upcoming Updates 🛠️

Acknowledgments 🙏

Conclusion ✨

Embedded Rust Bluetooth on ESP: Secure BLE Server

Introduction

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

📚 Knowledge Pre-requisites

💾 Software Setup

🛠 Hardware Setup

Materials

🔌 Connections

👨‍🎨 Software Design

👨‍💻 Code Implementation

📥 Crate Imports

🎛 Initialization/Configuration Code

📱 Application Code

🧪 Testing

📱Full Application Code

Conclusion

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Embedded Rust Bluetooth on ESP: Secure BLE Client

Introduction

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

📚 Knowledge Pre-requisites

💾 Software Setup

🛠 Hardware Setup

Materials

🔌 Connections

👨‍🎨 Software Design

👨‍💻 Code Implementation

📥 Crate Imports

🎛 Initialization/Configuration Code

📱 Application Code

🧪 Testing

📱Full Application Code

Conclusion

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Embedded Rust Bluetooth on ESP: BLE Client

Introduction

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

📚 Knowledge Pre-requisites

💾 Software Setup

🛠 Hardware Setup

Materials

🔌 Connections

👨‍🎨 Software Design

👨‍💻 Code Implementation

📥 Crate Imports

🎛 Initialization/Configuration Code

📱 Application Code

🧪 Testing

📱Full Application Code

Conclusion

If you found this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

Embedded Rust Bluetooth on ESP: BLE Server

Introduction

If you find this post useful, and if Embedded Rust interests you, stay in the know by subscribing to The Embedded Rustacean newsletter:

📚 Knowledge Pre-requisites

💾 Software Setup

🛠 Hardware Setup

Materials

🔌 Connections

👨‍🎨 Software Design

🔗 Connection Establishment & Management

🔃 Data Exchange

🛎️ Services & Characteristics