ESP32 quickstart - PumpLink

This guide walks you through connecting an ESP32 to PumpLink. By the end, your device will appear in the dashboard and respond to activation commands.

pumplink-esp32-firmware

Clone the starter repo to get all files ready to configure and flash.

What you need

An ESP32 board (any variant — ESP32-WROOM, ESP32-S3, etc.)
A relay module wired to your ESP32 (or just an LED for testing)
Arduino IDE installed
A PumpLink account — sign up free

Step 1 — Register your device

Sign in to the PumpLink dashboard, go to Devices → Add device, give it a name, and click Register. You’ll see a Device ID and a Password shown once. Copy both immediately — the password is never shown again. If you lose it, you’ll need to regenerate credentials and reflash.

The password is shown exactly once. Store it securely before closing the dialog.

Step 2 — Create your project

Install ESP32 board support

In Arduino IDE → Preferences, add this to Additional boards manager URLs:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Then go to Tools → Board → Boards Manager, search ESP32, and install.

Install dependencies

In Arduino IDE → Tools → Manage Libraries, install:

PubSubClient by Nick O’Leary

Create the sketch

Create a new sketch folder and add the following files:

`config.h`

// WiFi Credentials
#define WIFI_SSID           "YourNetworkName"
#define WIFI_PASSWORD       "YourNetworkPassword"

const char* MQTT_HOST = "mqtt.pumplink.dev";
const char* MQTT_USERNAME = "42";           // your numeric device ID
const char* MQTT_PASSWORD = "your_token_here";
const int MQTT_PORT = 42743;
const char* MQTT_PROTOCOL = "ssl";

#define RELAY_PIN 26   // GPIO pin connected to your relay IN pin — change to match your wiring

`ca_cert.h`

This is the Let’s Encrypt root CA certificate chain. It allows the ESP32 to verify the TLS connection to mqtt.pumplink.dev without disabling certificate verification.

#pragma once

