# Button Configuration

Configuring buttons, messages, crash and incident fallbacks

# Setting Up a Button

## Overview

iReporter supports up to 16 buttons. Each button is independently configured with its own mode, label, messages, webhook target, crash/incident fallbacks, and voice text. The number of visible buttons is controlled by the **Number of Buttons** setting.

## Button Mode

Each button has a **Button Mode** dropdown at the top of its section. The mode controls which fields are shown and how the button behaves when pressed:

<table id="bkmrk-modewhat-it-doesstan"><thead><tr><th>Mode</th><th>What it does</th></tr></thead><tbody><tr><td>**Standard Button**</td><td>Sends the three message lines via iRacing chat and Discord webhook. No crash or incident fallback panels.</td></tr><tr><td>**Crash Detection**</td><td>Includes a Crash Fallback field. When pressed with an active crash, sends the main messages using crash variables. When no crash is active, sends the fallback message instead. Only available when Crash Capture is enabled in iRacing Options.</td></tr><tr><td>**Incident Detection**</td><td>Same as Crash Detection but for incidents. Uses incident variables and the Incident Fallback field. Only available when Incident Capture is enabled.</td></tr><tr><td>**Blue Flag Helper**</td><td>A Standard button whose template dropdown shows only Blue Flag Helper templates. Useful for grouping blue flag acknowledgements, warnings, and reports on dedicated buttons without mixing them with other Standard templates.</td></tr><tr><td>**Voice Only**</td><td>Fires the voice message only — no text is typed into the iRacing chat box. Useful for quick radio calls that don't need a chat record. The voice input box is always shown regardless of the global Voice Options setting.</td></tr></tbody></table>

Changing the mode also filters the **Message Templates** dropdown to show only templates in the matching category.

## Button Fields

### Label

A descriptive name for the button shown in the settings panel (e.g. Contact Report, Yellow Flag). This is for your reference only and is not included in any sent message.

### Message Templates

The **Message Templates** dropdown appears above the message fields. It shows only templates whose category matches the button's current mode — so a Crash Detection button only shows Crash Detection templates. Select a template to instantly fill in all message fields and voice text.

### Message 1, 2, 3

Up to three message lines can be configured per button. When the button is pressed:

- All three messages are sent in sequence if populated.
- Messages support [Message Variables](/books/ireporter/chapter/button-configuration) — placeholders filled with live iRacing data at press time.
- Empty lines (containing only `~`) are skipped.

### Webhook

Selects which of the three configured webhooks receives this button's messages. Set to **None** to disable webhook posting for this button.

### Disable Text Logging

When ticked, this button's presses are not written to the log file even if logging is globally enabled.

## Voice (Speak Text)

Appears below the message rows. When Voice Options is globally enabled (or when the button is in **Voice Only** mode), a multi-line **Speak Text** box is shown. Enter the text to be spoken aloud when this button is pressed. Message variables such as `{CAR#}` and `{CRASHCAR}` are supported.

Tick **Disable Voice for this button** to suppress voice output while keeping the speak text saved for future use.

## Crash Fallback

Visible on buttons in **Crash Detection** mode (requires Crash Capture to be enabled in iRacing Options). The green-bordered panel is labelled *"Sent when the button is pressed but no Crash has been detected"* — this message is sent when no crash is currently active. Leave blank to send nothing if no crash is active.

## Incident Fallback

Visible on buttons in **Incident Detection** mode (requires Incident Capture to be enabled). Works identically to the Crash Fallback but activates when no incident is currently active.

## Test Fire

The **▶ TEST FIRE** button at the top of each button section simulates a button press without requiring a physical button press. Useful for testing your webhook delivery and voice output during setup. Test Fire does not type into the iRacing chat box — it only fires voice and webhooks.

## Message Templates (Saved)

The **Message Templates** dropdown (above the message rows) allows you to load a saved template into the current button. Templates are filtered by category to match the button's mode.

Click **Manage Templates** (in the top row of the settings panel) to open the template editor. In the editor you can:

