Connecting Your First ESP32 to the Hubble Network

The Hubble Network delivers device data to the cloud by leveraging over 90 million terrestrial gateways. These gateways pick up standard Bluetooth LE advertisements and forward them to the Hubble backend, creating a global infrastructure for IoT connectivity. While many platforms require specialized hardware or cellular contracts, Hubble works with off-the-shelf silicon like the Espressif ESP32-C6. This guide demonstrates how to make the ESP32-C6 DevKitC an energy-efficient beacon that transmits encrypted sensor data to the Hubble Network.

Prepare the Development Environment

You need a few tools to begin developing with the Hubble SDK on the ESP32-C6.

1. Download and install ESP-IDF.
2. Create a Hubble developer account at dash.hubble.com.
3. Clone the Hubble Device SDK from GitHub.

The SDK includes an integration layer specifically for the ESP-IDF. This layer handles the underlying Bluetooth LE stack interactions while providing a simple API for generating Hubble-compatible packets.

Register Your Device

The Hubble Network relies on AES-256 encryption to secure data and verify device identity. Each hardware unit requires a unique key to broadcast. Before registering a device, generate an API token within your developer account to enable communication with the platform. Save both the Key and Org ID for the following steps.

Next, navigate to the Register New Devices section of the dashboard. Locate the Request side panel and enter your API key into the Bearer Token field and your Org ID into the org_id field. Click Send API Request, and then you should see your unique device ID in the Response side panel.

You just successfully registered your device. The Response panel contains some useful information about your new Hubble device, but the most important piece is your key. The application uses it during initialization to derive ephemeral IDs and sign outgoing packets. Save it onto your PC so it can be baked into your firmware during the build process.

Build the Beacon Sample

To turn your ESP32-C6 into a beacon, you need it to run custom firmware that uses the Hubble API to communicate with the Hubble Network. Luckily, the Hubble SDK includes a sample beacon application that does all of this for you. All you need to do is to provision, build, and flash the application onto your board.

// Excerpt of the sample beacon main function
void app_main(void)
{
	esp_err_t ret;
	esp_timer_handle_t adv_timer;

	ret = hubble_init(unix_time, master_key);
	if (ret != 0) {
		ESP_LOGE(DEMO_TAG, "Failed to initialize Hubble BLE Network");
		return;
	}

	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);
	ESP_ERROR_CHECK(esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT));

	esp_bt_controller_config_t bt_cfg = BT_CONTROLLER_INIT_CONFIG_DEFAULT();
	ret = esp_bt_controller_init(&bt_cfg);
	if (ret) {
		ESP_LOGE(DEMO_TAG, "%s initialize controller failed: %s",
			 __func__, esp_err_to_name(ret));
		return;
	}

	ret = esp_bt_controller_enable(ESP_BT_MODE_BLE);
	if (ret) {
		ESP_LOGE(DEMO_TAG, "%s enable controller failed: %s", __func__,
			 esp_err_to_name(ret));
		return;
	}

	esp_bluedroid_config_t cfg = BT_BLUEDROID_INIT_CONFIG_DEFAULT();
	ret = esp_bluedroid_init_with_cfg(&cfg);
	if (ret) {
		ESP_LOGE(DEMO_TAG, "%s init bluetooth failed: %s", __func__,
			 esp_err_to_name(ret));
		return;
	}

	ret = esp_bluedroid_enable();
	if (ret) {
		ESP_LOGE(DEMO_TAG, "%s enable bluetooth failed: %s", __func__,
			 esp_err_to_name(ret));
		return;
	}
}

Provisioning

The provisioning process embeds your device’s unique key (that you generated in the previous section) and the current Unix time into the firmware. This allows the Hubble Network to successfully authenticate your device and allow it to communicate with your Hubble dashboard.

Before you begin, save your device key in plain text in a file named master.key. Next, move it to the root of your sample application folder. In this same location, run the embed_key_time.py script with the following command:

<SDK_ROOT>/tools/embed_key_time.py master.key -o main/

Now you have successfully provisioned your firmware.

Building and Running

Next, build your firmware in ESP-IDF. You can choose to use the GUI or the command-line. Either way, be sure to set the target device to esp32c6 before you begin the build process. After you successfully build your firmware, flash your board.

If you completed your flash with no errors, congratulations! You just turned your ESP32-C6 into a Hubble beacon.

Verify Communication with Hubble Cloud

Once your ESP32-C6 begins broadcasting, you need to verify that the packets reach the Hubble Cloud. If you have Sandbox access, the production terrestrial network will track your device’s activity but will not deliver the raw data to the dashboard.

Use the Hubble Connect mobile app to act as a local gateway during development.

1. Download the Hubble Connect app on your smartphone.
2. Log in with your developer credentials.
3. Place your ESP32-C6 near the phone.
4. The app will detect the advertisements and forward them to the cloud.

Open the web dashboard to see the incoming packets. You will see the timestamp of the receipt, the approximate location, and the signal strength (RSSI).

Optimize for Production

With your ESP32-C6 broadcasting, you can move toward full automation. For example, you can use the Platform API to programmatically fetch decrypted packets from the Hubble Cloud. You can also refine your edge logic by optimizing power states or expanding the 13-byte payload to include more complex telemetry. Building these data retrieval pipelines will transform your beacon into a functional component of Hubble’s global IoT network.

Ready to connect your devices anywhere on Earth? Get started with Hubble Network for free →