Equipment Performance Library Manual

About this documentation

This documentation provides essential information for working with components of the DDAS software ecosystem. It is intended for software developers and machine manufacturers who integrate, validate, and operate DDAS function blocks within CODESYS‑based applications.

Note!

Before installing or configuring any software, ensure that you have read and understood the operating instructions of all relevant hardware devices!

Tip!

Further information can be found at: https://www.ddas.digital

This manual is part of the DDAS library collection, which includes documentation for license management, date and time handling, scheduling, equipment performance, and other functional modules:

Document history

General

Library

This library provides a comprehensive solution for real-time monitoring and historical tracking of equipment performance. It enables the calculation and analysis of key performance indicators (KPIs) such as production counts, overall equipment effectiveness (OEE), performance rates, and loss metrics across different operational contexts, including batches, shifts, or product runs.

In addition to real-time evaluation, the library supports the structured capture and storage of performance data over time. This allows for detailed trend analysis, traceability, and long-term performance assessment.

The solution includes capabilities for identifying and analysing production losses and operational states, helping to improve transparency and support continuous optimization of manufacturing processes.

The library includes the following user function blocks:

• EquipmentPerformance

• EP_History

• EP_Result

EquipmentPerformance

This Function block calculating and tracking key equipment performance indicators (KPIs), including production counts,

OEE, performance rates, and loss analysis, for an active batch, shift, or product run.

EP_History

This Function block stores equipment performance data into historical arrays, capturing snapshots of performance, production, loss, and top-state metrics from the EquipmentPerformance function block.

EP_Result

This function block evaluates the history arrays of EP_History and returns one total result over several shifts, batches or product runs. The running schedule can be included.

Detailed descriptions of the function blocks and their relevant dependencies are provided in the following chapters.

Licensing

All DDAS libraries require a valid license. The license check is performed by the DDAS License Manager library (DDAS_LicenseManager_Lib), which is added to the project automatically as a dependency of this library. The function blocks of this library need no licensing code.

How the license is activated depends on your product:

• DDAS Machine Insight Suite (DDAS activation keys): DDAS License Manager Manual, https://ddas.cloudet.digital/html/DDAS-LicenseManager-LibraryManual-en.html

• DDAS Machine Insight Suite SL (CODESYS device license): DDAS Machine Insight Suite SL – Installation and Licensing, https://ddas.cloudet.digital/html/DDAS-MachineInsightSuiteSL-Manual-en.html

Without a valid license, the library runs in a time-limited demo mode, as described in the licensing documentation of your product. After the demo has expired, all function blocks of this library stop and report error 10 (no_ValidLicense). The function DDAS_LM.GetLicenseInfo returns the license status and the cause.

Note: The function Get_sError is available in every library and returns the error text and the enumeration value for an error code of this library.

FB EquipmentPerformance

General Information

This chapter describes the function block EquipmentPerformance.

Function Block Name: EquipmentPerformance

Library: DDAS_EquipmentPerformance_Lib

Dependent CODESYS libraries: None

CODESYS Version Compatibility: CODESYS V3.5 and higher

License / Usage Restrictions: Requires valid full or demo library license

Purpose & Scope

This Function block calculating and tracking key equipment performance indicators (KPIs), including production counts, OEE, performance rates, and loss analysis, for an active batch, shift, or product run.

It processes production data, schedules, and state information to generate detailed KPIs, production insights, and loss analytics, supporting performance optimization, OEE tracking, and reporting at batch, shift, or product level.

Typical Use Cases

This function block is used in industrial automation systems to monitor and analyse machine performance in real time.

Functional Overview

When enabled, the Equipment Performance function block provides real-time calculation and tracking of key equipment performance indicators (KPIs) for an active production context, such as a batch, shift, or product run.

It continuously processes operational inputs including production counts, product cycle time, machine performance targets, equipment states, and time information to generate a comprehensive view of machine efficiency and productivity.

The function block evaluates production output by distinguishing between good (OK) and defective (NOK) units and compares actual performance against planned production rates. Based on this data, it calculates key metrics such as performance rates and overall equipment effectiveness (OEE), enabling transparent assessment of production efficiency.

In addition to production metrics, the function block monitors equipment states to identify and categorize production losses. It analyzes downtime, scheduled breaks, and operational conditions to provide detailed loss information and supports prioritization through top-state analysis, highlighting the most significant contributors to reduced performance.

The solution manages lifecycle events of production schedules, including activation and completion, ensuring that KPI tracking is aligned with the current operational context. It also handles transitions between production runs by resetting and reinitializing relevant data at the end of each schedule.

