Edge IoT with Rust on ESP: HTTP Server

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

Prior posts include (in order of publishing):

Introduction

In the last post, we understood how to create an HTTP client on an ESP device using the Rust ESP-IDF framework. That also required a connection to WiFi that was established and explained in an earlier post. In this post, we are going to use HTTP to create a server using ESP and Rust. For that, we'll create a simple html page that will be returned by a GET request from a client.

📚 Knowledge Pre-requisites

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

Basic knowledge of coding in Rust.
Basic familiarity with WiFi & HTTP.
Basic familiarity with HTML.

💾 Software Setup

All the code presented in this post is available on the apollolabs ESP32C3 git repo. Note that if the code on the git repo is slightly different then it means that it was modified to enhance the code quality or accommodate any HAL/Rust updates.

Additionally, the full project (code and simulation) is available on Wokwi here.

🛠 Hardware Setup

Materials

ESP32-C3-DevKitM

👨‍🎨 Software Design

In the post last week, we mentioned that HTTP follows a client-server model and enables the exchange of data between web browsers and servers. When you enter a website's URL into your browser, it sends an HTTP request to the server hosting that site. This request specifies the action to be performed, like fetching a webpage or submitting data. Also, HTTP requests use methods like GET, POST, PUT, or DELETE to convey their purpose. Additionally, the Uniform Resource Locator (URL) identifies the resource to be accessed.

When a server receives a request, it responds with a status code indicating the outcome of the request. For instance, 200 signifies success, 404 denotes a resource not found, and 500 signals a server error. Also, a GET request is one type of HTTP request that's initiated by a client to request data/objects from a specified resource on a server. In the context of websites, on a server, typically the first object requested is the page base HTML object/file. The base HTML file would then include any other in-page elements that the client has to retrieve subsequently. We've covered the client-side interaction last post. Here's how a typical request interaction works on the server side:

Listen for Connections: A server is an "always on" entity. This is because it has to be available at all times to respond to client requests. Additionally, a server would have a static IP address that it can be reached on. This is not necessarily true for a client. As such, the server keeps on "listening" for any connection requests coming in.
Establish Connection: We've seen that clients have to establish a connection first before exchanging information with a server. Once a request comes in, the server opens an HTTP port establishing a connection with the client.
Process and Send Response: The server locates the requested resource and packages it into an HTTP response. This response includes a status code indicating the outcome of the request (commonly 200 OK for a successful request) and the requested data (like an HTML file for a webpage). If the resource is not located typically the server would respond with a 404 Not Found.
Closing the Connection: After the data is transmitted, the connection is closed. This completes the GET request interaction.

In this post, we are going to configure the ESP to operate as an HTTP server responding with a simple HTML page. The steps include the following:

Configure and Connect to WiFi
Configure HTTP and Create an HTTP Server Listener
Configure a Handler Function that Responds to Incoming Requests

👨‍💻 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 and embedded_svc crates to import the device services (wifi and HTTP in particular).
The embedded_svc crate to import the needed http and wifi service traits.
The std::thread and std::time to introduce delays.

use anyhow;
use embedded_svc::http::Method;
use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration};
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::http::server::{Configuration as HttpServerConfig, EspHttpServer};
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::wifi::{BlockingWifi, EspWifi};
use std::{thread::sleep, time::Duration};

🎛 Initialization/Configuration Code

1️⃣ Obtain a handle for the device peripherals: Similar to all past blog posts, in embedded Rust, as part of the singleton design pattern, we first have to take the device peripherals. This is done using the take() method. Here I create a device peripheral handler named peripherals as follows:

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

2️⃣ Configure and Connect to WiFi: this involves the same steps that were done in the last post.

3️⃣ Create the HTTP Connection Handle: Within esp_idf_svc::http::server there exists an EspHttpServer abstraction. This is the abstraction needed to set up and configure an HTTP server. EspHttpServer contains a new method for instantiation that takes a single reference to a http::server::Configuration type parameter. We're going to go for the default configuration. Following that we create a httpserver handle as follows:

// Create Server Connection Handle
let mut httpserver = EspHttpServer::new(&HttpServerConfig::default())?;

Note I am using HttpServerConfig instead of Configuration . This is because in the imports I declared Configuration as HttpServerConfig . I did this because the wifi::Configuration name overlaps with the wifi http::server::Configuration name.

That's it for Configuration!

📱 Application Code

