ESP-IDF

This guide explains how to integrate the Hubble Device SDK into an ESP-IDF project. The SDK ships as an ESP-IDF component, and can be added either from the ESP Component Registry or from a local copy of the repository.

See also

This page covers ESP-IDF SDK setup and component integration. For a complete, end-to-end satellite dual-stack application on ESP32 hardware — pass prediction, BLE beaconing, and RF verification — see the ESP-IDF Integration Guide.

Prerequisites

• ESP-IDF installed and exported in the current shell (e.g. source ~/esp/esp-idf/export.sh).

• A supported ESP32 target. The BLE Network module works on any ESP32 chip with a Bluetooth® Low Energy controller supported by ESP-IDF. The Satellite Network module currently targets the ESP32-C6 and ESP32-S31.

• Device key (generated when you register a new device to your organization through the Hubble Cloud API).

Adding Hubble Network to an ESP-IDF Project

Option 1: ESP Component Registry (recommended)

From the root of your project:

# change '^3.1.0' to your desired version of the SDK in the Registry
idf.py add-dependency "hubblenetwork/hubble-device-sdk^3.1.0"

This records the dependency in your project’s idf_component.yml and downloads the SDK into managed_components/ on the next build. ESP-IDF discovers components there automatically, so no EXTRA_COMPONENT_DIRS entry is needed in your CMakeLists.txt.

To declare the dependency by hand instead of running add-dependency, add it to main/idf_component.yml:

dependencies:
  hubblenetwork/hubble-device-sdk: ^3.1.0

Note

If your project narrows the build with set(COMPONENTS ...), add the SDK’s directory name under managed_components/ to that list as well because anything omitted from set(COMPONENTS ...) is excluded from the build.

Option 2: Local copy or Git submodule

Use this when building against an unreleased branch not listed in the Registry.

1. Add the Hubble Device SDK to your application, for example as a submodule:

   git submodule add https://github.com/HubbleNetwork/hubble-device-sdk
   

2. Point your top-level CMakeLists.txt at the SDK’s ESP-IDF component directory using EXTRA_COMPONENT_DIRS, and add hubblenetwork-sdk to the component list:

   cmake_minimum_required(VERSION 3.13.1)
   
   set(EXTRA_COMPONENT_DIRS path/to/hubble-device-sdk/port/esp-idf/)
   
   set(COMPONENTS
           "main"
           "bt"
           "hubblenetwork-sdk"
   )
   
   include($ENV{IDF_PATH}/tools/cmake/project.cmake)
   
   project(my-app LANGUAGES C)
   

Enabling Hubble Modules

This applies to both options above. Either run idf.py menuconfig and toggle the modules under Component config → Hubble, or set them in your project’s sdkconfig.defaults:

# Terrestrial (BLE) Network
CONFIG_HUBBLE_BLE_NETWORK=y

# Satellite Network
CONFIG_HUBBLE_SAT_NETWORK=y

When enabling the BLE Network module on ESP32 chips, you will also want the standard BLE controller bits:

CONFIG_BT_ENABLED=y
CONFIG_BT_BLE_50_FEATURES_SUPPORTED=n
CONFIG_BT_BLE_42_FEATURES_SUPPORTED=y

Satellite Network: Required PHY Blob

Depending on the SoC and ESP-IDF version, the shipped libphy may not include the PHY API required by the Satellite Network module. In that case, swap in the Early Access (EA) blob from Espressif before building any Satellite Network application:

SoC	PHY blob	Required for version	IDF_TARGET
ESP32-C6	libphy_C6_20260317_c83212e.zip	ESP-IDF < v6.1	esp32c6
ESP32-S31	libphy_S31_20260728_e963440.zip	All ESP-IDF	esp32s31

1. Download the PHY blob for your SoC from the table above.

2. Unzip the archive and copy the extracted *.a files over the matching files in your ESP-IDF installation, replacing <IDF_TARGET> with your target:

   unzip "<blob>.zip"
   cp *.a $IDF_PATH/components/esp_phy/lib/<IDF_TARGET>/