Chapter 268: Ultra-Wideband (UWB) Support

Chapter Objectives

By the end of this chapter, you will be able to:

• Understand the fundamental principles of Ultra-Wideband (UWB) technology.
• Describe how UWB enables high-precision distance measurement using Time-of-Flight (ToF).
• Explain the role of the ESP32 as a host controller for an external UWB transceiver.
• Set up a project using the esp-uwb library to communicate with a UWB module.
• Implement a basic two-way ranging application between two UWB devices.
• Recognize the benefits of UWB for secure positioning and asset tracking.
• Troubleshoot common hardware and software issues in an ESP32-UWB system.

Introduction

In the world of wireless technologies, determining a device’s precise location has always been a significant challenge. GPS is ineffective indoors, Wi-Fi Round-Trip Time (RTT) offers meter-level accuracy, and Bluetooth’s signal strength indicators (RSSI) are often unreliable. Ultra-Wideband (UWB) technology emerges as a game-changing solution to this problem.

UWB is a radio technology that enables highly accurate, secure, and real-time distance measurement with centimeter-level precision. This capability unlocks a new generation of applications, from indoor navigation and secure keyless entry for cars to augmented reality and precision asset tracking in warehouses.

While no current ESP32 variant includes an integrated UWB radio, Espressif provides a software solution, the esp-uwb library, that allows an ESP32 to act as a host controller for an external UWB transceiver. This chapter will explore the theory behind UWB and guide you through the process of integrating this powerful technology with an ESP32 host.

Theory

What is Ultra-Wideband?

Unlike conventional radio systems (like Wi-Fi or Bluetooth) that transmit on narrow frequency bands, UWB sends a series of very short-duration, low-energy pulses across a very wide spectrum of frequencies (typically over 500 MHz wide).

Analogy: Shouting in a Canyon

Imagine you are standing in a canyon and want to know the distance to the far wall. You could shout and time how long it takes for the echo to return. If you know the speed of sound, you can calculate the distance. UWB works on a similar principle, but instead of a slow sound wave, it uses a near-light-speed radio pulse.

This method is called Time-of-Flight (ToF). Because the UWB pulses are extremely short (nanoseconds), it’s possible to time their travel with incredible precision, which directly translates to centimeter-accurate distance measurements.

---
config:
    xyChart:
        width: 900
        height: 600
        showDataLabel: true
    themeVariables:
        xyChart:
            plotColorPalette: "#ff0000,#00ff00"
---
xychart-beta
    title "Signal Characteristics: UWB vs. Narrowband"
    x-axis "Frequency (GHz)" [1, 2, 3, 4, 5, 6, 7, 8, 9]
    y-axis "Power" 0 --> 1
    
    line [0, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0]
    line [0, 0, 0, 0, 0.8, 0, 0, 0, 0]

Two-Way Ranging (TWR)

To calculate the distance between two devices (let’s call them a Tag and an Anchor), a simple one-way ToF measurement is not enough due to clock synchronization challenges. Instead, UWB systems use a technique called Two-Way Ranging (TWR) or a more advanced variant like Symmetric Double-Sided TWR (SDS-TWR).

The basic TWR process is as follows:

1. The Tag sends a pulse to the Anchor and records the departure timestamp (T1).
2. The Anchor receives the pulse at its timestamp (T2) and, after a known delay, sends a response pulse back.
3. The Tag receives the response pulse at its timestamp (T3).
4. By exchanging these timestamps, the devices can collaboratively calculate the round-trip time, cancel out processing delays, and determine the ToF.

ToF = ((T3 – T1) – (Time Anchor spent processing)) / 2

Distance = ToF * speed_of_light

This method is highly robust and is the foundation of UWB’s precision.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
sequenceDiagram
    participant T as Tag (Initiator)
    participant A as Anchor (Responder)

    T->>A: Poll Message (Records T1)
    activate A
    Note right of A: Receives at T2
    A-->>T: Response Message (After known delay)
    deactivate A
    Note left of T: Receives at T3
    
    T->>T: Calculate Time-of-Flight (ToF)
    Note over T: ToF = ((T3 - T1) - (T_reply - T_round)) / 2
    Note over T: Distance = ToF * c

UWB vs. Other Technologies

ESP32 and the esp-uwb Library

