IoT Runtime Components Configuration#

The configuration file is a JSON structured file and it will be used by all components (Manager, Monitor, Controller, Driver). It allows the use of some tokens to be inserted depending on the context, those tokens are explained in the following table:

Name	Type	Usage	Description
applicationName	`Application`	`${applicationName}`	The name of the current application
pid	`Application`	`${pid}`	The process id of the current application
componentId	`Application`	`${componentId}`	Name of the component running (`AutomationManager`, `AutomationMonitor`, `AutomationController`, `DriverCsv`, etc)
entityName	`Application`	`${entityName}`	The name of the context entity for the current application
tmp	`OperatingSystem`	`${tmp}`	User temporary directory
pwd	`OperatingSystem`	`${pwd}`	Running script location
cwd	`OperatingSystem`	`${cwd}`	Working directory (where the command is being executed)

Table: Connect IoT Configuration Tokens

Base Structure#

Name	Type	Default Value	Description
id	String		Identifier of the process
monitorHost	String	`"localhost"`	Address of the local monitor listener address
monitorPort	Integer	`0`	Port of local monitor listener. 0 for automatic port assignment
cache	String		Local path where the packages will be downloaded and executed
monitorApplication	String	`""${pwd}\monitor.js"`	Complete path of the Monitor process
repository	`Repository`		Repository regarding packages handling
system	`System`		System access settings
storage	`Storage`		Section to configure persistency location
logging	`Logging`		Logging mechanism settings
monitor	`monitor`		Monitor process specific settings
controller	`controller`		Controller(s) process(es) specific settings
driver	`driver`		Driver(s) process(es) specific settings

Table: Connect IoT Base Structure

Repository Structure#

The repository represents the way the Monitor process handles the location where the packages are located (remote) and stored (local).

Name	Type	Possible Values	Default Value	Description
type	String	`Npm` `Directory` `System`		Type of repository - `Npm` - uses an NPM server - `Directory` - uses a local directory with the packages and a json-based database descriptor - `System` - downloads the packages from MES (retrieves settings from the `system` structure detailed below)
settings	Object			Repository settings (depending on the type)

Table: Connect IoT Repository Structure

Type `Npm` Settings#

Name	Type	Default Value	Description
url	String		URL where the NPM server is located (including port)
token	String		Optional Bearer token used for authentication

Table: Npm specific settings

Type `Directory` Settings#

Name	Type	Default Value	Description
path	String		Directory where the packages are located. Must be accessible by process and currently, UNCs are not supported

Table: Directory specific settings

Directory Examples#

"repository": {
    "type": "Npm",
    "settings": {
        "url": "YourNpmAddress",
        "token": "YourNpmToken"
    }
}

"repository": {
    "type": "Directory",
    "settings": {
        "path": "[UserSelectedDirectory]\\MyDirectoryRepository"
    }
}

Storage Structure#

Name	Type	Possible Values	Default Value	Description
type	String	`Directory`	`Directory`	Type of persistency location
settings	Object			Storage type settings
settings\path	String			Base path where the persistency data will be stored. `OperatingSystem` tokens are supported
settings\retentionTime	`Integer` `string`		`"30d"`	Number of seconds to store the data. `0` means forever. Supports string with a trailing token indicating the time unit: `s` - seconds `m` - minutes `h` - hours `d` - days `w` - weeks (7 days)
settings\logMaxLength	`Integer`		`4096`	Maximum number of characters displayed in the console when storing a value in storage. If the value exceeds this limit, it will be truncated for readability.

Table: Connect IoT Storage Structure

Storage Structure Examples#

"storage": {
    "type": "Directory",
    "settings": {
        "path": "[UserSelectedDirectory]/Persistency",
        "retentionTime": 3600,
        "logMaxLength": 4096
    }
}

"storage": {
    "type": "Directory",
    "settings": {
        "path": "[UserSelectedDirectory]/Persistency",
        "retentionTime": "10d",
        "logMaxLength": 0
    }
}

System Structure#

Name	Type	Default Value	Description
tenantName	String		System Tenant name to use by the components
address	String	`"localhost"`
port	Integer
timeout	Integer
useSsl	Boolean	`false`
authentication	`Authentication`		Object

