• Software Development
• Education

Contents:

• Introduction
• Links
• Additional Tools
• BLE Learning Resources
• Getting Started
• Cables
• ESP-IDF Installation
• Step 1. Install prerequisites (Linux)
• 1a. Dialout Group
• Step 2. Get ESP-IDF
• 2a. Python Version
• Step 3. Set up the tools
• ESP-IDF Development
• Examples
• Step 4. Set up the environment variables
• Step 5. Start a Project
• Step 6. Connect Your Device
• Step 7. Configure
• Step 8. Build the Project
• Step 9. Flash onto the Device
• Wrong Target
• Step 10. Monitor
• Debugging
• Debugger Connection
• OpenOCD
• GDB
• Managing Breakpoints
• Simultaneous Monitoring And Debugging
• Debugging Strategy
• Wireshark Sniffing
• Filtering On Known Data
• Creating Filters From Captured Data
• Using A Filter To Find Packets

Introduction

The ESP-C3-32S-Kit is a small dev board made by Ai.Thinker, containing an ESP-C3-32S SoC module, supporting WiFi and BLE:

Development for the board uses the Espressif IoT Development Framework (ESP-IDF), which the Ai.Thinker documentation refers to as the "Secondary development SDK".

You can get two of these for prototyping, using one as a BLE peripheral (the peripheral device you connect to, such as headphones or a mouse) and the other as a BLE central (the central device that connects to the peripheral, such as a smartphone or laptop).

ESP-IDF bundles software stacks and example applications for both of these use cases. This page shows using the Apache MyNewt NimBLE stack with FreeRTOS.

Much of the information on this page is useful for working with other ESP32 boards, since ESP-IDF is the official SDK for the ESP32 product line. Some of it is also useful for working with other vendor devices and BLE software stacks.

Links

• Alibaba order page
• ESP32-C3S module info page
• ESP32-C3 module document page
• ESP-C3-32S Specification
• ESP-C3-32S-Kit Specification
• ESP-IDF (Github)
• Getting Started with ESP-IDF
• ESP-IDF Programming Guide: Get Started
• ESP-IDF Programming Guide: IDF Monitor
• ESP-IDF API Guides: JTAG Debugging
• Debugging the ESP32-C3 Device with JTAG

Additional Tools

You can use phone apps like Nordic nRF Connect for Mobile to connect to these as either the peripheral or central for testing.

Another very useful tool is the Nordic BLE sniffer, which is custom firmware for a Nordic nRF52840 USB dongle:

The sniffer software includes a Wireshark package so that you can capture, analyze, and view BLE traffic on your laptop.

BLE Learning Resources

These resources aren't necessarily required to work with the ESP-C3-32S-Kit, but if you really want to understand BLE, they provide a good foundation and many subtle details.

The specifications are very long and probably far more detailed that you need. In general, the other resources summarize specific topics in a much briefer form.

I always like to learn from multiple resources, because each one offers a slightly different perspective and coverage.

• Bluetooth SIG
  • Bluetooth specifications
    • Download Core Specification 5.3
    • Download Core Specification 4.2
  • An Introduction to Bluetooth Low Energy Development free downloadable study guide.
  • The Bluetooth LE Security Study Guide free downloadable study guide.
  • Videos
    • Intro to Bluetooth Low Energy
    • Intro to Bluetooth Generic Access Profile (GAP)
    • Intro to Bluetooth Generic Attribute Profile (GATT)
    • Intro to Bluetooth Advertisements
    • Intro to Bluetooth Connections
    • Intro to Bluetooth Security Part 1
    • Intro to Bluetooth Security Part 2
  • Blog posts
    • Bluetooth Pairing Part 1 – Pairing Feature Exchange
    • Bluetooth Pairing Part 2 - Key Generation Methods
    • Bluetooth Pairing Part 3 – Low Energy Legacy Pairing Passkey Entry
    • Bluetooth Pairing Part 4: Bluetooth Low Energy Secure Connections – Numeric Comparison
    • Bluetooth Pairing Part 5: Legacy Pairing – Out of Band
