Configuration

    Global Configuration

    The tapio CloudConnector can be configured through a .xml-file named TapioCloudConnector.xml. The configuration provides two different ways to store the information. It is also possible to mix both ways together.

    If a section, e.g. Modules contains content in the GlobalConfig the tapio CloudConnector will take these information and will ignore the file behind the given file path. If you want to use the information from the file, you need to remove the content from the GlobalConfig file in the specific section like Modules.

    1. Store all information in one xml file. (see example 1)
    2. Split the different sections like ManufacturerConfig and CloudConnectorConfig in different files. (see example 2)

    By default it's located at: C:\ProgramData\tapio\CloudConnector\

    Example 1:

    <?xml version="1.0"?>
    <GlobalConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <!-- Optional: Manufacturer Configuration for on the fly machine registration -->
      <ManufacturerConfig>
        <ManufacturerSubscriptionId>33386422-f77e-493c-8db6-9d48a1a3cbbb</ManufacturerSubscriptionId>
        <DeviceType>Test</DeviceType>
      </ManufacturerConfig>
    
      <ConnectorConfig>
        <ConnectorId>q8AElWQ8Iqc7vbMiy2jnmYbguEH-K...</ConnectorId>
        <ConnectorCert>MIacAQMwgAYJKoZIhvcNAQcBoIAkg...</ConnectorCert>
        <DiscoveryServiceUri>https://disco.tapio.one</DiscoveryServiceUri>
        <DiscoveryServiceCert>MiIDQaDCCAiigAwIBAgI...</DiscoveryServiceCert>
        <AuthAppId>00000000-0000-0000-0000-000000000000</AuthAppId>
        <AuthSecret>secret</AuthSecret>
        <ResourceId>https://tapiousers.onmicrosoft.com/DiscoveryService</ResourceId>
        <Authority>https://login.microsoftonline.com/32896ed7-d559-401b-85cf-167143d61be0</Authority>
        <InstrumentationKey>00000000-0000-0000-0000-000000000000</InstrumentationKey>
        <LogLevel>Verbose</LogLevel>
        <OpcUaServerUrl>opc.tcp://somedomain:4433/CloudConnectorDiagnostic/</OpcUaServerUrl> <!-- optional -->
      </ConnectorConfig>
      <Modules>
        <Module xsi:type="DataModuleConfig">...</Module>
        <Module xsi:type="FileTransferModuleConfig">...</Module>
      </Modules>
    </GlobalConfig>

    Example 2:

    <?xml version="1.0"?>
    <GlobalConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
     <ManufacturerConfig source="C:\ReadOnlyPath\tapio\CloudConnector\config\ManufacturerConfig.xml">
      </ManufacturerConfig>
      <ConnectorConfig source="C:\ProgramData\tapio\CloudConnector\config\ConnectorConfig.xml">
      </ConnectorConfig>
      <Modules>
        <Module xsi:type="DataModuleConfig">...</Module>
        <Module xsi:type="FileTransferModuleConfig">...</Module>
      </Modules>
    </GlobalConfig>

    ModuleConfig.xml example 3:

    <Modules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
      <Module xsi:type="DataModuleConfig">...</Module>
      <Module xsi:type="AzureIotHubConfig">
          <Id>AzureIotHub</Id>
          <ServiceId>AzureIoTHub</ServiceId>
      </Module>
    </Modules>

    In case of using path information for one of the three section in a configuration, you are able to store e.g. the ManufacturerConfig in a section which is read-only.

    GlobalConfig Model

    Element Description
    ManufacturerConfig ManufacturerConfig, required for automatic machine registration
    ConnectorConfig Configuration required for connecting to the tapio platform.
    Modules List of module configurations.

    ManufacturerConfig Model

    This configuration section is required if you want to use automatic machine registration. The following information about a device will be stored in the manufacturer section.

    Element Description
    ManufacturerSubscriptionId The SubscriptionId of the manufacturer
    DeviceType The device type
    DeviceSubType Optional: Device sub type

    ConnectorConfig Model

    The ConnectorConfig will contain the following information. You will get the information via a xml file download by registering a device in My tapio.

    Property Required Description
    ConnectorId Identifier of the CloudConnector instance.
    ConnectorCert CloudConnector certificate (client-certificate).
    DiscoveryServiceUri Discovery service URI.
    DiscoveryServiceCert Discovery service certificate (server-certificate).
    AuthAppId App identifier for discovery service OAuth2 flow.
    AuthSecret App secret for discovery service OAuth2 flow.
    ResourceId Resource id for discovery service OAuth2 flow.
    Authority Authority for discovery service OAuth2 flow.
    InstrumentationKey Instrumentation key for logging into Application Insights
    LogLevel optional Verbosity of the logs. There are six log levels available. Default is Error.
    LogFileCount optional The count of log files to use, at least 1, default 10.
    LogFileSize optional The max size per log file, min 4K (4 KiB) , default 10M (10 MiB), format {number}{unit}, allowed units: K - KiB, M - MiB, G - GiB. See below for more examples.
    OpcUaServerUrl optional OPC UA server address. Default is opc.tcp://localhost/CloudConnectorDiagnostic/. You can set a specific port with this tag.

    Examples for LogFileSize:

    Value Description
    {number}{unit}
    4K 4 Kilobyte = 4096 Byte
    1M 1 Megabyte = 1024 Kilobyte = ‭1048576‬ Bytes
    10M 10 Megabyte = ‭10240‬ Kilobyte
    1G 1 Gigabyte = 1024 Megabyte

    Log level

    Level Logged events
    Verbose Everything
    Debug Information logs and information for developers.
    Information Warning logs and general information.
    Warning Error logs and expected exceptions.
    Error Critical logs and unexpected exceptions.
    Critical Only critical events.

    It is also possible to disable logging on the file system. You need to add the property LoggingSinkLocation to the ConnectorConfig.

    <ConnectorConfig>
        ...
        <InstrumentationKey>00000000-0000-0000-0000-000000000000</InstrumentationKey>
        <LogLevel>Verbose</LogLevel>
        <LoggingSinkLocation>Ai</LoggingSinkLocation>
    </ConnectorConfig>
    Location Description
    AiAndFile Logs are stored in the application insights and file log on the device
    Ai Logs are stored in the application insights

    If no location is set in the configuration, the CloudConnector will use the AiAndFile location.

    Module Configuration

    Each module has a unique configuration model. Have a look at the documentation of the module you want to configure.

    OPC UA Client Configuration

    Some modules like the file transfer or call endpoint module contain a OPC UA client which has to be configured according to the documentation of the module in charge. Configuration patterns for authentication and node identifiers are reused in multiple modules.

    Authentication

    There are three different ways for authentication. Set the xsi:type property of the Authentication XML tag to either AuthenticationUserName, AuthenticationCertificate or AuthenticationNone and configure accordingly.

    Currently used in BackupModule, DataModule and FileTransferModule.

    Authentication with username and password

    Example:

    <Authentication xsi:type="AuthenticationUserName">
      <UserName>thelegend27</UserName>
      <Password>somePassword!</Password>
    </Authentication>

    Model:

    Property Description
    UserName OPC UA username.
    Password OPC UA password for given username.
    Authentication with certificates

    Example:

    <Authentication xsi:type="AuthenticationCertificate">
      <X509CertBase64>
        HDAJBgNVBAYTAlJVMA8GA1UEAx4IAFQAZQBzAHQwggEiMA0GCSqGSIb3DQEBA...
      </X509CertBase64>
      <CertPassword>somePassword!</CertPassword>
    </Authentication>

    Model:

    Property Description
    X509CertBase64 A X509 certificate encoded as Base64 string.
    CertPassword Password to load certificate with private key, set when required.
    No authentication

    Example:

    <Authentication xsi:type="AuthenticationNone">
    </Authentication>

    Node Identifier

    There are many ways to format a NodeId. We support the following notations:

    Currently used in DataModule and FileTransferModule.

    Full notation

    The full notation is just a string with specific formatting.

    Format:

    ns=<namespaceIndex>;s=<identifier>

    Example:

    <NodeId>ns=2;s=MyServer.MyFolder.MyNode</NodeId>

    It is possible to resolve the index namespace on runtime:

    <!-- Note the nsu parameter has to be the first one -->
    <NodeId>nsu=http://tapio.one;i=45</NodeId>
    Identifier and Namespace Index notation

    Model:

    Property Description
    NamespaceIndex OPC UA namespace index of the node.
    Identifier OPC UA identifier string of the node.

    Example:

    <NodeIdIndex>
      <NamespaceIndex>2</NamespaceIndex>
      <Identifier>MyServer.MyFolder.MyNode</Identifier>
    </NodeIdIndex>
    Identifier and Namespace URI

    Model:

    Property Description
    NamespaceUri OPC UA namespace URI of the node.
    Identifier OPC UA identifier string of the node.

    Example:

    <NodeIdNamespace>
      <NamespaceUri>urn:MyCompany:MyServer</NamespaceUri>
      <Identifier>MyFolder.MyNode</Identifier>
    </NodeIdNamespace>

    Distributed Configuration

    The configuration can be split up into separate parts that are located at different locations. A location is given by an uri in the source attribute of the element for which the contents should be load. While loading the configuration, the serializer will resolve referenced uris and insert the contents.

    Example:

    <?xml version="1.0"?>
    <GlobalConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <ConnectorConfig source="file:///c:/programdata/tapio/cloudconnector/config/Modules.xml">
      </ConnectorConfig>
      <Modules>
        <Module xsi:type="DataModuleConfig">...</Module>
        <Module xsi:type="FileTransferModuleConfig">...</Module>
      </Modules>
    </GlobalConfig>
    <ConnectorConfig>
      <ConnectorId>q8AElWQ8Iqc7vbMiy2jnmYbguEH-K...</ConnectorId>
      <ConnectorCert>MIacAQMwgAYJKoZIhvcNAQcBoIAkg...</ConnectorCert>
      ....
    </ConnectorConfig>

    Currently the ConnectorConfig element and the Modules element support the source attribute. If the configuration is split up, each individual file needs to be a valid XML. Required namespaces (e.g. xsi) need to be defined in all files where they are used.

    The source must be a valid uri. Ideally, only absolute uris are used, but relative uris are supported as well if a base uri is provided while loading the configuration. When a source attribute is given for an element that also has children, it is ignored.

    By default only the file scheme is supported.