All calculated KPIs and analytical results are made available through structured data outputs, enabling further processing, visualization, or storage in higher-level systems. Built-in status and diagnostic signals provide transparency regarding execution state, licensing, and potential errors, ensuring reliable integration into industrial automation environments.

Stop counting and short stops

Every stop is counted once, with one occurrence and its whole duration. Whether it counts as a short stop or as a long stop depends on its duration:

While a stop is running and has not yet reached the threshold, it is shown as a short stop. When it reaches the threshold, its occurrence and the time elapsed so far are moved from the short stop to the long stop. At this moment tPerformanceLoss decreases by this amount and tAvailabilityLoss increases by the same amount; the sum tUnplannedDowntime does not change.

Example with a threshold of 5 s: a stop of 2 s results in tStarvedShort = 2 s and uiStarvedShort = 1. A stop of 7 s results in tStarved = 7 s and uiStarved = 1; nothing remains in the short stop.

If a schedule ends while a stop is still below the threshold, the time elapsed so far stays a short stop of this schedule. During an active scheduled break (xActiveScheduledBreak) no stops are counted.

Parts without an active schedule

Parts that are counted while no schedule is active (xActivated = FALSE) are not lost. The function block reports the hint 35 (productCount_NoSchedule) as long as no schedule is active and continues to run. The parts are taken over into the next schedule: they are included in lrQuantity, lrQuantityOK and lrQuantityNOK, but not in the performance, the throughput and the speed loss of that schedule.

Behaviour with invalid input parameters

The errors 30 and 32 are reported at the end of the PLC cycle, so that xScheduleEnd and the start of the next schedule are not affected by them.

Note: Multiple instances can be used in parallel. For example, one instance can monitor batch or shift OEE KPIs, while another instance can be used to track product-specific OEE KPIs.

Interface Description

Function block Inputs and Outputs

Execution & Timing Behaviour

The function block is intended to be executed cyclically in a task context.

Timing precision depends on the configured task cycle time and target platform

Error Handling & Diagnostics

If an internal error, a library issue, or a licensing problem occurs, xError is set to TRUE and iErrorID provides the corresponding error code. Detailed descriptions of the error codes are defined in the enumeration eError.

Assumptions & Limitations

Accuracy depends on the system clock. Hardware‑dependent behavior may vary across different CODESYS platforms.

All durations are calculated from the local date and time (dtLocalDateTime) with a resolution of one second. A change of the clock during an active schedule therefore changes the durations of this schedule: when the clock is set forward (for example at the start of daylight saving time), running durations jump forward by the same amount. When the clock is set back (for example at the end of daylight saving time), the function block may report error 21 for a time and does not calculate. Only the schedule that is active during the change is affected.

The function block KPI calculation is restricted to a 49-day window. If the required build time extends beyond this period, the function block cannot provide a valid result.

Before ordering this library, please verify the correct functionality of the library function block in your target system.

Example Implementation

Declaration and Call of the Function Block EquipmentPerformance:

GVL_MIF:

VAR_GLOBAL

END_VAR

GVL_Par_EP:

VAR_GLOBAL

END_VAR

GVL_EP_History:

VAR_GLOBAL RETAIN

END_VAR

VAR

fb_EP : DDAS_EP.EquipmentPerformance;

END_VAR

FB call in structure text:

fb_ EP(

xEnabled := TRUE,

xActivated := GVL_MIF.xActiveSchedule,

xActiveScheduledBreak := GVL_MIF.xActiveBreak,

diScheduleID := GVL_MIF.diJobID,

sScheduleDescription := GVL_MIF.sActiveScheduleDesc,

diProductID := GVL_MIF.diProductID,

sProductDescription := GVL_MIF.sProductDescription,

rProductsPerMin := GVL_MIF.rProductsPerMin,

lrProductCountOK := GVL_MIF.lrActualBuildOK,

lrProductCountNOK := GVL_MIF.lrActualBuildNOK,

rOEEpercent := GVL_MIF.rOEEpercent,

dtLocalDateTime := GVL_MIF.dtLocalDateTime,

eProdState := GVL_Par_EP.eProdState,

scPar := GVL_Par_EP.scPar,

scEP := GVL_EP_History.scEP,

scPD := GVL_EP_History.scPD,

scPL := GVL_EP_History.scPL,

scTS := GVL_EP_History.scTS

);

FB call in continuous function chart diagram:

Function block sample input and output parameter:

Screenshot example in Online / Monitor mode

Demo Visualisation

FB EP_History

General Information

This chapter describes the function block EP_History.

Function Block Name: EP_History

Library: DDAS_EquipmentPerformance_Lib

Dependent Codesys libraries: None

CODESYS Version Compatibility: CODESYS V3.5 and higher

