---
render_macros: false
pdfexport: true
alias: tutorials-connectiot-learning-path
timetoread: true
tutorial: full
module: Connect IoT (Equipment Integration)
description: "Follow the ordered Connect IoT tutorials, from the first connection to troubleshooting, and check what you can do after each step"
---

# Connect IoT - Learning Path

## Overview

An equipment integration combines MES configuration, a driver for each piece of equipment, and workflows that decide what happens with each value. Each of these parts is easy to build and easy to get subtly wrong, and most mistakes only show at run time.

This learning path orders the Connect IoT tutorials for an integrator: an automation engineer who builds and maintains integrations and knows the equipment and its protocols, but is new to Connect IoT. Each step names the tutorial to complete, what you can do afterwards, and a few questions to check yourself before you move on. At the end, you can design, build, test, and troubleshoot an integration that connects equipment to MES.

!!! info
    For the entities and tasks used throughout the path, see [[user-guide-automation-index]] and [[user-guide-automation-tasks-index]].

## Learning Path

### Step 1: Basic Configuration

Complete [[tutorials-connectiot-configuration-basic]]. Read [[user-guide-automation-controller-workflow-setup]] for the setup chain each driver needs, and [[tutorials-howto-configureeachmachinefrommes]] when one controller serves several machines. Afterwards, you can create the protocol, driver definition, and controller of an integration, connect an instance to an entity, and see its driver reach `Communicating`.

- Which process runs the workflows, and how does a task reach the equipment?
- In which order do you create the objects of an integration?
- Which tasks does the Setup workflow chain for each driver, and what answers the setup phase?
- How does a changed connection parameter reach a driver that is already `Communicating`?

??? note "Answers"
    - The controller process runs every workflow. A task reaches the equipment only through the driver it is bound to, and each driver runs in a process of its own.
    - The Automation Protocol, the Automation Driver Definition, the Automation Controller, and then the instance, created with Connect.
    - Driver Event on `OnInitialize`, Equipment Configuration, and Driver Command `Connect`, all bound to the same driver. Automatic Setup on the `OnInitialize` trigger answers the setup phase, or an `OnSetup` handler that ends with `SetupSuccess` or `SetupFailure`.
    - Only through a restart of the instance. A `Communicating` driver keeps the parameters it received.

### Step 2: How Values Travel

Complete [[tutorials-connectiot-how-values-travel]]. Afterwards, you can predict when a Data Flow task runs, which values it reads, and what it keeps between runs.

- What makes a Data Flow task run?
- What does a Data Flow task keep from one run to the next?
- Why does a handler for overlapping occurrences belong in Control Flow?
- What is the difference between an output that emits `null` and one that emits `undefined`?

??? note "Answers"
    - A value that reaches Activate. Values on the other inputs are what the task runs on, not what makes it run. Log Message and Switch also run only from Activate.
    - Each input, until a new value replaces it, unless the task clears its inputs after each run.
    - Each Data Flow task is a single instance, so a later occurrence replaces the values of an earlier one, and the log warns `will receive value '<new>' instead of '<old>'`.
    - A `null` is delivered like any other value. An `undefined` changes nothing and activates nothing.

### Step 3: Control Flow in Depth

Complete [[tutorials-connectiot-control-flow-in-depth]]. Afterwards, you can build handlers that branch, loop, and recover from failures, and reuse logic in functions and subworkflows.

- How does a task read the output of another task?
- Where do you write an expression?
- Which operators combine two conditions?
- What surrounds work that may fail, and what does the catch-all receive in Control Flow?
- When does a Data Flow subworkflow run?

??? note "Answers"
    - With `{{ $<name>.<output> }}`, using the stored name of a task placed before it, in the same branch or an enclosing one.
    - On an input row. Only a few settings evaluate their own expression.
    - `and`, `or`, and `not`. The expression engine refuses `&&`, `||`, and `!`.
    - A Try..Catch with a catch branch. The catch-all also receives every Return and Break, as `Execution Return invoked` and `Execution Break invoked`, so filter them.
    - Only when a Workflow task calls it. It does not start with the engine.

### Step 4: One Protocol Tutorial

Complete the tutorial of the protocol your equipment uses: [[tutorials-connectiot-secsgem]], [[tutorials-connectiot-fileraw-csv]], [[tutorials-connectiot-opcua]], [[tutorials-connectiot-mqtt]], [[tutorials-connectiot-rest]], or [[tutorials-connectiot-tcpip]]. Afterwards, you can configure a driver for real equipment, declare its properties, events, and commands, and read, react, and write from a workflow.