• https://www.novelbits.io/ includes blog posts, YouTube videos, and training courses.
  • Introduction to Bluetooth Low Energy free downloadable book.
  • YouTube channel
  • How Bluetooth Low Energy Works: Advertisements (Part 1)
  • Nordic nRF52840 USB Dongle
    • Video: How to use nRF52840 USB Dongle and nRF Connect for emulating a BLE peripheral 
    • Blog series: Prototyping BLE apps on the nRF52840 USB Dongle
      • Part 1
      • Part 2
      • Part 3
• Bluetooth LE wiki
• Argenox
  • Introduction to Bluetooth Low Energy (BLE)
  • BLE Advertising Primer
  • Ultimate Guide To Debugging BLE Products 
  • Using BLE Devices With A Raspberry Pi
  • Starting Bluetooth With Arduino
• Microchip
  • Introduction to Bluetooth Low Energy
    • Bluetooth Low Energy Link Layer Overview
      • BLE Link Layer Roles and States
      • BLE Link Layer Security Features
      • Bluetooth Low Energy Packet Types
      • Bluetooth Low Energy Discovery Process
      • Bluetooth Low Energy Connection Process
    • Generic Access Profile (GAP) Overview
      • Bluetooth Low Energy GAP Roles
      • Bluetooth Low Energy Security Modes and Procedures
    • Generic Attribute Profile (GATT) Overview
• Nordic Semiconductor
  • Bluetooth low energy Advertising, a beginner's tutorial
• TI
  • SimpleLink Academy Bluetooth 5
  • CC2541 Bluetooth Low Energy and proprietary wireless MCU
    • Datasheet
    • Software Developers Guide
• Silicon Labs
  • Next Generation BLE Beacons
•  Digi-Key
  • A Basic Introduction to BLE 4.x Security
• Rtone IoT Security Blog
  • Deep Dive into Bluetooth LE Security 
  • BLE Series Part 1: A Brief Overview of Bluetooth Low Energy
  • BLE Series Part 2: A Closer Look at BLE Pairing
• Miscellaneous tools and projects
  • RPi Bluetooth LE
  • bluepy - a Bluetooth LE interface for Python
  • Bluetooth Low Energy (BLE) Tutorial for Arduino

Getting Started

On the Getting Started with ESP-IDF page, click on the ESP32-C3 chip image (see red highlighted chip below) to get to the ESP-IDF Programming Guide. You can also navigate directly to ESP-IDF Programming Guide: Get Started or any of the Reference links below to go to the appropriate sections.

Cables

For programming and monitoring, you will need a micro USB data and charging cable. The board will not show up as a /dev/ttyUSB* device if you use a charging-only cable.

For debugging, you will need a USB data and charging cable with female connectors that fit on the board pins. You can modify an existing cable by cutting it and soldering on female jumper ends:

For the Nordic sniffer dongle, a USB-A extension cable allows you to move it around to receive BLE signals better.

Since two ESP-C3-32S-Kits, a debug cable, and a dongle require 4 USB ports, you may need a USB hub.

ESP-IDF Installation

ESP-IDF Programming Guide: Get Started contains instructions for installing ESP-IDF on Windows, Linux, and Mac OS.

This page shows actual installation on a Linux Ubuntu 18.04 laptop. Existing Linux configurations may create conflicts that require additional steps not covered by the ESP-IDF documentation, for instance the installed Python version.

The Step X headings here are the steps listed in the ESP-IDF Programming Guide; the Reference links in each section refer to the relevant instructions in the guide.

Step 1. Install prerequisites (Linux)

Reference: Get Started: Linux Setup

Refer to the reference to see the Linux prerequisites. Install them before proceeding to step 1a.

1a. Dialout Group

You will need to be a member of the dialout group in order to access the serial port. Add your username with this command:

You will need to logout and back in to apply this (you may need to reboot your laptop to apply it).

Verify that the command has been applied with this command, and look for the dialout group (there may be many groups):