// ISRG Root X1 — Let's Encrypt root certificate authority
// mqtt.pumplink.dev's TLS certificate is signed by this CA.
// This certificate expires 2035-06-04 and does not need to be updated
// when PumpLink renews its broker certificate.
const char* ROOT_CERT = R"EOF(
-----BEGIN CERTIFICATE-----
MIICizCCAhGgAwIBAgIQXd1w3TH4AchcGGp6BLgK/jAKBggqhkjOPQQDAzAuMQsw
CQYDVQQGEwJVUzENMAsGA1UEChMESVNSRzEQMA4GA1UEAxMHUm9vdCBZRTAeFw0y
NTA5MDMwMDAwMDBaFw0yODA5MDIyMzU5NTlaMDMxCzAJBgNVBAYTAlVTMRYwFAYD
VQQKEw1MZXQncyBFbmNyeXB0MQwwCgYDVQQDEwNZRTEwdjAQBgcqhkjOPQIBBgUr
gQQAIgNiAAQHZVB1/mimla2hfSurylScjPMZaOJXLz/NnAc2sylm8WDyhU9Ccp+z
ASQi5vSwGGJjSGklkD9fdPR8GpyDIOIjCEfrnbt/v+ZSEPLLEGbaM6EccDbN7p9x
teIm2Avf+ryjge4wgeswDgYDVR0PAQH/BAQDAgGGMBMGA1UdJQQMMAoGCCsGAQUF
BwMBMBIGA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0OBBYEFLsgykcL/tflnPmPCSqj
jDdFsbzYMB8GA1UdIwQYMBaAFKPIJlqOoUzQNWP8myPIOq5W809WMDIGCCsGAQUF
BwEBBCYwJDAiBggrBgEFBQcwAoYWaHR0cDovL3llLmkubGVuY3Iub3JnLzATBgNV
HSAEDDAKMAgGBmeBDAECATAnBgNVHR8EIDAeMBygGqAYhhZodHRwOi8veWUuYy5s
ZW5jci5vcmcvMAoGCCqGSM49BAMDA2gAMGUCMQDgjUEahFT/h3DRakqiPZpLvPgf
Zwkt6K2EOMmh1nvEzl83eMLYcod4GCl3b0J1Nn0CMBNYmEQJb4CEG5WoOe7aRn/L
VKu6saHmHEynI7ysIPd8zQsK1HdmhlHKlw9Z5GpGvA==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICpjCCAiugAwIBAgIRAIchZfw0tuX7qK3Vs3BftTowCgYIKoZIzj0EAwMwTzEL
MAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2VhcmNo
IEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDIwHhcNMjYwNTEzMDAwMDAwWhcN
MzIwOTAyMjM1OTU5WjAuMQswCQYDVQQGEwJVUzENMAsGA1UEChMESVNSRzEQMA4G
A1UEAxMHUm9vdCBZRTB2MBAGByqGSM49AgEGBSuBBAAiA2IABDwS/6vhrcVqcbBo
+wgdI3fwn9x7DNJJOY/lTOti0vkwuRN87RhEhTH17E7XyFjWsPYhIPt/wzOqxTd2
b+4ZJNy9ID04YywF9U5zasDVyGSNErVNtz8uSGh5izW87j77GaOB6zCB6DAOBgNV
HQ8BAf8EBAMCAQYwEwYDVR0lBAwwCgYIKwYBBQUHAwEwDwYDVR0TAQH/BAUwAwEB
/zAdBgNVHQ4EFgQUo8gmWo6hTNA1Y/ybI8g6rlbzT1YwHwYDVR0jBBgwFoAUfEKW
rt5LSDv6kviejM9ti6lyN5UwMgYIKwYBBQUHAQEEJjAkMCIGCCsGAQUFBzAChhZo
dHRwOi8veDIuaS5sZW5jci5vcmcvMBMGA1UdIAQMMAowCAYGZ4EMAQIBMCcGA1Ud
HwQgMB4wHKAaoBiGFmh0dHA6Ly94Mi5jLmxlbmNyLm9yZy8wCgYIKoZIzj0EAwMD
aQAwZgIxAMU19WCtmxVND8UHBZRoma49Z7jPs64Dma0eTu1OChVbB/2J7GV3nvYK
Ax54uk1G9QIxAO0miLVJu8PLNiXXXkiE/gsK3CTRTF/aeo4bMX42Zw40csRU6AC2
6hSW1/IWaas6dg==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEcDCCAligAwIBAgIQbI8dxyfHEX97r4U6yYD5zTANBgkqhkiG9w0BAQsFADBP
MQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJuZXQgU2VjdXJpdHkgUmVzZWFy
Y2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBYMTAeFw0yNjA1MTMwMDAwMDBa
Fw0zMjA5MDIyMzU5NTlaME8xCzAJBgNVBAYTAlVTMSkwJwYDVQQKEyBJbnRlcm5l
dCBTZWN1cml0eSBSZXNlYXJjaCBHcm91cDEVMBMGA1UEAxMMSVNSRyBSb290IFgy
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEzZvVn4CDCuwJSvMWSj5cz3es3mcFDR0H
ttwW+1qLFNvicWDEukWVEYmO6gbf9yoWHKS5xcUy4APgHoIYOIvXRdgKam7mAHf7
AlF9ItgKbppbd9/w+kHsOdx1ymgHDB/qo4H1MIHyMA4GA1UdDwEB/wQEAwIBBjAd
BgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwDwYDVR0TAQH/BAUwAwEB/zAd
BgNVHQ4EFgQUfEKWrt5LSDv6kviejM9ti6lyN5UwHwYDVR0jBBgwFoAUebRZ5nu2
5eQBc4AIiMgaWPbpm24wMgYIKwYBBQUHAQEEJjAkMCIGCCsGAQUFBzAChhZodHRw
Oi8veDEuaS5sZW5jci5vcmcvMBMGA1UdIAQMMAowCAYGZ4EMAQIBMCcGA1UdHwQg
MB4wHKAaoBiGFmh0dHA6Ly94MS5jLmxlbmNyLm9yZy8wDQYJKoZIhvcNAQELBQAD
ggIBAD2/e9frmMxNpCV03qUHegg+MV2wz9644YoXdqtH8RyWYcBO7xfjjGEXdU1e
/o0OkEFiynUCOSIk/vLLo7ttz6CPAeNlWfC0XNkoGeWgK6jjXvozBaGuGH5n0Ufo
shMeWTuURqNN5G00sSXDTBrpp2+mgvdZQjb8K11TYMA25QA+YHNfbIEL0BniAhKS
2gsnJjSzrdZLI+EZ7SEyqdR2rkjd1KutLDU+n3TFyxjniZVGur4YlhMP3mY/dV95
IruAkkjOZier6hGBdEgZXXvaCz9u9iVEadsIE75pAGL8oHV5vxdARDiotRpul1IN
/UZwzAbrfUFcw1HkAcYD/mlZfnQ2ieCF2MS7j3Vhv7JPDKp45fmykmzYNSrumRW0
upFFKDBOoF7hsOb7oLyHS+Uft6jOUfOrogj8YUx38hKb2K20r42OgsSdDdxdeYWc
MS3Sb6mwJeSZEYxJ2gaXnDSPaKhhrNkYwljyVQyr4Nq+MEJytXNTnHqaAcrNwZlV
pcJL1KBnMrMjP7eanvUwL3FYj3cF17jtboLt7gLoi4+2rWZFvn+w54jmd/FIuhhZ
cEaU/wvU6BUNMtcVquVGHp7itQeDth5j+XL3j4WJ2SABwzUl6OeYdgpIt/ITZa+p
TT0mQ/r5XyA4MEAiabn7XJjvCERlF2dcn2wqJw+CreTkkQ2R
-----END CERTIFICATE-----
)EOF";

