OhioIoT
Menu

Connect Your ESP32 — PlatformIO

Attach a device to the OhioIoT MQTT broker with a secure TLS connection.

Using the Arduino IDE instead? Switch to the Arduino IDE version of this page.
Prerequisites:
  • You should have completed the previous step: Create Your Account
  • You will need an ESP32 development board (or similar)
  • PlatformIO should already be installed in VS Code
1

Download the Minimalist SDK

Git clone the Minimalist SDK for PlatformIO:

$git clone https://github.com/OhioIoT-Firmware/Minimalist-PlatformIO minimalist
2

Set your credentials

#define WIFI_SSID "your_wifi_ssid"
#define WIFI_PASS "your_wifi_pass"
#define MQTT_USER "your_mqtt_user"    <-- from the Settings page in the app
#define MQTT_PASS "your_mqtt_pass"    <-- from the Settings page in the app
3

Flash and watch

Click Upload in PlatformIO. Open the Serial Monitor at 115200 baud. You should see:

  booting...

	existing deviceID: a8f3k2m1

	wifi connecting...
	wifi connected...

	mqtt connecting...
	mqtt connected...
✓ You're connected. Your ESP32 has a TLS-encrypted MQTT connection to OhioIoT.

What just happened

device_id.get_or_set(DEVICE_ID) checked the ESP32's non-volatile storage for a saved device ID. Since this is the first boot, it generated a random 8-character string, stored it, and returned it. Next boot, it returns the same ID.

wifi_tools.begin() connected to WiFi and set up an event handler that tracks connection state automatically.

mqtt.setup() configured the MQTT client with TLS. The SDK ships with the OhioIoT broker's CA certificate built in — you didn't need to configure it. That's why the connection just worked over port 8883.

mqtt.maintain() handles everything in the loop: reconnecting if dropped, processing incoming messages, keeping the heartbeat alive.

What's handling TLS?

The SDK ships with the CA certificate for Let's Encrypt's ISRG Root X1 — the certificate authority that signs the OhioIoT broker's TLS certificate. When your ESP32 connects to port 8883, it uses this CA cert to verify that it's talking to the real mqtt.ohioiot.com.

Try this code on a local broker?

You can override the SDK defaults with build flags. The most obvious user case is when you want to develop on an unsecured local MQTT broker running on your local network rather than develop while talking to the OhioIoT broker. To do some, simply add some build flags to your platformio.ini:

build_flags =
    -D MQTT_HOST="xxx.xxx.x.xxx"
    -D MQTT_PORT=1883
    -D ALLOW_INSECURE_MQTT

Troubleshooting

"failed to connect" in the Serial Monitor — double-check your MQTT username and password in credentials.h. They must match the Settings page in the dashboard exactly.

WiFi connects but MQTT doesn't — some networks block port 8883. Try a mobile hotspot. If it works there, your network is blocking outbound TLS-MQTT.

Device keeps reconnecting — two devices with the same device ID will kick each other off the broker. Unplug one and see if the other stabilizes.