ESP-IDF Integration Guide

This guide walks through integrating the Hubble Network dual-stack Satellite and BLE application with Espressif’s IoT Development Framework (ESP-IDF).

By the end of this guide you will know how to:

• Integrate the Hubble Satellite and Terrestrial (BLE) network stacks into an ESP-IDF application.

• Obtain ephemeris data and use pass prediction to schedule satellite transmissions.

• Transmit data to the Hubble satellite network from an ESP32 device.

Supported Devices and SDK Version

The Hubble Device SDK currently supports ESP-IDF v6.0. If you require support for a different version, contact us.

SoC	Notes
ESP32-C6	RISC-V, 20 dBm integrated PA

Prerequisites

Before starting, ensure you have the following:

• A supported development kit or custom board with a PA or FEM capable of at least +20 dBm transmit output power. The Hubble satellite link budget requires this minimum output to reach the network reliably.

• An antenna tuned to the Hubble satellite frequency band, connected to the RF output of the PA or FEM.

• A Hubble account and API key to fetch ephemeris data for pass prediction.

• ADALM-PLUTO SDR (optional, recommended for custom board bring-up): used to verify RF output at the physical layer. Available from common distributors such as DigiKey and Mouser. See the ADALM-PLUTO product page for details.

Create your Hubble Account

A Hubble account is required to access the Hubble Dashboard and generate an API key for fetching ephemeris data used in pass prediction.

1. Create an account at the Hubble Dashboard.

2. Once logged in, follow the Hubble Platform API documentation to authenticate and generate your API key.

Keep your API key accessible. It is used later in this guide when fetching orbital parameters for pass prediction.

SDK Setup

Install ESP-IDF

Follow the ESP-IDF Getting Started guide to install ESP-IDF v6.0 and all required dependencies. Once installed, source the export script to set up the environment:

. $IDF_PATH/export.sh

Clone the Hubble Device SDK

Clone the SDK alongside your application:

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

Add the Hubble Port as an ESP-IDF Component

Register the ESP-IDF port as a component by setting EXTRA_COMPONENT_DIRS in your application’s CMakeLists.txt:

set(EXTRA_COMPONENT_DIRS /path/to/hubble-device-sdk/port/esp-idf/)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(your-app LANGUAGES C)

See samples/esp-idf/sat-dual-stack/CMakeLists.txt for a complete reference.

Fetch the Satellite PHY Blob (ESP32-C6)

Important

The Satellite Network module requires a PHY library blob from Espressif that is currently in Early Access (EA). The libphy shipped with ESP-IDF does not include this API yet and must be swapped in manually before building.

1. Download the Espressif PHY blob:

   libphy_C6_20260317_c83212e.zip

2. Unzip and copy the extracted *.a files into your ESP-IDF installation:

   unzip "libphy_C6_20260317_c83212e.zip"
   cp *.a $IDF_PATH/components/esp_phy/lib/esp32c6/
   

This step is temporary. Once Espressif ships the API upstream, the blob swap will no longer be needed.

Project Configuration

sdkconfig.defaults

Enable the Hubble dual-stack by adding the following to your sdkconfig.defaults:

# Hubble Network
CONFIG_HUBBLE_BLE_NETWORK=y
CONFIG_HUBBLE_SAT_NETWORK=y

# Set to your oscillator's PPM rating (check your crystal datasheet)
CONFIG_HUBBLE_SAT_NETWORK_DEVICE_TDR=10

CONFIG_HUBBLE_SAT_NETWORK_DEVICE_TDR sets the clock drift rate in parts per million (PPM). See Clock Drift Compensation for details.

For the full set of available options, see Configuration Options.

Other common options for a dual-stack application:

# Bluetooth
CONFIG_BT_ENABLED=y
CONFIG_BT_NIMBLE_ENABLED=y

# Hubble uses legacy advertising, not extended advertising
CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT=n

# Optional: enable logging
CONFIG_LOG_VERSION_2=y

Register Application Components

In your main/CMakeLists.txt, declare the required component dependencies:

