Basic Configuration

The basic configuration of HumanOS® Runtime is set in appsettings.json. The configuration is for console host and windows service likewise.

The configuration file comprises the plugin directories, node space and logging settings.

The appsettings.json file is loaded when Runtime is started. There are the following options for placing this file:

Priority	Folder	Notes	Variable Name
1	any directory	is referenced using the launch parameter -AppSettingsDir=$(PathToTheDir)	$(AppSettingsDir)
2	working directory	is also named CurrentPath	$(CurrentPath)
3	installation directory	is also named MainPath	$(MainPath)

INFO

If the variable $(PathToTheDir) contains any spaces, please add double quotes to the variable: -AppSettingsDir="$(PathToTheDir)".

CAUTION

Changes in this file may cause program crashes or malfunctions. Do not change the settings unless you have professional support.

General App Configuration

The general application config is placed in section "AppConfig". Following attributes are used by the runtime:

Attribute	Description	Data Type
CommonAppPath	Path, where the runtime can create files and directories for log files and dump files. The folder must be writable to the user that runs HumanOS®	System.String
CertificatePath	File based certificate store	System.String
LicensePath	Path of the program and device licenses	System.String

Example:

{
  "AppConfig": {
    "CommonAppPath": "$(MainPath)Data\\",
    "CertificatePath": "$(MainPath)Certificates\\",
    "LicensePath": "$(AppConfig:CommonAppPath)Licenses\\"
  }
}

A variable can contain other setting variables from the appsettings.json. Referenced variables must be used in notation $(<var_name>). An exception is the $(MainPath) which is set by the application. The main path points to the path where the server library is located.

Additionally, environment variables can be used with the notation of %<env_variable>%.

Example:

"%PROGRAMDATA%\CyberTech\"

For LINUX

Note, that under Linux folder name are case sensitive and path is constructed with /. Also, environment variables are not supported.

Overview HumanOS Main Configuration

The main configuration section is called "HumanOS".

Figure 3: Configuration Model of HumanOS Runtime

Attribute	Description	Data Type
ServiceId	Unique Id of the HumanOS® Micro-Service. Important for inter connectivity with shared node space.	System.Guid
SingleInstance	True = Prevents the service from having multiple running instances. A valid ServiceId must be specified for this setting to take effect.	System.Boolean
ServiceName	Name of the service. Important if monitoring is used.	System.String
ServiceEnabled	Flag, if the service is enabled for monitoring.	System.Boolean
ProgramDataPath	Path to a folder writeable for users. Typically refers to $(AppConfig:CommonAppPath)	System.String
ConfigPath	Path containing the HumanOS® Runtime configuration files, such as scripts and data models.	System.String
PluginPath	Path to the plugin binaries. Typically refers to $(MainPath)	System.String

{
  "HumanOS": {
    "ServiceId": "{150023F1-2619-450A-A3EA-DF47BE294799}",
    "SingleInstance": true,
    "ServiceName": "CNC.FANUC.Service",
    "ServiceEnabled": true,
    "ProgramDataPath": "$(AppConfig:CommonAppPath)",
    "ConfigPath": "$(MainPath)Config\\",
    "PluginPath": "$(MainPath)"
  }
}

Node Space and Repository Configuration

HumanOS® Runtime provides different possibilities for node and data persistence and historization:

• In-memory node space: no persistence (data are kept in RAM)
• Persisting to SQLite database
• Persisting to MySQL or MariaDB
• Persisting to PostgreSQL

CAUTION

The repository configuration must correlate to the local node space configuration. Use PersistantMemoryNodeSpace if you want to keep data persistent.

In-Memory Configuration

In-Memory node space is useful to keep the disk storage at low level. All data are kept only in RAM and after the reboot the complete node space is rebuilt.

Use this feature, if:

• No history is needed.
• Only short history is used to reduce the network traffic.
• Problems with persistence of the node space (serialization problems)

{
  "HumanOS": {
    "LocalNodeSpace": {
      "Type": "HumanOS.Kernel.DataModel.Space.TInMemoryNodeSpace, HumanOS.Kernel"
    },
    "Repository": {
      "Type": "",
      "Path": "DataRepository\\",
      "Connection": "",
      "Prefix": "$(HumanOS:ServiceName)"
    }
  }
}

Persisting to SQLite Database

Often, IoT Gateways require persistent data, but have also the requirement to run on isolated areas. In such settings, the file-based SQLite database is a good approach to store data locally on the edge device.