1️⃣ Define Response Behaviour: Within the EspHttpServer abstraction there is an fn_handler method that is used to define response behavior. fn_handler takes three parameters; a uri, a Method , and a closure that includes the request object response. For the uri we need to define the path of the object. Here we are only going to serve a webpage for the root path / . Also, we're only going to respond to Get requests:

// Define Server Request Handler Behaviour on Get for Root URL
httpserver.fn_handler("/", Method::Get, |request| {
    // Retrieve html String
    let html = index_html();
    // Respond with OK status
    let mut response = request.into_ok_response()?;
    // Return Requested Object (Index Page)
    response.write(html.as_bytes())?;
    Ok(())
})?;

There remains the third argument which is the closure. This is where the response behavior is defined for the root HTML object request. There are four things happening here:

The HTML object to respond with is retrieved as a String. index_html is a function that contains and returns an HTML file as a formatted String. index_html is shown later in this post.
An OK response is constructed from the request using the into_ok_response method.
The request is responded to using the write method on response. write expects a slice of u8 or &[u8], therefore the usage of the as_bytes method on the html handle String.
An Ok is propagated to confirm the request has been completed successfully.

Note here that the EspHttpServer abstraction is taking care of several things for us. This includes opening and closing connections and responding with a 404 if a resource isn't found.

2️⃣ Define the HTML Object: Recall we retrieved the HTML object as a String using the index_html function. As such, we have to define this function. You can use the format! macro also:

fn index_html() -> String {
    format!(
        r#"
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>esp-rs web server</title>
    </head>
    <body>
    Hello World from ESP!
    </body>
</html>
"#
    )
}

r# is used with String literals to negate the need to escape special characters inside the string. More on it here.

3️⃣ Keep the Program Running: As mentioned earlier, the server needs to stay on. This means that we have to keep the program running so that it doesn't terminate. You might think the use of loop{} is sufficient. However, if you try to run the application that way, you'll face a problem. A watchdog will kick in. To avoid that behaviour you can use a simple sleep function from std::thread::sleep.

loop {
   sleep(Duration::from_millis(1000));
}

🏃‍♂️Running the Example

To run the example to access the webpage, you need to use the IP address of the ESP on your network. You can get that from the console output. In the below figure an example is shown. The IP address you need is the sta ip and it's 192.168.0.126 .

Additionally, if you are going to run the example on Wokwi, then you need a private gateway.

📱Full Application Code

Here is the full code for the implementation described in this post. You can additionally find the full project and others available on the apollolabs ESP32C3 git repo. Also, the Wokwi project can be accessed here.

use anyhow;
use embedded_svc::http::Method;
use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration};
use esp_idf_hal::peripherals::Peripherals;
use esp_idf_svc::eventloop::EspSystemEventLoop;
use esp_idf_svc::http::server::{Configuration as HttpServerConfig, EspHttpServer};
use esp_idf_svc::nvs::EspDefaultNvsPartition;
use esp_idf_svc::wifi::{BlockingWifi, EspWifi};
use std::{thread::sleep, time::Duration};

fn main() -> anyhow::Result<()> {
    esp_idf_sys::link_patches();

    // Configure Wifi
    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: "SSID".into(),
        bssid: None,
        auth_method: AuthMethod::None,
        password: "PASSWORD".into(),
        channel: None,
    }))?;

    // Start Wifi
    wifi.start()?;

    // Connect Wifi
    wifi.connect()?;

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

    println!("Wifi Connected, Starting HTTP Server");

    // HTTP Configuration
    // Create HTTP Server Connection Handle
    let mut httpserver = EspHttpServer::new(&HttpServerConfig::default())?;

    // Define Server Request Handler Behaviour on Get for Root URL
    httpserver.fn_handler("/", Method::Get, |request| {
        // Retrieve html String
        let html = index_html();
        // Respond with OK status
        let mut response = request.into_ok_response()?;
        // Return Requested Object (Index Page)
        response.write(html.as_bytes())?;
        Ok(())
    })?;

    // Loop to Avoid Program Termination
    loop {
        sleep(Duration::from_millis(1000));
    }
}

fn index_html() -> String {
    format!(
        r#"
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>esp-rs web server</title>
    </head>
    <body>
    Hello World from ESP!
    </body>
</html>
"#
    )
}

Conclusion

HTTP is a core protocol in Internet applications. As a result, it forms a crucial aspect of IoT projects and enables a wide variety of applications. ESPs also some of the most popular devices among makers for enabling such projects. This post introduced how to create an HTTP server on ESP using Rust and the esp_idf_svc crate. Have any questions? Share your thoughts in the comments below 👇.

Edge IoT with Rust on ESP: HTTP Server

Comments