An standards-based and containerized industrial connectivity edge application translating from many proprietary protocols to OPC UA leveraging the W3C Web of Things (WoT) thing descriptions via the new WoT-Connectivity specification. Data transformation into OPC UA Companion Specs is also supported. Thing Descriptions can be easily edited using the Eclipse Foundation's edi{TD}or, or automatically generated using AI. UA Edge Translator runs on both ARM and X64 architectures, it runs on both Windows and Linux and it runs in both Docker and Kubernetes environments.
UA Edge Translator solves the common "brownfield" use case of connecting disparate industrial assets with many different interfaces and translates their data into an OPC UA information model (ideally to one of the standardized companion specifications from the UA Cloud Library), enabling processing of the assets' data either on the edge or in the cloud leveraging a normalized, IEC standard (OPC UA) data format. This accelerates Industrial IoT projects and saves cost since the data doesn't need to be normalized in the cloud and makes use of the OT expertise often only found on-premises. For defining a mapping from the proprietary data format to OPC UA, the Web of Things (WoT) Thing Description schema (JSON-LD-based) is used. Additionally, the mechanism to provide the schema to the UA Edge Translator is also leveraging OPC UA. Therefore, for the first time, OPC UA is used for both the control and data plane for industrial connectivity, while previous solutions only used OPC UA for the data plane and a proprietary REST interface for the control plane.
UA Edge Translator is available as a pre-built Docker container (supporting both AMD64 and ARM64 CPUs) directly from GitHub and will run on any Docker- or Kubernetes-enabled edge device. See "Packages" in this repo for details.
UA Edge Translator supports provisioning via GDS Server Push functionality as described in part 12 of the OPC UA specification. Until an issuer certificate is provided in the issuer certificate store of UA Edge Translator, it is in provisioning mode and access to the WoT-Connectivity-related OPC UA nodes in its address space is restricted. An issuer certificate can be provided as part of the GDS Server Push mechanism or by manually copying a certificate into the issuer certificate store found in the /app/pki/issuer/certs directory. During provisioning, all client certificates are auto-approved by UA Edge Translator, but afterwards they need to be manually trusted by copying them from the rejected certificate store to the trusted certificate store, unless of course the certificates were already trusted (for example because they were provided by the GDS Server Push mechanism). These stores can also be found in the /app/pki/ folder.
UA Edge Translator can be controlled through the use of just 2 OPC UA methods (and OPC UA file transfer functionality) readily available through the OPC UA server interface built in. The methods are:
- CreateAsset(assetName) - Creates an asset node and an OPC UA File API node below the asset node (which can be used to upload the WoT Thing Description), returning the node ID of the newly created asset node on success.
- DeleteAsset(assetNodeId) - deletes a configured asset.
The following southbound asset interfaces (a.k.a. protocol drivers) are supported:
- Modbus TCP
- Modbus RTU (experimental)
- OPC UA
- HTTP
- Aveva PI (experimental)
- Rockwell CIP (Ethernet/IP)
- Beckhoff ADS (TwinCAT)
- LoRaWAN
- Matter
- OCPP (Open Charge Point Protocol) V1.6J
- OCPP (Open Charge Point Protocol) V2.1 (experimental)
- Siemens S7Comm (experimental)
- Mitsubishi MC Protocol (experimental)
- BACNet (experimental)
- IEC61850 (experimental)
Note: Since BACNet uses UDP messages, BACNet support is limited to running UA Edge Translator natively or with the --net=host argument within a Docker container!
Note: Network discovery for Rockwell PLCs only works when running UA Edge Translator natively or with the --net=host argument within a Docker container!
Note: The LoRaWAN Network Server is available on port 5000 (not secure) and port 5001 (secure), which needs to be mapped to the Docker host for access. If you need a LoRaWAN Gateway, you can use the open-source Basic Station together with a LoRaWAN HAT for Raspberry Pi.
Note: The OCPP Central System is available on port 19520 (not secure) and on port 19521 (secure), which needs to be mapped to the Docker host for access.
Note: Since Matter uses BluetoothLE and mDNS as the underlying network protocol for commissioning, Matter support is limited to running UA Edge Translator natively or with the --network=host argument as well as with the -v /run/dbus:/run/dbus:ro argument within a Docker container! Also, if you are using the BlueZ stack on Linux, make sure that experimental features are enabled since Matter uses some Bluetooth features that are not enabled by default in this stack.
Note: For testing the Matter asset interface, you will also need to create a Thread network using an OpenThread Border Router (OTBR). An open-source OTBR is available here and runs on a Raspberry Pi equipped with a Thread radio USB dongle, the setup instructions are here. If you need a Matter commissioning QR-code scanner/decoder, there is an online one here.
Note: The Modbus RTU interface requires access to a serial port on the host system. When running UA Edge Translator in a Docker container, make sure to map the serial port device into the container using the --device argument, e.g. -v /dev/ttyUSB1:/dev/ttyUSB1 and run the container with the --privileged argument.
Other interfaces can easily be added by implementing the IAsset interface (for runtime interaction with the asset) as well as the IProtocolDriver interface (for asset onboarding).
There is also a tool provided (WoTThingModelGenerator) that can convert from an OPC UA nodeset file (with instance variable nodes defined in it), an AutomationML file, a TwinCAT file, or an Asset Admin Shell file to a WoT Thing Model file.
UA Edge Translator loads protocol drivers as DLLs from the /app/drivers folder at runtime. To build your own protocol driver, create a new .NET10 Class Library project and add a project reference to the UaEdgeTranslator, making sure that only the protocol driver DLL is published:
<ItemGroup>
<ProjectReference Include="..\..\UAServer\UaEdgeTranslator.csproj">
<Private>true</Private>
<ReferenceOutputAssembly>false</ReferenceOutputAssembly>
</ProjectReference>
</ItemGroup>
Then implement the IProtocolDriver and IAsset interface and publish your project into the ..\..\UAServer\drivers\<yourdrivername> folder and restart UA Edge Translator to load your new protocol driver.
# 1) Create a named volume for drivers
docker volume create translator_drivers
# 2) Copy drivers from the driver-pack image into the volume
docker run --rm -v translator_drivers:/out ghcr.io/opcfoundation/ua-edgetranslator-drivers:main /bin/sh -c 'cp -a /drivers/. /out/'
# 3) Run UA Edge Translator with the drivers volume mounted to /app/drivers
docker run -d --name ua-edge-translator -v translator_drivers:/app/drivers -p 4840:4840 ghcr.io/opcfoundation/ua-edgetranslator:main
In addition, the following folders within the Docker container store certificates, secrets and settings and should be mapped and persisted (-v argument in Docker command line) to the Docker host to encrypted folders, e.g. protected folders using BitLocker:
/app/logs(log files)/app/pki(certificates and keys)/app/settings(WoT Thing Descriptions)/app/nodesets(OPC UA nodesets for referenced companion specifications)/app/drivers(protocol driver DLLs, see above)
E.g. -v c:/uaedgetranslator/pki:/app/pki, etc.
Client certificates need to be manually moved from the /pki/rejected/certs folder to the /pki/trusted/certs folder to trust an OPC UA client trying to connect.
OPCUA_USERNAME- OPC UA username to connect to UA Edge Translator.OPCUA_PASSWORD- OPC UA password to connect to UA Edge Translator.
APP_NAME- OPC UA application name to use. Default is UAEdgeTranslator.UACLURL- UA Cloud Library URL (e.g. https://uacloudlibrary.opcfoundation.org or https://cloudlib.cesmii.net).UACLUsername- UA Cloud Library username.UACLPassword- UA Cloud Library password.OPCUA_CLIENT_USERNAME- OPC UA client username to connect to an OPC UA asset.OPCUA_CLIENT_PASSWORD- OPC UA client password to connect to an OPC UA asset.DISABLE_ASSET_CONNECTION_TEST- Set to1to disable the connection test when mapping an asset to OPC UA.IGNORE_PROVISIONING_MODE- Set to1to ignore provisioning mode and allow access to WoT-Connectivity-related OPC UA nodes in the address space.OPC_UA_GDS_ENDPOINT_URL- The endpoint URL of an OPC UA Global Discovery Server on the network, which will then be used during network discovery.DISABLE_TLS- Set to1to turn off TLS for OCPP and LoRaWAN connections.
The following guide will help you get started with adding protocol drivers to UA Edge Translator and onboard your first asset using the httpclient WoT driver.
This should give you a fast way to get to a state that you can modify with other drivers and WoT files.
-
Publish the HttpClient driver. This will copy the httpclient.dll and its debug file in the "drivers" folder under "UAServer"
-
Copy the WoT File "SimpleHTTPClient.td.jsonld" in the "settings" folder under "UAServer"
-
Load the UAEdgeTranslator project and run it.
-
Connect to the opc server of the UAEdgeTranslator using your favorite OPC UA Client (i.e. UAExpert). The default credentials are "myUsername" and "myPassword".
You can change these credentials in the launchSettings.json file under "Properties" of the UAEdgeTranslator project:
"OPCUA_USERNAME": "myUsername",
"OPCUA_PASSWORD": "myPassword",
To test your setup before provisioning the UAEdgeTranslator with the proper certificates you can also set this in the launchSettings.json:
"IGNORE_PROVISIONING_MODE": "1"
Once connected, you will see the OPC UA address space with a node called "WoTAssetConnectionManagement"
- Open this node and you will find another node called "SimpleHTTPClient.td"
In this branch you will find a variable "IPAddress" that was defined in the "SimpleHTTPClient.td.jsonld". The variable is read every 60 seconds, although it probably does not change since it just calls a service on the internet determining your external IP address.
For more details on the Web of Things file format and description see https://www.w3.org/TR/wot-thing-description-2.0/
UA Edge Translator uses a zero trust security model and implements the following security features:
- UA Edge Translator runs within a Docker container in a restricted network environment and with limited permissions to the host system.
- UA Edge Translator comes with extensive logging to the console and to disk, but does not log any sensitive information such as passwords or private keys.
- OPC UA SHA256 sign & encrypt server security policy and username/passowrd user authentication for secure communication between clients and the UA Edge Translator OPC UA server as well as between the UA Edge Translator OPC UA client protocol driver and OPC UA assets.
- OPC UA GDS Server Push provisioning mechanism for secure provisioning of the UA Edge Translator with issuer certificates and client certificates.
- Secure Websockets using TLS for secure communication with LoRaWAN Network Server and OCPP Central System.
- Matter Fabric persistency of certificates and keys in the /app/pki folder for secure communication with Matter assets.
- Protocol drivers are loaded as DLLs at runtime and drivers considered insecure can be easily turned off by removing the respective DLL from the "drivers" folder.
Note: If the /app/pki folder is mapped to a folder on the Docker host, make sure to protect this folder since it contains private keys and certificates. For example, you can use BitLocker to encrypt the folder on the Docker host.
- Spoofing: Mitigated by OPC UA username/password authentication and client certificate authentication.
- Tampering: Mitigated by OPC UA message signing and encryption.
- Repudiation: Mitigated by OPC UA message signing and encryption, as well as append-only logging.
- Information Disclosure: Mitigated by OPC UA message encryption.
- Denial of Service: Mitigated by OPC UA secure channels and session management with maximums set for sessions, subscriptions, monitored items and message size limits.
- Elevation of Privilege: Mitigated by OPC UA user authentication as well as a provisioning mode preventing read/write access to variables before GDS Push is carried out.
- Spoofing: Mitigated by TLS client certificate authentication for the LoRaWAN Network and communication for OCPP Central System.
- Tampering: Mitigated by TLS encryption for the LoRaWAN Network and OCPP Central System.
- Repudiation: Mitigated by TLS encryption for the LoRaWAN Network and OCPP Central System, as well as append-only logging.
- Information Disclosure: Mitigated by TLS encryption for the LoRaWAN Network and OCPP Central System.
- Denial of Service: Mitigated by secure Websocket communication and retry/backoff mechanisms in the code.
- Elevation of Privilege: Mitigated by TLS client certificate authentication for the LoRaWAN Network and secure Websocket communication for OCPP.