Skip to content
Docs

Quickstart with Arduino

The kit is also an Arduino library. It needs Arduino-ESP32 3.x and an ESP32 with Bluetooth LE.

Using an AI coding agent?

Fill these in, copy the prompt, and paste it into your agent (Claude Code, Cursor, Copilot) at the root of your firmware project. It follows the steps below and shows you the diff.

Prompt · Arduino
Add Device Configs Wi-Fi setup to this Arduino sketch (Arduino-ESP32 core 3.x).

Device Configs lets this device's owner put it on Wi-Fi from the Device Configs phone app: they scan the QR label on the unit, the app connects to that unit over Bluetooth LE with an encrypted session (Espressif protocomm security 2, a setup code per unit), and sends the Wi-Fi network, a token and a label. The device then says whether it joined, or why not. The firmware side is the DeviceConfigs Arduino library.

Product:
- Product id: <your product id>
- Bluetooth name prefix: <YOUR-PREFIX> (each unit advertises <YOUR-PREFIX>-<serial>)
- The library folder: <path to the deviceconfigs kit folder>

Steps:
1. Check the board is an ESP32 with Bluetooth LE and the esp32 core is version 3.x. If it isn't, stop and tell me.
2. Install the library: copy <path to the deviceconfigs kit folder> into the Arduino libraries folder (~/Arduino/libraries/DeviceConfigs). With PlatformIO, add it to lib_extra_dirs or lib_deps instead.
3. Copy examples/BasicSetup/partitions.csv from the library into the sketch folder (Arduino uses a sketch's partitions.csv automatically), merging any partition the sketch already needs. With PlatformIO, set board_build.partitions = partitions.csv. Tell me to choose Tools > Partition Scheme > Minimal SPIFFS so the IDE checks the size against the right app slot.
4. In setup():
   #include <DeviceConfigs.h>
   DeviceConfigs.begin("<YOUR-PREFIX>", "<your product id>");
   DeviceConfigs.waitOnline();
   Remove the sketch's own Wi-Fi setup: WiFi.begin(ssid, password), hard-coded credentials, WiFiManager, WiFiProv, SmartConfig. Keep using WiFi, HTTPClient and NetworkClientSecure as before: Arduino's WiFi stays in charge of the connection. If the sketch uses Bluetooth itself, call DeviceConfigs.keepBluetooth() before begin().
5. Where the device talks to its server, send DeviceConfigs.token() as the device's credential (for example an Authorization header). DeviceConfigs.label() is the name the owner gave the device.
6. If the device has an LED or a button: use DeviceConfigs.onEvent() (SetupOpen, WrongPassword, NetworkNotFound, SetupDone, Online, Offline) to show setup state, call DeviceConfigs.openSetup() on a press to re-run setup, and DeviceConfigs.factoryReset() on a long press. Keep the event handler short: it runs on the system event task.
7. Compile (arduino-cli compile --fqbn esp32:esp32:<board> --board-options PartitionScheme=min_spiffs, or pio run) and fix any errors.

Rules:
- Never log or print the Wi-Fi password, the token or a setup code.
- Don't add hard-coded Wi-Fi credentials or any shared default password.
- Don't change code unrelated to Wi-Fi setup.
- When you're done, show me the diff, where the dc_factory partition is (its offset), and the command that gives a unit its identity:
  python <Device Configs firmware folder>/tools/dc_factory.py --product <your product id> --partitions partitions.csv --port <serial port>

Reference: https://deviceconfigs.com/docs/quickstart/arduino/ (every docs page as plain text: https://deviceconfigs.com/llms-full.txt)

By hand

Section titled “By hand”

  1. Install the library. Zip the firmware/components/deviceconfigs folder and choose Sketch > Include Library > Add .ZIP Library, or copy the folder into ~/Arduino/libraries/.

  2. Make room for the unit’s identity. Copy examples/BasicSetup/partitions.csv into your sketch folder (Arduino uses it automatically) and choose Tools > Partition Scheme > Minimal SPIFFS, so the IDE checks your sketch against the right size.

  3. Start it.

    #include <DeviceConfigs.h>
    

    void setup() {
      DeviceConfigs.begin("ACME-AIR");          // your product's Bluetooth prefix
      DeviceConfigs.waitOnline();
      String token = DeviceConfigs.token();     // for your service
      String name = DeviceConfigs.label();      // what the owner named it
    }

  4. Label a unit and upload. See Label each unit.

Arduino’s WiFi stays in charge of the connection, so WiFi.status(), HTTPClient and NetworkClientSecure work as usual once the device is online.

Events

Section titled “Events”
DeviceConfigs.onEvent([](DeviceConfigsEvent e) {
  if (e == DeviceConfigsEvent::WrongPassword) Serial.println("The app asks for the password again");
});

SetupOpen, DeviceSet, WrongPassword, NetworkNotFound, SetupDone, Online, Offline. Keep the handler short: it runs on the system event task.