Table: Connect IoT System Structure

`Authentication` Structure#

Name	Type	Possible Values	Default Value	Description
type	String	`SecurityPortal` `ClientCredentials`		Authentication type to use
settings	Object			Authentication settings (depending on the type)

Table: Authentication structure

Authentication type `SecurityPortal` settings#

Name	Type	Description
clientId	String	Id of the client accessing to (MES)
accessToken	String	Security Portal generated long term Access Token. To be set on non-interactive scenarios with Security Portal
openIdConfiguration	String	URL where the OpenId endpoint can be accessed. Example: `http://YourEnvironment/tenant/YourTenant/.well-known/openid-configuration`
applicationBaseUrl	String	Optional: In the case of apps, the Monitor will send requests to this address

Table: Authentication type SecurityPortal structure

Authentication type `ClientCredentials` settings#

Name	Type	Description
clientId	String	Id of the client accessing to (MES)
openIdConfiguration	String	URL where the OpenId endpoint can be accessed. Example: `http://YourEnvironment/tenant/YourTenant/.well-known/openid-configuration`
applicationBaseUrl	String	Optional: In the case of apps, the Monitor will send requests to this address
password	String	Optional: Password to login - Should not be used

Table: Authentication type SecurityPortal structure

Examples#

"system": {
    "tenantName": "YourTenant",
    "address": "YourEnvironment",
    "port": 8093,
    "timeout": 60000,
    "useSsl": false,
    "authentication": {
        "type": "SecurityPortal",
        "settings": {
            "clientId": "MES",
            "accessToken": "user created access token",
            "openIdConfiguration": "http://YourEnvironment/tenant/YourTenant/.well-known/openid-configuration"
        }
    }
}

"system": {
    "tenantName": "YourTenant",
    "address": "YourEnvironment",
    "port": 8093,
    "timeout": 60000,
    "useSsl": false,
    "authentication": {
        "type": "ClientCredentials",
        "settings": {
            "clientId": "MES",
            "openIdConfiguration": "http://YourEnvironment/tenant/YourTenant/.well-known/openid-configuration"
        }
    }
}

Logging Structure#

The logging configuration allows several different loggers to be configured at same time, meaning that for each type of logger, different options can be configured.

Name	Type	Possible Values	Description
id	String		Identifier of the logger, if none is configured, only one of the same type is allowed
type	String	`Console` `File` `Http` `OTLP`	Type of the transport
options	Object		Transport options,different for each type of transport, see each transport information below
applications	Array of String	`AutomationMonitor` `AutomationController` `AutomationManager` `DriverSecsGem` `DriverOpcUA` `DriverMqtt` `DriverBle` `DriverCsvFile` `DriverRawFile` `DriverKeyboardWedge` `DriverOib` `DriverOpcDA` `DriverSerial` `DriverTcpIp`	A wildcard can configure all or filter by name, example: ’`Driver*`’

Table: Connect IoT Logging Structure

Common Transport Options#

These options apply to all types:

Name	Type	Possible Values	Default Value	Description
level	String	`debug` `info` `warn` `error`	`"info"`	Minimum level of messages that this transport should log. If `info`level is defined, all entries of level `info`, `warn` and `error` will be logged and `debug` entries will be ignored.
label	String		`"${applicationName}"`	Label to append in the beginning of the log entry (if used in the format)
format	String		`"${log.timestamp}${log.level}:${log.message}"`	Format of the line of the log
timestamp	Boolean		`true`	Flag indicating if we should prepend output with timestamps. If function is specified, its return value will be used instead of timestamps
timestampFormat	String		`"YYYY-MM-DD HH:mm:ss.SSS"`	Format of the timestamp in the log entry. Please refer to https://github.com/taylorhakes/fecha#formatting-tokens ⧉ for full format information
maxLength	Integer		`0`	Max length of the message entry to log (<=0 to ignore). If entry is larger than the value, will log (70% of the maxLength) of the start of the message and the last (30% of maxLength) characters. This setting is useful to keep huge communication logs in a more controllable state.
specificLevelLock	Boolean		`false`	Only log the specified verbosity level. With this setting set to `true` the levels greater than the `level` will be ignored.
isEnabled	Boolean		`true`	Is the Transport enabled

