Connecting a device

Connecting a device

This walks through an ESP32 from an empty project to a device showing up in your list. You’ll need the API key from Getting started.

1. Create the project

Make a new PlatformIO project for your board and open platformio.ini:

[env:esp32dev]
platform  = espressif32
board     = esp32dev
framework = arduino
 
lib_deps =
    https://github.com/gregtriant/SocketClient.git
 
; The library needs C++14 or newer. Many ESP32 cores still default to
; gnu++11, which will not compile the config below.
build_unflags = -std=gnu++11
build_flags   = -std=gnu++17
⚠️

Don’t skip the build flags

If you leave them out you’ll get compiler errors on the config block that look unrelated to the library. Set them once and forget about them.

2. Write the firmware

This is a complete, working sketch. Replace the token with your own API key.

#include <SocketClient.h>
 
SocketClient sc;
 
SocketClientConfig_t config = {
    .name       = "MyDevice",              // shown on your dashboard
    .version    = 1.0,
    .type       = "ESP32",
    .ledPin     = -1,                      // status LED pin, -1 for none
    .host       = "api.sensordata.space",
    .port       = 443,
    .isSSL      = true,
    .token      = "paste-your-api-key-here",
    .handleWifi = true,                    // let the library manage WiFi
 
    // Called whenever the platform asks what your device is doing.
    // Every key you set here becomes an entity you can put on a dashboard.
    .sendStatus = [](JsonDoc doc) {
        doc["temperature"] = 21.5;
        doc["ledOn"]       = false;
    },
 
    // Called when a dashboard button or timer sends something.
    .receivedCommand = [](JsonDoc doc) {
        String cmd = doc["data"];
        if (cmd == "ledOn") {
            // turn something on
        }
    },
 
    .entityChanged = [](JsonDoc doc) { },
    .connected     = [](JsonDoc doc) { },
};
 
void setup() {
    Serial.begin(115200);
    sc.init(&config);
    sc.initWebserver(80);   // optional: WiFi settings and OTA upload pages
}
 
void loop() {
    sc.loop();              // must be called every loop
}

Two rules worth remembering:

  • sc.loop() must run on every pass of loop(). Long delay() calls will stall the connection.
  • Whatever you put into doc inside sendStatus is what the platform sees. Start with one or two values; you can add more later and they’ll appear automatically.

3. Flash it

Upload as usual, then open the serial monitor at 115200 baud so you can watch what happens next.

4. Put it on your WiFi

With handleWifi = true, a device that has no saved network starts its own hotspot:

  • Network name: {type}-{name} — for the sketch above, ESP32-MyDevice
  • Password: the last 10 characters of your API key

Connect a phone or laptop to that hotspot and open http://192.168.4.1. Pick your network, enter the password, and save. The device stores the credentials in flash and reconnects by itself after a reboot or a dropout — you only do this once per device.

💡

Nothing appears?

Check the network is 2.4 GHz, and that the hotspot password is the last 10 characters of the token, not the WiFi password.

5. Find it in your device list

Open Devices. Because your firmware carries a valid API key, the device registers itself against your account the first time it connects — there’s nothing to add by hand. It appears with the name from your config, its card highlighted while it’s online and greyed out when it isn’t.

Click the card to open its dashboard, or the gear button to rename it and change its settings.

Devices without a key

A device that connects without a valid API key can’t be attributed to anyone, so it shows up as a free device with a Claim button. Pressing Claim attaches it to your account. This is the fallback for firmware you don’t want to bake a key into — using a key is simpler and safer.

What next

Troubleshooting

SymptomLikely cause
Compiler errors on the config blockMissing build_flags = -std=gnu++17
Device never joins WiFi5 GHz network, or wrong hotspot password (last 10 chars of the token)
Connects then drops repeatedlysc.loop() isn’t being called often enough — look for delay()
Shows as free instead of yoursToken missing, mistyped, or the key was deleted
Online but the dashboard is emptysendStatus isn’t setting any keys yet