- How do you choose the driver for a piece of equipment?
- How does a workflow reach the equipment?
- Whose role does `connectionMode` or `mode` describe?
- Which outputs do you link on equipment tasks?
- Where does equipment work start in the connection lifecycle?

??? note "Answers"
    - From how the equipment offers its data: files on File Raw, a GEM tool on SECS/GEM, an OPC UA server on OPC UA, a broker on MQTT, and HTTP by direction, REST Client to ask and REST Server to be asked.
    - Through the entries of its driver definition, with On Equipment Event, Execute Equipment Command, and the property tasks. The file driver tasks are deprecated in 12.0.
    - The role of the driver, not the role of the equipment.
    - Error on every read, on every command whose failure matters, and on every On Equipment Event that waits for one event with a timeout.
    - In the `OnSetup` handler or in an equipment event. On `OnInitialize`, the driver is not connected yet.

### Step 5: Talking to MES

Complete [[tutorials-connectiot-talking-to-mes]]. Afterwards, you can call MES services and actions, answer requests from MES, and read configuration from MES.

- When do you use a system action, and when a message bus subject?
- How do you name the inputs of Execute Service Call?
- What does a reply task send when the answer is `0` or `false`?
- How many tasks answer one request?

??? note "Answers"
    - A system action addresses one instance. A message bus subject reaches every listener.
    - By the bare property name, as the designer names them. An input renamed to `input$<property>` reaches MES under that name.
    - The answer itself. The default reply is sent only when no answer arrived since the previous activation.
    - One. Answer each request once, within a reply timeout longer than the work.

### Step 6: Timing and State

Complete [[tutorials-connectiot-timing-and-state]]. Afterwards, you can schedule work, wait, set deadlines, and keep values and per-item state between occurrences.

- Which task fits a period, a moment, a pause, and a deadline?
- What type must an interval have when it arrives on a Data Flow link?
- What activates a Synchronize?
- What happens when you retrieve a value whose expiration passed?
- Which stored values survive a restart?

??? note "Answers"
    - On Timer for a period, On Cron Job for a moment, evaluated in UTC, Sleep for a pause, and Timeout for a deadline.
    - A number. On Timer and Sleep do not convert an interval that arrives on a Data Flow link.
    - The tasks that produce its values, never the trigger that starts the work.
    - The first retrieval emits an error, and later retrievals emit the default.
    - Values stored as `Persistent`. Values stored as `Temporary` are lost.

### Step 7: Writing a Code Task

Complete [[tutorials-connectiot-writing-a-code-task]]. Afterwards, you can decide when a Code task is the right tool, write and test it, and handle its failures.

- What do you check before you write code?
- What belongs in a Code task, and what does not?
- Where does the code keep a value between runs?
- How does the code report a failure?

??? note "Answers"
    - Whether a task or a converter already does the step, such as an expression evaluator, JSONata, a merge task, or Calculate Checksum.
    - One small algorithm over the task's inputs and outputs. Subscriptions, equipment access, and state belong to triggers, equipment tasks, and the data store.
    - In the data store, not in a variable of the code.
    - It throws an `Error`, and the workflow links the task's Error output in Data Flow or catches the failure in Control Flow.

### Step 8: Troubleshooting and Anti-Patterns

Read [[user-guide-automation-troubleshooting-symptoms]], [[user-guide-automation-workflow-antipatterns]], and [[operation-guide-connect-iot-runbook]]. Afterwards, you can diagnose a failing integration from its symptoms, avoid the designs that cause failures, and operate running instances.

- Where do you look first when an integration misbehaves?
- How do you tell that a task never ran?
- How do you confirm that a change reached a running instance?
- What does a restart start again, and what does it lose?

??? note "Answers"
    - The instance state on the Connect IoT page, then the first failure in the controller log, and the driver log when the connection itself fails.
    - The line the task writes when it starts is missing from the log.
    - Find the line of the change in the controller log. When it is missing, restart the instance.
    - Every workflow of the controller and every Setup chain start again, and values stored as `Temporary` are lost.

## Next Steps

Start with [[tutorials-connectiot-configuration-basic]]. To extend the same integration step by step, continue with [[tutorials-connectiot-configuration-intermediate]], [[tutorials-connectiot-configuration-advanced]], and [[tutorials-connectiot-configuration-controlflow]], and enable the scenarios of MES with [[tutorials-connectiot-mes-interop-scenarios]].