idf_component_register(SRCS ${YOUR_APP_SOURCES}
                       PRIV_REQUIRES bt nvs_flash esp_timer hubblenetwork-sdk
                       INCLUDE_DIRS ".")

bt and hubblenetwork-sdk are required for the dual-stack. nvs_flash is required by NimBLE. esp_timer is used in the reference sample for pass scheduling, however, any timer peripheral works.

Preparing for Satellite Transmission

The satellite stack requires three inputs before it can schedule and transmit:

• Unix time: used for pass prediction and key derivation

• Device location: latitude and longitude, used to compute satellite passes

• Orbital parameters: satellite ephemeris data describing each satellite’s orbit

How these are provisioned is up to the application.

Time

Many approaches work: BLE provisioning from a phone, NTP over Wi-Fi, GPS, an RTC, or reading from persistent storage across reboots. See Time Management for best practices and trade-offs.

Location

If the device is deployed at a fixed location, latitude and longitude can be hard-coded directly in firmware:

struct hubble_sat_device_pos device_pos = {
    .lat = 47.6,
    .lon = -122.3,
};

For mobile devices, location can be obtained from an onboard GPS module if present, or provisioned at runtime from a companion app. For example, delivered over BLE from a phone/gateway that has GPS access.

Orbital Parameters

Orbital parameters describe each satellite’s orbit and are used by hubble_sat_next_pass_get() to predict when a satellite will be visible from the device location.

Since Hubble satellites are station-keeping, orbital parameters are stable enough to be baked into firmware at build time. Use the tools/orbital_params_fetch.py helper to fetch current parameters from the Hubble API and generate a sat_params.c file ready to compile into your application:

export HUBBLE_API_TOKEN=<your-api-token>
python tools/orbital_params_fetch.py path/to/output

See Orbital Parameters (Satellites information) for details on the generated format and how to register the array with the SDK.

Initializing the Hubble Device SDK

Once time, location, and orbital parameters are available, initialize the SDK before calling any other Hubble API:

/*
 * At this point unix_time_ms, device_pos, and orb_params are assumed to be
 * valid. Either baked into firmware or received via BLE provisioning.
 */
err = hubble_init(unix_time_ms, master_key);
if (err != 0) {
    LOG_ERR("Failed to initialize Hubble Device SDK (err %d)", err);
    return err;
}

err = hubble_sat_satellites_set(orb_params, orb_params_count);
if (err != 0) {
    LOG_ERR("Failed to set orbital parameters (err %d)", err);
    return err;
}

hubble_init() takes the current Unix time in milliseconds and a pointer to the master key. hubble_sat_satellites_set() registers the orbital parameters array with the SDK.

Warning

• The key buffer MUST remain valid for the lifetime of SDK usage. The SDK stores the pointer directly and does not copy the key. Do not use a stack or temporary buffer.

• Unix time must be non-zero. Passing 0 in CONFIG_HUBBLE_COUNTER_SOURCE_UNIX_TIME mode returns an error.

• The orbital parameters array MUST remain valid for as long as pass prediction is used. The SDK stores a pointer and does not copy the array.

On ESP-IDF, nvs_flash_init() must be called before initializing the NimBLE stack and registering GATT characteristics and services:

/* NVS flash init, dependency of NimBLE stack */
ret = nvs_flash_init();
if (ret == ESP_ERR_NVS_NO_FREE_PAGES ||
    ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
    ESP_ERROR_CHECK(nvs_flash_erase());
    ret = nvs_flash_init();
}
ESP_ERROR_CHECK(ret);

ret = nimble_port_init();
if (ret != ESP_OK) {
    ESP_LOGE(BLE_TAG, "Failed to init NimBLE (rc=%d)", ret);
    return ret;
}

/*
 * Call your BLE setup function here. For example:
 * Register GATT services, configs, callbacks, NimBLE host task, etc.
 */

The Pass Prediction Loop

With the SDK initialized, the application enters the main dual-stack loop: compute the next satellite pass, beacon over BLE while waiting, stop BLE, transmit to the satellite, then repeat.

