OEE-simulators Introduction

Introduction OEE-simulators microservice

The Cumulocity IoT OEE application is a powerful tool for measuring the efficiency, effectiveness, and performance of production processes. By breaking down processes into the three components of Availability, Performance, and Quality, the OEE application allows users to identify and measure problems and provides a standard method of benchmarking progress to optimize production processes.
To make it even easier for users to get started with the OEE application, the OEE-simulators microservice provides a collection of simulators that can be used to automatically create preconfigured devices and start sending data of events and measurements to the OEE application. These simulators are designed to simulate commonly seen machine types, making it easier to calculate OEE based on configuration profiles that can be set up in the OEE app. The OEE-simulators are a powerful tool that can help users to save time and resources and get started with the Cumulocity IoT OEE app quickly and easily.

The OEE-simulators microservice has notable features that make it attractive and worth giving a try:

  1. Configuration in JSON, which eliminates the need to write code.
  2. Automatic creation of simulators and oee-profiles and data transmission between them.
  3. Identification of simulators and oee- profiles through a configurable externalId.
  4. Option to disable devices, preventing them from sending any events or measurements.
  5. Written in Python, allowing for easy modification and further development.
  6. Simulators that operate based on their assigned shift and random status probabilities.

Description OEE-Simulators

OEE-simulators offers two main features:

  • The oee-simulators microservice generates simulators that send data to the OEE application and produces OEE profiles, revealing the OEE calculation results. The data is sent periodically based on the pre-defined frequency and also on shiftplan that the simulators are assigned to.
  • The profile generator creates/deletes OEE calculation profiles from the command line. It is also used as a support script in the main script simulator.py.

There are extra features that support the use of simulators and OEE application:

  • The export profile data exports Measurements or/and Alarms from OEE profiles into json data files.
  • The import data uploads Measurements or/and Alarms from json data files to OEE profiles. The sample json data files in export data directory can be used to test the import script.


  • Having a Cumulocity tenant with OEE application fully installed (oee-bundle, apama-oeeapp, oee-ui) and full administration right to work with inventory, alarms, measurements, events, identity, oee configuration (refer to cumulocity.json for more details on required roles).
  • In order to use the OEE-simulators:
    • Prepare microservice zip package:
      • The repository can be cloned and built manually by following the instruction in README.md at section build-the-docker-image.
      • Or download the release package from Github release section.
    • Upload the zip package to the Cumulocity microservice section and subscribe to it. It takes a bit of time for all simulators to generate data.

How to create a simulator

If you are working with simulators and testing software or applications, you may want to create your own sample definitions instead of relying on the ones provided in the repository. This can help you tailor your simulations to specific use cases or scenarios and ensure that they accurately reflect the behavior of the system you are testing.

1. Create simulator

There are two main files that must be created/modified in order to establish a simulator:

  • simulator.json: this json file provides definition for the simulator. The creation of the simulator definition is explained in the README.md inside the simulators directory.

  • profile template: This template file is the pre-defined definition for oee profile so that the script can generate oee profiles which connect to the appropriate simulator.

There are a couple of considerations to take into account:

  • If you are not familiar with the template creation of oee profile, only copy the sample template and change the name field of the oee profile. Any other modifications should be conducted carefully or the oee profile may not work properly.
  • The profile template file’s name must be set as the simulator’s id definition in simulator.json (for example: sim_001) and add the “_profile.template” part to it (sim_001_profile.template).
  • The template file must be put inside the profile_templates directory which locates inside the main directory.

There is a feature to set up the shift for the simulators called shiftplan. It can be done by defining shift information in shiftplans.json. The instruction on defining the shiftplan is written in README.md inside simulators directory. After having the shiftplan, the locationId field can be added to the definition of the simulator that follows the shift.

2. Check the availability of simulators and oee-profiles

  • After running the oee-simulators microservice, wait a bit for it to generate simulators and data for them.

  • Open Device management application in the Cumulocity platform, click the Devices tab on the right-hand side and click the All devices option. The simulators which are created by the oee-simulators microservice can be seen here.

  • Now choose any simulator, i.e Normal #1, to open the device-info window and click Child devices. The oee-profile of the chosen simulator is shown here, i.e Simulator Normal #1 - 1[OEE calculation profile].

3. Check the function of simulators and oee-profiles

  • For the simulators, click any simulator and check the Events tab. You can see some events appeared like Availability, Piece_Produced, etc.

  • For the oee-profiles, click an oee-profile inside a simulator and check the Measurements tab. You can see the graphs such as Actual production amount, Actual production time, etc.

Notice: Sometimes, it takes about 1-2 hours so that all simulators can generate events and measurements (maybe longer due to shiftplan).

Export and import data of oee-profiles

Exporting and importing alarms and measurements data from oee-profiles is crucial for several reasons:

  • First, it allows users to back up their data and restore it if necessary, ensuring data continuity and reliability.
  • Second, it enables easy data sharing between different applications, systems, or organizations, facilitating collaboration and analysis.
  • Finally, exporting and importing data from the Cumulocity platform can help users comply with regulations, audits, and data governance policies, ensuring data privacy, security, and transparency.

Therefore, the scripts ExportProfileData.py and ImportData.py in extras directory are created to solve the issues from these reasons. The manual for the scripts can be found in README.md inside the directory.

There are notices when using these scripts:

  • Inside extras, the directory is an export_data directory that stores the JSON data files of the simulators. The name of the files follows the external Id of the simulator.
  • The export and import script will store and take the data from files in this directory so users should copy the old data files first before running the export script to avoid the loss of any important data.