Device Builder

What you need

Three ways in, one page per question

The builder starts with What do you want to do? and three cards. Each card is its own short wizard. A rail on the left shows the steps; a finished step gets a tick, and you can go back to any of them.

Seven questions, one page each

Build for a sensor asks all seven. The template wizards ask only the ones they need.

1. 1
   Sensor

   The HydroNode sensor the device reports to. Click one to go on.
2. 2
   Board

   Your ESP board. If yours is not listed, pick the development kit with the same chip. Each chip family is tagged with what it takes over the air: firmware and config, or config only on the ESP8266.
3. 3
   Wiring

   Add each sensor and output and pick its pin. The pin map shows conflicts as you go, a scan finds what is wired.
4. 4
   Power

   Whether it stays on, naps or deep sleeps between rounds.
5. 5
   Timing

   How often a round starts, what it costs, and which values go out less often.
6. 6
   WiFi

   Network name and password, filled in with your passkey if you saved them. Or skip to download with placeholders.
7. 7
   Flash or download

   Check the summary, then flash over USB, take the code or save the setup as a template.

Sensors and pins

A new sensor lands on the usual pin of your board, marked default in the pin list, for example GPIO4 (1-Wire default) or GPIO21 (SDA default). You can move it to any pin that fits. The pin map shows what is taken, and pins that decide how the chip boots or carry the serial console are flagged. Every value gets its own HydroNode type; a second temperature becomes TEMPERATURE2.

Gas sensors learn the normal air of the room and need regular samples. The SGP40 and the VOC value of the SGP41 run in light sleep: the board wakes every 10 s for a 30 ms reading, Sensirion's low-power mode. The SGP30 and the NOx value of the SGP41 need one sample per second, so Always on or Modem sleep. Their first values arrive after about a minute, NOx after about five. A temperature and humidity sensor on the same device is used for their humidity compensation automatically. The SCD41 works in deep sleep: two shots per round, the first after waking is thrown away as Sensirion recommends, then it powers down. The SCD40 cannot.

Sensors are read the frugal way and sleep in between: BME280, BMP280 and BME680 in forced mode, TMP117, DPS310, BH1750 and the light sensors in one-shot mode, the INA current sensors triggered. A Plantower fan (PMS5003, PMSA003I) sleeps when its SET pin is wired and runs 30 s before a reading; a SEN5x idles or, when it sends VOC or NOx, keeps learning on its own with the fan off. A sensor whose values are not due in a round is not woken at all. Each part's behaviour per power mode is in the firmware's catalog, and the power step tells you which part rules out a mode and what would free it.

The battery input measures through a voltage divider: battery plus to a 100 kΩ resistor, that to a second 100 kΩ resistor, that to GND. The point between the two goes to the ADC pin, which then sees half the battery voltage. A divider factor of 2 turns it back.

A sensor that measures more than you need sends less: remove a value with its ×, it comes back under Not sent. Distance sensors also report a fill level once you enter the distance to the empty and to the full tank.

Scan the board

Not sure the wiring is right? Scan the board next to the pin map flashes a small scanner, then lists every I²C address that answers and every DS18B20 on the 1-Wire pin you pick. Next to each address stand the sensors it could be, for example 0x76: BME280, BMP280, BME680, MS8607. One click adds it to the device. Flashing the HydroNode firmware at the end replaces the scanner. Without a browser that talks to USB, download the scanner as an .ino sketch for the Arduino IDE instead.

Relays, LEDs and buttons

Outputs are switched by commands from the HydroNode app or the sensor console. Each output has a command name you choose, relay1 by default, and says whether it switches on at HIGH or at LOW (most cheap relay modules switch at LOW) and whether it starts on or off after power-up.

