Help Shape What We Build Next: Take the 2026 Blues Developer Survey

Blues Developers
What’s New
Resources
API Reference
Notecard and Notehub API documentation
Blog
Technical articles for developers
Connected Product Guidebook
In-depth guides for connected product development
Developer Certification
Get certified on wireless connectivity with Blues
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Webinars
Listing of Blues technical webinars
Blues.comNotehub
Shop
Docs
Help
Support DocsNotehub StatusSecurity AdvisoriesVisit our Forum
Sign In
Docs Home
What’s New
Resources
API Reference
Notecard and Notehub API documentation
Blog
Technical articles for developers
Connected Product Guidebook
In-depth guides for connected product development
Developer Certification
Get certified on wireless connectivity with Blues
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Webinars
Listing of Blues technical webinars
Blues.comNotehub
Shop
Docs
Tools & SDKs
Notecard CLI
Firmware Libraries
Arduino Library
C Library
ESP-IDF Library
OverviewRequirementsGetting Set UpBuilding and RunningChanging Transport
Go Library
Python Library
Zephyr Library
Notehub SDKs
Notehub JS Library
Notehub Py Library
Notehub API Postman Collection
Generative AI Tools
Blues Expert MCP
Notehub MCP
homechevron_rightDocschevron_rightTools & SDKschevron_rightFirmware Librarieschevron_rightESP-IDF Library

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

  • Blues Notecard
  • Blues Notecarrier F
  • Adafruit ESP32 Feather V2
  • USB C cable

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

  • Visual Studio Code (VS Code)
  • ESP-IDF Extension

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.

note

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:

  1. Open the Command Palette and select Workspaces: Add Folder to Workspace.
  2. Select the basic_usage_i2c folder and press enter.
  3. 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_i2c from 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.

ESP-IDF extension buttons

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 menuconfig

Navigate to Component config → Notecard Configuration, set Notehub product UID to your project's ProductUID, then save and exit.

ESP-IDF menuconfig

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.

ESP-IDF extension build

note

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.

ESP-IDF extension build

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.

ESP-IDF extension flash

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.

ESP-IDF extension monitor

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 menuconfig

These values become the defaults used by the macros above.

Links

  • ESP-IDF
  • GitHub: note-espidf
Can we improve this page? Send us feedback
© 2026 Blues Inc.
© 2026 Blues Inc.
AboutDocsAPI ReferenceTermsPrivacy