Sensor Wiring
This guide covers physical wiring and configuration parameters for all sensor types supported by the RIoT ESP32 firmware. Each section includes pin assignments, wiring requirements, and the params fields accepted in config.json.
Refer to Sensors for the software-side configuration schema and reading formats.
GPIO Pin Map
The ESP32 firmware reserves the following GPIO pins for peripheral communication.
| Function | GPIO | Description |
|---|---|---|
| I2C SDA | 21 | I2C data line |
| I2C SCL | 22 | I2C clock line |
| CAN TX | 27 | CAN bus transmit |
| CAN RX | 25 | CAN bus receive |
| ADC | 32--39 | Analog input channels (ADC1 only) |
| UART RX | Configurable | GPS receiver input |
| UART TX | Configurable | GPS module output |
ADC pins 32--39 belong to ADC1. Do not use ADC2 pins (GPIO 0, 2, 4, 12--15, 25--27) -- they conflict with Wi-Fi.
I2C Sensors
All I2C sensors share a single bus on GPIO 21 (SDA) and GPIO 22 (SCL).
Wiring requirements:
- Install 4.7 kΩ pull-up resistors from SDA to 3.3V and from SCL to 3.3V. One pair per bus is sufficient -- do not add additional pull-ups per sensor.
- Keep total I2C cable length under 1 meter. Longer runs degrade signal integrity and cause read failures.
- Use shielded cable in environments with high electromagnetic interference.
- Connect all I2C sensors in parallel to the same SDA/SCL lines. Each sensor is addressed by its fixed or configurable I2C address.
Bus sharing: Multiple I2C sensors coexist on the same bus provided their addresses do not collide. The ADXL345 address is selectable via the SDO pin (0x53 or 0x1D). SHT2x/SHT3x/SHT4x devices have fixed addresses -- consult the datasheet before adding a second sensor of the same family.
ESP32 Sensor (I2C)
───── ────────────
GPIO 21 (SDA) ──┬──── SDA
│
4.7kΩ
│
3.3V
GPIO 22 (SCL) ──┬──── SCL
│
4.7kΩ
│
3.3V
3.3V ──────────────── VCC
GND ──────────────── GND
ADXL345
3-axis accelerometer. I2C interface at address 0x53 (SDO tied to GND) or 0x1D (SDO tied to VCC).
Wiring notes:
- Connect SDA, SCL, VCC (3.3V), and GND as shown in the I2C diagram above.
- Tie the CS pin to VCC to select I2C mode.
- Tie SDO to GND for address 0x53, or to VCC for address 0x1D.
- Mount the sensor rigidly to the surface under measurement. Vibration isolation defeats the purpose of acceleration monitoring.
Configuration parameters:
| Parameter | Type | Values | Default | Description |
|---|---|---|---|---|
range | string | 2g, 4g, 8g, 16g | 16g | Measurement range. Lower range yields higher resolution. |
data_rate | float | 0.1--3200 Hz | 100 | Output data rate in Hz. Higher rates increase power consumption. |
enable_fifo | boolean | true, false | false | Buffer readings in the sensor FIFO. Reduces I2C traffic for high data rates. |
tap_detection | boolean | true, false | false | Enable single/double tap event detection. |
free_fall_detection | boolean | true, false | false | Enable free-fall event detection. |
SHT21 / SHT3x / SHT4x
Temperature and relative humidity sensors. I2C interface.
| Sensor | I2C Address | Voltage | Accuracy (typical) |
|---|---|---|---|
| SHT21 | 0x40 | 3.3V | +/-0.3 C, +/-2% RH |
| SHT3x | 0x44 or 0x45 | 3.3V | +/-0.2 C, +/-2% RH |
| SHT4x | 0x44 | 3.3V | +/-0.1 C, +/-1.8% RH |
Wiring notes:
- Connect SDA, SCL, VCC (3.3V), and GND as shown in the I2C diagram above.
- Place a 100 nF decoupling capacitor between VCC and GND, as close to the sensor as possible.
- Avoid routing I2C traces near heat sources. Radiated heat from nearby components will bias temperature readings.
- If a second SHT3x is needed on the same bus, set the ADDR pin high to select address 0x45.
Configuration parameters (SHT21):
| Parameter | Type | Values | Default | Description |
|---|---|---|---|---|
resolution | string | 12bit_14bit, 11bit_11bit, 10bit_13bit, 8bit_12bit | 12bit_14bit | Humidity/temperature resolution pair. Higher resolution increases measurement time. |
heater_enable | boolean | true, false | false | Activate the on-chip heater. Use briefly to drive off condensation -- do not leave enabled during normal operation. |
SHT3x and SHT4x sensors use the same params schema with resolution and heater_enable fields. Consult the firmware changelog for any model-specific extensions.
Analog Sensors
Analog sensors connect to ADC1 pins (GPIO 32--39). The firmware reads a 12-bit raw value and applies a linear transform: output = (raw * scale) + offset.
Wiring notes:
- Connect the sensor output to one of GPIO 32--39. Do not exceed 3.3V on the input.
- For sensors that output 0--5V, use a resistor voltage divider to scale the signal to 0--3.3V.
- For sensors that output 4--20 mA, place a precision resistor (e.g., 165 Ω) to ground and read the voltage across it.
- Keep analog signal wires away from digital lines and power traces to minimize noise.
Attenuation: The ESP32 ADC attenuation setting controls the input voltage range.
| Attenuation | Input Range | Notes |
|---|---|---|
| 0 dB | 0--1.1V | Highest accuracy, narrowest range. |
| 2.5 dB | 0--1.5V | |
| 6 dB | 0--2.2V | |
| 11 dB | 0--3.3V | Full range. Reduced linearity at extremes. |
Configuration parameters:
| Parameter | Type | Values | Default | Description |
|---|---|---|---|---|
gpio | integer | 32--39 | -- | ADC1 GPIO pin number. Required. |
scale | float | any | 1.0 | Multiplier applied to the raw 12-bit ADC value. |
offset | float | any | 0.0 | Offset added after scaling. |
attenuation | string | 0dB, 2.5dB, 6dB, 11dB | 11dB | ADC input attenuation. Determines the measurable voltage range. |
Digital Sensors
Binary-state sensors (switches, relays, proximity sensors) connect to any available GPIO pin.
Wiring notes:
- Connect the sensor output to the selected GPIO pin. Connect the other terminal to GND (for active-low) or 3.3V (for active-high).
- Enable the internal pull-up resistor in configuration if no external pull-up is present on the line.
- For open-collector or open-drain outputs, enable
pull_upand setinvert_logicas needed. - Mechanical switches require debounce. Set
debounce_msto suppress contact bounce -- 50 ms is a typical starting value.
Configuration parameters:
| Parameter | Type | Values | Default | Description |
|---|---|---|---|---|
gpio | integer | any valid GPIO | -- | GPIO pin number. Required. |
pull_up | boolean | true, false | false | Enable the ESP32 internal pull-up resistor (~45 kΩ). |
invert_logic | boolean | true, false | false | Invert the logical reading. When true, a low voltage reads as HIGH. |
debounce_ms | integer | 0--5000 | 0 | Debounce interval in milliseconds. Readings within this window after a state change are suppressed. |
GPS Module
UART-based GPS receivers (NEO-8M, A9G, or compatible) connect to a configurable UART port on the ESP32.
Wiring notes:
- Connect the GPS module TX pin to the ESP32 RX pin, and the GPS module RX pin to the ESP32 TX pin (crossover).
- Power the GPS module from 3.3V or 5V depending on the module datasheet. If the module operates at 5V logic, add a level shifter on the data lines.
- Ensure the GPS antenna has a clear view of the sky. Indoor installations require an external active antenna.
- The default baud rate for most NMEA GPS modules is 9600. Do not change the baud rate unless the module firmware has been reconfigured to match.
ESP32 GPS Module
───── ──────────
RX pin (configurable) ──── TX
TX pin (configurable) ──── RX
3.3V ───────────────────── VCC
GND ───────────────────── GND
Configuration parameters:
| Parameter | Type | Values | Default | Description |
|---|---|---|---|---|
uart_num | integer | 1, 2 | 1 | ESP32 UART peripheral number. UART0 is reserved for debug console. |
rx_pin | integer | any valid GPIO | -- | GPIO pin for UART RX (connects to GPS TX). Required. |
tx_pin | integer | any valid GPIO | -- | GPIO pin for UART TX (connects to GPS RX). Required. |
baud_rate | integer | 4800, 9600, 19200, 38400, 57600, 115200 | 9600 | UART baud rate. Must match the GPS module configuration. |
CAN Bus
The CAN bus interface uses an external CAN transceiver (e.g., MCP2551, SN65HVD230) connected to the ESP32 TWAI peripheral.
Wiring notes:
- Connect ESP32 GPIO 27 (TX) to the transceiver TXD input, and GPIO 25 (RX) to the transceiver RXD output.
- The transceiver connects to the CAN bus via CANH and CANL differential lines.
- Install 120 Ω termination resistors between CANH and CANL at both physical ends of the bus. Omitting termination causes reflections and communication failures.
- Use twisted-pair cable for the CANH/CANL bus. Maximum bus length depends on bitrate -- 40 m at 1 Mbit/s, 500 m at 125 kbit/s.
- Do not exceed 30 nodes on a single bus segment.
ESP32 CAN Transceiver CAN Bus
───── ─────────────── ───────
GPIO 27 (TX) ──────── TXD
GPIO 25 (RX) ──────── RXD
3.3V ─────────────── VCC
GND ─────────────── GND
CANH ────────────┬───── CANH
120Ω │
CANL ────────────┴───── CANL
The CAN bus bitrate is configured in the device firmware, not in config.json. Consult the firmware documentation for bitrate selection and filter configuration.