> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your first FDD routine

> Learn how FDD alarms and events work, then build a flexible sensor-to-setpoint routine, test it, and enable it on a device.

FDD

## Build your first FDD routine

Learn what FDD watches for, then build a simple sensor-over-threshold rule you can reuse on almost any equipment.

Beginner
About 30 min

![Completed VAV Over Setpoint logic canvas with sensor, setpoint, deadband, sum, greater than, debounce, and alarm trigger blocks](https://docs.kodelabs.com/images/kode-os/fdd/tutorials/fdd-tutorial-completed-canvas.png)

Progress

/

<ol />

Step 0

### What does FDD do?

FDD (Fault Detection and Diagnostics monitors equipment and surfaces operational issues in real time.) watches building equipment for conditions that need attention. You define the rule once as a routine. KODE then evaluates live point data and opens an event when the rule holds true.

A useful fault always answers four questions:

![Example fault text broken into Start Time, Device, Condition, and Duration](https://mintcdn.com/kodelabs/SxbaONoYYoMWCQfA/images/kode-os/fdd/kode-os-fdd-fault-definition.png?fit=max\&auto=format\&n=SxbaONoYYoMWCQfA\&q=85\&s=c4df71c12274395be68d37e59423f26c)

Every fault combines a start time, device, condition, and duration

**Alarms** are the simplest checks. They usually watch one or two points and fire as soon as the condition is true. Think zone temperature over a max, or a fan failure status.

**Events** are richer. A routine can combine sensors, setpoints, parameters, and timing blocks. When the Alarm Trigger receives `true`, FDD opens an event you can triage on the Events page.

![Events page showing Pause Streaming, Last 7 Days date range, Filters, priority cards for Total 297, Life-Safety 0, Critical 2, Warning 66, and Alert 229, and a Table View of active events with Name, Device, Device Type, Point Name, Point Value, Start Time, End Time, Duration, and Ack'ed columns](https://mintcdn.com/kodelabs/SxbaONoYYoMWCQfA/images/kode-os/fdd/kode-os-fdd-events-list.png?fit=max\&auto=format\&n=SxbaONoYYoMWCQfA\&q=85\&s=f2464097b2f7a916f2bd137070d7718b)

Events list with priorities, filters, and active fault events

This walkthrough builds one event routine end to end: create the rule, test it, enable it on a device, then confirm the event. For the full concept map, see [What is Fault Detection and Diagnostics?](https://docs.kodelabs.com/products/fdd/overview.md).

Step 1

### Before you begin

You will build a VAV zone air temperature greater-than-setpoint rule. Treat that as a starting pattern, not a one-off recipe.

The same shape works for:

* Sensor **greater than** setpoint (this walkthrough)
* Sensor **less than** setpoint (swap Greater Than for Less Than)
* Sensor versus a **Number parameter** when the device has no setpoint point

You only need a readable sensor value and a threshold to compare against. The threshold can come from another point or from a parameter you set yourself.

Confirm the following before you build:

* Access to `FDD` on a building where you can create and enable routines
* At least one online VAV with zone air temperature sensor and setpoint points templated (or a sensor plus a parameter threshold)
* Prefer a non-production building or a device you can safely monitor while you learn

> [!NOTE]
>
> Compatible devices appear in Configs only when they carry the canonical types and entities you select on the routine. Missing templating means an empty device list later.

Step 2

### Create the routine

![Routines page with callouts for FDD in the sidebar, Routines in the secondary menu, and the Create Routine button](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-create-routine-nav.png?fit=max\&auto=format\&n=i9tCc_I6OZNqDXAw\&q=85\&s=2a1711e9beecd92b1d5119f984ee8147)

Open FDD, select Routines, then Create Routine

Create a local routine and tell FDD which VAV points it may read.

**1. Open Create Routine**

In Cloud BMS, open `FDD`, select `Routines`, then select `+ Create Routine`.

**2. Fill Workflow Details**

On the `Workflow Details` tab, enter:

| Field | Value |
| - | - |
| `Name` | `VAV Over Setpoint` |
| `Description` | Alarms when zone air temperature stays above setpoint plus deadband |
| `Recommended Type` | `Event` |
| `Domains` | `Heating Issue` (or the domain your site uses) |
| `Events Grouping` | `None` |
| `Priority` | `Alert` |

![Workflow Details tab with Name VAV Over Setpoint, Recommended Type Event, Domains Heating Issue, Events Grouping None, Priority Alert, and a Vavs device group](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-workflow-details.png?fit=max\&auto=format\&n=i9tCc_I6OZNqDXAw\&q=85\&s=346554b77ed5ff5f9fc1e8a4cc6e439a)

Workflow Details for VAV Over Setpoint

**3. Add VAV devices and ZTSS**

Select `+ Add Devices`. Set `Name As` to `Vavs`, select the `vav` canonical, and select the `ZTSS` entity (Zone Temperature Control).

`ZTSS` brings in `zone_air_temperature_sensor` and `zone_air_temperature_setpoint` so those fields appear in the Logic builder.

First click includes an entity. Second click excludes it (shown in red). Include only what this routine needs.

![Add Devices dialog with Name As Vavs, vav canonical selected, ZTSS entity selected with Zone Temperature Control tooltip, and zone air temperature points listed on the right](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-add-devices-ztss.png?fit=max\&auto=format\&n=i9tCc_I6OZNqDXAw\&q=85\&s=25b68295b919a709450400827a5ae72d)

Add Devices with vav and ZTSS selected

Select `Save` in the dialog to return to Workflow Details.

Step 3

### Build the detection logic

Open the `Logic` tab. Drag blocks from the left panel onto the canvas and connect outputs to inputs.

You build three layers: read the points, compare the sensor to a threshold, then delay and trigger the alarm.

Substep 3.1

#### Add the read points

![Dragging two Number Point blocks onto the Logic canvas and setting Main sensor and Secondary setpoint fields](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-add-number-points.gif?s=bb523a7706d84dfdeeee591e91d48e49)

Drag two `Number Point` blocks from Read onto the canvas.

| Block | Name | Role | Field |
| - | - | - | - |
| Sensor | `ZAT Sensor` | `Main` | `zone_air_temperature_sensor` |
| Setpoint | `ZAT Setpoint` | `Secondary` | `zone_air_temperature_setpoint` |

Every routine needs exactly one `Main` read block. The system uses that point as the reference when an event links to other Cloud BMS modules. Set all other reads to `Secondary`.

> [!TIP]
>
> No setpoint on the device? Skip the setpoint Number Point. In the next substep, compare the sensor to a Number parameter instead.

Substep 3.2

#### Compare sensor to threshold

A deadband (An allowable offset from the setpoint. The fault condition is true only after the sensor crosses setpoint plus (or minus) this offset.) is a buffer around the setpoint. Without it, a sensor that briefly ticks one degree over setpoint can raise an event. With it, the zone must move further past the setpoint before the comparison turns true.

Use a deadband when you want a more severe, less noisy alert. You can still tune the value later in Configs without rewriting the logic.

**1. Add Setpoint Deadband**

Drag a `Number` parameter from Parameters. Set `Name` to `Setpoint Deadband` and `Value` to `5`.

![Adding a Number parameter block named Setpoint Deadband with value 5](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-add-deadband.gif?s=1a75a7700ee55382a7711f2ea523821e)

**2. Sum setpoint and deadband**

Drag a `Sum` block. Connect `ZAT Setpoint` `Value` to the first operand. Connect `Setpoint Deadband` `Output` to the second operand.

The Sum result is your effective threshold: setpoint plus deadband.

![Connecting setpoint Value and Setpoint Deadband Output into a Sum block](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-add-sum.gif?s=457d55548f9ddbad763a35a747d6235e)

**3. Add Greater Than**

Drag a `Greater Than` block. Connect `ZAT Sensor` `Value` to the left operand. Connect the Sum `Result` to the right operand.

The block outputs a boolean `Result` that is true when the sensor is greater than setpoint plus deadband.

![Connecting sensor Value and Sum Result into a Greater Than block](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-greater-than.gif?s=a331ede9aa1a6022ee7e0a70173e7b02)

> [!NOTE]
>
> Building a less-than rule? Use `Less Than` instead. Comparing to a fixed limit with no setpoint? Wire the sensor to Greater Than and use the Number parameter as the right operand. Skip Sum.

Substep 3.3

#### Add delay and alarm trigger

Deadband reduces how often the condition becomes true. Debounce reduces how quickly a true condition becomes an event. Together they filter brief spikes and leave more meaningful alerts.

**1. Add Debounce**

Drag a `Debounce` block. Set the unit to `Minutes` and the count to `15`. Connect the Greater Than `Result` to the Debounce input.

Debounce outputs a value only when that value stays unchanged for the full period.

![Adding a Debounce block set to 15 minutes and connecting Greater Than Result to Debounce](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-debounce.gif?s=a37ef8445ceba38790664640b5d23f8d)

> [!NOTE]
>
> Library routines often expose delay as an `Alarm On Delay` Number parameter. Debounce is the timing block that holds a stable true condition before the alarm.

**2. Add Alarm Trigger**

Drag an `Alarm Trigger` block. Connect the Debounce `Output` to it.

When Alarm Trigger receives `true`, FDD generates an event. Without this block, the routine cannot create events.

![Connecting Debounce Output to an Alarm Trigger block](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-alarm-trigger.gif?s=a96e72a5db3ada3357f3c9841a1e4fef)

![Completed logic canvas with ZAT Sensor Main, ZAT Setpoint Secondary, Setpoint Deadband, Sum, Greater Than, Debounce at 15 minutes, and Alarm Trigger](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-completed-canvas.png?fit=max\&auto=format\&n=i9tCc_I6OZNqDXAw\&q=85\&s=dad98064040d4273ee3d62b4faed2ae8)

Completed VAV Over Setpoint pipeline

Step 4

### Test in the debugger

![Debugger tab showing Setpoint Deadband 5, ZAT Sensor 50, ZAT Setpoint 40, and Simulator log with Event Started and Event Ended](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-debugger.png?fit=max\&auto=format\&n=i9tCc_I6OZNqDXAw\&q=85\&s=5254c6ba50556d96ca5c2749510af8c2)

Debugger with over-threshold inputs and Event Started in the Simulator

Open the `Debugger` tab and prove the rule before you enable it on live devices.

**1. Review PARAMS**

Confirm `Setpoint Deadband` is `5` (or the value you want to test).

**2. Start Simulation**

Select `Start Simulation`.

**3. Send an over-threshold case**

Set `ZAT Sensor` above setpoint plus deadband (for example, sensor `50` and setpoint `40`). Set status to `ok`, then select `Send`.

With a 15-minute Debounce, wait for the Simulator to log `Event Started` after the delay.

**4. Send a should-not-fire case**

Set the sensor below the threshold and select `Send`. Confirm the routine does not start a new event for that input.

**5. Save the routine**

Select `Save`. The routine appears in the Routines list and becomes available under Configs.

> [!TIP]
>
> Debounce runs in real time during simulation. Temporarily set Debounce to seconds to speed up testing, then return to minutes before you save.

Step 5

### Configure and enable

![Batch Configuration page with callouts for Configs in the sidebar, VAV Over Setpoint selected, and the Configure button](https://mintcdn.com/kodelabs/i9tCc_I6OZNqDXAw/images/kode-os/fdd/tutorials/fdd-tutorial-configs-configure.png?fit=max\&auto=format\&n=i9tCc_I6OZNqDXAw\&q=85\&s=8114c0e9810f6c7cda07e939bcf83383)

Select VAV Over Setpoint on Configs, then select Configure

Apply the routine to devices and start monitoring.

**1. Open Configs**

Open `FDD` > `Configs`. Search for `VAV Over Setpoint`.

**2. Select the routine and Configure**

Select the checkbox for `VAV Over Setpoint`, then select `Configure` in the bottom toolbar.

**3. Choose a notification policy**

Batch configure asks you to pick a notification policy (Defines which contacts receive notifications and through which channels.) before it finishes.

Choose an existing policy for this building, or create one under `Policies` first. See [Notification policies](https://docs.kodelabs.com/products/fdd/notification-policies.md) if your site does not have one yet.

**4. Finish device and status setup**

Select compatible VAVs. In `Routine Params`, set `Setpoint Deadband` for this building.

In `Status Setup`, turn on `Event Config` so the routine can generate events. Enable `Routine Config` so the folder monitors devices.

**5. Configure and Enable**

Select `Configure and Enable` when you want monitoring to start immediately.

> [!NOTE]
>
> If your site always prompts for a policy during Configure, that is expected for this path. You can change the assigned policy later in Config Details under Notification Settings.

See [FDD configuration](https://docs.kodelabs.com/products/fdd/configuration.md) for Multi-Config folders and detailed settings.

Step 6

### Confirm the event

Close the loop by confirming the routine can produce a live event.

**1. Open Events**

Open `FDD` > `Events` > `List`.

**2. Find your routine**

Filter or search for `VAV Over Setpoint` (or the device you enabled).

**3. Open the event report**

Open the event and confirm the device, parameters, and condition match the rule you built.

> [!TIP]
>
> You created a flexible sensor-to-threshold routine, tested it in the debugger, enabled it on a device, and confirmed an event in FDD.

> [accordion] Events are not generating
>
> Confirm `Event Config` and `Routine Config` are on. Check that Debounce and deadband match real conditions. Confirm the routine status is Enabled.

> [accordion] Too many notifications
>
> Increase Debounce duration or widen `Setpoint Deadband` to filter transient conditions.

> [accordion] No compatible devices found
>
> Verify devices have the correct point templating. Routines match devices from the canonical types and entities on the routine.

## Related reading

> [card] [What is Fault Detection and Diagnostics?](https://docs.kodelabs.com/products/fdd/overview.md)
>
> Learn how events, incidents, and faults fit together.

> [card] [Routine logic blocks](https://docs.kodelabs.com/products/fdd/routine-logic-blocks.md)
>
> Explore comparison, timing, parameter, and alarm blocks beyond this walkthrough.

> [card] [FDD configuration](https://docs.kodelabs.com/products/fdd/configuration.md)
>
> Tune devices, parameters, Multi-Config folders, and status setup.

> [card] [Notification policies](https://docs.kodelabs.com/products/fdd/notification-policies.md)
>
> Control who gets notified and through which channels when events fire.

> [card] [Events](https://docs.kodelabs.com/products/fdd/events.md)
>
> Triage, acknowledge, and investigate events from the Events list.

> [card] [Routine library](https://docs.kodelabs.com/products/fdd/routine-library.md)
>
> Browse pre-built routines you can configure without building logic from scratch.