- Set the template **Name** and **Category** (Standard, Crash Detection, Incident Detection, or Voice Only)
- Edit **Msg 1, 2, 3** — the three message lines
- Edit **Failover** — the crash or incident fallback message (shown in orange)
- Edit **Voice** — the speak text (shown in blue, wraps to multiple lines)
- Tick **Voice Disabled** — saves the voice-disabled state with the template
- Use <kbd>{</kbd> in any field to open the variable picker
- Reorder templates with the **â–²** and **â–¼** buttons
- Add a blank template with **+ Add New Template**
- Delete a template with **Delete**

To save the current button's configuration as a new template, click **Save as Template** below the voice box. The template's category is automatically set to match the button's current mode.

## Default Templates

iReporter ships with 17 ready-to-use templates covering the most common race reporting scenarios. They are created automatically in `Documents\iReporter\templates.txt` the first time SimHub starts. Each template is pre-assigned to the correct button mode category so it appears in the right dropdown automatically.

### Crash Detection templates

These templates require **Crash Capture** to be enabled in iRacing Options and work best on buttons set to **Crash Detection** mode.

<table id="bkmrk-templatepurposeavoid"><thead><tr><th>Template</th><th>Purpose</th></tr></thead><tbody><tr><td>**Avoidable Contact**</td><td>Reports avoidable contact to Race Control. Sends three chat lines identifying your car, the car involved (`{CRASHCAR}`), the lap, and the relative direction of contact (`{CRASHDIR}`). The fallback message is sent if no crash is currently active. Includes a spoken voice report with pauses for clarity.</td></tr></tbody></table>

### Incident Detection templates

These templates require **Incident Capture** to be enabled in iRacing Options and work best on buttons set to **Incident Detection** mode.

<table id="bkmrk-templatepurposeincid"><thead><tr><th>Template</th><th>Purpose</th></tr></thead><tbody><tr><td>**Incident Report Close1**</td><td>Reports a close incident to Race Control. Identifies your car, the incident car (`{INCCAR}`), and the lap number (`{INCLAP}`). The fallback sends a general incident report if no incident is currently active. Includes a spoken voice report.</td></tr></tbody></table>

### Voice Only templates

These templates work on buttons set to **Voice Only** mode — no text is sent to the iRacing chat box.

<table id="bkmrk-templatepurposecall-"><thead><tr><th>Template</th><th>Purpose</th></tr></thead><tbody><tr><td>**Call Race Control (Voice)**</td><td>Speaks a radio-style call to Race Control three times followed by your car number. Use this to open a voice communication when you need Race Control's attention without cluttering the chat. No chat messages are sent.</td></tr></tbody></table>

### Standard templates

These templates work on any button set to **Standard Button** mode.

<table id="bkmrk-templatepurposeyello"><thead><tr><th>Template</th><th>Purpose</th></tr></thead><tbody><tr><td>**Yellow Flag Overtake**</td><td>Reports being overtaken under a yellow flag. Identifies your car, the lap, and the car ahead (`{CARAHEAD}`) as the likely overtaker. Includes a voice report.</td></tr><tr><td>**Blue Flag Overtake Issues**</td><td>Reports that a car is failing to observe the blue flag while you are lapping it. Identifies the car ahead (`{CARAHEAD}`) as the offender. Includes a voice report.</td></tr><tr><td>**Car Ahead Blinking**</td><td>Reports that the car directly ahead is brake-testing or blinking, creating a safety hazard. Identifies the car ahead (`{CARAHEAD}`). Includes a voice report with pauses.</td></tr><tr><td>**Sorry Car Behind**</td><td>Sends a private in-car message directly to the car behind (`{CARBEHIND}`) saying "Sorry — My fault!". Voice is disabled — chat only, no spoken output.</td></tr><tr><td>**Sorry Car Ahead**</td><td>Sends a private in-car message directly to the car ahead (`{CARAHEAD}`) saying "Sorry — My fault!". Voice is disabled — chat only, no spoken output.</td></tr><tr><td>**Blue Flag Observed**</td><td>Notifies the car behind (`{CARBEHIND}`) that you have seen the blue flag and will let them past when it is safe to do so. Two chat messages. Voice is disabled.</td></tr><tr><td>**Pitting This LAP**</td><td>Announces that your car is pitting this lap. Voice is disabled — use this as a quick notification to nearby cars via chat.</td></tr><tr><td>**Unsafe Rejoin Ahead**</td><td>Reports an unsafe track rejoin by the car ahead (`{CARAHEAD}`) to Race Control. Includes a spoken voice report.</td></tr><tr><td>**Unsafe Rejoin Behind**</td><td>Reports an unsafe track rejoin by the car behind (`{CARBEHIND}`) to Race Control. Includes a spoken voice report.</td></tr><tr><td>**Impeding Qualifying Behind**</td><td>Reports that the car behind (`{CARBEHIND}`) is impeding your qualifying lap. Includes a spoken voice report.</td></tr><tr><td>**Impeding Qualifying Ahead**</td><td>Reports that the car ahead (`{CARAHEAD}`) is impeding your qualifying lap. Includes a spoken voice report.</td></tr><tr><td>**Outlap Overtake Ahead**</td><td>Reports being overtaken during an outlap by the car ahead (`{CARAHEAD}`). Includes a voice report with pauses.</td></tr><tr><td>**Tow Requested**</td><td>Notifies Race Control that your car requires a tow. Includes a voice report asking when it is safe to tow.</td></tr><tr><td>**Bad Driver Standards**</td><td>Reports poor driving standards to Race Control. Identifies your car, lap, and the three closest cars (`{CLOSECAR1}`, `{CLOSECAR2}`, `{CLOSECAR3}`) as likely vehicles involved. Includes a voice report.</td></tr></tbody></table>

## Variable Helper — Type { to Browse Variables

Every message text box (including fields in the Manage Templates editor) has a built-in variable picker. Type an opening curly brace `{` and a list of available variables will appear directly below the text box, each with a short description.

### Filtering the list

Keep typing after the `{` to narrow the list. For example, typing `{CRASH` will immediately filter the list to show only crash-related variables. The filter is not case-sensitive.

### Inserting a variable

- **Arrow keys** — press <kbd>↑</kbd> and <kbd>↓</kbd> to move through the list.
- **Tab or Enter** — inserts the highlighted variable at the cursor position and closes the picker.
- **Click** — click any entry to insert it immediately.
- **Escape** — dismisses the picker without inserting anything.

# Message Variables Reference

## Overview

Variables are placeholders wrapped in curly braces that are substituted with live iRacing data when a button is pressed. They can be used in any message field and in the Speak Text field.

If a variable is used in a message but has no current value, the entire message line is suppressed (or replaced by the fallback message if one is configured).

## Your Car

<table id="bkmrk-variabledescription%7B"><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td>`{CAR#}`</td><td>Your car number</td></tr><tr><td>`{CARTYPE}`</td><td>Your car model / type</td></tr><tr><td>`{CARLAP}`</td><td>Your current lap (with decimal fraction)</td></tr><tr><td>`{DRIVER}`</td><td>Your driver name</td></tr><tr><td>`{FLAG}`</td><td>Current flag colour (e.g. Green, Yellow, Red, Black, Checkered)</td></tr></tbody></table>

## Crash Variables

Available only when a crash is currently active (within the crash timeout window).

<table id="bkmrk-variabledescription%7B-1"><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td>`{CRASHCAR}`</td><td>Car number of the crashed car</td></tr><tr><td>`{CRASHNAME}`</td><td>Driver name of the crashed car</td></tr><tr><td>`{CRASHDIR}`</td><td>Relative direction of the crash (Ahead / Behind / Left / Right)</td></tr><tr><td>`{CRASHLAP}`</td><td>Lap number at which the crash occurred</td></tr></tbody></table>

## Incident Variables

Available only when an incident is currently active (within the incident timeout window).

<table id="bkmrk-variabledescription%7B-2"><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td>`{INCCAR}`</td><td>Car number involved in the incident</td></tr><tr><td>`{INCNAME}`</td><td>Driver name involved in the incident</td></tr><tr><td>`{INCDIR}`</td><td>Relative direction of the incident</td></tr><tr><td>`{INCLAP}`</td><td>Lap number at which the incident occurred</td></tr></tbody></table>

## Cars Around You

<table id="bkmrk-variabledescription%7B-3"><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td>`{CARAHEAD}` / `{CARAHEAD1}`</td><td>Car number of the 1st car ahead</td></tr><tr><td>`{CARAHEAD2}`</td><td>Car number of the 2nd car ahead</td></tr><tr><td>`{CARAHEAD3}`</td><td>Car number of the 3rd car ahead</td></tr><tr><td>`{NAMEAHEAD}` / `{NAMEAHEAD1}`</td><td>Driver name of the 1st car ahead</td></tr><tr><td>`{NAMEAHEAD2}`</td><td>Driver name of the 2nd car ahead</td></tr><tr><td>`{NAMEAHEAD3}`</td><td>Driver name of the 3rd car ahead</td></tr><tr><td>`{CARBEHIND}` / `{CARBEHIND1}`</td><td>Car number of the 1st car behind</td></tr><tr><td>`{CARBEHIND2}`</td><td>Car number of the 2nd car behind</td></tr><tr><td>`{CARBEHIND3}`</td><td>Car number of the 3rd car behind</td></tr><tr><td>`{NAMEBEHIND}` / `{NAMEBEHIND1}`</td><td>Driver name of the 1st car behind</td></tr><tr><td>`{NAMEBEHIND2}`</td><td>Driver name of the 2nd car behind</td></tr><tr><td>`{NAMEBEHIND3}`</td><td>Driver name of the 3rd car behind</td></tr><tr><td>`{CLOSECAR1}`</td><td>Closest car number (any direction)</td></tr><tr><td>`{CLOSECAR2}`</td><td>2nd closest car number</td></tr><tr><td>`{CLOSECAR3}`</td><td>3rd closest car number</td></tr><tr><td>`{CLOSENAME1}`</td><td>Closest driver name (any direction)</td></tr><tr><td>`{CLOSENAME2}`</td><td>2nd closest driver name</td></tr><tr><td>`{CLOSENAME3}`</td><td>3rd closest driver name</td></tr><tr><td>`{GAPHEAD}` / `{GAPHEAD1}`</td><td>Gap in seconds to 1st car ahead</td></tr><tr><td>`{GAPHEAD2}`</td><td>Gap in seconds to 2nd car ahead</td></tr><tr><td>`{GAPHEAD3}`</td><td>Gap in seconds to 3rd car ahead</td></tr><tr><td>`{GAPBEHIND}` / `{GAPBEHIND1}`</td><td>Gap in seconds to 1st car behind</td></tr><tr><td>`{GAPBEHIND2}`</td><td>Gap in seconds to 2nd car behind</td></tr><tr><td>`{GAPBEHIND3}`</td><td>Gap in seconds to 3rd car behind</td></tr><tr><td>`{TOPX}`</td><td>Comma-separated list of top X race leaders by position (e.g. #3, #11, #27)</td></tr></tbody></table>

## Timing Controls

<table id="bkmrk-variabledescription%7B-4"><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td>`{PAUSE:N}`</td><td>Insert a pause of N milliseconds between message segments</td></tr></tbody></table>

## Skip Marker — ~

Enter `~` (tilde) alone in a message slot to skip that slot entirely. No keystrokes are sent.

## Conditional Statements

iReporter supports a simplified conditional syntax that lets you include or suppress parts of a message based on live race data. The syntax uses parentheses rather than curly braces, keeping it visually distinct from variables.

For full documentation including AND / OR compound conditions, examples, and the current supported condition types, see the dedicated page:

[**Using Conditionals in Messages →**](https://books.speedtech.co.nz/books/ireporter/page/using-conditional-statements-in-messages)

# LED Reference

## Overview

iReporter can drive hardware LEDs on your iReporter Button Box to provide visual indicators for active crash/incident timers and the Blue Flag Helper approach warning.

## Serial Protocol

iReporter communicates with the button box using a simple text-based protocol over the configured COM port at 9600 baud. Each LED command is a single line in the format:

```
LED;{COLOUR};{STATE};
```

Where:

- **COLOUR** — one of: `RED`, `BLUE`, `GREEN`, `AMBER`
- **STATE** — `1` to turn the LED on, `0` to turn it off

Examples:

```
LED;RED;1;      (turn red LED on)
LED;RED;0;      (turn red LED off)
LED;AMBER;1;    (turn amber LED on)
```

## LED Assignments

<table id="bkmrk-featuresettingbehavi"><thead><tr><th>Feature</th><th>Setting</th><th>Behaviour</th></tr></thead><tbody><tr><td>Crash Capture</td><td>Timeout LED (in Crash Capture settings)</td><td>Steady ON while crash is active (timed mode) — OR — brief 600ms flash on capture (No Timeout mode)</td></tr><tr><td>Incident Capture</td><td>Timeout LED (in Incident Capture settings)</td><td>Steady ON while incident is active (timed mode) — OR — brief 600ms flash on capture (No Timeout mode)</td></tr><tr><td>Blue Flag Helper</td><td>Approach LED (in Blue Flag Helper settings)</td><td>ON when a top-X leader is within the configured gap AND more than 1 full lap ahead</td></tr></tbody></table>

## Timed vs No Timeout LED Behaviour

The crash and incident LEDs behave differently depending on the timeout setting:

<table id="bkmrk-timeout-settingled-b"><thead><tr><th>Timeout Setting</th><th>LED Behaviour</th><th>Data Cleared When</th></tr></thead><tbody><tr><td>Timed (1–60s)</td><td>Stays ON for the full timeout duration, then turns OFF</td><td>Timeout expires</td></tr><tr><td>No Timeout (0)</td><td>Flashes ON for 600ms on detection, then turns OFF</td><td>Next crash/incident is detected (overwrites previous)</td></tr></tbody></table>

The brief flash in No Timeout mode confirms that a crash or incident has been captured without implying it is still pending — the data remains available in message variables indefinitely.

## Colour Options

<table id="bkmrk-optiondescriptionnon"><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td>None</td><td>No LED output for this feature</td></tr><tr><td>RED</td><td>Red LED</td></tr><tr><td>BLUE</td><td>Blue LED</td></tr><tr><td>GREEN</td><td>Green LED</td></tr><tr><td>AMBER</td><td>Amber / orange LED</td></tr></tbody></table>

## Notes

- iReporter only sends a new LED command when the state changes — it does not repeatedly send the same command.
- Multiple features can use different colours simultaneously (e.g. RED for crash, AMBER for incident).
- If two features are assigned the same colour, the last state change wins. It is recommended to assign a unique colour to each feature.
- The COM port and baud rate (9600) are fixed. Ensure your iReporter Button Box firmware listens on 9600 baud and parses the `LED;COLOUR;STATE;` format.

# Using Conditional Statements in Messages

## Conditional Messages

iReporter supports conditional message lines using a simple bracket syntax. Place a condition in parentheses at the start of any message field — if the condition is false at press time, that line is silently skipped and nothing is sent for it.

## Syntax

```
(condition)message text here
```

Everything after the closing `)` is sent only when the condition is true. No closing tag needed — the condition applies to the whole line.

### Example

```
(GAPBEHIND1<2)/msg {CARBEHIND1} Car {CAR#} is pitting this lap!
```

This sends a private message to the car immediately behind only if it is within 2 seconds. If the gap is greater the line is skipped entirely and nothing is sent.

## AND and OR

Combine multiple conditions on the one line using `&&` (AND) or `||` (OR). AND is evaluated before OR.

<table id="bkmrk-examplesends-when-%28c"><thead><tr><th>Example</th><th>Sends when</th></tr></thead><tbody><tr><td>`(CRASH && GAPBEHIND1<5)/rc Contact near traffic!`</td><td>A crash is active AND car 1 behind is within 5s</td></tr><tr><td>`(CRASH || INCIDENT)/rc Incident detected!`</td><td>A crash OR an incident is currently active</td></tr><tr><td>`(FLAG=Yellow && GAPHEAD<3)/rc Yellow — tight ahead!`</td><td>Yellow flag AND less than 3s to car ahead</td></tr></tbody></table>

You can also write `AND` and `OR` in plain English instead of `&&` and `||`.

## Available Conditions

### Crash and Incident

<table id="bkmrk-conditiontrue-when-c"><thead><tr><th>Condition</th><th>True when</th></tr></thead><tbody><tr><td>`CRASH`</td><td>A crash is currently detected</td></tr><tr><td>`NOCRASH`</td><td>No crash is currently active</td></tr><tr><td>`INCIDENT`</td><td>An incident is currently detected</td></tr><tr><td>`NOINCIDENT`</td><td>No incident is currently active</td></tr></tbody></table>

### Gap Conditions

Replace `N` with any number of seconds. Operators: `<` `>` `<=` `>=`

<table id="bkmrk-conditiontrue-when-g"><thead><tr><th>Condition</th><th>True when</th></tr></thead><tbody><tr><td>`GAPHEAD<N` or `GAPHEAD1<N`</td><td>Gap to 1st car ahead is less than N seconds</td></tr><tr><td>`GAPHEAD2<N`</td><td>Gap to 2nd car ahead is less than N seconds</td></tr><tr><td>`GAPHEAD3<N`</td><td>Gap to 3rd car ahead is less than N seconds</td></tr><tr><td>`GAPBEHIND<N` or `GAPBEHIND1<N`</td><td>Gap to 1st car behind is less than N seconds</td></tr><tr><td>`GAPBEHIND2<N`</td><td>Gap to 2nd car behind is less than N seconds</td></tr><tr><td>`GAPBEHIND3<N`</td><td>Gap to 3rd car behind is less than N seconds</td></tr></tbody></table>

### Flag Condition

<table id="bkmrk-conditiontrue-when-f"><thead><tr><th>Condition</th><th>True when</th></tr></thead><tbody><tr><td>`FLAG=Yellow`</td><td>Current flag is Yellow / Caution</td></tr><tr><td>`FLAG=Green`</td><td>Current flag is Green (racing)</td></tr><tr><td>`FLAG=Red`</td><td>Current flag is Red</td></tr><tr><td>`FLAG=White`</td><td>Current flag is White (final lap)</td></tr><tr><td>`FLAG=Checkered`</td><td>Current flag is Checkered</td></tr></tbody></table>

## Practical Examples

### Notify close cars when pitting

<table id="bkmrk-fieldcontent-message"><thead><tr><th>Field</th><th>Content</th></tr></thead><tbody><tr><td>Message 1</td><td>`/rc Car {CAR#}, {DRIVER} Pitting this LAP`</td></tr><tr><td>Message 2</td><td>`(GAPBEHIND1<2)/msg {CARBEHIND1} Car {CAR#} pitting this LAP!`</td></tr><tr><td>Message 3</td><td>`(GAPBEHIND2<3)/msg {CARBEHIND2} Car {CAR#} pitting this LAP!`</td></tr></tbody></table>

Message 1 always fires. Messages 2 and 3 fire only when the cars behind are within the gap threshold — each sends a separate private message.

### Flag-aware status

<table id="bkmrk-fieldcontent-message-1"><thead><tr><th>Field</th><th>Content</th></tr></thead><tbody><tr><td>Message 1</td><td>`(FLAG=Yellow)/rc Yellow flag — Car {CAR#} Lap {CARLAP} holding position`</td></tr><tr><td>Message 2</td><td>`(FLAG=Green)/rc Racing — Car {CAR#} Lap {CARLAP}`</td></tr></tbody></table>

### Combined condition

```
(CRASH && GAPBEHIND1<5)/rc Contact AND close traffic behind — Car {CARBEHIND1} at risk
```

## Using the Variable Picker

Type `(` in any message box to open the variable picker and browse all available conditions. AND / OR examples are included at the bottom of the list.

## Backward Compatibility

The older `{IF:condition}text{ENDIF}` syntax is still fully supported for any messages you have already saved.