IOCAN

# Waveform Input

## Overview

A **Waveform Input** generates a **timed value** — a waveform — in response to the

edges of another input. When the observed input switches on or off, it plays back a

sequence of *(time, value)* points you define. Typical uses are clutch-by-wire

**engage on button press** and **release on button release**, **blinker / hazard**

lights, and simple **test signals**. It watches an input you already configured and

produces a value from it.

## Prerequisites & hardware

- A **source input** to observe — usually a button or switch (for example a

  [Digital Input](Digital-Input.md)). Create it first and note its identifier.

- The observed input is treated as **digital**: a value **< 512 is LOW**, a value

  **≥ 512 is HIGH**.

  - A **LOW → HIGH** transition fires the **RISE** trigger.

  - A **HIGH → LOW** transition fires the **FALL** trigger.

- At startup no transition is detected, so the first trigger can occur no earlier

  than the second cycle.

## Add it in the app

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

2. Set the **Observed input** to the source you want to watch.

3. Give it a clear **alias** (e.g. `Clutch Command`).

4. Define the **Rise waveform** and **Fall waveform** as lists of *(time, value)*

   points.

5. Set the **idle values** and the **repeat** / **minimum repeats** behaviour.

## Settings reference

> Schema: `config/WaveformInputConfigData.proto`.

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

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

| **Observed input** | The input whose edges trigger the waveforms | — | int32 (input id) | Read as digital: `< 512` LOW, `≥ 512` HIGH. |

| **Rise waveform** | Points played on a LOW → HIGH edge | (ms, value) pairs | list of sint32 times + sint32 values | Time stamps in ms; output value at each point. An empty list outputs the idle value. |

| **Fall waveform** | Points played on a HIGH → LOW edge | (ms, value) pairs | list of sint32 times + sint32 values | As above, for the falling edge. |

| **Rise repeat** | Loop the rise waveform | — | on / off | **Off:** play once, then hold the idle value (or stop early if a new trigger arrives and minimum repeats > 0). **On:** when the timer passes the last point, reset and replay from the start. |

| **Fall repeat** | Loop the fall waveform | — | on / off | As above, for the fall waveform. |

| **Rise minimum repeats** | Full plays before a new trigger can interrupt the rise waveform | plays | int (`0`, `1`, `n`) | `0` = interruptible as soon as the next trigger is seen; `1` = play at least once fully; `n` = at least n times. **Ignored when Rise repeat is off.** |

| **Fall minimum repeats** | Full plays before a new trigger can interrupt the fall waveform | plays | int (`0`, `1`, `n`) | As above, for the fall waveform. |

| **Idle value (LOW)** | Output when no waveform is playing and the observed input is LOW | value | sint32 | Held between waveforms. |

| **Idle value (HIGH)** | Output when no waveform is playing and the observed input is HIGH | value | sint32 | The input picks LOW or HIGH idle from the observed input's current state. |

### How a waveform is described

Each waveform is a list of **(time, value)** points. After a trigger, a timer starts

at `0 ms` and the input outputs the value scheduled for the elapsed time, **linearly

interpolating** between points to give a smooth ramp:

```

value

 1000 |          ______

      |         /

    0 |________/

      +--------+----+----> time (ms)

      0       200  300

   points: (0,0) (200,1000) (300,1000)   -> interpolated between points

```

When the timer passes the **last** point, the input either holds the idle value

(repeat off) or resets to `0 ms` and plays again (repeat on).

## Common settings

Waveform Input also uses the shared setting — alias. See

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

## Example — clutch engage on press, ramped release on release

Watch a clutch button (a [Digital Input](Digital-Input.md)) and drive a clutch

command from `0` (open) to `1000` (closed).

1. Type **Waveform Input**, alias `Clutch Command`, **Observed input** = the

   clutch button.

2. **Rise waveform** (button pressed → engage quickly):

   `(0 ms, 0) → (200 ms, 1000)` — ramps up over 200 ms.

3. **Fall waveform** (button released → ramp out gently):

   `(0 ms, 1000) → (600 ms, 0)` — ramps down over 600 ms.

4. **Rise repeat off**, **Fall repeat off** — each plays once, then holds idle.

5. **Idle value (LOW)** `0`, **Idle value (HIGH)** `1000` — so once engaged it

   stays closed and once released it stays open.

For a **hazard light** instead: put a square pulse in the Rise waveform and turn

**Rise repeat on** so it blinks continuously until the next trigger.

## Troubleshooting

- **Nothing happens on the first press:** at startup no edge exists; the first

  trigger comes no earlier than the second cycle. Toggle the input once.

- **Waveform never stops / keeps looping:** **repeat** is on. Turn it off for a

  one-shot, or set **minimum repeats** so the next trigger can interrupt it.

- **A new press is ignored mid-play:** **minimum repeats** is too high — lower it

  (or use `0`) so the next trigger can interrupt.

- **Output sits at the wrong level between presses:** check **Idle value (LOW/HIGH)**.

- **Ramp too fast or too slow:** adjust the point **timestamps** — the output

  interpolates linearly between consecutive points.

- **Triggers fire on the wrong edge:** LOW/HIGH is split at **512** — make sure the

  observed input crosses that threshold.

## Related

- [Digital Input](Digital-Input.md) — a typical button/switch source to observe.

- [Constant Value Input](Constant-Value-Input.md) — a fixed value with no timing.

- [Counter Input](Counter-Input.md) — count edges rather than play a waveform.