Automations & hardware

Set up an ESP32

Turn a low-cost ESP32 board into an automation controller — flash it from your browser, wire a relay or sensor, and pair it with your POS in minutes.

An ESP32 is a small, inexpensive Wi-Fi controller — ideal when you want to switch one relay or read one or two sensors. You flash it once straight from your browser (no software to install), wire up your hardware, and enter a pairing code to connect it to your POS. After that it reconnects on its own whenever it has power and Wi-Fi.

What you'll need

• An ESP32 dev board (a common "WROOM" board with a USB port).
• A USB cable that carries data (not a charge-only cable) and a computer running Chrome or Edge (these support flashing from the browser).
• Your hardware: a relay module for anything you want to switch (a lock, lights), and/or sensors you want to read (a temperature probe, a door switch, a button).
• A few jumper wires, and a separate power supply for whatever the relay switches.

Step 1 — Flash the board

1. In the Automations area, go to Devices → Flash a board.
2. Plug the ESP32 into your computer with the USB cable.
3. Click Connect, pick the board's serial port from the browser prompt, and start the flash. It takes a minute or two and only has to be done once per board.
4. When it finishes, the board is running the Mavos firmware and is ready to pair.

If no port appears, try a different USB cable (some are charge-only) or a different USB port, and make sure you're using Chrome or Edge.

Step 2 — Create the device

1. Go to Devices → New device and choose ESP32.
2. Add a channel for each thing you want to control or read, and pick the type that matches the hardware:
   • Relay — locks, lights, fridge power (on / off / timed pulse).
   • PWM / analog out — dimmers, fan speed, servos.
   • Boolean sensor — anything on/off: buttons, motion (PIR), door/window contacts, water-leak, smoke, and alarm contacts. Choose the matching preset and it reports the moment it changes.
   • Temperature — DS18B20 probes (fridge, ambient).
   • Humidity — DHT22 sensors.
   • Counter — pulse / flow / footfall counting.
   • Analog in — general analog sensors.
3. For each channel, choose the GPIO pin it's wired to. The editor only offers pins that are safe for that job, flags strapping and input-only pins, and won't let you pick the boot pin. Tap the help icon (?) on a channel for exact wiring steps for the pin you chose — for example, how to wire a button to GPIO 18.
4. Save the device. You'll see a 6-character pairing code, valid for 15 minutes.

Step 3 — Pair the board

When the board powers on without being paired, it starts its own temporary Wi-Fi hotspot:

1. On your phone or laptop, join the Mavos-Setup Wi-Fi network the board broadcasts.
2. A setup screen opens. Enter your venue's Wi-Fi name and password so the board can reach the internet, and the pairing code from the device page.
3. The board connects, pairs, and within a few seconds shows online on its device page.

If the code expires before you finish, generate a fresh one with Regenerate code on the device page.

Step 4 — Wire it up and test

1. Wire each channel to the GPIO pin you assigned (use the per-channel help for the exact steps). Power locks, lights, and motors from their own supply through the relay — never directly from the board.
2. On the device page, use the On / Off / Pulse buttons to test a relay, and watch a sensor's recent readings update on its chart.
3. Build a Rule to automate it — for example, pulse the lock relay when an order is paid — or group commands into a Scene.

Wiring tips

• The ESP32 runs at 3.3V logic. Most sensors are fine, but a 5V sensor output should be dropped to 3.3V with a divider or level shifter before it reaches a pin.
• For a fridge or freezer lock, use a timed pulse so it always re-locks, and add a door switch so a rule can confirm the door closed.
• Use an ADC1 pin (GPIO 32–36, 39) for analog sensors — these read reliably while Wi-Fi is on.
• Avoid GPIO 0 (the editor blocks it): it's the boot pin and using it can make the board reset itself.

Troubleshooting

See also the Wiring reference for per-sensor diagrams, and Common questions. Need a hand? Contact support.