Skip to content

Rotary controls and external notification outputs

This repository's Full Companion on ESP32, nRF52 and RP2040 supports a user-wired incremental rotary encoder, an optional push switch, a passive buzzer, and separate notification, GPS and Bluetooth LEDs. All assignments start disabled. Settings are saved separately from the node preferences and take effect without reboot. The encoder needs a supported display UI; outputs also work without a display. Existing board-provided encoders remain the default until a custom encoder is enabled.

Heltec V4.3 preview: download 1.18.0.3 Preview 1 for ESP32-S3R2 (not R8). Use *-merged.bin for USB installation; use the application .bin for Wi-Fi only with a compatible existing Full partition layout. Build and host checks passed; physical accessory qualification is pending.

For the EC11, buzzer and three LEDs: OLED needs no expander after the OLED selection and reboot. TFT uses an expander for the encoder and LEDs, leaving native GPIO6 for the buzzer.

Connect and configure an encoder

Disconnect USB, the battery and any solar/external supply before soldering. Use an incremental quadrature encoder, such as an EC11 with A, B and common contacts plus a separate normally-open push switch. A three-terminal analog potentiometer is not a substitute. Identify the actual terminals from the component documentation or a continuity test; shaft shape and photographs do not establish its pinout or whether a switch is fitted.

Use 3.3 V signals and a common ground. Connect the encoder's common contact to ground, A/CLK and B/DT to two available MCU pins, and the optional normally-open push switch between its selected pin and ground. Powered encoder modules must also use 3.3 V. Internal pull-ups are enabled by default.

First inspect the running image:

get rotary
get rotary.pins.available

The list shows rotation-input pins for the current pull-up setting, excluding pins held by other functions. A board's existing active-low user-button pin can additionally be selected as the push switch, even when absent from that list. Every wire must use a different physical pad.

Command Effect
set rotary.pins <CLK>,<DT>[,<SW>] Select Arduino GPIOs or ESP32 expander xN pins; omit SW or use -1 for no switch
set rotary on / set rotary off Enable the selected encoder, or release its pins
set rotary.steps <1..255> Electrical transitions per detent; default 4
set rotary.reverse on / off Reverse the turn direction
set rotary.pullup on / off Select internal pull-ups or external pull resistors
get rotary.pins, .steps, .reverse, .pullup Read an individual setting

Select the pins before enabling. Turning the encoder moves through the new menu UI; pressing selects, and holding uses the existing long-press action. A sleeping screen wakes before a switch action is performed. The original status UI retains its existing page/button actions. If a detent moves twice or needs two detents, adjust rotary.steps; if direction is reversed, change rotary.reverse. Test the actual encoder at your intended turning speed: a polling driver cannot reconstruct electrical transitions missed between polls.

With power saving enabled, fast rotation polling runs while the screen is on. Rotation is ignored while the screen is off; the optional push switch still wakes it. With power saving disabled, rotation continues to be sampled with the screen off. During fast polling, ESP32 skips manual CPU sleep and uses a short cooperative yield; WiFi/Bluetooth modem power saving remains available. nRF52/RP2040 use GPIO-change wakeups and stay awake for switch debounce/hold deadlines. set rotary off releases the pins and restores normal manual sleep behavior.

On classic ESP32, GPIO34 through GPIO39 cannot supply internal pull-ups and cannot drive outputs. Set rotary.pullup off before selecting a permitted input-only pin, and fit external pull resistors on every encoder wire.

Heltec V4.2/V4.3 with the unified OLED/TFT image

The standard native-USB image permits this encoder assignment, subject to get rotary.pins.available on the actual installed image:

get rotary
set rotary.pullup on
get rotary.pins.available
set rotary.pins 6,43,0
set rotary.steps 4
set rotary on
get rotary

This assignment is checked against the firmware pin policy; test physical encoder operation on your hardware before relying on it.

Encoder terminal Connection on the native-USB Full Companion
A / CLK GPIO6
B / DT GPIO43 through a 1 kohm series resistor
Common / C GND
One push-switch contact GPIO0
Other push-switch contact GND

These are GPIO numbers, not positions in the header. A bare mechanical encoder needs no 5 V supply. Use the two actual switch contacts, not mounting tabs.

GPIO0 reuses the existing user button. Release the switch during reset to avoid entering the board's download mode. GPIO43 is available here because the console uses native USB CDC; it remains reserved in a UART-console image or when an explicit serial/bridge assignment claims it.