Compute the Next Pass

for (;;) {
    now_ms = hubble_time_get();

    err = hubble_sat_next_pass_get(now_ms, &device_pos, &pass_info);
    if (err != 0) {
        LOG_ERR("Failed to get next pass (err %d)", err);
        return err;
    }

    /* If the pass has already started, find the next one. */
    if (pass_info.start <= now_ms) {
        err = hubble_sat_next_pass_get(
            pass_info.start + pass_info.duration,
            &device_pos, &pass_info);
        if (err != 0) {
            LOG_ERR("Failed to get next pass (err %d)", err);
            return err;
        }
    }

hubble_sat_next_pass_get() returns the soonest pass visible from the device location. If pass_info.start is already in the past, a pass is in progress, skip it and compute the next one by searching from after its end (pass_info.start + pass_info.duration).

Beacon over BLE While Waiting

Schedule a one-shot timer for the pass window and start BLE advertising while the device waits. The example below uses esp_timer; any timer peripheral that can schedule a future callback works equally well.

sat_wait_us = (pass_info.start - now_ms) * US_PER_MS;
esp_timer_start_once(_sat_timer, sat_wait_us);

/*
 * Get the Hubble beacon payload using hubble_ble_advertise_get()
 * and start BLE advertising with ble_gap_adv_start().
 */
ble_adv_start();

/*
 * Block and wait until the pass timer fires. Common approaches are
 * a semaphore, task notification, or event flag.
 */
block_until_timer_expires();

The timer callback signals the waiting task when the pass window is overhead.

Transmit to the Satellite

Stop advertising, then build and send the packet:

    /* Stop advertising to release the radio. */
    ble_gap_adv_stop();

    err = hubble_sat_packet_get(&packet, NULL, 0);
    if (err != 0) {
        ESP_LOGE(APP_TAG, "Failed to build packet (err %d)", err);
        return;
    }

    /* Blocking call. Retries are handled internally by the SDK */
    err = hubble_sat_packet_send(&packet, HUBBLE_SAT_RELIABILITY_NORMAL);
    if (err != 0) {
        ESP_LOGE(APP_TAG, "Failed to send packet (err %d)", err);
        return;
    }
} /* end while loop, back to compute the next pass, re-enable bluetooth, and beacon */

hubble_sat_packet_send() is blocking. It returns only after the full transmission sequence completes, including all retries. See Reliability and Power Consumption for guidance on reliability modes and their effect on power consumption.

Building and Flashing

Set the target, build, flash, and open the serial monitor:

idf.py set-target esp32c6
idf.py build flash monitor

Verifying the Application

Expected Log Output

Enable logging by adding the following to your sdkconfig.defaults:

CONFIG_LOG_VERSION_2=y

After a successful hubble_init() call, the SDK logs:

I (xxx) hubblenetwork: Hubble Device SDK initialized (HDCV:1.0/E:256/CS:UT/RP:S86400/N:TS/TV:0/SV:0)

Note

If using ESP-IDF Log v1 (CONFIG_LOG_VERSION_1=y), the log level prefix and timestamp are omitted and only the plain message appears, e.g.:

Hubble Device SDK initialized (HDCV:1.0/E:256/CS:UT/RP:S86400/N:TS/TV:0/SV:0)

At debug level, once pass prediction runs and a transmission is scheduled:

D (xxx) hubblenetwork: Time drift since last sync: 20000 ms
D (xxx) hubblenetwork: Number of additional retries due TDR: 1
D (xxx) hubblenetwork: Number of retries: 9 - interval: 20 seconds

After hubble_sat_packet_send() completes:

I (xxx) hubblenetwork: Hubble Satellite packet sent

If this line appears without any preceding error from the hubblenetwork tag, the device has successfully transmitted to the satellite network.

Verify BLE

Use the SDK’s scan script to confirm BLE advertising is working:

pip install -r tools/requirements-scan.txt
python tools/scan.py --key "<your-device-key>"

