Skip to main content

Husarnet Library for ESP32

danger

At the moment ESP32 platform support is still using an outdated codebase. We've already started the migration process so it'll become a proper library, but it'll take time. We expect it to be available at the end of IV quarter of 2023.

The Husarnet embedded library is currently available only for ESP32 Wi-Fi microcontrollers. It allows a peer-to-peer connection of your ESP32 devices with other hosts running the Husarnet Client app.

Quickstart​

Prerequsities

Install Visual Studio Code and platformio extension first!

Let's run a simple webserver hosted on ESP32 that is based on AsyncTCP and ESPAsyncWebServer libraries. They are not required by Husarnet to work, but are faster than default ones provided in Arduino Core for ESP32.

Create a folder for your ESP32 project, eg. esp32-proj. Inside that folder create two files:

  • platformio.ini
  • src/simple-webserver.ino

with the following content:

#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <Husarnet.h>

// WiFi credentials
const char *ssid = "my-wifi-ssid";
const char *password = "my-wifi-pass";

// Husarnet credentials
const char *hostName = "esp32-webserver";
const char *husarnetJoinCode = "fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX";

// HTTP Server on port 8080
AsyncWebServer server(8080);

void setup(void)
{
  Serial.begin(115200);
  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.println("waiting for Wi-Fi...");
  }

  Husarnet.join(husarnetJoinCode, hostName);
  Husarnet.start();

  server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
    request->send(200, "text/plain", "Hello world!!!");
  });
  server.begin();
}

void loop(void){}

replace fc94:...:932a/XXX...XXXXX with your own Join Code and place your own Wi-Fi credentials in the *.ino file

Open the project folder using Visual Studio Code. Platformio extension should now automatically download and install locally all required tools and libraries needed to build and flash a firmware.

Click PlatformIO: Upload button in Visual Studio Code. After a few seconds your first HTTP webserver on ESP32 should be available from a level of any device from your Husarnet network under the following URL: http://esp32-webserver:8080.

a simple webserver hosted by ESP32

Reseting IPv6 addr

Husarnet IPv6 address of each ESP32 is stored in a flash. If you want to generate a new IPv6 address for you ESP32 run: pio run --target erase inside the project folder.

Husarnet Library API​

Husarnet on ESP32 (similar to no-embedded hosts) runs in the background and creates a virtual network interface on the Lwip layer. This is why there are only a few C++ methods:

Husarnet.h
#ifndef Husarnet_h
#define Husarnet_h

#include "Arduino.h"
#include "HusarnetServer.h"
#include "IPv6Address.h"
#include "WString.h"
#include <vector>
#include <utility>
#include <string>

struct _Husarnet
{
    // Sets up Husarnet to use self-hosted base server
    void selfHostedSetup(const char *hostname);

    // Starts the Husarnet
    void start();

    // Provides join code. Use before Husarnet.start().
    void join(const char *joinCode, const char *hostname = "");

    // Get list of peers' hostnames and addresses
    std::vector<std::pair<IPv6Address, String>> listPeers();

    // Get hostname you're currently known at
    String getHostname();
};

extern _Husarnet Husarnet;

#endif

For writing a UDP/TCP client or server code, use regular libraries for ESP32.

danger

The current version of Husarnet for ESP32 works with a forked version of Arduino Core for ESP32. There are some modifications related to IPv6 support.

Also to work with some networking libraries, like AsyncTCP, an IPv6 related customization is needed. If you need AsyncTCP in your project use our fork

A project template​

The Husarnet API for ESP32 is very short and self-describing, however to work in Husarnet you need to use a forked version of Arduino Core.

To make the environment configuration as straightforward as possible we recommend using Husarnet with PlatformIO.

The fastest way to start is making a new project based on this GitHub template.