Table: Connect IoT Common Transport Options

Console Transport Options#

This transport log all the messages to the application console.

Name	Type	Default Value	Description
colorize	Boolean	`true`	Flag indicating if we should colorize output.
colorizeMessage	Boolean	`true`	Is the colorization to apply to the full message or only the verbosity.

Table: Connect IoT Console Transport Options

Example#

{
    "type": "Console",
    "options": {
        "level": "debug",
        "prettyPrint": true,
        "colorizeMessage": true
    },
    "applications": [ "*" ]
}

File Transport Options#

As the name states, this transport log all the messages to the file system.

Name	Type	Default Value	Description
frequency	String		A string representing the frequency of rotation. This is useful if you want to have timed rotations, as opposed to rotations that happen at specific moments in time. Valid values are `'#m'` or `'#h'` (e.g., '5m' or '3h'). Leaving this null relies on datePattern for the rotation times.
datePattern	String	`"YYYY-MM-DD"`	A string representing the moment.js date format to be used for rotating. The meta characters used in this string will dictate the frequency of the file rotation. For example, if your datePattern is simply `'HH'` you will end up with 24 log files that are picked up and appended to every day.
filename	String	`"LogFile_${date}.log"`	Filename to be used to log to. This filename can include the ${date} placeholder which will include the formatted datePattern at that point in the filename
dirname	String	`"."`	The directory name to save log files to
maxSize	String	`"10m"`	Maximum size of the file after which it will rotate. This can be a number of bytes, or units of kb, mb, and gb. If using the units, add `k`, `m`, or `g` as the suffix. The units need to directly follow the number.
maxFiles	String	`"30d"`	Maximum number of logs to keep. If not set, no logs will be removed. This can be a number of files or number of days. If using days, add `d` as the suffix
option	Object	`{ flags: 'a', mode: 0o777 }`	An object resembling https://nodejs.org/api/fs.html#fs_fs_createwritestream_path_options ⧉ indicating additional options that should be passed to the file stream
auditFile	String	`${dirname}/.<hash>-audit.json`	A string representing the name of the audit file.

Table: Connect IoT File Transport Options

File Transport Options Example#

{
    "id": "MyFileLogger01",
    "type": "File",
    "options": {
        "filename": "${applicationName}_${date}.log",
        "dirname": "${tmp}/YourManager01/Logs/${applicationName}",
        "level": "debug",
        "timestampFormat": "HH:mm:ss.SSSSS",
        "maxSize": "10m",
        "maxFiles": 5,
        "maxLength": 5000,
        "specificLevelLock": false
    },
    "applications": [ "AutomationMonitor", "AutomationManager" ]
}

HTTP Transport Options#

The HTTP transport is a generic way to log, query, and stream logs from an arbitrary HTTP endpoint, preferably winstond. It takes options that are passed to the node.js http or https request:

Name	Type	Default Value	Description
host	String	`"localhost"`	Remote host of the HTTP logging endpoint.
port	Integer	`80` or `443`	Remote port of the HTTP logging endpoint.
path	String	`"/"`	Remote URI of the HTTP logging endpoint.
auth	Object	`None`	An object representing the username and password forHTTP Basic Auth.
ssl	Boolean	`false`	Value indicating if we should us HTTPS

Table: Connect IoT HTTP Transport Options

HTTP Transport Options Example#

{
    "id": "MyHttp01",
    "type": "Http",
    "options": {
        "host": "localhost",
        "port": "80",
        "path": "logger",
    },
    "applications": [ "AutomationController" ]
}

OTLP Transport Options#

The OTLP transport is a transport to broadcast logs using the open telemetry standard. It requires the endpoint to be configured:

Name	Type	Default Value	Description
isEnabled	Boolean		Flag to enable the transport.
level	String		Logging Level.
isInternal	Boolean	False	Flag only used if the automation manager is running in the same stack as the MES application.
endpoint	String		An external endpoint that receives and processes telemetry signals sent according to the OTLP (open telemetry protocol) format (i.e https://mytelemetrystack.com/telemetry/http).

Table: Connect IoT OTLP Transport Options

OTLP Transport Options Example#

 {
    "type": "OTLP",
    "options": {
        "isEnabled": true,
        "level": "debug"
    },
    "applications": [ "*" ] 
},

Monitor Structure#

The optional monitor section is specifically for the monitor process and are not used by the other applications.

Name	Type	Default Value	Description
notifyBeforeKill	Boolean	`true`	Flag indicating if a notification to the processes before killing them (allowing them to properly cleanup any resources, disconnect from devices, etc), or simply kill them.
killNotificationTimeout	Integer	`10000`	Number of milliseconds to wait for the "about to be killed" process reply that it has finished the cleanup an is ready to be killed.
retryAttempts	Integer	`30`	When calls protected by retry mechanism fail, number of executions before failing
sleepBetweenAttempts	integer	`1000`	When calls protected by retry mechanism fail, time to wait between retries
processCommunication	`SslConfig`		Configuration to allow inter-process communications to be using SSL (monitor <-> controller(s) and monitor <-> driver(s))

Table: Connect IoT Monitor Structure

Monitor Structure Example#

"monitor": {
    "notifyBeforeKill": "true",
    "killNotificationTimeout": 30000,
    "retryAttempts": 45,
    "sleepBetweenAttempts": 1000,
    "processCommunication": {
        "useSsl": true,
        "privateKey": "YourCertificatesRepository\\key.pem",
        "certificate": "YourCertificatesRepository\\cert.pem",
        "certificateAuthority": "YourCertificatesRepository\\ca-cert.pem"
    }
}

Controller Structure#

The optional controller section is specifically for the controller(s) process(es) and are not used by the other applications.

Name	Type	Default Value	Description
retryAttempts	Integer	`30`	When calls protected by retry mechanism fail, number of executions before failing
sleepBetweenAttempts	integer	`1000`	When calls protected by retry mechanism fail, time to wait between retries
profilerSessionsLocation	string		Location where the profiler sessions will be stored

Table: Connect IoT Controller Structure

Controller Structure Example#

"controller": {
    "retryAttempts": 45,
    "sleepBetweenAttempts": 1000,
    "profilerSessionsLocation": "YourControllerRepository\\tempController"
}

Driver Structure#

The optional driver section is specifically for the driver(s) process(es) and are not used by the other applications.

Name	Type	Default Value	Description
retryAttempts	Integer	`30`	When calls protected by retry mechanism fail, number of executions before failing
sleepBetweenAttempts	integer	`1000`	When calls protected by retry mechanism fail, time to wait between retries
processCommunication	`SslConfig`		Configuration to allow inter-process communications to be using SSL (driver<-> controller)

Table: Connect IoT Driver Structure

Driver Structure Example#

"driver": {
    "retryAttempts": 45,
    "sleepBetweenAttempts": 1000,
    "processCommunication": {
        "useSsl": true,
        "privateKey": "YourCertificatesRepository\\key.pem",
        "certificate": "YourCertificatesRepository\\cert.pem",
        "certificateAuthority": "YourCertificatesRepository\\ca-cert.pem"
    }
}

SslConfig structure#

When communication between processes require SSL use these settings.

Name	Type	Default Value	Description
useSsl	Boolean	`false`	Use SSL communication on component communication
rejectUnauthorized	Boolean	`false`	If not false a server automatically reject clients with invalid certificates. Allows bypass of error: "Connection with monitor error: unable to verify the first certificate" on a completely unsecured way when set to false! also, if we want to ignore environment variable "NODE_TLS_REJECT_UNAUTHORIZED=" we may set rejectUnauthorized: true On self-signed certificates, we can pass the correct CA (certificate authority) certificate with certificateAuthority option
privateKey	string		PEM encoded SSL private key Value or file full path containing the key value
certificate	string		PEM encoded SSL certificate Value or file full path containing the certificate value
certificateAuthority	string		PEM encoded SSL custom certificate authority (CA) Value or file full path containing the certificate value

Table: Connect IoT SslConfig Structure

SslConfig Structure Example#

{
    "useSsl": true,
    "privateKey": "YourCertificatesRepository\\key.pem",
    "certificate": "YourCertificatesRepository\\cert.pem",
    "certificateAuthority": "YourCertificatesRepository\\ca-cert.pem"
}

SystemCertificate structure#