---
title: ESP-IDF Library
description: A guide for installing and using the Notecard ESP-IDF library, known as note-espidf.
source_url: https://dev.blues.io/tools-and-sdks/firmware-libraries/esp-idf-library/
canonical_url: https://dev.blues.io/tools-and-sdks/firmware-libraries/esp-idf-library/
markdown_url: https://dev.blues.io/tools-and-sdks/firmware-libraries/esp-idf-library.md
---

# ESP-IDF Library

[note-espidf](https://github.com/blues/note-espidf) is the official [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/index.html) 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](https://shop.blues.com/collections/notecard?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) communication! This library is designed to work with the ESP-IDF framework version 5.5 or later (previous versions may work, but are not tested). It supports the following Espressif chips:

- ESP32
- ESP32-S2
- ESP32-C3
- ESP32-S3
- ESP32-C2
- ESP32-C6
- ESP32-H2
- ESP32-P4
- ESP32-C5
- ESP32-C61

## 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 and voltage, using the `card.temp` and `card.voltage` requests, and sends a Note to Notehub with the data. 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](https://code.visualstudio.com/) (VSCode) and the [ESP-IDF extension](https://github.com/espressif/vscode-esp-idf-extension/blob/master/README.md). The ESP-IDF extension will download the pre-requisites in order to use the ESP-IDF framework.

Use the [Installation Guide](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/installation.html) from Espressif to get started with the ESP-IDF extension.

## Requirements

### Hardware

- [Blues Notecard](https://shop.blues.com/collections/notecard?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link)
- [Blues Notecarrier](https://shop.blues.com/collections/notecarrier?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link)
- [Adafruit ESP32 Feather V2](https://www.adafruit.com/product/5400)
- USB C cable

### Software

- [Visual Studio Code (VS Code)](https://code.visualstudio.com/Download)
- [ESP-IDF Extension](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/installation.html)

### Cloudware

- [Notehub.io](https://notehub.io)

## Getting Set Up

### Notehub.io

Before you can utilize this example, you must set up a free account (no credit card required) on [Notehub.io](https://notehub.io). Once you have created your account, then you need to [create a project](https://dev.blues.io/quickstart/notecard-quickstart/notecard-simulator.md#create-a-notehub-project) to serve as an endpoint for the Notes that are tracking the state of the LED.

Once you have a project, you will need to update the `define` named `PROJECT_UID` in `main.c` with [the UID of the project you have just created](https://dev.blues.io/notehub/notehub-walkthrough.md#finding-a-productuid).

After the Notecard has connected to Notehub, you can look inside the project and see a device named `espidf-i2c`. The Notecard will be running in `continuous` mode, which will allow it to maintain a constant cellular connection. `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](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#configuring-synchronization-modes).

### 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.

```plaintext
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 Command Palette and select **Workspaces: Add Folder to Workspace**.
2. From there, select the `basic_usage_i2c` folder and press enter.
3. Then, you'll need to tell the ESP-IDF that this is your target project.
4. In the Command Palette, select **ESP-IDF: Pick Workspace Folder** and select `basic_usage_i2c` from the dropdown.
5. Now 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](https://dev.blues.io/images/tools-and-sdks/esp-idf/extension-buttons.png?v=91fecb48)

## 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](https://dev.blues.io/images/tools-and-sdks/esp-idf/extension-buttons-all.png?v=78a59cd7)

> **Note:**
>
> Check that the correct serial port is selected with the **ESP-IDF: Select Port to Use** command.

### 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](https://dev.blues.io/images/tools-and-sdks/esp-idf/extension-buttons-build.png?v=8e787663)

### 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](https://dev.blues.io/images/tools-and-sdks/esp-idf/extension-buttons-flash.png?v=27270687)

### 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](https://dev.blues.io/images/tools-and-sdks/esp-idf/extension-buttons-monitor.png?v=e626ee1a)

## 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, you need to override the `NOTECARD_I2C_CONFIG_DEFAULT()` macro.

```c
// 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, by overriding the `NOTECARD_UART_CONFIG_DEFAULT()` macro.

```c
// Configure Notecard for UART communication using Kconfig defaults
notecard_config_t config = NOTECARD_UART_CONFIG_DEFAULT();

// Or override the default options
config.uart.port = 0;
config.uart.tx_pin = 21;
config.uart.rx_pin = 20;
config.uart.rts_pin = 23;
config.uart.cts_pin = 24;
config.uart.baudrate = 9600;
config.uart.tx_buffer_size = 1024;
config.uart.rx_buffer_size = 1024;
```

> **Note:**
>
> The default options are also configurable within the `Kconfig` file. Use the `make menuconfig` command to view and modify the default options.

Alternatively, you can modify the `Kconfig` file to change the default options.

```plaintext
idf.py menuconfig
```

This will open the menuconfig tool, where you can modify the default options.

![ESP-IDF menuconfig](https://dev.blues.io/images/tools-and-sdks/esp-idf/menuconfig.png?v=efe0d81c)

## Links

- [ESP-IDF](https://www.espressif.com/en/products/software/esp-idf)
- [GitHub: `note-espidf`](https://github.com/blues/note-espidf)