ModBee Node-UIO Hardware

This document describes the Node-UIO board as drawn in the schematic,
../schematics/modbee-node-uio.pdf
(KiCad, Rev 0.01, 2025-05-16). Sheet numbers below refer to that PDF:

Where the schematic does not give a value (for example a part number or a
resistor value), this document says so rather than guess. Check the schematic
and the board itself for those items.

For the software interface, see API.md.

Overview

The Node-UIO is an I/O module built around the Espressif ESP32-S3FH4R2. It has:

• 8 opto-isolated digital inputs in two groups, each group with its own common
• 8 opto-isolated high-side (sourcing) MOSFET digital outputs
• 4 analog inputs on an ADS1115 16-bit ADC, 0-20 mA or 0-10 V per channel (solder bridge)
• 2 analog outputs on a GP8413 15-bit DAC, 0-10 V or 0-20 mA per channel (solder bridge)
• 2 RS485 ports
• 2.4 GHz Wi-Fi and Bluetooth LE (in the ESP32-S3)
• 2 Grove I2C connectors and two 8-pin stackable HAT headers
• An addressable RGB status LED and Reset, Boot and WiFi buttons
• USB-C (native USB of the ESP32-S3)

Specifications

Part numbers not stated on the schematic: buck regulator U3, RS485
transceivers U2/U4, opto-couplers U5-U8, output MOSFETs Q11-Q18, input
transistors Q3-Q10, fuse F1, USB ESD device U10, and the protection diodes.
Their ratings are therefore not given here.

GPIO map

Every ESP32-S3 pin the board connects (sheet 1), and what the library does
with it.

Notes:

• GPIO 3 is a strapping pin (JTAG signal source). It is only sampled if the
  eFuse that enables that selection has been burned. On this board it is DI03.
• GPIO 39-42 are the ESP32-S3 pin JTAG interface. GPIO 39 and 40 are used by
  the LED and the WiFi button, so JTAG over pins is not available. JTAG over
  USB (the USB Serial/JTAG controller) is unaffected.
• Only GPIO 0-21 are RTC-capable on the ESP32-S3. That is why DO01-DO04
  (GPIO 11-14) and the HAT enable (GPIO 9) can keep their level through deep
  sleep and DO05-DO08 (GPIO 33-36) cannot.
• The schematic's names for the RS485 UART nets (U1, U2) do not fix which UART
  peripheral is used. The ESP32-S3 routes any UART to any of these pins.

Power

Sheet 2, "Synchronous Buck".

Input connector J2

Supply rails

• F1 is drawn as a resettable (PTC) fuse. Its rating is not stated.
• U3 output is set by the feedback divider R16 (100 kOhm) / R17 (22 kOhm).
  U3's part number is not stated.
• D8 with R19 (2.2 kOhm) is a power indicator LED on the 3.3 V rail.
• The "Voltage Supervisor" block (IC1, a MAX809 footprint, and C28) is marked
  not fitted. Its note reads "Monitor 3.3v rail and switch off MCU
  automatically or reset while being powered from 1s Batt".

Powering from USB only

USB VBUS reaches only the buck input. D4 stops it reaching V_IN, so on USB
power alone V_Supply and V_Supply_F are not powered (sheet 2). In that
condition:

• the GP8413 DAC has no supply, so the analog outputs do not work and
  begin() reports the DAC missing (the status LED shows red);
• the digital outputs have no supply as shipped (V_Switch comes from
  V_Supply);
• HAT J7 pin 1 (V_Supply_F) is not powered.

The ESP32-S3, the ADC, the RS485 ports, the digital input logic, the Grove
connectors and HAT J6 pin 1 (3.3 V) work from USB.

Supply voltage for the analog outputs

The GP8413 datasheet gives a supply range of 9-36 V (typical 12 V). Its VCC is
V_Supply_F, which is V_IN less the drop across F1 and D2. The analog outputs
therefore need V_IN of at least 9 V plus those drops. At the low end of the
board's 5-24 V input range they are outside the converter's specification.