License / Usage Restrictions: Requires valid full or demo library license

Purpose & Scope

This function block stores equipment performance data into historical arrays, capturing snapshots of performance, production, loss, and top-state metrics from the EquipmentPerformance function block.

This function block is used to maintain a rolling history of equipment performance data for analysis, visualization, and reporting.

It enables controlled storage and clearing of historical KPI datasets, preserving time-based snapshots in reverse chronological order.

Typical Use Cases

Typical applications include trend analysis, dashboard visualization, batch/shift comparison, and short-term buffering of performance data for higher-level systems such as SCADA, MES, or cloud analytics.

Functional Overview

When enabled, the Equipment Performance History function block provides structured storage and management of time-based equipment performance data. It captures snapshots of key performance datasets, including performance metrics, production details, loss information, and top-state analysis, and organizes them into historical records for further use.

The function block enables selective recording of different data categories, allowing flexible control over which information is stored. Data is captured on demand and inserted into history buffers in reverse chronological order, ensuring that the most recent dataset is always immediately accessible while maintaining a defined history depth.

In addition to data storage, the function block supports controlled clearing of historical records, enabling reset operations when required, such as at the start of new production phases or for memory management purposes.

The stored historical data can be used for trend analysis, visualization, and reporting in higher-level systems. This supports use cases such as performance monitoring over time, comparison of batches or shifts, and short-term buffering of KPIs before transfer to SCADA, MES, or cloud-based analytics platforms.

Status signals indicate the successful execution of storage and clearing operations, while integrated diagnostic outputs provide transparency regarding licensing status and potential errors. This ensures reliable and traceable operation within industrial automation environments.

Note: Multiple instances can be used in parallel. For example, one instance can store history data of batch or shift OEE KPIs, while another instance can be used to store history data of product-specific OEE KPIs.

Interface Description

Function block Inputs and Outputs

Execution & Timing Behaviour

The function block is intended to be executed cyclically in a task context.

Timing precision depends on the configured task cycle time and target platform

Error Handling & Diagnostics

If an internal error, a library issue, or a licensing problem occurs, xError is set to TRUE and iErrorID provides the corresponding error code. Detailed descriptions of the error codes are defined in the enumeration eError.

Assumptions & Limitations

Accuracy depends on the system clock. Hardware‑dependent behavior may vary across different CODESYS platforms.

Before ordering this library, please verify the correct functionality of the library function block in your target system.

Example Implementation

Declaration and Call of the Function Block EP_History:

GVL_Par_EP:

VAR_GLOBAL

END_VAR

GVL_EP_History:

VAR_GLOBAL RETAIN

END_VAR

Note: Declare the data of the running schedule and the history arrays as RETAIN, so that they survive a restart of the controller and a power failure. To keep them also after a cold reset or a new download of the application, declare them as persistent variables. The Application Template Manual describes both options.

VAR

fb_EP_History : DDAS_EP.EP_History;

END_VAR

FB call in structure text:

fb_EP_History(

xEnabled := TRUE,

xStoreHistoryEP := TRUE,

xStoreHistoryPD := TRUE,

xStoreHistoryPL := TRUE,

xStoreHistoryTS := TRUE,

xStoreHistoryData := GVL_Par_EP.xScheduleEnd,

xClearHistoryData := GVL_Par_EP.xClearHistoryData,

scEP := GVL_EP_History.scEP,

scPD := GVL_EP_History.scPD,

scPL := GVL_EP_History.scPL,

scTS := GVL_EP_History.scTS,

ascEP := GVL_EP_History.ascEP,

ascPD := GVL_EP_History.ascPD,

ascPL := GVL_EP_History.ascPL,

ascTS := GVL_EP_History.ascTS

);

FB call in continuous function chart diagram:

Function block sample input and output parameter:

Screenshot example in Online / Monitor mode

FB EP_Result

General Information

This chapter describes the function block EP_Result.

Function Block Name: EP_Result

Library: DDAS_EquipmentPerformance_Lib

Dependent CODESYS libraries: Standard

CODESYS Version Compatibility: CODESYS V3.5 and higher

License / Usage Restrictions: Requires valid full or demo library license

Purpose & Scope

This function block evaluates the history arrays of the function block EP_History and returns one total result over several schedules (shifts, batches or product runs). The running schedule can be included.

Typical Use Cases

Analysis on request, for example the result of a day (three shifts), of a week or of the last batches, for a dashboard or for a report to a higher-level system.

Functional Overview

When enabled, the function block calculates the result once on a rising edge of xExecute and holds it until the next calculation. It does not calculate cyclically.

