---
pdfexport: true
alias: tutorials-ei-scoping
description: "Explain where the effort of an equipment integration comes from and collect the answers that decide it before you estimate"
---

# Scoping an Integration

Each equipment integration is a separate problem, and even equipment from the same supplier can vary. See [[tutorials-ei-introduction]]. The effort of an integration still comes from a known set of drivers. Use this page to explain to the customer where that effort goes, and to collect the answers that decide it before you estimate. The page gives no effort figures: estimate from the answers and from the history of your own projects.

## Effort Drivers

| Effort driver | What raises the effort | More information |
|---|---|---|
| **Protocol and driver** | A driver that ships no driver definition, such as SECS/GEM, OPC UA, MQTT, TCP/IP, or REST Client, needs every ID collected from the equipment and declared. Equipment that fits no shipped driver needs a custom driver. The driver is chosen once: the driver definition, the parameters, and every equipment task are written for one protocol. | [[user-guide-automation-protocol-protocols-index]] |
| **Characterization and machine time** | The documentation of the equipment names its messages, but not always when the equipment produces them. The real behavior must be checked on the equipment, and machine time for tests is usually limited. | [[tutorials-basic-ei-concepts]] |
| **Use cases and MES interoperability** | Each use case is a workflow of its own. Each use case that calls MES adds services, replies, and timeouts to design and test. | [[tutorials-connectiot-mes-interop-scenarios]] |
| **Variation per machine** | Machines that differ only in their settings share one controller, with the settings kept in MES. Machines that differ in behavior need logic of their own. | [[tutorials-connectiot-landscape-design]] |
| **Custom code** | A Code task, a custom task, a converter, or a custom driver must be written, tested, versioned, and released as a package. | [Developer Portal](https://developer.criticalmanufacturing.com/explore/guides/customizations/automation/concepts/) |
| **Simulators for testing** | Without a simulator, every test needs the equipment. The Test Orchestrator emulates MES and provides simulators for many shipped protocols. | [Test Orchestrator simulators](https://developer.criticalmanufacturing.com/explore/guides/customizations/automation/how-tos/test-orchestrator/plugins/simulators/) |
| **Cost per release** | An upgrade of MES can bring steps of its own for each integration, such as moving tasks to **Automation Tasks Libraries**, migrating deprecated tasks, and rolling a new controller version out to every instance. | [Connect IoT 12.0 Upgrade Checklist](https://developer.criticalmanufacturing.com/explore/guides/migration/version-specific/1200/connect_iot_upgrade_checklist_1200/) |

Table: Effort drivers of an equipment integration

No fixed effort ranges apply per driver or per use case, because the effort depends on how the integration is used. Estimate it from the effort drivers above, and plan tests in conditions as similar as possible to production, to confirm that the integration meets the non-functional requirements.

## Characterization Checklist

Go through these questions with the equipment owner and the process owner. An open answer is a risk to name in the estimate.

### Equipment and Connection

- [ ] How does the equipment offer its data: files in a folder, a GEM host port, an OPC UA server, an MQTT broker, an HTTP API, or text on a socket?
- [ ] Who starts the conversation: the driver, or the equipment? For a GEM tool, which HSMS role does its manual state?
- [ ] Does another host, such as a vendor tool, already use the one host connection that a GEM tool accepts?
- [ ] Which network path and ports are open between the equipment and the **Automation Manager**, and in which direction?
- [ ] Does the driver need a Windows host, a device attached to the computer, or a mounted folder?

### Data, Events, and Commands

- [ ] For a driver that ships no definition, does the equipment document every ID: variables, collection events, reports, and remote commands for SECS/GEM, NodeIds for OPC UA, topics and payload encoding for MQTT, the frame format for TCP/IP, or the endpoints of a REST API?
- [ ] When does the equipment raise each event in the real process, and what happens to a file after it is written: is it appended to, moved, or deleted?
- [ ] Which commands does each use case send, in which equipment state, and what does the equipment reply?
- [ ] Which values does MES need, at which moment, and in which unit and format?

### Use Cases and MES

- [ ] Which use cases does the integration cover, for example data collection, tracking, recipe selection, or interlocking, and which MES services does each one call?
- [ ] Which use cases stop production when MES does not answer, and how long can each one wait?

### Variation and Scale

- [ ] How many machines are in scope, and do they share the model and the software version?
- [ ] What differs between the machines: only settings, such as a folder or an address, or also behavior?
- [ ] Does any use case need logic that no task of the product provides?

### Testing and Operation

- [ ] How much machine time is available for characterization and tests, and is there a simulator for the protocol?
- [ ] Which maintenance windows exist, and which changes must roll out without stopping production? See [[tutorials-automation-scheduled-action-what-is-asa]].
- [ ] Who operates the integration after go-live, and how often is MES upgraded? See [[operation-guide-connect-iot-runbook]].