As mentioned, ESP32 chips do not have a built-in UWB radio. The esp-uwb component is an ESP-IDF library that provides an API for an ESP32 to control an external UWB chip (like the Qorvo DW3000 series) over an SPI interface.

This architecture has several benefits:

• Flexibility: You can pair a powerful UWB chip with the ESP32 variant that best suits your application’s other needs (e.g., an ESP32-S3 for its processing power and Wi-Fi 6, or an ESP32-C6 for its Wi-Fi, BLE, and Thread capabilities).
• Separation of Concerns: The ESP32 handles the main application logic, connectivity (Wi-Fi/BLE), and user interface, while the dedicated UWB chip handles the complex, timing-critical radio operations.

Practical Example: Basic UWB Ranging

This example demonstrates how to set up an ESP32 as a UWB Tag that performs ranging with an Anchor. This requires two identical hardware setups. One will be programmed as the “initiator” (Tag), and the other as the “responder” (Anchor).

Warning: This practical example is more advanced than previous chapters as it requires external hardware. You will need two ESP32 development boards and two compatible UWB modules (e.g., from Qorvo, Decawave, or NXP). The wiring must be done correctly via SPI.

1. Hardware Setup

• ESP32 Host: An ESP32-S3 or ESP32-C6 is recommended.
• UWB Module: A module based on the Qorvo DW3000 series is a common choice and is supported by esp-uwb.
• Connections: Connect the ESP32 to the UWB module via SPI. You will need to connect MISO, MOSI, SCLK, CS, and an IRQ pin.
  • ESP32 GPIO2 -> UWB_MISO
  • ESP32 GPIO7 -> UWB_MOSI
  • ESP32 GPIO6 -> UWB_SCLK
  • ESP32 GPIO10 -> UWB_CS
  • ESP32 GPIO4 -> UWB_IRQ
  • 3.3V -> UWB_VCC
  • GND -> UWB_GND
  (Note: These GPIO pins are an example; they can be configured in software.)

2. Project Setup and esp-uwb

1. Start with a base project: idf.py create-project my_uwb_project.
2. Add esp-uwb as a component: The easiest way is to add it as a git submodule within your project’s components directory.cd my_uwb_project mkdir components cd components git submodule add https://github.com/espressif/esp-uwb.git
3. Update the main CMakeLists.txt: In your project’s root directory, edit CMakeLists.txt to tell the build system about the new component.# At the end of the file, add: set(EXTRA_COMPONENT_DIRS components/esp-uwb)

3. Code Implementation

Create a main/app_main.c file. The code will initialize the UWB chip and start a task that periodically initiates ranging.

/* main/app_main.c */
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "uwb.h" // Main header for the esp-uwb library

static const char *TAG = "UWB_RANGING_APP";

#define UWB_DEVICE_ROLE UWB_DEVICE_ROLE_INITIATOR // Change to UWB_DEVICE_ROLE_RESPONDER for the anchor device

// Callback function to handle ranging results
void ranging_cb(uwb_mac_evt_t *evt)
{
    if (evt->type == UWB_MAC_EVE_RANGING_DONE) {
        uwb_ranging_done_t *ranging_result = (uwb_ranging_done_t *)evt->data;
        if (ranging_result->status == UWB_RANGING_SUCCESS) {
            ESP_LOGI(TAG, "Ranging successful! Distance: %.2f meters", ranging_result->distance);
        } else {
            ESP_LOGW(TAG, "Ranging failed with status: %d", ranging_result->status);
        }
    }
}