Example:

Step 2. Get ESP-IDF

Reference: Get ESP-IDF

Run the following commands to clone the ESP-IDF repo from Github (this includes a number of submodules):

All remaining steps take place in the esp-idf directory, so change to that:

2a. Python Version

Your Linux may be setup to use Python 2 as the default. The installation process needs Python 3. This requires two changes:

1. Define an alias for python. This is only required for performing installation.
2. Modify two lines in file tools/idf_tools.py, function action_install_python_env().

Define this alias:

Make these changes to tools/idf_tools.py:

Step 3. Set up the tools

Reference: Set up the tools

Run the following command to setup the tools for all supported targets:

Example (note the all done message at the end indicating ready to export environment variables):

If there are any problems with the installation, either during this step or subsequently, you can easily remove it, then repeat the install.sh script. To remove it:

ESP-IDF Development

Examples

ESP-IDF includes a number of examples in the examples directory, each with a README.md file.

The simplest one is get-started/hello_world. This boots, prints a "Hello world!" message and board information, then counts down for 10 seconds and resets, repeating this boot loop forever.

The remaining examples will use hello_world.

Step 4. Set up the environment variables

Reference: Set up the environment variables

Whenever you start a terminal session for building, you must set up the environment with the following command:

Example (note the done message at the end indicating ready to build a project):

Step 5. Start a Project

Reference: Start a Project

Create a project directory, using one of the examples as a starting point:

Example:

The file main/hello_world_main.c contains the app_main() function. Add your name and date to the "Hello world!" string as a sign of life for the toolchain, to prove that this is your build when you see it running on the board.

Step 6. Connect Your Device

Reference: Connect Your Device

Plug the board into your laptop via USB. Depending on the image in the flash, the white LED may go off shortly after power-on. The black chip adjacent to the USB jack is the CH340 reported in the lsusb output below. 

You can locate the board via the following commands:

Example:

The board is on /dev/ttyUSB0, owned by root, but in the dialout group to allow access.

Step 7. Configure

Reference: Configure

You need to set the target any time you start a build session or new project (it defaults to esp32, and needs to be esp32c3 for this board). You may need to run menuconfig to set up project specific variables, e.g. Wi-Fi network name and password, the processor speed, etc. The hello_world example does not need it.

Example (note the done messages at the end indicating ready to build):

Step 8. Build the Project

Reference: Build the Project

Build the project by running:

Example (note the completion message at the end indicating ready to flash):

Step 9. Flash onto the Device

Reference: Flash onto the Device

Flash the binaries to the board, specifying the USB port device:

Example (note the done message at the end indicating ready to monitor):

Wrong Target

If you didn't set-target esp32c3 at the Configure step before building, it defaults to the plain esp32 target. This will cause the following error:

Go back to the Configure step and set-target esp32c3, then repeat the remaining steps to configure, build, and flash the board.

Step 10. Monitor

Reference: Monitor

Monitor the board serial output with the following, terminating the monitor by entering Ctrl-] (ESP-IDF Programming Guide: IDF Monitor lists all keyboad shortcuts):

Example (note the modified message "Hello world  sbranam Jul 30 2021!" before the "Restarting in X seconds..." lines, indicating toolchain proof of life):

This is the help menu accessed by Ctrl+T followed by Ctrl+H (not all functions are actually supported):

Debugging

Note that a debugger is not required for general development and operation. The board can be flashed and run via the Micro USB connection. This section describes interactive debugging on a board.

The ESP32-C3 chip includes a built-in USB-to-JTAG interface (diagram from Debugging the ESP32-C3 Device with JTAG):

This can be accesssed via OpenOCD to allow debugging via GDB. The ESP-IDF installation includes OpenOCD and ESP-specific board configuration files, as well as the cross-tool version of GDB, xtensa-esp32-elf-gdb:

The ESP-IDF idf.py tool includes commands to run OpenOCD, and to run GDB with an ELF image to be debugged, connecting to OpenOCD automatically (diagram from ESP-IDF API Guides: JTAG Debugging):

