Husarnet component for ESP-IDF
Migration process from the legacy codebase has been completed 🎉 - the Husarnet library for ESP32 is now available as a proper standalone ESP-IDF component.
The Husarnet embedded library is available for all Espressif Wi-Fi microcontrollers. It allows for a tunneled (simmilar to a classic VPN) or a peer-to-peer connection between your ESP32 devices and other hosts running Husarnet.
Currently, the Husarnet library for ESP32 is shipped as a standalone ESP-IDF component. You can download it from managed ESP Registry service or clone the component directly from GitHub.
It can be used with a standard ESP-IDF framework or Arduino as a component projects. Alpha support for the PlatformIO IDE is also available with the Arduino as a component configuration, for more information visit the Husarnet PlatformIO guide.
Due to Arduino Core for ESP32 limitations related to the default menuconfig entries, the library is currently not available for Arduino IDE or standard Arduino ESP32 PlatformIO projects. We are working on making it possible, though.
Quickstart
ESP-IDF
Install the ESP-IDF framework following the official guide first! Remember to source the ESP-IDF environment variables before running the idf.py commands.
Currently ESP-IDF versions v4.4+ or v5.0+ are supported. Simple webserver example can be set up in a few steps:
Create a new project using idf.py tool:
idf.py create-project-from-example "husarnet/esp_husarnet:husarnet-web-server"
Select your target microcontroller (eg. ESP32-S3):
idf.py set-target esp32s3
Edit the main/husarnet_web_server.c file and replace the join_code and hostname with your own Husarnet join code and hostname obtained from the Husarnet Dashboard:
#define HOSTNAME "husarnet-esp32"
#define JOIN_CODE "fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXX"
Provide your Wi-Fi credentials by running:
idf.py menuconfig
Put your Wi-Fi SSID and Wi-Fi password in the Example Connection Configuration section.
Finally, build and flash the project:
idf.py build && idf.py flash
After a few seconds your first HTTP webserver on ESP32 should be available on every device in your Husarnet network under the provided hostname URL: http://husarnet-esp32.
URL used above won't work on Chrome and Chromium-based browsers as they ignore the hosts file. Husarnet uses it to allow resolution of device names to Husarnet IPv6 addresses. You will need to type the IPv6 address enclosed with square brackets directly in the browser (eg. http://[fc94:b01d:1803:8dd8:b293:5c7d:7639:932a]).
Under Firefox everything should work ok.
API reference can be found here. In case of any issues, refer to the Husarnet ESP32 troubleshooting guide and the Husarnet Community Forum.
ESP-IDF - Arduino as a component
Install the ESP-IDF framework following the official guide first! Remember to source the ESP-IDF environment variables before running the idf.py commands.
To use Arduino libraries in your project and still have access to extended features of ESP-IDF, you can use the ESP-IDF framework in a Arduino as a component configuration. As stated by the Espressif documentation, this setup is recommended for advanced users and has some limitations.
As this setup requires a bit more manual work, we prepared a template project that you can use as a starting point.
Clone the repository and submodules (used for external Arduino libraries):
git clone --recurse-submodules https://github.com/husarnet/esp32-husarnet-cam
cd esp32-husarnet-cam
Set your Husarnet join code and Wi-Fi credentials in the main/main.cpp file.
#define HOSTNAME "husarnet-esp32-cam"
#define JOIN_CODE "XXXXXXXXXXXXXXXXXX"
#define WIFI_SSID "your_ssid"
#define WIFI_PASS "your_password"
Flash the project to your ESP32 device:
idf.py build && idf.py flash
Including Arduino libraries
Some Arduino libraries already have the CMakeLists.txt file provided in the root folder and can be included as a normal ESP-IDF component dependency. In case you want to include a library that does not have it, you need to create it manually. In this example this has been done with components/esp32cam library.
For more details, refer to the official documentation.
Configuration
Kconfig
Husarnet component
Husarnet component can be configured using the idf.py menuconfig tool. At the moment of writing this document it is possible to change logging verbosity (HUSARNET_LOG_LEVEL option) and adjust internal task priorities (HUSARNET_*_TASK_PRIORITY options).
Be careful when changing task priority values, as it may affect the stability of the Husarnet connection. Default values are tuned to work correctly with the default LwIP configuration.
Required Kconfig options
All the following options are set to the correct values in sdkconfig.defaults file provided in the official examples. This file is used to create actual sdkconfig during first configuration step. You don't need to worry about these options when starting from the example project.
It is required to enable the default weak LwIP IP6 Route Hook (CONFIG_LWIP_HOOK_IP6_ROUTE_DEFAULT) to allow Husarnet stack to process IPv6 packets destined to the Husarnet network (fc94::/16).
protocol_example_common utilities used in examples to simplify WiFi and Ethernet connection add various event listeners including on_got_ip. Unfortunately, the current implementation assumes that every network interface uses ESP-NETIF abstraction layer. Adding Husarnet interface during initialization will cause an undefined behaviour resulting in a core panic as it uses only the LwIP layer. To avoid this, disable the CONFIG_EXAMPLE_CONNECT_IPV6 option.
Partition size
The Husarnet component requires a bit of additional flash memory to store the Husarnet configuration and the IPv6 address. Setting the main application partition size to at least 2MB is recommended.
It can be done by providing a custom partition table in the partitions.csv containing the following lines:
# Name, Type, SubType, Offset, Size, Flags
nvs, data, nvs, 0x9000, 0x6000,
phy_init, data, phy, 0xf000, 0x1000,
factory, app, factory, 0x10000, 2M,
Husarnet uses a NVS partition to store configuration data. This includes it's encryption keys, security tokens and the identity of the host itself. Erasing it will disconnect your device from the network. Our library will try to join the network automatically after the next reboot but it will not clear the old association from the dashboard, thus other devices may see multiple IPv6 addresses under the hostname of the device. In case you notice inconsistencies - go to app.husarnet.com and inspect your account for duplicates.