Fit a 1 kohm series resistor between GPIO43 and the encoder contact. The ESP32-S3 ROM can drive UART0 TX on this pad before firmware starts, even when the application console uses USB. The resistor limits current while that contact is grounded. See Espressif's ESP32-S3 startup wiring.

In the default Auto mode, the unified image protects the union of OLED, TFT and touch-controller pins, even if startup detects only an OLED or no display. GPIO44, GPIO47 and GPIO48 remain reserved for touch reset/I2C, and GPIO40/41 remain reserved for GNSS wake/PPS. Radio, GNSS, battery, memory, debug and USB nets also stay protected. After GPIO6/43 are allocated to this encoder, Auto mode has no spare permitted native GPIO for the four additional outputs. The ESP32 I2C expander arrangement moves the encoder and LEDs to an external chip and frees GPIO6 for the passive buzzer. Alternatively, explicitly select OLED expansion mode and reboot to use four native output pins. Do not substitute display or GNSS pins merely because an accessory was not detected.

In particular, the following proposed LED/buzzer assignments are not valid in Auto mode:

Proposed connection Why the pin is unavailable
Notification LED on GPIO35 The board's built-in LED already uses this pin; firmware reserves it.
GPS LED on GPIO34 This controls the GNSS power supply. It is not an external status-LED output.
Bluetooth LED on GPIO36 This controls the Vext power rail. Toggling it would change peripheral power.
Passive buzzer on GPIO33 Auto mode reserves it for TFT display data, including when only an OLED is detected. Explicit OLED mode plus reboot can release it.

The GPIO34/35/36 board connections are documented in Heltec's V4 pin map and V4.3 schematic. This mapping is for the ESP32-S3R2 board, not the V4 R8 variant.

Check get peripheral.pins.available after assigning the encoder. An empty GPIO list means there are no permitted output pins left. The commands below do not override reservations. For an encoder plus three independent LEDs and a buzzer, use hardware with enough available pins or an expansion design with matching firmware support. ESP32 Full Companion can use explicitly named expander pins for rotary inputs and LEDs; a passive buzzer still needs a native waveform output/driver.

OLED expansion mode in the same unified firmware

For a V4/V4.3 ESP32-S3R2 with only an OLED, the unified Full Companion firmware can release GPIO33, GPIO44, GPIO47 and GPIO48 for accessories. This is an explicit boot profile: saving display.type oled and rebooting releases the pins. Auto-detection of an OLED does not. Do not attach the TFT/touch expansion kit in this mode. It does not apply to V4 R8 boards.

With the 1.18.0.3 preview installed, enter separately:

set display.type oled
reboot

Reconnect and check get display.type: it should report oled without reboot required. Disconnect power before adding wires.

Component Connection
Encoder CLK GPIO6
Encoder DT GPIO43 through 1 kohm
Encoder switch GPIO0
Encoder common and switch ground GND
Passive buzzer signal GPIO33, with a suitable driver if required
Notification LED positive GPIO44 through its current-limiting resistor
GPS LED positive GPIO47 through its current-limiting resistor
Bluetooth LED positive GPIO48 through its current-limiting resistor
Buzzer and LED negatives GND

After reconnecting:

set rotary.pins 6,43,0
set rotary.steps 4
set rotary on
set peripheral.buzzer 33
set peripheral.led.notify 44
set peripheral.led.gps 47
set peripheral.led.ble 48

The usual sound/mute and alert rules still apply. GPIO38/39 and GPIO40/41 remain reserved for GNSS. Native USB must be enabled to use GPIO43/44 this way. Release the encoder button during reset. Prewired LEDs with verified suitable built-in resistors do not need another series resistor.

Clear assignments and remove accessory wiring from these four pins before using the TFT/touch kit. Save set display.type auto and reboot to restore the default TFT/OLED pin protections. Profile changes never release pins immediately while the old display is running.

Passive buzzer and status LEDs

Use current-limiting resistors for LEDs, and an appropriate driver when a buzzer or other load exceeds the GPIO's current rating. Native LED outputs default to active high. ESP32 native and expander LEDs accept ,low or ,high; nRF52/RP2040 native outputs remain active high.

Check the electrical ratings before choosing outputs

  • Pre-wired LEDs: verify that each assembly actually contains a series resistor and check its value/current specification. A listing that says "5 V" or "3-5 V" does not establish the resistor value or guarantee useful brightness from a 3.3 V GPIO. Use an assembly specified for 3.3 V, or check the current using its resistor value and the LED's forward voltage. Keep the resistor in circuit; positive goes to an available output and negative to common ground for direct active-high drive.
  • 5 V loads: a separate 5 V supply requires an appropriate driver and common ground. Do not connect 5 V to an ESP32-S3 GPIO; the chip's pins are not 5 V tolerant.
  • Buzzer: use a passive transducer compatible with the generated tones. A black two-pin case or a polarity mark does not identify its type or current demand. Verify the part specification before connecting it directly. Use a suitable transistor/MOSFET driver for a higher-current or higher-voltage transducer, with a flyback diode for an inductive magnetic load. An active buzzer with its own oscillator is not a substitute for variable-pitch RTTTL playback.