Commands arrive with the answer to a sent value, so a board with outputs always sends at least one value. WiFi signal needs no wiring for that. The timing step shows how long a command can take at most. A button sends each press at once as the value 1 and can toggle an output on the same board, even without WiFi. Outputs keep their state in light and deep sleep (firmware 0.6.0, not on the ESP8266) and get their commands with the next round; dimming needs the board awake. A button or a rain gauge wakes the board from deep sleep when it is wired to a pin that can (the builder marks the others): the press goes out right away, a tip is counted and sent with the next round.

How it sleeps, and how often it sends

The board works in rounds: wake the sensors that are due, nap while they measure, read them, send the values, sleep. The power step picks the most frugal mode your parts allow and moves it again when you add or remove one; choose another and the builder keeps it. Next to each mode it shows the average current of this very setup.

Boards marked with the battery icon have no USB chip or power LED that stays on, so in deep sleep the whole board draws well under 1 mA. Development kits keep drawing 1 to 10 mA. The ESP8266 wakes from deep sleep only with a wire from GPIO16 (D0) to RST; the builder asks you to confirm it.

The timing step sets how often a round starts. Rounds start on the interval, however long the board was awake, and in sleeping modes they are aligned to internet time, so a sleep timer that runs a few percent fast does not add up. The step also shows what a round costs: WiFi, the secure connection, every value and the time napping while sensors measure. Measured on a NodeMCU, four values take about 6 seconds awake; the fastest interval leaves room for a slow router. Single values can go out less often, every n-th round or every so many minutes, for example CO₂ every 5 minutes while the temperature goes every minute; their sensor then only wakes in those rounds, and the step shows the average round. Enter your battery's capacity to see how long it lasts, an estimate from the data sheets of board and sensors.

Four ways onto the board

The last step sums up your answers and offers the ways onto the board. Only Flash now puts the HydroNode firmware on it, and only that firmware updates over the air afterwards. The step says so in a box above the choices, together with what your board can take.

While flashing, the page shows each phase (preparing, connecting, writing, restarting) and then follows the board through its checklist until the first reading arrives. Erase the whole flash first wipes anything an earlier firmware stored; it takes longer and is rarely needed. Afterwards the step links to the device in Fleet.

Downloads contain only code written for your device. Libraries are fetched by your build tool, each under its own license. The firmware used for flashing is open source: hydronode-firmware, licenses on the firmware licenses page.

After a firmware update

When a new HydroNode firmware comes out, Fleet shows it in the firmware column of every board that can take it, for example → 0.5.1. What to do depends on the board.

An update over the air keeps the saved setup in step: its firmware version and config revision follow the board. When you open a setup or a template that was saved with an older firmware, the builder checks it against today's list of boards and sensors. A yellow box names what changed, for example "Saved with firmware 0.4.2, the builder now uses 0.5.0. Check the marked steps.", and a dot on the rail marks the steps to look at. Pins are never moved silently.

How the update runs, the check after the restart and the rollback are described in Fleet and Over-the-Air Updates.

Reflash and the saved setup

After every flash and every download, the builder saves its answers on the sensor: board, wiring, power and timing. This device setup never contains the WiFi network, the password or the sensor secret, and never any code. It is what makes config changes over the air and one-click reflashing possible. A sensor keeps only its latest setup. If saving fails, the flash still counts: the page says "Flashed. The setup could not be saved for reflashing later."

Open it under Sensor settings → Device setup. The owner and Admin shares of an HTTP sensor see it; LoRaWAN sensors have no such tab.

Reflash opens the builder with this setup. Sensor, board, wiring, power and timing are ticked, and it starts on the WiFi step. Change any step on the way, then flash. Use it to put a board back to its known state, to replace a broken board with the same wiring, or to move a board from firmware before 0.5.0 to one that updates over the air.

One setup for many boards

A template is a setup without a sensor and without WiFi. Build it once, then flash every board of the same kind from it in four steps. Templates have versions: saving a changed template adds v2, v3 and so on, each with a short summary of what changed. Boards flashed from a template stay linked to it, so a later change can reach all of them at once.