Digital inputs

Sheet 3, "A Digital Inputs 1-4" and "B Digital Inputs 5-8".

Terminal J8

Circuit

Each input feeds the LED of an opto-coupler (U5, U6) through 5.1 kOhm. A
second branch, 10 kOhm and an indicator LED (D11-D18), lights when the input
is on. The opto-coupler output drives a PNP transistor (Q3-Q10) whose
collector, with a 47 kOhm pull-down, is the GPIO.

• Rated input: 5-24 V DC (sheet 3 note).
• Polarity: current flows into the DI terminal and out through the group's
  return. The DI terminal must be positive with respect to that return.
• Logic: an energised input reads high at the GPIO. digitalIn() returns
  true for an energised input.
• Group return: the opto LED returns of each group go to the centre pad of a
  three-pad solder jumper (JP4 for DI01-DI04, JP5 for DI05-DI08). Pad 1 is
  board GND and pad 3 is the group's COM terminal. The sheet note reads "Cut
  bridge 1&2 to use isolated supply". As shipped (pads 1-2 bridged), the inputs
  return to board GND and are not isolated from it. See
  Solder bridges.

Library features

• Wake from sleep: sleep() takes a mask of inputs that wake the board on a
  high level (ESP32-S3 ext1 wake).
• Pulse counting: pulseStart(), pulseCount() and pulseStop() count
  rising edges on any input with the ESP32-S3 pulse counter (PCNT). The chip
  has four counter units, so four inputs can be counted at once. The maximum
  pulse rate the input circuit passes is not specified.

Digital outputs

Sheet 4, "A Digital Outputs 1-4" and "B Digital Outputs 5-8".

Terminal J9

Circuit

The GPIO drives the LED of an opto-coupler (U7, U8) through 470 Ohm, with a
47 kOhm pull-down. Each output MOSFET (Q11-Q18) is a high-side switch between
V_Switch and the DO terminal. Its gate is held to V_Switch by 10 kOhm and a
clamp diode, and the opto-coupler pulls it toward G_Switch through 1 kOhm to
turn the output on. When the output is on, the DO terminal is connected to
V_Switch.

• The outputs source current. Connect the load between the DO terminal and the
  supply return (GND, or GSW on J9 pin 10).
• Each output has an indicator LED (D23-D26, D35-D38) and a diode from the
  output to G_Switch (D27-D30, D39-D42).
• All eight outputs share one V_Switch and one G_Switch. The "A" and "B"
  groups are separate drawings, not separate supplies.
• Ratings (sheet 4 note): "5-24v Outputs switched from Input Supply by default
  100ma MAX per output. If jumpers cut or separate supply wire used in
  terminal 5 500ma MAX per output."
• Supply selection: JP6 (pad 1 V_Supply, pad 2 V_Switch, pad 3 J9 pin 5) and
  JP7 (pad 1 GND, pad 2 G_Switch, pad 3 J9 pin 10). The sheet note reads "Cut
  Bridge 1&2 to use an Isolated separate supply and Ground". See
  Solder bridges.

Library behaviour

• begin() drives every output low before anything else.
• setDigitalOut() sets an output and digitalOut() reads the commanded
  state back. The pins are written on each update().
• In deep sleep, DO01-DO04 can be held at a chosen level (the
  outputsInSleep argument of sleep()). DO05-DO08 are outside the RTC domain
  and turn off.

Analog inputs

Sheet 5, "0-20ma/0-10v Analog Inputs" and "ADS1115 16bit ADC".

Terminal J10

Circuit

Per channel: a shunt resistor (R100-R103) to GND through a solder bridge
(JP8-JP11), then 1 kOhm in series, clamp diodes, and a 47 kOhm / 12 kOhm divider
to the ADC input, with clamp diodes to 3.3 V and GND and 100 nF to GND.

