IOCAN

# Digital Input

## Overview

A **Digital Input** reads an on/off (digital) state on a hardware pin — a switch,

button or relay contact. The input is **on** when the pin is **shorted to signal

ground (sGND)** and **off** when it is open. On reads as **1024**, off as **0**

(use **Invert** to swap them). In its other modes the same pin can instead measure

a property of a digital waveform: its duty cycle, frequency, or pulse time.

Use it for door/neutral switches, mode buttons, and simple signals you only need a

single value from. For richer frequency/speed/position work, prefer the

[Frequency Input](Frequency-Input.md).

## Prerequisites & hardware

- A contact or signal that **shorts the pin to sGND** to signal "on", and leaves it

  open for "off".

- On = `1024`, off = `0`; use **Invert** if your wiring is the other way round.

- Mechanical contacts bounce; plan to use the **debounce** timings below.

- For Duty/Frequency/Time modes the signal must be a clean repeating waveform.

## Add it in the app

1. Add a new input and choose **Digital Input** as the type.

2. Select the **pin** the signal is wired to.

3. Give it a clear **alias** (e.g. `Neutral Switch`).

4. Choose the **mode** (plain on/off, or duty / frequency / time).

5. Set **Invert** and the **debounce** timings as needed.

## Settings reference

> Schema: `config/DigitalInConfiguration.proto`.

| Setting | Meaning | Unit | Range / values | Notes |

|---|---|---|---|---|

| **Mode** | What the pin reads | — | `Digital In`, `Duty`, `Frequency`, `Time` | `Digital In` = plain on/off. The other modes measure that property of a digital waveform on the same pin. |

| **Invert** | Swaps on/off (`1024` ↔ `0`) | — | on / off | By default on = pin shorted to sGND. Invert if the active state is the open one. |

| **Enable filter** | Turns on debounce filtering | — | on / off | Recommended for mechanical switches. The three timings below apply when on. |

| **Delay** | Debounce delay before a state change is accepted | ms | sint32 | A new level must be stable for this long before it is reported. |

| **Hold** | Minimum time a state is held once accepted | ms | sint32 | Stops rapid re-triggering; the state is kept at least this long. |

| **Interspace** | Minimum gap between transitions | ms | sint32 | Ignores transitions that arrive closer together than this. |

**Debounce:** **Delay**, **Hold** and **Interspace** work together to reject

contact bounce and electrical noise. Start with small values (a few ms) and

increase only if you still see false toggles.

## Common settings

Digital Input also uses the shared settings — alias and pin. See

[Common IO Settings](../Common-IO-Settings.md).

## Example — neutral switch

1. Type **Digital Input**, alias `Neutral Switch`, on the switch's pin.

2. Mode `Digital In`.

3. The switch closes to sGND in neutral, so it reads **on (1024)** in neutral

   directly — no invert needed (turn **Invert on** only if your wiring is opposite).

4. **Enable filter**, set **Delay** `20`, **Hold** `30`, **Interspace** `10` to

   reject contact bounce.

## Troubleshooting

- **State flickers / chatters:** enable the filter and raise **Delay** /

  **Interspace**.

- **Reads the opposite of what you expect:** toggle **Invert**.

- **Change is missed or too slow:** **Delay** is too high — lower it.

- **Duty/Frequency/Time reads zero:** confirm the mode matches the signal and that

  the waveform actually toggles cleanly on that pin.

## Related

- [Frequency Input](Frequency-Input.md) — frequency, speed, duty or pulse time.

- [Analog Switch Input](Analog-Switch-Input.md) — multi-position switch on one

  analog pin.

- [Counter Input](Counter-Input.md) — count events/edges.