IOCAN

# CAN Bus Input

## Overview

A **CAN Bus Input** decodes a single **CANbus signal** directly out of a raw

incoming CAN frame, using a byte/bit layout you define by hand. Use it when you

know the frame layout (e.g. from a DBC) for an arbitrary or custom device and

there is no [CAN Preset](Working_with_the_CAN_Bus#can-presets) for it.

This is the **raw frame signal** approach: you give the message ID, say how the

bits are encoded and where they sit, then scale the raw value to engineering

units. To read a named object from a supported device instead, use a

[CAN Object Input](CAN_Object_Input).

## Prerequisites & hardware

- A **defined CAN bus** for the channel the frame arrives on — see

  [Working with the CAN Bus](Working_with_the_CAN_Bus).

- The frame's **message ID** and **bit layout** for the signal you want (length,

  offset, signedness, endianness).

## Add it in the app

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

2. Give it a clear **alias** (e.g. `Engine RPM`).

3. Enter the **Message ID** and its **ID type**, then the **decoding type**,

   **length** and **offset** that locate the signal in the frame.

4. Set the **raw → out** scaling and the **fault** / **timeout** behaviour below.

## Settings reference

> Schema: `config/CanbusInputConfiguration.proto`.

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

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

| **Message ID** | CAN frame identifier to match | hex | fixed32 | The arbitration ID of the frame carrying the signal. |

| **Message ID type** | Identifier width | — | `Extended (29-bit)`, `Standard (11-bit)` | Must match how the sending device addresses the frame. |

| **Decoding type** | How the raw bits are interpreted | — | `UnsignedBigEndian`, `UnsignedLittleEndian`, `SignedBigEndian`, `SignedLittleEndian`, `BitField`, `BitFieldBigEndian`, `SignedBitField`, `SignedBitFieldBigEndian`, `FloatLittleEndian`, `FloatBigEndian` | Selects signedness, endianness, bitfield or float decoding. Match the sender's encoding. |

| **Length** | Signal length | bytes / bits | uint32 | In **bytes** for the integer/float types; in **bits** for the bitfield types (`BitField`, `BitFieldBigEndian`, `SignedBitField`, `SignedBitFieldBigEndian`). |

| **Offset** | Position of the signal in the frame | bytes / bits | uint32 | Same units as Length: **bytes** for integer/float types, **bits** for bitfield types. |

| **Enable interpolation** | Linearly interpolates between the raw/out points | — | on / off | Off = step/clamped mapping. |

| **Raw min / Raw max** | Raw signal range to scale **from** | — | sint32 | The decoded low/high points. |

| **Out min / Out max** | Engineering range to scale **to** | signal unit | sint32 | The value reported at Raw min / Raw max. |

| **Fault input** | An input whose state flags this signal as faulted | — | input alias | When that input is in its fault band the signal is treated as faulted. |

| **Fault min / Fault max** | Values that indicate a fault | — | sint32 | Decoded values inside this band mark the signal as faulted. |

| **Saturate** | Clamps the output to the out range | — | on / off | On = limit to `Out min … Out max` instead of extrapolating. |

| **Default value** | Value used before any frame arrives / when default selected | signal unit | sint32 | Reported until the first valid frame. |

| **Fault value** | Value reported on fault | signal unit | sint32 | Substituted while the signal is faulted. |

| **Timeout** | Maximum time between frames | ms | uint32 | A gap longer than this triggers the timeout behaviour. |

| **Timeout mode** | What to report on timeout | — | `UsePrevious`, `UseDefault`, `UseFault` | See the [Timeouts](../Working-with-the-CAN-Bus.md#timeouts-inputs) section. |

**Scaling:** the decoded value is mapped from `Raw min…Raw max` to

`Out min…Out max` using

[two-point interpolation](Scaling_and_Maps#two-point-interpolation).

## Common settings

CAN Bus Input also uses the shared setting — alias. See

[Common IO Settings](Common_IO_Settings).

## Example — engine RPM from a 500 kbit/s bus

1. Type **CAN Bus Input**, alias `Engine RPM`.

2. **Message ID** `0x0CF00400`, **ID type** `Extended (29-bit)`.

3. **Decoding type** `UnsignedLittleEndian`, **Length** `2` (bytes), **Offset** `3`

   (starts at byte 3) — a 16-bit value. (A bitfield type would use bits here.)

4. **Raw min/max** `0`/`65535` → **Out min/max** `0`/`8191` (0.125 rpm/bit gives

   the right scale); **Saturate on**.

5. **Timeout** `100` ms, **Timeout mode** `UseFault`, **Fault value** `0` so a lost

   ECU is detected rather than the last rpm being held.

## Troubleshooting

- **Value is garbage / wildly wrong:** check the **decoding type** (signedness and

  endianness) and that **Length** and **Offset** match the frame layout — remember

  they are in **bytes** for integer/float types and **bits** for bitfield types.

- **Reads zero / never updates:** confirm the **Message ID** and **ID type**, and

  that the CAN bus baud rate matches the sender.

- **Scaled wrong:** verify **Raw min/max** and **Out min/max**.

- **Holds a stale value when the device drops off:** set a **Timeout** and a

  **Timeout mode** of `UseDefault` or `UseFault`.

## Related

- [CAN Object Input](CAN_Object_Input) — read a named object from a CAN Preset

  instead of decoding bytes by hand.

- [CAN Bus Output](CAN_Bus_Output) — pack a signal into an outgoing

  frame.

- [Working with the CAN Bus](Working_with_the_CAN_Bus)