The function block reads the newest entries of the history arrays, starting at index 0. The input uiHistoryEntries limits the number of entries; with 0 all stored entries are evaluated. With xIncludeActual = TRUE the running schedule is added. A running schedule that is empty or that is already stored as the newest history entry is not counted a second time.

A rising edge of xExecute within tMinInterval after the last calculation is ignored. This limits the load when the input is triggered from a visualization or a higher-level system.

The result is provided in the structure scEP_Result and is calculated as follows:

The KPIs are calculated from the sums. They are not the average of the KPIs of the single schedules.

The following values are not evaluated and stay empty: diScheduleID, sScheduleDescription, diProductID, sProductDescription and rProductTime in scPD, and eEP_PT in scPL.

Note: Multiple instances can be used in parallel on the same history arrays, for example one instance for the day and one for the week.

Interface Description

Function block Inputs and Outputs

The function block does not write to the Inout variables.

Execution & Timing Behaviour

The function block is intended to be executed cyclically in a task context. The result is calculated within one PLC cycle, on the rising edge of xExecute.

When the function block is disabled (xEnabled = FALSE), scTotal is cleared.

Error Handling & Diagnostics

If a licensing problem occurs or the result is not complete, xError is set to TRUE and iErrorID provides the corresponding error code (enumeration eError). The result stays visible also with an error. An error of a calculation is held until the next calculation.

Assumptions & Limitations

The history must contain Performance Details, Production Details and Production Loss Details (xStoreHistoryEP, xStoreHistoryPD and xStoreHistoryPL of EP_History = TRUE). Top State data of the history are not required.

The sum of a time is limited to 49 days, the sum of an occurrence to 65535. The KPIs are not affected by this limit.

Before ordering this library, please verify the correct functionality of the library function block in your target system.

Example Implementation

Declaration and Call of the Function Block EP_Result:

GVL_Par_EP:

VAR_GLOBAL

END_VAR

VAR

fb_EP_Result : DDAS_EP.EP_Result;

END_VAR

FB call in structure text:

fb_EP_Result(

xEnabled := TRUE,

xExecute := GVL_Par_EP.xExecute,

xIncludeActual := GVL_Par_EP.xIncludeActual,

uiHistoryEntries := GVL_Par_EP.uiHistoryEntries,

tMinInterval := GVL_Par_EP.tMinInterval,

dtLocalDateTime := GVL_MIF.dtLocalDateTime,

scEP := GVL_EP_History.scEP,

scPD := GVL_EP_History.scPD,

scPL := GVL_EP_History.scPL,

ascEP := GVL_EP_History.ascEP,

ascPD := GVL_EP_History.ascPD,

ascPL := GVL_EP_History.ascPL,

scTotal => GVL_Par_EP.scTotal

);

FB call in continuous function chart diagram:

Function block sample input and output parameter:

Screenshot example in Online / Monitor mode

Global

Structures

scPar

This structure provides input user‑configuration.

scPerformanceDetails

This structure provides Equipment performance KPI’s about the active scheduled batch, shift, or product run.

scProductionDetails

This structure provides detailed information about the active scheduled batch, shift, or product run.

scProductionLossDetails

This structure provides detailed information about the losses of the active scheduled batch, shift, or product run.

scTopState

This structure provides top-state analysis of the duration and occurrences of losses in the active scheduled batch, shift, or product run.

scTopStateDuration

This structure provides the duration of losses in the active scheduled batch, shift, or product run.

scTopStateOccurances

This structure provides occurrences of losses in the active scheduled batch, shift, or product run.

scEP_Result

This structure provides the result of an evaluation over several schedules (shifts, batches or product runs).

Enumerations

eProductionState

Defined input production states as enumeration.

eTopState

Defined provided production loss states as enumeration.

eEP_ProductionState

Defined output production states as enumeration.

eError

Library Possible Error Codes and Descriptions as enumeration.

Global Variable

GVL_Constant_EP

Library constants.

GVL_LibGuide

This Global Variable List provides the library GUID. It is used for activation keys (DDAS_LM.GVL_License) and for the license status (DDAS_LM.GetLicenseInfo); see the licensing documentation of your product.

Example Implementation

The following screenshot illustrates a complete implementation of the library function blocks.

The current local date, time, and day of the week can be obtained using the DDAS function block DDAS_DT.GetDateTimeInfo from the DDAS_DateTime_lib library.

Your Feedback Matters

These instructions have been prepared to the best of our knowledge and belief to provide you with the highest possible level of support when working with our product.

Despite our best efforts, we may not always fully achieve this objective. If you identify any issues or have suggestions for improvement, we would greatly appreciate your feedback.

Please send your comments or criticism in a short e‑mail to:

support@ddas.digital

Thank you for your support.

Your DDAS Application Software Team