> For the complete documentation index, see [llms.txt](https://help.tillit.cloud/tillit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tillit.cloud/tillit/knowledge-base/setting-up-tillit/causal-analysis.md).

# Causal Analysis

## Overview

Causal Analysis is an automated root-cause detection feature in Tillit. Its primary objective is to automatically identify and categorize machine downtime events, eliminating the need for operators to manually select and justify downtime reasons on the shop floor.

By capturing real-time telemetry from machine PLCs at the exact moment a line stoppage occurs, Tillit automatically determines **why** the line stopped (*Event Reason*) and **where** or on which equipment the fault originated (*Machine Reason*).

{% hint style="info" icon="lightbulb" %}
On the shop floor interface, Tillit presents these automated root-cause suggestions identified by a lightbulb icon. Operators can quickly review and accept these suggestions individually or in bulk, drastically reducing manual data entry time.
{% endhint %}

Causal Analysis helps to trace the journey of an alarm signal from the physical machine to the Tillit user interface:

<figure><img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2FOdhIuFmmKiEzYDwO2AYE%2Fimage.png?alt=media&amp;token=ae85c92d-1f2e-41b3-b404-358146c3ad5e" alt=""><figcaption><p>See <a href="https://help.tillit.cloud/tillit/knowledge-base/setting-up-tillit/causal-analysis/detailed-data-and-hardware-flow.md">Detailed data &#x26; Hardware Flow</a> for more information.</p></figcaption></figure>

## Setting Up Causal Analysis

### **Prerequisites & Integration Setup: Connecting PLC & Ignition to Tillit DO**

For Causal Analysis to operate successfully and automatically suggest downtime reasons, data flow must be configured correctly across your hardware and software stack:

#### Ignition & PLC Setup:

{% hint style="info" %}
It is the user's/integrator's responsibility to configure the logic on the PLC/SCADA side to push alarm signals to [Ignition](https://help.tillit.cloud/tillit/tools/ignition-module.md).
{% endhint %}

{% hint style="info" %}
Factory assets must first be created within the Tillit DO environment. Once created, the Tillit module within Ignition will perform a refresh and mirror this asset hierarchy directly into the Ignition Tags.

<img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2FXhUNgHOFjMn2wcClp9c8%2F1.png?alt=media&amp;token=ca3f08c9-cbfd-4e67-b1b3-2a923d685e0b" alt="" data-size="original">
{% endhint %}

**Within the specific asset hierarchy in Ignition, the user must map and update two specific tags**:

* `AlarmTriggered`
* `AlarmCleared`

<figure><img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2FqW2XTbQb1PLhqkkjUtcc%2F7.png?alt=media&amp;token=2b233000-c097-4d8c-8ab7-d7ee25f971b6" alt=""><figcaption></figcaption></figure>

These control tags are located in the ***Write*** section of each corresponding asset within the Tillit module's tag structure. It is exactly to these two tags that the fault codes sent by the PLC must be directed in order for the system to trigger or clear the event.

<figure><img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2FXq3BBcxAqExRsUMnEtW2%2F2.png?alt=media&amp;token=edf26bba-048d-43c0-8dc9-e1e977468ba5" alt=""><figcaption></figcaption></figure>

#### Alarm Dashboard

Ignition provides a dedicated ***Alarm Dashboard*** on its interface.

<figure><img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2FW0VZtMLXCXnmK6pBRCy0%2F3.png?alt=media&amp;token=c5dd32c8-4115-432a-a7d4-65b3c82e77b4" alt=""><figcaption></figcaption></figure>

This dashboard offers a quick overview of the history of all alarms that have been triggered and cleared over time for each asset. To prevent data overload and optimize performance, the system keeps a recent rolling window, limiting the history to the last 5,000 events.

The Alarm Dashboard is divided into key viewing areas to help monitor the line's status:

* **Current Alarm State:** Displays the alarms that are currently active. You can filter by Asset or Fault Code to pinpoint ongoing issues.

<figure><img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2FL89rq5ZeYOJAQwFJHly1%2F4.png?alt=media&amp;token=fc8201c2-6be3-4030-9acb-532a008a7909" alt="" width="375"><figcaption></figcaption></figure>

* **Recent Events:** Provides a running history of all alarm triggers and clears across all assets. While Tillit does not use this historical display for the Causal Analysis logic itself, it is highly useful for troubleshooting. It allows users to filter by specific asset names or fault codes to track the exact transitions an alarm has gone through recently.

<figure><img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2FIXaqp6pI4gd6bVX2R8ME%2F5.png?alt=media&amp;token=31282f82-e997-4403-a5a3-38adc0b05909" alt="" width="375"><figcaption></figcaption></figure>

Within the Alarm Dashboard, the **Administration** section contains critical settings for data management and event processing:

* **Event Retention:** Determines the maximum number of processed events (alarm triggers and clears) to keep in the local history window. The default value is 5000. This rolling window prevents the data from growing indefinitely, preserving system memory while keeping enough recent history for troubleshooting.
* **Alarm Context Lookback (seconds)**: This is a crucial setting that dictates which alarms are linked to a stoppage event. When an equipment stop event is raised, the system looks back in time by this specified duration (e.g., 30 seconds) to find any alarms that were triggered or cleared for the assets involved in the current order. Only the alarms within this specific time window are packaged and sent to Tillit DO to be evaluated by the Causal Analysis rules.
* **Reset Data:** The "Reset All Alarm Data" button allows you to manually clear the current tracked alarms and events history if a full reset is needed.

<figure><img src="https://352909507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrNT40XJFAFlAhUX8CcQS%2Fuploads%2F8CoUZtKwrVD94s7Ycxpp%2F6.png?alt=media&amp;token=a10ffce8-7890-49cd-8904-84f22bbf5acf" alt=""><figcaption></figcaption></figure>

#### Data Flow Example:

* When a machine fault occurs (or during manual testing), the PLC updates the `AlarmTriggered` tag value in Ignition to the corresponding code (e.g., `000000001`).
* Ignition transmits this payload to Tillit DO.
* Provided that `Alarm Types`, `Alarm Type Assignments`, and `Rules` are correctly set up in Tillit DO, the system will record the downtime event and display the suggested root cause (e.g., *Short Circuit*) on the Downtime screen.

### Set Up in Tillit DO

For Causal Analysis to work successfully, administrators must complete the following configuration steps in Tillit:

{% stepper %}
{% step %}

#### Alarm Types

Catalog all physical PLC fault codes into Tillit as standardized, human-readable alarm definitions.

**See** [**Alarm Types**](https://help.tillit.cloud/tillit/knowledge-base/setting-up-tillit/causal-analysis/alarm-types.md) **for configuration details.**
{% endstep %}

{% step %}

#### Alarm Assignments

Map each cataloged Alarm Type to its corresponding physical asset in the Tillit Asset Hierarchy.

**See** [**Alarm Assignments**](https://help.tillit.cloud/tillit/knowledge-base/setting-up-tillit/causal-analysis/alarm-assignments.md) **for configuration details.**
{% endstep %}

{% step %}

#### Rules Configuration

Build conditional logic (AND/OR) mapping combinations of active alarms and states to specific *Event* and *Machine* reasons. Set rule priorities.

**See** [**Rules**](https://help.tillit.cloud/tillit/knowledge-base/setting-up-tillit/causal-analysis/rules.md) **for configuration details.**
{% endstep %}

{% step %}

#### Rule Set Activation

Test the logic using the Preview Tool, then publish and activate the Rule Set for the line.

**See** [**Rules**](https://help.tillit.cloud/tillit/knowledge-base/setting-up-tillit/causal-analysis/rules.md) **for details.**
{% endstep %}
{% endstepper %}
