Connect IoT Administration#
To use the Connect IoT module in the MES system, you must have an approved license. For more information, see Automation.
Activate Entities to be used by IoT#
At least one entity type must be enabled to be used by Connect IoT workflows. To enable them, in the Administration/Entity Types/<EntityName> page, you will need to activate the Connect IoT Enabled checkbox.
Enable the <entity>.Connect feature on the Security page to display the Connect button for the selected entity, as shown in the image below.
Package Repository#
The Package Repository contains the runtime components used by Connect IoT.
To configure the type and location, use the Configuration page located in Administration > Configuration, search for "IoT" and fill out the values for path /Cmf/System/Configuration/ConnectIoT according to the following table:
| Name | Type | Possible Values | Default Value | Description |
|---|---|---|---|---|
| RepositoryType | String | NPMDirectory | NPM | Type of Package Repository to use: - NPM: NPM server based repository- Directory: Directory-based repository. Must use .rebuildDatabase.ps1 script supplied in the ISO to generate the database. |
| RepositoryLocation | String | Depending on the RepositoryType, fill with: - NPM: Url of the NPM server. Example: /opt/connectiot- Directory: Path where the packages were deployed. Must be accessible by MES host and IoT runtime components. Example: E:\Repository | ||
| RepositoryToken | String | If RepositoryType is set to NPM, enter the Bearer token for authentication, if needed. Example: VGhpcyBpcyBhIHRlc3Q= |
Table: Connect IoT System Configurations
Managing Packages in the Repository#
The Automation Repository page supports listing and uploading packages natively only when the Repository Type is set to Directory.
When the Repository Type is set to NPM, you cannot manage packages directly through the MES UI. Instead, you must manage packages externally using a standard NPM client CLI (for example, npm publish) or an NPM server native user interface (such as Nexus, Verdaccio, or Artifactory) to list, upload, and maintain them.
NPM Registry Compatibility Requirements#
To ensure full compatibility with MES, the underlying NPM registry or repository manager must support specific standard NPM API behaviors. The host automatically handles discovery and version retrieval by interacting with the registry through the following mechanisms:
| Functionality | API Endpoint(s) | Requirement & Behavior |
|---|---|---|
| Package Discovery & Search | GET /v1/search | When the registry search API returns unscoped names for packages that are actually scoped, the host automatically reconciles them. This ensures scoped packages are discovered and mapped correctly within MES without requiring manual naming overrides. |
| Version Retrieval & Fallback Resolution | GET /{package}/{version} GET /{package} | If a direct fetch via GET /{package}/{version} returns an HTTP 404 Not Found, the host executes a fallback strategy. It queries the full package metadata via GET /{package} and programmatically resolves the required version from the returned versions map. |
| Tarball Download Redirects | Follows redirect targets | The host supports registries that offload storage by redirecting package requests to external storage endpoints via HTTP 301, 302, 307, or 308. The host follows the Location header to the final endpoint, supporting up to five sequential redirects. |
Table: NPM Registry Compatibility Requirements
Enable Customizations#
Custom Automation Business Scenarios#
By default, only the automation business scenarios supplied by Critical Manufacturing are visible when using the AutomationBusinessScenario entity. To allow custom/additional business scenarios packages to be used, use the Configuration page located in Administration > Configuration, search for "IoT" and fill out the values for path /Cmf/System/Configuration/ConnectIoT according to the following table:
| Name | Type | Possible Values | Default Value | Description |
|---|---|---|---|---|
| BusinessScenarioPackageNameFilter | String | @criticalmanufacturing/connect-iot-business-scenarios-* | Filter to use to identify packages that can be used for AutomationBusinessScenario entities. Update the value if custom automation business scenarios packages are intended to be used. Use ; as separator and * as wildcard. Example: @criticalmanufacturing/connect-iot-business-scenarios-*;@customer/connect-iot-business-scenarios-* |
Table: Automation Business Scenarios Packages filter configuration
Custom Automation Task Library#
By default, only the task library packages supplied by Critical Manufacturing are visible when using the Automation Task Library (ATL) entity. To allow custom/additional ATL packages to be used, use the Configuration page located in Administration > Configuration, search for "IoT" and fill out the values for path /Cmf/System/Configuration/ConnectIoT according to the following table:
| Name | Type | Possible Values | Default Value | Description |
|---|---|---|---|---|
| TasksLibraryPackageNameFilter | String | @criticalmanufacturing/connect-iot-controller-engine-* | Filter to use to identify packages that can be used for Automation Task Libraries entities. Update the value if custom ATL pacakages are intended to be used. Use ; as separator and * as wildcard. Example: @criticalmanufacturing/connect-iot-controller-engine-*;@customer/connect-iot-controller-engine-* |
Table: ATL Packages filter configuration
Custom Protocol Drivers#
By default, only the protocol drivers supplied by Critical Manufacturing are visible when using the Automation Protocol entity. To allow custom/additional drivers to be used, use the Configuration page located in Administration/Configuration, search for "IoT" and fill out the values for path /Cmf/System/Configuration/ConnectIoT according to the following table:
| Name | Type | Possible Values | Default Value | Description |
|---|---|---|---|---|
| ProtocolPackageNameFilter | String | @criticalmanufacturing/connect-iot-driver-* | Filter to use to identify packages that can be used for Automation Protocol entities. Update the value if custom drivers are intended to be used. Use ; as separator and * as wildcard. Example: @criticalmanufacturing/connect-iot-driver-*;@customer/connect-iot-driver-* |
Table: Protocol Drivers filter configuration
Additional Configurations#
In the section /Cmf/System/Configuration/ConnectIoT of the Configuration, the additional values can be defined:
| Name | Type | Possible Values | Default Value | Description |
|---|---|---|---|---|
| ConfigurationTemplate | Json in string format | <default configuration> | The configuration template to use within the Automation Manager entity. Can be changed in the Configuration Wizard. There is only one possible template and will be stored in this configuration entry.Note: Just change the value here if there is a problem with the json. Otherwise, always use the wizard in Automation Managerentity. |
Table: Connect IoT additional configurations
Interlocking Timeouts#
When a Resource has an interlocking property enabled, the MES sends a request to the Automation Controller that owns the Resource and waits for the reply before completing the operation. See the Connect IoT - MES Interoperability Scenarios Tutorial for an explanation of how each interlocking scenario works. Each of these calls has its own timeout, defined in the section /Cmf/System/Configuration/Resource of the Configuration.
Raise the value for an operation that legitimately takes longer than the default, such as uploading a large recipe body, and lower it when the MES should give up earlier and fail the operation.
| Name | Type | Default Value | Description |
|---|---|---|---|
| GetRecipeListTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the list of recipes available at the equipment. |
| RecipeBodyDownloadTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for a recipe body downloaded from the equipment. |
| RecipeBodyUploadTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the equipment to accept an uploaded recipe body. |
| SetupInterlockingTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the reply to a Resource begin setup request. |
| MaterialDispatchInterlockingTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the reply to a Material dispatch request. |
| MaterialTrackInInterlockingTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the reply to a Material track in request. |
| MaterialTrackOutInterlockingTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the reply to a Material track out request. |
| ContainerDockInterlockingTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the reply to a Container dock request. |
| ContainerUndockInterlockingTimeOut | Int32 | 60000 | Time, in milliseconds, that the MES waits for the reply to a Container undock request. |
Table: Connect IoT interlocking timeouts
When an entry is missing or has no value, the MES uses 60000 milliseconds.
Warning
The timeout on the MES side and the Reply Timeout of the corresponding trigger task in the Automation Workflow are independent. Keep the task Reply Timeout below the MES timeout, so the workflow reports the failure before the MES gives up on the call.
Access Tokens#
Each Automation Manager signs in to MES with a long-term access token of a user, and its controllers use the same token. Where the token comes from depends on how you deploy the manager.
| Deployment | Token | Expiration | Stored in |
|---|---|---|---|
| Package created by Download (Windows service or console) | Created by Download for the user selected in the wizard, named <user account>_<automation manager id> | 1 year. When you run Download as an administrator, 10 years, and at least until 2037-12-28. | system.authentication.settings.accessToken of config.json and config.full.json |
Kubernetes, with the Deployment Mode AutomaticDeploy | Issued by the Automation Manager Controller for the integration user, named AMC-<timestamp>-<automation manager id> | Requested 30 years ahead | A Kubernetes secret, passed to the container as APPLICATION_PAT. See Deploy Automation Manager. |
| Docker container that you start | An access token that you create for the integration user | The date you choose | The APPLICATION_PAT variable. See Docker Container Support. |
Table: Access token of an Automation Manager per deployment
Each Download creates a new token and does not revoke the tokens that earlier downloads created. Revoke the tokens that no manager uses.
When the token expires or is revoked, every instance on that manager loses MES. The monitor log shows Error connecting to MES: … and Waiting 30s until next attempt at start, and Looks like the token has expired and must be renewed! about once a minute while it runs.
To replace the token of a manager created by Download:
- Create a new token for the user: run Download again, or create an access token on the Users page. See Users.
- Set the new token in
system.authentication.settings.accessTokenof theconfig.jsonof the manager. - Restart the manager. The processes read the token only when they start. The manager is the parent process of the monitor and of every controller and driver process, so all its instances restart. Plan a maintenance window.
- Revoke the old token in the Access Tokens sub-section of the user on the Users page. See Users.
For a manager deployed by the Automation Manager Controller, Undeploy revokes the token, and the next Deploy issues a new one. See Undeploy Automation Manager.
A manager with the ClientCredentials authentication type has no access token: the processes read the client secret from the SECURITY_PORTAL_CLIENT_SECRET environment variable. See IoT Runtime Components Configuration.
Data on the Manager Host#
An Automation Manager keeps stored values, packages, and logs in folders on its host. The default configuration, in the configuration entry /Cmf/System/Configuration/ConnectIoT/ConfigurationTemplate, puts them under <temp>/ConnectIoT, where <temp> is the temporary folder of the account that runs the manager. A clean-up of that folder, or a container without a volume for it, deletes them.
| Data | Configuration key | Default folder | Contents | Back up |
|---|---|---|---|---|
| Persistency | storage.settings.path | <temp>/ConnectIoT/Persistency | Values that workflows store as Persistent, kept for retentionTime (30d by default) | Yes |
| Package cache | cache | <temp>/ConnectIoT/Cache | One folder per package version that the monitor downloaded | No. The monitor downloads a missing package again from the repository. |
| Logs | dirname of each File transport in logging | <temp>/ConnectIoT/Logs and <temp>/ConnectIoT/Jobs | Logs of the instances, the manager, the monitor, and the jobs. A new file starts every 10 MB, and files are kept 30 days. | Only when your retention rules require it |
| Configuration | None | The manager installation folder | config.json with the access token, config.full.json, and config.downloaded.json | Optional. A new Download creates it again, with a new token. |
Table: Data that an Automation Manager keeps on its host
- Move the persistency out of the temporary folder to a folder that is backed up. Change
storage.settings.pathwith Configure Automation Manager. For the keys, see IoT Runtime Components Configuration. - Stored values stay on the host where the instance ran, in the store of its instance ID. The ASA Change Automation Manager action replaces the instance with a new one, with a new ID, on the target manager, so the new instance does not read the values of the old one, even when both managers share the persistency folder. See Actions.
- For High Availability, put the persistency in a shared folder that every manager node reaches. See Deployment.
Network Connections#
Open the following connections in every firewall between the manager host, MES, the package repository, and the equipment. The configuration keys are described in IoT Runtime Components Configuration.
| From | To | Address | Notes |
|---|---|---|---|
| Monitor and controller processes | MES | system.address and system.port, over HTTPS when system.useSsl is true | Every call to MES. |
| Monitor and controller processes | Security Portal | The URL in system.authentication.settings.openIdConfiguration, and the token endpoint that it returns | Sign-in with the access token or the client secret. |
| Monitor and controller processes | Message bus | The address that MES publishes in /.well-known/criticalmanufacturing-configuration, or the one set in MESSAGEBUS_GATEWAY_ADDRESS, MESSAGEBUS_GATEWAY_PORT, and MESSAGEBUS_GATEWAY_WS_PROTOCOL when all three are set | WebSocket connection. |
| Monitor | Package repository | repository.settings.url for Npm, repository.settings.path for Directory | With the System repository type, the monitor downloads the packages through MES and needs no connection to the repository. |
| Controller and driver processes | Monitor | monitorHost and monitorPort (localhost and 0 by default) | With 0, the operating system assigns a free port when the manager starts. |
| Controller processes | Driver processes | hostName (localhost by default) and a port that each driver process opens when it starts | The port changes every time the driver process starts. It crosses the network only when the controller and the driver run on different managers. |
| Driver processes | Equipment | The address and port in the communication parameters of the protocol | See the page of each protocol in Communication Drivers. |
| Equipment or other systems | REST Server driver | address and port of the driver | The REST Server driver listens for requests. See Connect IoT - Rest Server. |
Table: Network connections of an Automation Manager
When the logging section has an OTLP transport, the processes also send telemetry to its endpoint.