Debugger Connection

 Reference: Debugging the ESP32-C3 Device with JTAG

The board brings the USB-to-JTAG connection out to the breakout headers. Connect a USB cable with female connectors to the following pins:

The device does not report a name:

OpenOCD

Reference: idf.py debug targets

See OpenOCD General-Commands for command reference. You must be connected to OpenOCD via TCL (localhost port 6666), telnet (localhost port 4444), or GDB (localhost port 3333) to issue commands. Note that most direct OpenOCD commands are not needed when using the ESP-IDF idf.py tool.

Note that a hardware reset that occurs while OpenOCD is running causes it to error out.

In a separate terminal, start a sudo shell to allow access to the debugger connection. Setup the ESP-IDF environment variables, then start the  OpenOCD server with the board/esp32c3-builtin.cfg configuration file:

The idf.py command is equivalent to the following manual command:

Example (this also shows GDB connecting, resetting and halting the device, and disconnecting):

GDB

See Debugging with GDB for full GDB command reference. You can run OpenOCD commands in GDB by prefixing the command with the keyword "monitor" (abbreviated as "mon").

These examples show where I was testing the ESP-IDF NimBLE stack examples for peripheral and central devices, including customizations I made to test Secure Connection (SC) pairing with out of band (OOB) device association (see this blog series for information on pairing methods; register for and download this excellent free BLE Security Study Guide).

In the terminal where the application has been built and flashed to the device, run GDB:

This runs the cross-tool version of GDB, xtensa-esp32-elf-gdb, with the automatically-generated build/gdbinit file. The file sets the ELF file, connects to OpenOCD, resets and halts the device, sets a temporary hardware assisted breakpoint at app_main(), and continues to that point:

Example (this also shows that the source is more recent than the executing code, so may be out of synch):

You can switch back and forth between CLI (command line interface) and TUI (text user interface) mode using Ctrl-x a. Example TUI, at the above breakpoint at app_main():

You can use most normal GDB commands. For example set a breakpoint and continue to it, showing source and backtrace (in this case, at a debug function ble_sm_dbg_set_sc_oob() I added):

You can get info for all threads, and backtrace for all threads:

Managing Breakpoints

Pausing a multi-threaded embedded device at software breakpoints to examine data and step through instructions can be problematic, because timers may continue running and expire, and other interrupts may occur. This may result in unexpected execution when you continue, as the device vectors off to other code.

Anything leading up to a software breakpoint that occurs after soft reset can be trusted, so examining backtraces and existing data at that point is similar to examining a coredump. However, continuing from that point may not be reliable.

There are two useful strategies for making progress when using breakpoints:

• If using a software breakpoint (the GDB "b" and "tb" commands), clear the breakpoint if it wasn't temporary, set a new one further along the execution path, and soft reset the device with the "mon reset halt" command. This allows you to gather incremental information one reset at a time.
• Use hardware breakpoints (the GDB "hb" and "thb" commands). These should hold all activity within the processor so that it can continue safely. However, external activity may still cause unexpected results.

Simultaneous Monitoring And Debugging

You can monitor the device via the Micro USB connection and debug it via the USB-to-JTAG connection at the same time, with both cables connected. However, because starting the monitor causes a hardware reset that would cause OpenOCD to error out, you need to do operations in a specific order:

1. Start the monitor with the idf.py -p monitor command. This will reset the device and begin executing.
2. Start OpenOCD with the OPENOCD_COMMANDS="-f board/esp32c3-builtin.cfg" idf.py openocd command.
3. Start GDB with the idf.py gdb command. This will soft reset the device and break at app_main(). The monitor output will show partial normal startup activity.

Once you continue execution from this point, if you need to reset the device, use the GDB mon reset halt command. This maintains all OpenOCD, GDB, and monitor operation so you can continue debugging without having to restart everything.

Debugging Strategy

