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++17Don’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 ofloop(). Longdelay()calls will stall the connection.- Whatever you put into
docinsidesendStatusis 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
- Entities — what those
sendStatuskeys become - Creating your first dashboard — display them
Troubleshooting
| Symptom | Likely cause |
|---|---|
Compiler errors on the config block | Missing build_flags = -std=gnu++17 |
| Device never joins WiFi | 5 GHz network, or wrong hotspot password (last 10 chars of the token) |
| Connects then drops repeatedly | sc.loop() isn’t being called often enough — look for delay() |
| Shows as free instead of yours | Token missing, mistyped, or the key was deleted |
| Online but the dashboard is empty | sendStatus isn’t setting any keys yet |