Buttons & Switches
NodeBlue groups under "buttons" the modules that turn a physical contact closure into a clean digital signal — push-buttons, toggle/SPDT switches, analog buttons (a button read through a resistor divider on an ADC pin), and the matrix-scan pattern that lets a small number of GPIOs read a much larger number of contacts. The plain digital pin readers (nDigitalInput, nDigitalInt) belong here too — they're the lowest-level building blocks the higher modules wrap.
The plain digital readers
These are the floor of the family — no debouncing, no toggling, just "is this pin high or low right now".
| Module | What it does | When to reach for it |
|---|---|---|
| nDigitalInput | Reads a digital pin on every Sync tick. Output u8 is 0 / 1 (with optional invert). Configurable pull mode. | The signal you're reading is already clean — a logic-level output from another chip, an opto-isolator, a Schmitt-triggered front end. |
| nDigitalInt | Same idea, but triggered by a pin interrupt (CHANGE / RISING / FALLING) rather than by a Sync. Adds itself to the InterruptSync group. The pin must be interrupt-capable on the target MCU. | You can't afford polling latency — a tachometer pulse, a hardware encoder index, an external event that may occur between ticks. |
Neither does debouncing. For a mechanical contact bouncing in free air, you want nButton instead.
See Examples/02-Digital/DigitalIn.
Push-buttons — nButton
nButton is the workhorse for a momentary contact wired between a digital pin and ground (or Vcc).
| Parameter | Description |
|---|---|
| Pin | Digital pin the button is wired to. |
| Pull | INPUT_PULLUP, INPUT, etc. Pick the matching pull so the un-pressed state is a stable logic level. |
| Debounce | Debounce time in ms. 10 is a safe default for clicky tact switches; long-throw arcade buttons may need 20–30. |
| DebounceMode | Template default DM_SAFE — see debounce modes below. |
| Invert | Flip the logic so "pressed" reads as 1 regardless of which rail you wired the common to. |
Output is a single u8 port that's 1 while the button is held, 0 otherwise. It auto-connects to any *Packer downstream (the HID buffer chain).
See Examples/02-Digital/Button.
Debounce modes
The shared DebounceMode parameter on every button-family module picks how the firmware deglitches the raw read. DM_SAFE is the right answer for almost every mechanical switch; the other modes are there for the corner cases where you'd rather optimise for speed or for specific bouncing profiles.
Push-button variants for value-style outputs
The plain nButton outputs a Boolean. The variants below produce an analog-style output instead — useful when the button is acting as a modifier on a numeric value rather than as a digital event.
| Module | Inputs | Output | What it does |
|---|---|---|---|
| nButtonGain | Gain (f32), In (u8) | f32 | While the button is pressed, the output equals the Gain input multiplied by the Gain parameter. Released, the output is 0. Typical sim-racing use: "flat-shift" modifier on a throttle value while a paddle is held. |
| nButtonToggle | Toggle, On, Off (u8 each) | u8 | Latching toggle. Each press of Toggle flips the state; On forces 1; Off forces 0. The latched state survives across cycles (unlike a momentary nButton). |
| nButtonGainToggle | Gain (f32), In (u8) | f32 | The toggle variant of nButtonGain — the Gain × multiplier output is latched on by In's rising edge and latched off by the next one. |
Each of those modules can also drive a physical pin directly (the Pin parameter is optional — leaving it as PIN_UNUSED makes the module purely "wire-driven"). The Pull / Debounce / Invert controls are hidden when no pin is wired.
See Examples/02-Digital/ButtonToggleLed for nButtonToggle driving an LED.
Toggle / SPDT switches — nToggleSwitch
A physical toggle has either two positions (SPDT — one moving, two outer pins) or three positions (centre-off). nToggleSwitch is a template module that handles both cases:
- Internally it instantiates one or two
nButtons (one per outer pin) sharing the same Pull / Debounce / Invert settings. - The output is one port per outer pin — only one is
1at a time (or none, for the centre position of a 3-position toggle).
| Parameter | Description |
|---|---|
| Pin 1 / Pin 2 | The two outer-pin GPIOs. For a 2-position switch only Pin 1 is used. |
| Nb Outputs | 1 for a centre-off / two-position behaviour, 2 for full SPDT or 3-position. |
| Pull / Debounce / Invert | Shared across both internal buttons. |
The centre position of a 3-position toggle is implicit — when neither pin is grounded, both outputs read 0.
A single button on an analog pin — nAnalogButton
When you want to put a single button on a pin that's already configured as an ADC input, nAnalogButton is the right reader. It reads the analog pin and uses a comparator with hysteresis to decide whether the voltage is in the "pressed" range.
| Parameter | Description |
|---|---|
| Pin | The analog pin. |
| ADC Ref / Resolution | Analog front-end tuning — same controls as nAnalogInput. |
| Debounce | Debounce time (ms). Often less critical than for digital buttons because the analog-domain comparator already smooths short glitches. |
| Invert | Flip the "high voltage = pressed" sense if you wired the resistor to the other rail. |
| Threshold (high / low) | The comparator's switching thresholds, in raw ADC units, volts, percent, or unsigned counts (selected by the Units sub-field). Hysteresis is the gap between the two — set it wide enough that one button press doesn't oscillate between the two states. |
Output is a u8 — 1 while the comparator says "pressed", 0 otherwise.
For several buttons sharing one analog pin, see the next section.
Several buttons on one analog pin
When you want to read multiple buttons through a single ADC pin, you have two options depending on whether you need simultaneous presses to be detected.
Resistor ladder — one button at a time
The simplest scheme: each button is wired through a different resistor in a resistor ladder, so each press produces a distinct analog voltage. The nResLadder module (covered in the Multiplexers tutorial) decodes that voltage to a position index.
The canonical chain:
nAnalogInput→nResLadder→nDeMultiplexer→ individual button outputs
That's exactly the chain inside nJoycoder. The constraint: only one button can be pressed at a time — if two are pressed, the resulting voltage is somewhere between two known values and the decoder picks the closest, which is wrong for both.
BODAC — several buttons pressed simultaneously
For multi-press detection, the BODAC (Buttons Organized as a Digital to Analog Converter) trick is the right answer. Each button switches in a resistor whose value is a different power of two, so the parallel combination of any subset of pressed buttons produces a unique analog value the firmware can decode back to the exact set. Up to 5 buttons on one analog pin, any combination at once, no diodes required.
The nBodac module handles the decode side. The hardware side is described in the BODAC product page; a typical wiring is shown in this wiring example. A 1.6 kΩ pull-up resistor on the analog line is required — several ElectroSeed boards already include it on-board (the MMWB family and the SamD21 WB series), so for those boards you just connect the BODAC PCB and skip the external pull-up.
| Parameter | Description |
|---|---|
| Pin | Analog pin reading the BODAC ladder voltage. |
| Nb Buttons | 2 to 5. |
| Debounce | Debounce time in ms. |
| K0..K4 | Calibration constants — the expected ADC value when only that button is pressed. Defaults match the standard BODAC PCB resistor values; the Cal / CalStop inputs let the firmware learn them from a live calibration sweep instead of trusting nominal values. |
| ADC Ref / Resolution / Average | Analog front-end tuning. |
Output: one u8 per button (0/1), plus a buffer Msg port carrying calibration-progress text — wire that into a serial / dashboard / Nextion display while you calibrate.
A standalone tutorial covers the BODAC end-to-end: BODAC — multi-press analog buttons.
Many buttons on few pins — nDigitalMatrix
For larger button counts that don't fit on a single analog pin (more than ~5), the classic answer is a button matrix: N rows × M columns of buttons wired so each row and each column is a single MCU pin. The matrix reads N × M buttons with N + M GPIOs — a 4×4 matrix gives 16 buttons on 8 pins, an 8×8 matrix gives 64 buttons on 16 pins. Worth the wiring effort only when you have a lot of buttons to read; for anything under ~10 buttons, BODAC or per-pin reading is simpler.
nDigitalMatrix is the scanner: it walks the rows one at a time, driving each in turn, and reads back the column pins to see which buttons in that row are pressed. It does this within one Sync tick — fast enough that the user can't perceive a delay.
| Parameter | Description |
|---|---|
| Nb Rows / Nb Columns | Up to 8 × 8 (= 64 buttons). |
| Row pins (r0..r7) / Column pins (c0..c7) | The MCU pins for each row / column line. |
| Debounce | Debounce time in ms — applied per-button after the scan. |
| Scan Level | Whether the scan drives each row to 0 (active-low matrix with column pull-ups, the common arrangement) or to 1. |
The output is a single u32 with one bit per matrix position — the firmware packs the whole matrix into one integer so downstream you have one wire carrying the state of every button. Feed that into an nBitUnPacker to split it back into individual button signals, or into a nBitPacker → nSerializer → nHID chain to send the whole matrix as 64 HID buttons in one go.
A bare button matrix can produce "ghost" key reports when three keys are pressed simultaneously along an L-shape — the scan can't distinguish the real third press from a "phantom" press at the opposite corner. The standard fix is to put a diode in series with each button (anode at the button, cathode at the column line), so current can flow only one way around the matrix. The nDigitalMatrix module assumes you've done this on the hardware side; nothing in the firmware can recover from missing diodes. (BODAC needs no diodes — it's the much simpler answer when ≤ 5 buttons is enough.)
See Examples/02-Digital/ButtonMatrixHid.
HID key encoding — nKey
nKey is the bridge between "a button was pressed" and "an HID keyboard wants this key code". It's in the HID category rather than Input because it's about emitting a USB-keyboard message, not about reading hardware.
Two modes, picked from the Mode parameter:
| Mode | Input shape | What it emits |
|---|---|---|
| KEY_MODULE_MODE_NUMBER | A single Index input (u8). | Looks up entry Index in the internal table and emits its Press / Release codes. Used downstream of an nResLadder / nDeMultiplexer chain when several buttons all need their HID code from the same lookup table. |
| (per-entry mode) | One input port per table entry (up to 16). | Each input is a rising-edge trigger that fires its corresponding key code. Used when each of N buttons drives its own pin. |
The output is two ports:
- Press (
u16) — the HID usage code to press (e.g.KEY_A,MODIFIERKEY_SHIFT,KEY_MEDIA_PLAY_PAUSE). - Release (
u16) — the code to release.
Wire those into the corresponding inputs of nKeyboard (USB) or nBLEKeyboard (BLE).
The 16 text fields (Text 1 .. Text 16) accept either a single character (a, 5, ,) or one of the named constants from keylayouts.h (KEY_F1, MODIFIERKEY_CTRL, KEY_MEDIA_VOLUME_INC, KEY_SYSTEM_SLEEP, …). The IDE's Key port type does autocomplete on the named constants.
See Examples/09-USB/Keyboard and the radio/host pairs in Boards/MM_NRF_Host/NRF_Host_To_HID_Keyboard / Boards/NRF_Dongle/NRF52_Dongle_Keyboard.
Putting it together
A common pattern for a button box with mixed input types:
Push-buttons →
nButton× N →nBitPacker(1 bit each) →nSerializer→nHID2-position toggles →
nToggleSwitch(1 output) → same packer chain.Resistor-ladder buttons (joystick hat, navigation pad — only one pressed at a time) →
nAnalogInput→nResLadder→nDeMultiplexer→ same packer chain.BODAC buttons (up to 5 buttons, any combination at once) →
nAnalogInput→nBodac→ 5 button outputs → same packer chain.Button matrix (8×8 = 64 buttons, for large button counts) →
nDigitalMatrix→nBitUnPacker→ 64 wires →nBitPacker→nSerializer→nHID. Or skip the unpack and feed theu32straight into thenBitPacker(one 64-bit field — same wire, fewer connections).
For HID keyboard output instead of gamepad buttons, swap the final stage for nKey → nKeyboard (USB) or nKey → nBLEKeyboard (BLE).
Next, on rotational inputs that also act as buttons (Joycoders, push-encoders, freely-rotating switches) and the templates that wrap them: Encoders & Rotary Inputs.