MAVOS
Documentation

Automations & hardware

Wiring reference

How to physically wire each kind of channel — relays, buttons, motion, door contacts, temperature and humidity probes, analog sensors, and counters — with recommended pins and safety notes.

This is the companion to the per-channel help shown in the device editor. When you add a channel, tap the help icon (?) next to it for steps tailored to the exact pin you picked; this page is the fuller reference you can read end-to-end.

It applies to ESP32 and Raspberry Pi devices, which connect to real hardware through GPIO pins. (HTTP devices have no wiring — see Send readings over HTTP.)

Before you start — pin basics

  • Both boards use 3.3V logic. A sensor that outputs 5V should be dropped to 3.3V with a divider or level shifter before its signal reaches a pin.
  • On the ESP32, the editor lists only usable pins. Prefer plain GPIOs for outputs, and ADC1 pins (GPIO 32–36, 39) for analog inputs. GPIO 0 is blocked because it's the boot pin.
  • On the Raspberry Pi, pin numbers are BCM numbering, not the physical header position — find the pin with a Pi pinout (run pinout on the Pi).
  • Always share a common ground between the board, any driver board, and the load's own power supply.

Relay (output) — locks, lights, pumps

Parts: a relay module rated for your load, jumper wires, a separate supply for the load.

  1. Power the relay module: VCC to 5V (or 3.3V for a 3.3V module), GND to GND.
  2. Connect the module's IN pin to the channel's GPIO pin.
  3. Wire the load through the relay's COM and NO (normally-open) terminals, powered from its own supply.

Many relay modules are active-low (they switch on when the pin goes LOW). If on/off ends up reversed, turn on Invert (active-low) for the channel. Switching mains can be lethal and may legally require a licensed electrician — prefer low-voltage loads or a certified switched powerboard.

PWM / analog out — dimmers, fans, servos

Parts: a MOSFET module or LED/motor driver, a supply for the load.

  1. The pin is logic-level — don't drive a strip or motor straight from it.
  2. Connect the GPIO pin to the gate / PWM input of a MOSFET or driver board.
  3. Power the load from its own supply and share grounds. The output level (0–100%) sets the PWM duty.

Button (boolean sensor)

Parts: a momentary push button, 2 wires.

  1. One leg of the button to the GPIO pin, the other to GND.
  2. The internal pull-up keeps the pin HIGH when released; pressing pulls it LOW. No external resistor needed.

Use the Button preset; debounce smooths the contact.

Door / window contact (boolean sensor)

Parts: a reed switch or magnetic contact, 2 wires.

  1. Mount the magnet on the door/window and the switch on the frame so they meet when closed.
  2. Wire the contact between the GPIO pin and GND.

Use the Door / window preset. If Open/Closed look swapped, flip Triggered when, or swap a normally-open for a normally-closed contact.

Motion / PIR (boolean sensor)

Parts: a PIR module (e.g. HC-SR501), 3 wires.

  1. Power it: VCC to 5V, GND to GND.
  2. Connect the PIR's OUT to the GPIO pin.
  3. Give it ~1 minute after power-on to settle. Use the Motion (PIR) preset.

The HC-SR501's output is 3.3V-safe. A 5V-logic sensor needs its output dropped to 3.3V first.

Alarm / leak / smoke contact (boolean sensor)

Parts: a detector with a dry-contact or open-collector output, 2 wires.

  1. Wire the contact between the GPIO pin and GND.
  2. The pull-up idles the pin HIGH; on trigger the contact closes to GND. Use the Alarm / contact preset.

Use a detector's relay or open-collector output, not its supply rails, and test the whole path after wiring.

Temperature — DS18B20

Parts: a DS18B20 (bare or waterproof probe), a 4.7 kΩ resistor, 3 wires.

  1. The probe has VDD (red), GND (black), DATA (yellow).
  2. VDD to 3.3V, GND to GND, DATA to the GPIO pin.
  3. Add the 4.7 kΩ resistor between DATA and 3.3V — this 1-Wire pull-up is required.

On a Raspberry Pi the installer enables 1-Wire for you.

Humidity — DHT22

Parts: a DHT22 / AM2302, a 10 kΩ resistor (built into 3-pin modules), 3 wires.

  1. VCC to 3.3V, GND to GND, DATA to the GPIO pin.
  2. Add a 10 kΩ resistor between DATA and VCC unless your module already has one.
  3. Set a sample interval of 60 s or more — the sensor only refreshes every ~2 seconds.

Analog / battery

Parts: the sensor, plus resistors for a voltage divider if needed.

  1. An ADC pin reads 0–3.3V only — never connect a higher voltage directly.
  2. If the sensor's output stays within 0–3.3V, connect it straight to the pin; otherwise scale it with a voltage divider first.
  3. Share grounds. For battery monitoring, remember the pin sees a fraction of the real voltage — account for the divider ratio in your rule thresholds.

Prefer an ADC1 pin for a stable reading while Wi-Fi is on.

Counter — flow, footfall, pulses

Parts: your pulse source, wires.

  1. Connect the pulse output to the GPIO pin and its GND to the board's GND.
  2. Each pulse increments the count; debounce filters bounce on mechanical sources.
  3. An open-collector source needs a pull-up so the line returns HIGH between pulses.

Once wired, save the channel — the device applies the new configuration automatically within a few seconds; there's no code to write. See Common questions for more.