{
  "HumanOS": {
    "LocalNodeSpace": {
      "Type": "HumanOS.Kernel.DataModel.Space.TPersistantMemoryNodeSpace, HumanOS.Kernel"
    },
    "Repository": {
      "Type": "HumanOS.PeMiL.SQLiteDataBase.TNodeRepository, HumanOS.PeMiL.SQLiteDataBase",
      "Path": "DataRepository\\",
      "Connection": "",
      "Prefix": "$(HumanOS:ServiceName)"
    }
  }
}

Persisting to Shared Database

To share the data with other HumanOS® Micro-Services, use a shared database like MySQL, MariaDB or PostgreSQL.

Use the "Connection" attribute to specify the database connection. The connection attribute is a standard SQL connection:

• server: database host system
• port: for MySQL use port 3306
• database: use the database name created above, e. g. humanos
• uid: user identification, e. g. humanos.admin
• password: password in clear text
• SslMode: ssl mode must be "none" for older MySQL databases or MariaDB

IMPORTANT

Older MySQL databases fail connecting, because the plugin uses by default the SSL mode. Use the SslMode=false option to avoid the failure.

{
  "HumanOS": {
    "LocalNodeSpace": {
      "Type": "HumanOS.Kernel.DataModel.Space.TPersistantMemoryNodeSpace, HumanOS.Kernel"
    },
    "Repository": {
      "Type": "HumanOS.PeMiL.MySQLDataBase.TRepositoryManager, HumanOS.PeMiL.MySQLDataBase",
      "Path": "DataRepository\\",
      "Connection": "server=localhost;SslMode=none;port=3306;database=mydb;uid=user;password=pw",
      "Prefix": "HOS.WebPortal"
    }
  }
}

Shared Node Space Configuration

The shared node space configuration allows to intercommunicate with other HumanOS® Micro-Services. The communication is managed by a message broker (MQTT or RabbitMQ).

Figure 4: Shared NodeSpace allows to intercommunicate within different Micro-Services

MQTT

The MQTT connection can be configured with different properties. The following properties can be set:

Parameter	Description	Data Type
Type	Class type of shared node space hub	System.String
Address	IP Address or host name of the message broker	System.String
ServerPort	[OPT] Port of the server. Default ports must not be specified (1883 without TLS & 8883 with TLS)	System.Int32
ClientId	[OPT] Mqtt client id -> default is Id of the Publisher	System.String
Username	[OPT] Username	System.String
Password	[OPT] Password of the user.	System.String
CleanSession	[OPT] MQTT Clean Session Flag	System.Boolean
TransportLayerSecurity	[OPT] Security settings for encrypted connection. Possible values are: “None”, “Default”, “Ssl2”, “Ssl3”, “Tls”, “Tls11”, “Tls12”	System.String
IgnoreServerCertificateErrors	[OPT] Flag to ignore certificate errors.; Ignores chain errors and name mismatches of server certificate. Default value is false.	System.Boolean
ClientCaCertificateFile	[OPT] Path to client chain certificate for certificate authentication. Requires a “.crt” file. (Is only used for authentication, not for encrypted connection)	System.String
ClientCertificateFile	[OPT] Path to client certificate for certificate authentication. Requires a “.pfx” file (Is only used for authentication, not for encrypted connection)	System.String
ClientCertificatePassword	[OPT] Password for the client certificate	System.String
NetworkTimeout	[OPT] Timeout in milliseconds [ms] of the network call. This avoids hang-ups if RabbitMQ platform is not reachable.	System.Double

Example of simple MQTT:

{
  "HumanOS": {
    "SharedNodeSpace": {
      "Type": "HumanOS.PeMiL.MQTTMessageBus.TSharedNodeSpaceHub, HumanOS.PeMiL.MQTTMessageBus",
      "Address": "localhost"
    }
  }
}

Example of complex MQTT:

{
  "HumanOS": {
    "SharedNodeSpace": {
      "Type": "HumanOS.PeMiL.MQTTMessageBus.TSharedNodeSpaceHub, HumanOS.PeMiL.MQTTMessageBus",
      "Address": "10.196.24.12",
      "ServerPort": 8883,
      "Username": "HumanOS",
      "Password": "MyPassword",
      "TransportLayerSecurity": "Tls12",
      "ClientCaCertificateFile": "$(AppConfig:CertificatePath)ca.crt",
      "ClientCertificateFile": "$(AppConfig:CertificatePath)client.pfx",
      "ClientCertificatePassword": "MyCertPassword"
    }
  }
}

RabbitMQ

Example RabbitMQ:

{
  "HumanOS": {
    "SharedNodeSpace": {
      "Type": "HumanOS.PeMiL.RmQMessageBus.TSharedNodeSpaceHub, HumanOS.PeMiL.RmQMessageBus",
      "Address": "Server=localhost:5672;uid=myuser;pwd=mypassword;vhost=test;"
    }
  }
}

Plugin Configuration

Currently, there exist five different plugin types. Each one has its own manager setting.

• ServicePluginManager: Managing all service plugins (PeSeL)
• DriverPluginManager: Managing the connectors and drivers (UHAL)
• DeviceDetectorPluginManager: Manages plugins to detect devices (UHAL)
• DataBasePluginManager: Manages the plugins for persistence storage (PeMiL)
• DataObjectPluginManager: Manages all external data objects and entity classes (PeMiL)
• ProcessorPluginManager: Manages external data processors and correlation logic (PeMiL)

Following attributes can be used to configure the plugin manager:

Attribute	Description	Data Type
BinPath	Binary path. If not specified, it takes the $(MainPath)as default.	System.String
ConfigPath	Configuration path. Default is $(HumanOS:ConfigPath)	System.String
UserDataPath	Data path. Default is $(HumanOS.ProgramDataPath)	System.String
SearchPattern	Search pattern to select all plugin DLLs. Default is *.*	System.String

The standard configuration for HumanOS® Runtime is:

{
  "HumanOS": {
    "Plugins": {
      "ServicePluginManager": {
        "SearchPattern": "HumanOS.PeSeL.*.dll"
      },
      "DriverPluginManager": {
        "SearchPattern": "HumanOS.UHAL.*.dll"
      },
      "DeviceDetectorPluginManager": {
        "SearchPattern": "HumanOS.UHAL.*.dll"
      },
      "DataBasePluginManager": {
        "SearchPattern": "HumanOS.PeMiL.*.dll"
      },
      "DataObjectPluginManager": {
        "SearchPattern": "HumanOS.PeMiL.*.dll"
      },
      "ProcessorPluginManager": {
        "SearchPattern": "HumanOS.PeMiL.*.dll"
      }
    }
  }
}

Logger Configuration

HumanOS® Runtime uses Serilog to generate log-files. The logger configuration can be placed directly in the appsettings.json file.

Currently following sinks are supported:

• Serilog.Sinks.Console
• Serilog.Sinks.File

Use the manual from Serilog to change the configuration:

• See https://github.com/serilog/serilog-settings-configuration

Example of a standard logger configuration:

{
  "Serilog": {
    "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System": "Fatal",
        "System.Net.Http.HttpClient": "Information"
      }
    },
    "WriteTo": [
      {
        "Name": "Console",
        "Args": {
          "theme": "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console",
          "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{Level:u3}] {LoggerName}: {Message:lj}{NewLine}{Exception}"
        }
      },
      {
        "Name": "Debug"
      },
      {
        "Name": "File",
        "Args": {
          "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {MachineName}/{Application}/{LoggerName} [{ThreadId}] {SourceContext} {Message:lj} {NewLine}{Exception}",
          "path": "$(AppConfig:CommonAppPath)Logs\\HumanOS.IoT.Gateway-.log",
          "fileSizeLimitBytes": null,
          "rollingInterval": "Day",
          "retainedFileCountLimit": "7",
          "rollOnFileSizeLimit": "false",
          "shared": "true",
          "flushToDiskInterval": "00:00:01"
        }
      }
    ],
    "Enrich": [ "WithMachineName", "WithEnvironmentUserName", "WithThreadId" ],
    "Properties": {
      "Application": "HumanOS"
    }
  }
...
}

License Manager Configuration

The section LicenseManager defines how licenses are used when running a HumanOS Runtime.

Attribute	Description	Data Type
Source	Following source types can be used: LocalFile: default setting. Licenses are stored locally in the path-folder. Http: Source is a http endpoint.	System.String
Path	Path of the licenses (local or http url).	System.String
PersistLicenses	Only for Http source: license files are persisted locally.	System.Boolean
IgnoreCertificateErrors	Flag to ignore certificate errors when using HTTPS endpoints with self signed certificates	System.Boolean

Example

Example shows a LocalFile source for licenses.

  "LicenseManager": {
    "Source": "LocalFile",
    "Path": "$(AppSettingsDir)Licenses\\"
  }

Example

Example shows a HTTP source for licenses. Once licenses are received over http endpoint, they are stored locally (PersistLicenses is true).

  "LicenseManager": {
    "Source": "Http",
    "Path": "https://localhost:48081",
    "PersistLicenses" : true
  }