> For the complete documentation index, see [llms.txt](https://docs.tricloudnexus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tricloudnexus.io/management-portal/oee/oee-concepts.md).

# OEE Concepts

How Availability, Performance and Quality combine into one OEE score, and how Sites, Areas, Equipment, Tags, Shifts and Stops fit together.

This page covers the vocabulary and the model used by the OEE feature in Tricloud Nexus. Read it once before configuring your first Site — most fields in the configuration UI map directly to one of the concepts below.

***

## The OEE Score

**OEE** (Overall Equipment Effectiveness) expresses, as a single score, how close a piece of equipment is to running at its full potential during the time it’s scheduled to run. It is the product of three pillars:

> **OEE = Availability × Performance × Quality**

| Pillar           | What it answers                                           | Typical loss it captures                                         |
| ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
| **Availability** | Was the equipment running when it was supposed to?        | Unplanned stops, breakdowns, micro-stops                         |
| **Performance**  | When it was running, did it run at the ideal speed?       | Slow cycles, reduced speed, minor stops below the stop threshold |
| **Quality**      | Of the units produced, how many met the expected quality? | Scrap, rework, rejected units                                    |

Each pillar is calculated independently and **can be enabled or disabled per equipment**. If, for example, you don’t yet collect quality data on a particular line, you can disable the Quality pillar and Nexus will calculate OEE as `Availability × Performance` until you turn Quality on.

Each pillar also has a **target percentage** so dashboards can compare the actual score against the expected score. There is an additional **Total OEE Target** for the combined score.

***

## The Structure: Site → Area → Equipment

OEE configuration lives in a three-level tree that mirrors a typical plant layout:

```
Site                  e.g. "Mintastic Fredericia" (a physical plant or location)
└── Area              e.g. "Gumbase" (a cell, line group, or production area)
    └── Equipment     e.g. "Mixer" (the machine OEE is calculated for)
```

| Node          | Configures                                                                                                          | Notes                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Site**      | Location (lat/long), time zone, OEE data store, **shift calendars**, **product lists**                              | All time-of-day calculations on equipment under this site use the Site’s time zone                               |
| **Area**      | Name and description only                                                                                           | Pure container — useful for organizing equipment, not for configuration. Areas have no OEE settings of their own |
| **Equipment** | OEE pillar enable + targets, **tag mapping**, shift assignment, planned stops, stop causes, state mapping, products | This is where the actual OEE calculation runs                                                                    |

The structure is created and re-organized from the **OEE → Sites** page. Drag-and-drop is constrained by node type: equipment can only live under an Area, Areas only under a Site, and Sites cannot be moved.

***

## Tags Drive the Calculation

Nexus doesn’t require any special PLC integration to compute OEE — it consumes the same **tags** you already collect through the [Designer](/management-portal/designer.md) (OPC-UA, MQTT, Modbus, etc.). On each equipment, the **Tag Mapping** tab tells the OEE engine which tags carry which signal:

* **State & Error Codes** — Equipment Run State, Error Code(s)
* **Product & Order** — Current Product Id, Order Id, Ordered Products count
* **Data Quality** — Total / Approved / Rejected counts (any two of the three are enough)

Each input slot can be filled in three ways:

* **Single Tag** — pick a tag from your asset hierarchy.
* **Single Tag with JSONata Value Parser** — for tags that carry structured payloads (e.g. a JSON object), extract the relevant field with a [JSONata](https://jsonata.org/) expression.
* **Calculation** — combine multiple tag values into one signal using a variable-based expression. Same syntax and operators as the [Equation data connector](/management-portal/designer/assets/data-connectors/equation.md), so anything that engine can express can drive an OEE input.

***

## Availability Categories Tie the Model Together

An **Availability Category** is a labelled, color-coded bucket that classifies time. Four types are built in:

* **Running** — productive time, counts toward Availability.
* **Idle** — scheduled time when the equipment should produce but isn’t (no orders, operator stop, line starvation, blocked downstream). Counts against **Performance**, not Availability.
* **Unplanned Stop** — counts against Availability (breakdown, jam, error).
* **Planned Stop** — does not count against Availability (changeover, maintenance, break).

You can create as many categories of each type as you like — the type drives the score effect, the name and color drive how it shows up in reporting.

Categories are global and managed under [**OEE → Availability**](/management-portal/oee/availability-categories.md). They’re referenced from two places:

1. **States Mapping** on each equipment maps raw state values (e.g. `Running`, `Stopped`) to a category.
2. **Planned Stops** on each equipment are mapped to a category — typically a `PlannedStop`-typed one — so they are excluded from Availability loss.

Because categories are global, a single change (e.g. renaming "Maintenance" or changing its color) is reflected wherever the category is used.

***

## Shifts and Planned Stops Shape "Scheduled Time"

The OEE engine produces facts continuously based on the equipment’s state. Two configuration concepts let you express *when the equipment is expected to run* so reporting can frame the score against scheduled time rather than wall-clock time:

* **Shift Calendars** are defined on the Site (using a recurring scheduler) and optionally **assigned** to each equipment, so dashboards can filter or group results by shift.
* **Planned Stops** are recurring downtime windows defined per equipment (changeovers, sanitation, scheduled maintenance, breaks). They’re published as dimension data alongside the facts, ready for queries to subtract from scheduled time when computing Availability.

A typical shift-aware Availability query reads:

> **Net Scheduled Time = Shift Time − Planned Stops**\
> **Availability = Run Time ÷ Net Scheduled Time**

But this framing is **applied by the query layer, not enforced by the engine**. If no shift is assigned, the engine still produces OEE facts; queries can either compute OEE across all equipment time or skip the shift filter altogether.

***

## Stop Causes Explain Lost Time

When the equipment isn’t running during scheduled time, the lost minutes are attributed to a **Stop Cause**. Stop Causes are configured per equipment and are categorized — most are `Unplanned Stop`, but you can also use `Planned Stop` for known categories of stop you don’t schedule individually.

To translate vendor error codes coming from a PLC or SCADA system into Stop Causes, the **Error Code Mapping** table on each equipment maps a numeric range (e.g. `101..110`) to a Stop Cause and an optional vendor description. Anything not matched falls into a default unmapped bucket; the special **No Error Value** field tells the engine which value means "no error currently active" (typically `0`).

***

## How OEE Is Calculated Over Time

Availability is measured from time, while Performance and Quality are measured per order and distributed across the time each order was actually running — and period totals are rolled up from summed base values rather than averaged percentages. These mechanics explain why your dashboards and trends look the way they do, and they have their own page: [**How OEE Is Calculated Over Time**](/management-portal/oee/oee-concepts/how-oee-is-calculated-over-time.md).

***

## Next

* Make sure the [Prerequisites](/management-portal/oee/prerequisites.md) are met.
* Then start building your structure in [Sites](/management-portal/oee/sites.md).