Verify Satellite RF

To verify the satellite RF output before a live pass, use an ADALM-PLUTO SDR and the pyhubblenetwork scan tool. See the RF Verification with an SDR section in Next Steps below for full instructions.

Troubleshooting

hubble_init returns an error

Symptom: <wrn> hubblenetwork: Failed to set Unix Epoch time

Cause: unix_time_ms passed to hubble_init() is 0. The SDK requires a valid non-zero Unix timestamp.

Fix: Ensure time is provisioned (over BLE, NTP, GPS, or RTC) before calling hubble_init(). See the Preparing for Satellite Transmission section in this guide.

—

Symptom: <wrn> hubblenetwork: Failed to set key

Cause: The key buffer is NULL, zero-length, or the wrong size for the configured key type.

Fix: Verify the key is correctly decoded and its length matches the configured key size.

Pass prediction returns an error

Symptom: <wrn> hubblenetwork: Hubble Satellite next pass get: no satellites configured

Cause: hubble_sat_satellites_set() was not called before hubble_sat_next_pass_get().

Fix: Call hubble_sat_satellites_set() with a valid orbital parameters array immediately after hubble_init().

—

Symptom: <wrn> hubblenetwork: Hubble Satellite next pass get: no pass found

Cause: No satellite pass is visible from the given location within the search window. Most commonly caused by incorrect device coordinates or a stale Unix timestamp.

Fix: Verify that device_pos.lat and device_pos.lon are correct and that unix_time_ms reflects current wall-clock time.

—

Symptom: Firmware appears to hang or stall inside hubble_sat_next_pass_get().

Cause: The pass prediction algorithm iterates forward orbit-by-orbit until it finds a pass. If the input time is near zero (e.g. Unix time was passed in seconds instead of milliseconds), or if device_pos.lat and device_pos.lon are invalid, the loop can spin through thousands of orbits before returning.

Fix: Confirm unix_time_ms is in milliseconds and that device_pos.lat and device_pos.lon hold the actual device coordinates.

Build fails with missing PHY symbols

Symptom: Linker error referencing undefined symbols.

Cause: The EA PHY blob was not swapped into the ESP-IDF installation.

Fix: Follow the Fetch the Satellite PHY Blob (ESP32-C6) steps in the SDK Setup section.

NimBLE fails to initialize

Symptom: nimble_port_init() returns an error.

Cause: nvs_flash_init() was not called before initializing the NimBLE stack.

Fix: Ensure nvs_flash_init() is called before nimble_port_init().

Next Steps

RF Verification with an SDR

Before waiting for a live satellite pass, you can verify that your device is transmitting a valid Hubble packet at the physical layer using an ADALM-PLUTO product page and the pyhubblenetwork Python library.

Install the library:

pip install pyhubblenetwork

Connect the ADALM-PLUTO near the device antenna and run the scanner with your device key to decode captured packets in real time:

hubblenetwork sat scan --key "<your-device-key>"

A successfully decoded packet confirms the RF output, packet framing, channel hopping sequence, and PA/FEM sequencing are all correct. For the full list of available commands, run:

hubblenetwork --help

See the pyhubblenetwork repository for detailed usage and setup instructions.

Viewing Upcoming Passes

Use the Hubble Pass Explorer to see when the next satellite pass is predicted for your location. This is useful to cross-check pass prediction results from the device and to plan test windows.

Dashboard Verification

Once a live satellite pass has occurred and hubble_sat_packet_send() returned without error, after the downlink data is successful, log into the Hubble Dashboard Devices Page to confirm the packet was received by the network. A packet appearing on the dashboard is end-to-end proof that the device is operational on the Hubble satellite network.

Further Reading

• Satellite Network Overview: satellite protocol details, reliability modes, and power trade-offs.

• Configuration Options: full configuration reference for all CONFIG_HUBBLE_* options.

• Time Management: time management best practices for devices with and without a real-time clock.

• Espressif’s IoT Development Framework: ESP-IDF documentation, examples, and API reference.