void app_main(void)
{
    // 1. Initialize the UWB controller
    ESP_LOGI(TAG, "Initializing UWB Controller");
    uwb_controller_init();

    // 2. Configure the SPI interface for the UWB chip
    spi_bus_config_t bus_cfg = {
        .miso_io_num = 2,
        .mosi_io_num = 7,
        .sclk_io_num = 6,
        .quadwp_io_num = -1,
        .quadhd_io_num = -1,
        .max_transfer_sz = 1024,
    };
    spi_bus_initialize(UWB_SPI_HOST, &bus_cfg, SPI_DMA_CH_AUTO);

    spi_device_interface_config_t dev_cfg = {
        .clock_speed_hz = 10 * 1000 * 1000, // 10 MHz
        .mode = 0,
        .spics_io_num = 10,
        .queue_size = 7,
    };
    spi_device_handle_t spi_device;
    spi_bus_add_device(UWB_SPI_HOST, &dev_cfg, &spi_device);

    // 3. Configure the UWB MAC layer
    uwb_mac_config_t mac_config = {
        .role = UWB_DEVICE_ROLE,
        .ranging_cb = ranging_cb, // Register our callback
    };

    // 4. Initialize the UWB device (this communicates with the chip)
    uwb_init(spi_device, 4); // The second parameter is the IRQ GPIO
    uwb_mac_init(&mac_config);

    ESP_LOGI(TAG, "UWB Initialized. Role: %s", UWB_DEVICE_ROLE == UWB_DEVICE_ROLE_INITIATOR ? "Initiator (Tag)" : "Responder (Anchor)");

    // 5. If this device is the initiator, start the ranging process
    if (UWB_DEVICE_ROLE == UWB_DEVICE_ROLE_INITIATOR) {
        while (1) {
            ESP_LOGI(TAG, "Starting a new ranging attempt...");
            // The address 0x1234 is a placeholder; in a real system, you'd discover anchors.
            uwb_ranging_start(0x1234); 
            vTaskDelay(pdMS_TO_TICKS(2000)); // Range every 2 seconds
        }
    }
    // The responder device will automatically listen and respond to ranging requests.
}

4. Build, Flash, and Run

1. Build and Flash the Responder (Anchor):
   • In app_main.c, make sure #define UWB_DEVICE_ROLE UWB_DEVICE_ROLE_RESPONDER.
   • Run idf.py build flash monitor. The device will initialize and wait.
2. Build and Flash the Initiator (Tag):
   • In app_main.c, change the define to #define UWB_DEVICE_ROLE UWB_DEVICE_ROLE_INITIATOR.
   • Run idf.py build flash monitor on the second device.
3. Observe:
   • On the Initiator’s monitor, you will see it attempting to range every two seconds.
   • If the Anchor is nearby and running, the callback will fire on the Initiator, and you will see the calculated distance printed to the log: I (xxxx) UWB_RANGING_APP: Ranging successful! Distance: 0.45 meters

Variant Notes

The most critical point to understand is that no current ESP32-series SoC has a built-in UWB radio. Support is provided by using an ESP32 as a host controller for an external UWB chip.

Common Mistakes & Troubleshooting Tips

Exercises

1. Ranging Data Logger: Modify the initiator’s code. When a successful ranging measurement is received in the ranging_cb, store the distance and a timestamp into Non-Volatile Storage (NVS). Write a separate function that can be triggered (e.g., by a button press) to read and print the last 10 stored measurements from NVS.
2. Multi-Anchor System Design (Conceptual): You are tasked with creating an indoor positioning system for a small room. You can use three Anchor devices and one Tag. Conceptually describe the process required to determine the Tag’s 2D (x, y) coordinates.
   • How would the Tag perform ranging with all three Anchors?
   • Once the Tag has the three distances (d1, d2, d3) to the three known Anchor positions (A1, A2, A3), what mathematical principle would you use to calculate the Tag’s position? (Hint: Think about circles and where they intersect). This process is called trilateration.

Summary

• Ultra-Wideband (UWB) is a radio technology that provides centimeter-level distance measurement using Time-of-Flight (ToF) calculations.
• ESP32 SoCs do not have integrated UWB radios but can act as a host controller for an external UWB chip via an SPI interface.
• The esp-uwb library provides the necessary drivers and MAC layer functions to integrate an ESP32 with UWB modules.
• The core of UWB operation is Two-Way Ranging (TWR), a message exchange protocol between an Initiator (Tag) and a Responder (Anchor).
• UWB’s precision and security make it ideal for advanced applications like secure keyless entry, indoor navigation, and asset tracking.
• Proper hardware wiring (especially SPI and IRQ) is critical for a functional ESP32-UWB system.

Further Reading

• Espressif esp-uwb Example: The unofficial GitHub repository is the best source for code and examples.
  • https://github.com/espressif/esp-uwb
• FiRa Consortium: The industry group standardizing UWB for interoperability.
  • https://www.firaconsortium.org/
• Qorvo (formerly Decawave) UWB Resources: A leading manufacturer of UWB chips with extensive application notes and datasheets.
  • https://www.qorvo.com/products/ultra-wideband