1. 1
   Create

   Pick Create template in the builder, or Save as template on the last step of any build. Give it a name (up to 80 characters) and an optional description.
2. 2
   Flash from template

   Pick the template, then the sensor (an existing HTTP sensor or Create sensor), join WiFi and flash. A sensor with another saved setup gets it replaced; the builder says so first. Customize switches to a normal build with the template prefilled.
3. 3
   Edit

   Opens the template in the builder. Save changes stores the next version. Save as new template keeps the old one as it is.
4. 4
   Apply to linked boards

   After a change, Fleet asks whether linked boards should take it over the air. You check every board before anything is sent.

You can keep up to 50 templates, each with its own name. The list, the linked devices and Apply to linked devices live on the Templates tab in Fleet, see Fleet and Over-the-Air Updates.

Your WiFi password stays with you

Save WiFi with a passkey

Typing the same WiFi password for every board gets old. On the WiFi step you can save the network in your HydroNode account, encrypted with a passkey, and fill it in with one touch on this or any other computer. HydroNode stores only the encrypted copy and cannot read the network name or the password.

1. 1
   Type the network once

   Enter name and password on the WiFi step as usual. Below the fields, Save this network with your passkey appears.
2. 2
   Save with passkey

   A dialog explains what is stored. Confirm with Save with passkey. The first time, your browser creates a passkey called "HydroNode WiFi vault"; it cannot sign anyone in.
3. 3
   Fill in next time

   On any computer signed in to your account, Fill in with your passkey lists your saved networks after one passkey prompt. Pick one and the fields are filled in.
4. 4
   Remove or delete all

   The bin icon next to a network removes it on all your devices. Delete saved networks removes all of them, for example when the passkey is lost. Boards that already use a network keep working.

Five typical devices

Battery probe in the garden

ESP32-C3 SuperMini, two DS18B20 probes on one pin, deep sleep every 15 minutes, battery voltage.

DS18B20 probes  GPIO10 (1-Wire default), 4.7 kΩ from data to 3.3 V
Battery         GPIO3 (analog default), 100 kΩ / 100 kΩ divider
Sends           TEMPERATURE, TEMPERATURE2, BATTERY_VOLTAGE

Greenhouse climate on USB power

ESP32 DevKitC, BME280 and a soil moisture sensor, modem sleep every minute.

BME280          I²C: SDA GPIO21, SCL GPIO22, address 0x76
Soil moisture   GPIO34 (analog default)
Sends           TEMPERATURE, HUMIDITY, PRESSURE, SOIL_MOISTURE

Indoor air quality on USB power

ESP32-C3 SuperMini, SCD41 for CO₂, SGP41 for VOC and NOx, SHT40 for compensation, modem sleep every minute.

SCD41           I²C: SDA GPIO6, SCL GPIO7, address 0x62
SGP41           same bus, address 0x59
SHT40           same bus, address 0x44
Sends           CO2, TEMPERATURE, HUMIDITY, VOC_INDEX, NOX_INDEX, TEMPERATURE2, HUMIDITY2

Watering with a tank level

ESP32 DevKitC, a relay for the pump, an ultrasonic sensor above the tank and a button, modem sleep every minute.

Relay relay1    GPIO26, switches on at LOW
JSN-SR04T       trigger GPIO27, echo GPIO25 through a 1 kΩ / 2 kΩ divider
Button          GPIO32 to GND, toggles relay1
Sends           DISTANCE, TANK_LEVEL, BUTTON
Commands        relay1 true, relay1 false, relay1 30000 (water for 30 s)

Room sensor from the drawer

Wemos D1 mini (ESP8266) with a DHT22, modem sleep every 5 minutes.

DHT22           D6 (GPIO12, digital default)
Sends           TEMPERATURE, HUMIDITY

When it does not send

The Device Console on the sensor page shows every request the device makes, including refused ones and why.