• As shipped, the bridge is closed and the channel measures 0-20 mA (sheet 5
  note: "0-20ma Default Cut Bridge to use 0-10v").
• Cut the channel's bridge for 0-10 V.
• The shunt resistor values are not stated on the schematic.
• In 0-10 V mode the terminal sees 60 kOhm to GND (1 + 47 + 12 kOhm), and the
  ADC pin sees 12/60 of the terminal voltage. With the converter at
  +/-2.048 V, its full count therefore corresponds to 10.24 V at the terminal,
  so an uncalibrated 0-10 V reading is about 2.3 % low. Calibrate each channel
  (see below).

Converter

• ADS1115IDGS (U9), supplied from 3.3 V.
• I2C address 0x49: ADDR is tied to VDD (sheet 5 note "Default I2c Address
  0x49"; ADS1115 datasheet, ADDR pin table).
• On the internal bus, GPIO 37 (SDA) / GPIO 38 (SCL).
• ALERT/RDY is pulled up through 10 kOhm and not connected to the MCU.
• The library sets the full-scale range to +/-2.048 V (the sheet 5 note asks
  for this), single-shot mode, 250 samples per second, and converts the four
  channels in turn.

Range in software

The solder bridge sets what a terminal accepts. setInputRange() only sets
the scaling, and it defaults to UIO_VOLTAGE on every channel. A channel left
in the factory 0-20 mA configuration must be set to UIO_CURRENT by the
program, or its reading is wrong.

Uncalibrated, the library maps the converter's full count (32767) to 10 V or
20 mA. Use setInputCalibration(), saveCalibration() and
resetCalibration() for two-point calibration, which is stored in NVS.
analogInRaw() returns the converter count.

Analog outputs

Sheet 5, "0-20ma/0-10v Analog Outputs".

Terminal J11

Circuit

• GP8413 (IC2), dual-channel 15-bit voltage-output DAC. VOUT0 is AO01 and
  VOUT1 is AO02.
• Supply VCC from V_Supply_F. The datasheet range is 9-36 V; see
  Power.
• I2C address 0x5F: A0, A1 and A2 are tied to 3.3 V (sheet 5 note "Default
  I2c Address 0x5F"). The GP8413 address is 0x58 plus A2-A0.
• On the internal bus, GPIO 37 (SDA) / GPIO 38 (SCL).
• Each output has 100 nF and a clamp diode (D63, D64) to GND.
• Range: a three-pad solder bridge per channel (JP12 for AO01, JP13 for AO02).
  Pad 1 is the DAC output, pad 3 is the DAC output through a series resistor
  (R120, R121), and pad 2 is the terminal. As shipped, pads 1-2 are bridged
  and the output is 0-10 V. The sheet note reads "0-10v Default Cut Bridge 1&2
  to use 0-20ma". The terminal then connects only through pad 3, so pads 2-3
  must be bridged. R120 and R121 values are not stated on the schematic.
• In 0-20 mA mode the output is the DAC voltage through the series resistor.
  The GP8413 is a voltage-output converter, so the current also depends on
  the load resistance. Calibrate against the actual load.
• The GP8413 datasheet does not state an output current rating.

Library behaviour

• begin() sets the GP8413 to its 0-10 V range.
• setAnalogOut() takes volts or milliamps according to setOutputRange(),
  which defaults to UIO_VOLTAGE. That matches the factory bridge.
• Uncalibrated, 10 V or 20 mA maps to the full count (32767).
  setOutputCalibration() adjusts this. analogOutRaw() returns the count
  written.
• The DAC is written only when a value changes.

RS485

Sheet 2, "RS485 Transceiver CH1" (port 0) and "RS485 Transceiver CH2"
(port 1). The board provides the transceivers only. This library does not open
the ports. Modbus RTU or ModBee protocol libraries can run over them.

Terminal J3

The A and B lines of both ports are also on HAT header J7.

Per port

• Direction: DE and RE of each transceiver are tied to 3.3 V on the
  schematic. No GPIO controls direction. The transceiver part number is not
  stated; see the schematic.
• RO and DI each have a 10 kOhm pull-up to 3.3 V.
• Termination: the sheet note reads "Cut Bridge to disable 120ohm EOL
  termination resistor". Fit termination only at the two ends of a bus.
• Pins: the Arduino-ESP32 core's default pins for Serial1 and Serial2 on
  the ESP32-S3 are not these. Pass the RX and TX pins above when opening a
  port.

Expansion

HAT headers J6 and J7

Sheet 2, "Stackable Header Pins for Hats".

Sheet 2 note: "V_Supply_F Fused Supply to Hat. V_IN Supply AUX power From
Hat". The note also advises a diode on the HAT if needed. J7 pin 3 connects
directly to V_IN, ahead of the fuse. A HAT can supply the board through it.

HAT power enable: the base board connects GPIO 9 to J6 pin 7 and nothing
else. It has no switch of its own on this line, so any switching is done on
the HAT. The library drives GPIO 9 with setHatPower() (low after begin())
and reports it with hatPower(). sleep() can hold it through deep sleep
(hatInSleep).

Grove connectors J4 and J5

Sheet 2, note "Grove Connectors I2C 3.3V MAX". Both connectors are identical:

Use 3.3 V I2C devices only. The bus has 4.7 kOhm pull-ups to 3.3 V (R2, R3).

Two I2C buses

The schematic has two separate I2C buses:

begin() starts both: Wire1 for the converters and Wire for the
expansion bus. The library's expansion functions (i2cProbe(),
expansionBus()) use Wire, so they reach what is plugged into the Grove
connectors and the HAT header. The converters have their bus to themselves,
so any address is free on the expansion bus, including 0x49 and 0x5F.

Buttons and LEDs

WiFi button: the sheet 2 note gives the intended use, "Short Press Enable WIFI
for set time. Long Press Reset EEPROM Press > 30sec". The library does not
implement either action. It reports presses: button(), buttonHeldMs(),
takeShortPress() and takeLongPress(). A long press defaults to 2000 ms
(setButtonLongMs()), with 30 ms debounce (setButtonDebounceMs()).
setRadioPolicy() and requestRadio() are the library's radio duty-cycle
controls, which a program can tie to the button.

Status LED: until setLed() is called, the library shows green when both the
ADS1115 and the GP8413 answered at begin() and red when either did not.
setLed() takes the LED over. sleep() can leave it at a dim blue
(ledInSleep).

Solder-bridge configuration

All configuration is by solder jumper. There is no software control of any of
these. "As shipped" is taken from the sheet notes. Check the board before you
rely on it, especially for JP1, which has no note.

The state of pads 2-3 on JP4-JP7, as shipped, is not shown on the schematic.

Not fitted (marked DNP on the schematic): IC1 (MAX809 supervisor) and C28 on
sheet 2; C17, C18 and R9 (antenna matching) on sheet 1.

Programming

• Connector: USB-C J1, wired to the ESP32-S3 native USB pins (GPIO 19/20).
  CC1 and CC2 have 5.1 kOhm pull-downs (R7, R8). There is no USB-to-UART
  bridge.
• Serial: the example build (platformio.ini) sets ARDUINO_USB_MODE=1 and
  ARDUINO_USB_CDC_ON_BOOT=1, so Serial is USB CDC on the native port. UART0
  (GPIO 43/44) goes only to HAT header J6.
• Download mode: hold BOOT (SW2), press and release RESET (SW1), then release
  BOOT. With GPIO 0 low at reset and GPIO 46 low (not connected; internal
  pull-down), the ESP32-S3 enters joint download boot, which includes USB
  download.
• Debug: JTAG is available over USB (USB Serial/JTAG controller). It is not
  available over pins, because GPIO 39 and 40 are used on the board.

For the software interface, see API.md.