Skip to main content

Getting started

:::warning Not yet run on hardware This firmware is compile-verified and hardware-verified by nobody yet. It is a faithful implementation of the contract rather than a tested binary, so treat every claim here as what the code intends to do, and check the behaviour on a bench before you wire it to anything that matters. See Edge firmware for the full status. :::

This is the build, flash, and first-boot path the firmware repo documents. Expect to fix what the compiler and the bench find.

What you need​

  • An ESP32 dev board. The default build targets a plain ESP32-WROOM board, the cheapest option. An ESP32-S3 target is also defined, same firmware. A two-channel or four-channel ESP32 relay board uses the same build; only the profile's pins differ.
  • PlatformIO, which pulls the ESP32 platform and the libraries the firmware depends on (the async web server, ArduinoJson, and the sensor libraries for OneWire, the HX711 load cell, the INA219 current sensor, and the MFRC522 RFID reader).
  • The peripheral you are wiring, and a profile for it.

Build and flash​

From the repo root:

pio run                       # compile (env esp32dev; esp32-s3 also defined)
pio run -t upload -t monitor  # flash over USB, then watch the serial log

The serial monitor runs at 115200 baud. On boot the log prints the firmware version and the chip's hostname, which is cobblr-edge- followed by four hex characters derived from the board's MAC.

First boot and provisioning​

With no stored profile, the chip has no network to join, so it starts its own access point named after that hostname (cobblr-edge-XXXX) and serves a setup page:

  1. Join the cobblr-edge-XXXX WiFi network from a phone or laptop.
  2. Open http://192.168.4.1/.
  3. Paste a filled-in profile: WiFi credentials, the token, the devices, and any commands. Save.
  4. The chip stores the profile, reboots, and joins your WiFi. It is then reachable at http://cobblr-edge-XXXX.local over mDNS, which survives a DHCP address change.

The provisioning route is open while the chip is in setup mode (there is no token yet) and requires the token once the chip is provisioned, so a later profile change is authenticated.

Never commit a filled-in profile. It carries your WiFi credentials and the device token. The repo gitignores the local profile filenames for this reason.

Over-the-air updates​

Once the chip is online it advertises itself for Arduino OTA, so later firmware ships without plugging in a cable. Note that OTA image signing, which the design spec calls for so a LAN attacker can't push a rogue image, is not in this P0 build. Until it lands, treat OTA as something to run only on a network you trust.

Wire it to Cobblr​

The firmware works with Cobblr today through a declarative machine connection: a machine-driver whose commands point at the chip's /command route. Set the connection's base URL to the chip's address, set its apiKey to the profile's token, and give each command a body that names the profile command and its params. For the irrigation profile above, a run-zone command posts { "command": "open-valve", "params": { "seconds": "{seconds}" } }, and a wire fills seconds from the entity's field.

Cobblr reaches the chip at its http://192.168.x.x address, so an instance on the same network works out of the box. An instance somewhere else cannot reach a private address directly: an outbound tunnel from the chip is a later firmware phase and is not in this build, so for now put the chip behind your own VPN and register the address that resolves.

The full request-and-response shape, including which routes the chip honestly refuses, is in the edge-adapter contract.