Configure outputs on a board with available pins

Numeric pins below are Arduino MCU GPIOs. ESP32 Full Companion also accepts explicit xN expander pins for LEDs; see the expander guide.

get peripherals
get peripheral.pins.available
get peripheral.buzzer
set peripheral.buzzer <pin|off>
set peripheral.led.notify <pin|off>
set peripheral.led.gps <pin|off>
set peripheral.led.ble <pin|off>

Each set has a matching individual get. Inspect peripheral.pins.available and choose unused output-capable pins for the exact board. The notification LED indicates message arrivals and follows programmable alert patterns. The GPS LED indicates active GPS use. The Bluetooth LED stays on while the transport is enabled, including advertising; it does not distinguish a connected phone.

The selected passive buzzer replaces the built-in RTTTL output and follows the existing sound/mute settings. Configure melodies and LED patterns through the Companion notification builder. For example, set notify.sound channel:3 order:d=8,o=5,b=180:c,e,g,4c6 selects that channel's ringtone after the sound output is enabled. Assigning a buzzer does not unmute notifications or enable a disabled alert rule.

Pin protection and board coverage

Assignments are checked before pins are initialized. Radio/front-end, flash/PSRAM, USB, debug, strapping, display/touch, active buses, GPS, battery, charger and power-control pins are excluded. The push switch has a narrow exception for an existing active-low user button. In-use pins are locked across rotary inputs, custom outputs, programmable notification GPIO and ordinary user GPIO/timers. A low output remains owned until reset or reassignment. nRF52/STM32 Arduino aliases of one pad share one claim.

The board policy covers ESP32, S2, S3, C3 and C6. nRF52 expansion maps cover Heltec T096, ProMicro, RAK3401/4631 and XIAO/IKOKA boards. RP2040 maps cover Pico/Pico W, XIAO and RAK11310. STM32 LoRa-E5 Mini has a header map for explicit custom builds. Other boards require an audited USER_GPIO_ALLOWED_PINS list of exposed Arduino pins in the target or build flags. That allowlist never overrides hardware reservations. Use Arduino pin indices on nRF52/STM32, rather than raw MCU port numbers.

Station G2 is limited to its documented IO extension socket. Cardputer-Adv, T-Deck, SenseCAP Indicator and Wio Tracker L2 keep their internally wired display, keyboard/audio and control nets protected and require an audited expansion allowlist before accepting custom pins.

The MCU cannot detect extra wiring omitted from its board definition. Confirm the physical header and attached modules before using an allowed pin. Invalid saved records or pins that become reserved after an update are left inactive. A failed or unconfirmed save returns an error.

Custom builds

Full ESP32/nRF52/RP2040 images enable MESH_CUSTOM_PERIPHERALS=1 automatically. Legacy profiles and STM32 leave it off by default. Set the flag explicitly to opt in, or set UI_ROTARY_INPUT_GPIO=1 with the pin definitions below. MESH_CUSTOM_PERIPHERALS=0 disables the optional feature. Compact STM32 builds still need enough flash and a supported display UI for rotary navigation.

A direct PlatformIO environment in platformio.local.ini can opt the legacy V4 Bluetooth Companion into custom peripherals with the checked native-USB pin mapping. This example retains that profile's Bluetooth transport; the release builder selects the separate Full transport/profile configuration.

[env:heltec_v4_rotary]
extends = env:heltec_v4_companion_radio_ble_femon
build_flags =
  ${env:heltec_v4_companion_radio_ble_femon.build_flags}
  -D MESH_CUSTOM_PERIPHERALS=1
  -D UI_ROTARY_INPUT_GPIO=1
  -D PIN_ROTARY_CLK=6
  -D PIN_ROTARY_DT=43
  -D PIN_ROTARY_BUTTON=0
  -D ROTARY_TRANSITIONS_PER_DETENT=4

Build with pio run -e heltec_v4_rotary. Optional ROTARY_REVERSE=1 and ROTARY_PULLUP=0 change the defaults. An existing saved record takes precedence, including a saved disabled state. Every build default passes the same board pin checks as a CLI assignment.