ESP-IDF Library
note-espidf is the official ESP-IDF framework component
for communicating with the Notecard over serial or I2C.
In this article, you'll learn how to use note-espidf with an ESP32-based development board with Notecard
communication!
This library requires ESP-IDF version 5.5.1 or later.
It supports the following Espressif chips:
- ESP32
- ESP32-S2
- ESP32-S3
- ESP32-C3
- ESP32-C6
- ESP32-H2
Overview
This example is designed to illustrate the ease of using Notecard functionality
with an ESP32-based development board.
Functionally, the application reads Notecard's temperature with the card.temp
request and sends it to Notehub in a Note. It takes 25 readings, one every 15
seconds, and then stops.
This example is considered "advanced" as it uses FreeRTOS and the ESP-IDF framework,
which uses specific design considerations (RTOS, Mutexes, etc.).
This example walks through using the ESP-IDF with Visual Studio Code (VSCode) and the ESP-IDF extension. The ESP-IDF extension will download the prerequisites in order to use the ESP-IDF framework.
Use the Installation Guide from Espressif to get started with the ESP-IDF extension.
Requirements
Hardware
The example's default pin assignments match an Adafruit ESP32 Feather V2 seated on a Notecarrier F. If you use a different board, see Changing Transport to set your own pins.
Software
Cloud
- A free Notehub account
Getting Set Up
Notehub
Before you can utilize this example, you must set up a free account (no credit card required) on Notehub. Once you have created your account, then you need to create a project to serve as an endpoint for the Notes that contain the temperature readings. Copy the project's ProductUID, as you'll need it shortly.
The example puts Notecard in continuous mode, which keeps it connected to
Notehub at all times. continuous mode offers the lowest latency possible for
sending messages to Notehub, but it comes at the cost of battery life.
Fortunately, this is typically not a concern while bench testing.
To learn more about the Notecard modes and API, please visit our Essential Requests Walkthrough.
Downloading the Example Project
First, select an empty directory to create the example project and open it in VS Code. Now open the Command Palette and select ESP-IDF: Open ESP-IDF Terminal and press enter.
Use the following command to create the example project.
idf.py create-project-from-example "blues/notecard:basic_usage_i2c"This will create a new directory called basic_usage_i2c, pre-populated with the example code for the Notecard I2C example.
If you want to build the UART example instead, use basic_usage_uart instead of basic_usage_i2c.
To point the ESP-IDF extension at the example, you'll need to:
- Open the Command Palette and select Workspaces: Add Folder to Workspace.
- Select the
basic_usage_i2cfolder and press enter. - Tell the ESP-IDF extension that this is your target project. In the Command
Palette, select ESP-IDF: Pick Workspace Folder and select
basic_usage_i2cfrom the dropdown.
Once you've set your ProductUID (below), you can use the ESP-IDF extension to
build, flash, and monitor the project. Buttons to build, flash, and monitor the project are located in the bottom left corner of the VS Code window.
![]()
Setting Your ProductUID
The example reads your ProductUID from the project configuration, not from
main.c. In the ESP-IDF terminal, change into the basic_usage_i2c directory
and open the configuration tool:
idf.py menuconfigNavigate to Component config → Notecard Configuration, set Notehub product UID to your project's ProductUID, then save and exit.

Building and Running
Connect your ESP32 Feather's USB C port to your computer.
Using the following Command Palette option, you can build, flash, and monitor the project: ESP-IDF: Build, Flash, and Start a Monitor on Your Device.
Or, you can use the following Build, Flash, and Monitor button.
![]()
Check that the correct serial port is selected with the ESP-IDF: Select Port to Use command.
Once the firmware is running, the monitor logs a line such as
Sample 1 sent: temp=24.56°C for each reading. In Notehub, the device appears
with the serial number espidf-i2c-basic, and each reading arrives as an event
in the data.qo Notefile with a body like {"temp":24.56,"count":1}.
Building
To build the project, you can either use the following Command Palette option, ESP-IDF: Build Your Project.
Or, you can use the following Build button.
![]()
Flashing
To flash the project, you can either use the following Command Palette option, ESP-IDF: Flash Your Project.
Or, you can use the following Flash button.
![]()
Monitoring
To monitor the project, you can either use the following Command Palette option, ESP-IDF: Monitor Device.
Or, you can use the following Monitor button.
![]()
Changing Transport
To change the transport, you can modify the notecard_config_t config = NOTECARD_I2C_CONFIG_DEFAULT(); object in main.c.
If you want to use the Notecard's UART interface, you can modify the config object to use the NOTECARD_UART_CONFIG_DEFAULT() macro.
Additional Configurations
If you wish to adjust the I2C configuration, initialize config with the
NOTECARD_I2C_CONFIG_DEFAULT() macro and then override individual fields
before calling notecard_init().
// Configure Notecard for I2C communication using Kconfig defaults
notecard_config_t config = NOTECARD_I2C_CONFIG_DEFAULT();
// Or override the default options
config.i2c.port = 0;
config.i2c.sda_pin = 22;
config.i2c.scl_pin = 20;
config.i2c.frequency = 100000;
config.i2c.address = 0x17;
config.i2c.internal_pullup = false;The same can be done for the UART configuration, starting from the
NOTECARD_UART_CONFIG_DEFAULT() macro. Avoid UART port 0, which ESP-IDF uses
for the serial console by default.
// Configure Notecard for UART communication using Kconfig defaults
notecard_config_t config = NOTECARD_UART_CONFIG_DEFAULT();
// Or override the default options
config.uart.port = 1;
config.uart.tx_pin = 8;
config.uart.rx_pin = 7;
config.uart.baudrate = 9600;
config.uart.tx_buffer_size = 1024;
config.uart.rx_buffer_size = 1024;Alternatively, you can change the default options without editing code by running the menuconfig tool and navigating to Component config → Notecard Configuration.
idf.py menuconfigThese values become the defaults used by the macros above.