In general, a mix of GDB breakpoints and prints that are reported on the monitor terminal form an effective strategy for debugging and testing. Stopping at breakpoints allows you to dig around in the internals of the code, while prints allow you to log real-time activity without significantly disrupting it.

Excessive logging can interfere with the timing characteristics of real-time code. Just as it's useful to reset after halting at a breakpoint and collecting information, it may be necessary to change the logging and rebuild after collecting information in a test run. Then each successive run allows you to log and collect incremental information, one step at a time.

Eventually you have enough information to strip the logging back down to a minimum and allow the code to run without breakpoints.

Wireshark Sniffing

This section assumes you've downloaded and setup the Nordic sniffer package and User Manual, and the nRF Connect For Mobile application.

In a terminal, run Wireshark via sudo to allow access to the serial port containing the dongle:

Follow the instructions in User Manual chapter 3 "Running nRF Sniffer" and 4 "nRF Sniffer usage" to run the sniffer in Wireshark.'

The sniffer works in two modes:

Default is to listen on all advertising channels, when "Device" is set to "All advertising devices". This only captures advertising-related packets, for all devices:

This is an example capture:

Filtering On Known Data

Capturing BLE data in "All advertising devices" mode is noisy if you have multiple devices in range. A simple way to isolate an advertiser you control is to configure it to send known data, then filter for that data in Wireshark.

In this example, the Nordic "nRF Connect for Mobile" app on a smartphone has been configured to advertise Service Data in the "Heart Rate" and "Health Thermometer" services: heart rate 0xDEAD and temperature 0xBEEF.

Enter the following In the Wireshark display filter box:

You can use this to view other fields, such as the source address (Advertising Address), matched up with the known data:

You can also create a display filter for a specific value automatically by right-clicking on the value in the packet decode. Click on "Apply as Filter" in the popup menu, then click on "Selected" in the submenu. This is an easy way to get the right field name and syntax for the filter.

Once you've identified a particular device of interest, select that device in the "Device" list.

Creating Filters From Captured Data

Wireshark filters can be difficult to form if you don't know the field names or syntax. You can create them from actual captured data. This greatly simplifies using filters, since it shows the field name and value syntax. Then you can modify the filter to look for other things; editing the field name will bring up a pop-up list of fields you can select from. The filter will also be recorded in the Wireshark filter history drop-down list, and you can copy and paste it to save it.

This example shows how to create a filter to display only connection indication packets, using an existing capture file.

Open the file in Wireshark. It will contain a number of advertising packets, and all items in the middle frame decode pane will be collapsed down:

Scroll down the upper packet summary pane to find the CONNECT_IND packet and click on it. This is the first non-advertisement in this capture. Click on the expansion triangle next to "Bluetooth Low Energy Link Layer" in the middle pane to expand that layer:

In the expansion, click on the expansion triangle next to "Packet Header" to expand that next layer:

Click on the expanded line showing PDU Type:

Right-click on the line to bring up the pop-up menu. Go to "Apply as Filter", then click on "Selected":

This will add the filter to the display filter box, and filter the packet summary pane to just the packets matching the selection criteria:

Using A Filter To Find Packets

You can find packets using the filter syntax. If you have a filter set in the display filter box (for instance, created from an actual packet as shown above), you can copy the filter for use in the find box.

Select the filter text in the display filter box and copy it. Click the X button on the right end of the box to clear the filter:

Scroll the upper pane up to some random packet so that you can see when the find command actually finds a packet. Hit Ctrl+F to bring up the find box, then paste the copied filter text into it and click the "Find" button:

The CONNECT_IND packet will now be selected:

Scroll down to see the interesting packets that show activity on the connection:

Note that all of the above shows unsecured connections. Once encryption has been enabled on a connection, Wireshark will be unable to decrypt the packets. It will report "Encrypted packet decrypted incorrectly (bad MIC)" on each packet.

For Legacy pairing with OOB association, you can enter the OOB key in the Wireshark "Passkey / OOB Key" text box to decrypt traffic, but for Secure Connection pairing with OOB association, there is no way to enter the required information.

Sign in