The CA certificate above verifies mqtt.pumplink.dev’s TLS certificate chain. You do not need to update this when PumpLink renews its broker certificate — the root CA is valid until 2035.

`pumplink_esp32.ino`

Name the sketch file to match your folder name (e.g. a folder named pumplink_esp32 needs pumplink_esp32.ino).

#include <Arduino.h>
#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <PubSubClient.h>
#include "config.h"
#include "ca_cert.h"

// ── Topic helpers ─────────────────────────────────────
String topicCommand() { return "device/" + String(MQTT_USERNAME) + "/command"; }
String topicAck()     { return "device/" + String(MQTT_USERNAME) + "/ack"; }
String topicStatus()  { return "device/" + String(MQTT_USERNAME) + "/status"; }

// ── Globals ───────────────────────────────────────────
WiFiClientSecure espClient;
PubSubClient     mqtt(espClient);

// ── MQTT callback ─────────────────────────────────────
void onMessage(char* topic, byte* payload, unsigned int length) {
  String msg;
  for (unsigned int i = 0; i < length; i++) msg += (char)payload[i];
  Serial.println("[MQTT] command: " + msg);

  if (msg == "on") {
    digitalWrite(RELAY_PIN, HIGH);
    Serial.println("[RELAY] ON");
    // Acknowledge the activation — any publish counts
    mqtt.publish(topicAck().c_str(), "ack", false);
    Serial.println("[MQTT] ack sent");
  }

  if (msg == "off") {
    digitalWrite(RELAY_PIN, LOW);
    Serial.println("[RELAY] OFF");
    // Acknowledge the shutdown — the backend ack-gates "off" the same way
    // it ack-gates "on". If this doesn't arrive within 10s, the backend
    // records the device as UNKNOWN and blocks re-activation until it
    // hears back.
    mqtt.publish(topicAck().c_str(), "ack", false);
    Serial.println("[MQTT] ack sent");
  }
}

// ── WiFi ──────────────────────────────────────────────
void connectWiFi() {
  Serial.print("[WiFi] connecting to " + String(WIFI_SSID));
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("\n[WiFi] connected — IP: " + WiFi.localIP().toString());
}

// ── MQTT connect ──────────────────────────────────────
void connectMQTT() {
  while (!mqtt.connected()) {
    Serial.print("[MQTT] connecting...");
    if (mqtt.connect(
          ("esp32-" + String((uint32_t)ESP.getEfuseMac())).c_str(),
          MQTT_USERNAME,
          MQTT_PASSWORD)) {
      Serial.println(" connected");
      // Subscribe at QoS 1 — PubSubClient doesn't implement the QoS 2
      // PUBREC/PUBREL/PUBCOMP handshake, so the broker downgrades delivery
      // to QoS 1 for this subscription regardless of what it publishes at.
      mqtt.subscribe(topicCommand().c_str(), 1);
      Serial.println("[MQTT] subscribed to " + topicCommand());
    } else {
      Serial.printf(" failed (state=%d), retry in 5s\n", mqtt.state());
      delay(5000);
    }
  }
}

// ── Setup ─────────────────────────────────────────────
void setup() {
  Serial.begin(115200);
  pinMode(RELAY_PIN, OUTPUT);
  digitalWrite(RELAY_PIN, LOW);

  connectWiFi();

  // Load root CA — enables proper TLS certificate verification
  espClient.setCACert(ROOT_CERT);

  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setCallback(onMessage);
  mqtt.setKeepAlive(60);

  connectMQTT();
}

// ── Loop ──────────────────────────────────────────────
void loop() {
  if (!mqtt.connected()) connectMQTT();
  mqtt.loop();
}

Step 3 — Flash

Open pumplink_esp32.ino in Arduino IDE, select your board and port under Tools, then click Upload. Open the Serial Monitor at 115200 baud and you should see:

[WiFi] connecting to YourNetworkName........
[WiFi] connected — IP: 192.168.1.42
[MQTT] connecting... connected
[MQTT] subscribed to device/42/command

Step 4 — Verify

Go to the PumpLink dashboard — your device should appear as Online. To trigger an activation without writing any client code, connect to the broker with MQTT Explorer using your device’s username and password (same host and port as your firmware — mqtt.pumplink.dev:42743, TLS enabled). Then:

Subscribe to device/42/# (replace 42 with your device ID) to watch all traffic for your device.
Publish on to device/42/command.

Your relay should click on immediately, and the device should publish to device/42/ack within 10 seconds. Publish off to the same command topic to turn it back off — the device must ack that too, within the same 10 seconds, or the backend marks it UNKNOWN and refuses to re-activate it until it hears back. The serial monitor will show:

[MQTT] command: on
[RELAY] ON
[MQTT] ack sent
[MQTT] command: off
[RELAY] OFF
[MQTT] ack sent

This manual publish is just for testing. In production, the backend publishes on/off to the command topic on your behalf when a user triggers an activation from the dashboard or API — see the device contract for the full handshake.

Using PlatformIO instead

If you prefer PlatformIO in VS Code over the Arduino IDE, the same three files work as-is — just place them under src/ and add a platformio.ini:

[env:esp32]
platform  = espressif32
board     = esp32dev
framework = arduino

lib_deps =
  knolleary/PubSubClient @ ^2.8

monitor_speed = 115200

Change board to match your specific board if needed (e.g. esp32-s3-devkitc-1). Save config.h and ca_cert.h from above into src/, and save the sketch from above as src/main.cpp. Build and flash with:

pio run --target upload
pio device monitor

Troubleshooting

Device doesn’t appear in dashboard

Check serial monitor for connection errors
Verify MQTT_USERNAME is your numeric device ID (e.g. "42" not "device_42")
Verify MQTT_PASSWORD is correct — regenerate from dashboard if unsure

TLS handshake fails

Confirm mqtt.pumplink.dev resolves from your network
The CA cert in ca_cert.h must be complete and unmodified

Relay doesn’t click

Verify RELAY_PIN matches your wiring
Most relay modules are active HIGH — digitalWrite(HIGH) closes the relay

Ack timeout (device shows offline after activation, or won’t re-activate)

The backend expects an ack within 10 seconds of sending "on" or "off" — a missed off-ack marks the device UNKNOWN and blocks the next activation until it hears back
Check that topicAck() publishes successfully — look for [MQTT] ack sent in serial after both command: on and command: off
If a device gets stuck UNKNOWN, it self-heals the moment it publishes its real state to device/{id}/status — reconnecting is usually enough if your firmware reports status on connect

Next steps

Device contract — full MQTT topic and handshake reference
GitHub repo — clone the starter firmware
Dashboard — manage devices, users, and schedules
Support: hello@pumplink.dev

pumplink-esp32-firmware

​What you need

​Step 1 — Register your device

​Step 2 — Create your project

​Install ESP32 board support

​Install dependencies

​Create the sketch

​config.h

​ca_cert.h

​pumplink_esp32.ino

​Step 3 — Flash

​Step 4 — Verify

​Using PlatformIO instead

​Troubleshooting

​Next steps

What you need

Step 1 — Register your device

Step 2 — Create your project

Install ESP32 board support

Install dependencies

Create the sketch

`config.h`

`ca_cert.h`

`pumplink_esp32.ino`

Step 3 — Flash

Step 4 — Verify

Using PlatformIO instead

Troubleshooting

Next steps