Asset Gateway - Getting Started
Industrial Asset Hub connects to existing shop floor assets via a gateway which is hosted on Industrial Edge. These assets are referred to as indirectly managed devices. The same agents can be directly integrated with devices to connect them directly to the IAH backend services (IAH native devices).
The Asset Gateway offers a gRPC (google protocol-buffer) interface for Asset links. Asset links abstract the device specific protocols and interfaces to the normalized gRPC interface provided by the Asset Gateway. This can be done distributed over box boundaries (indirectly managed) or fully integrate with the native managed device.
The agents are provided as docker containers.
IAH users can execute the following functionalities on IAH gateway:
Asset Gateway Docker Compose stack
Introduction
The Docker Compose Asset Gateway package provides infrastructure containers to extend the cloud based Industrial Asset Management services to the field.
The package contains all the necessary containers in tar.gz format and the docker-compose file. It is available for the processor architectures amd64 and arm64.
Prerequisites
| Component | Version |
|---|---|
| Docker | >=20.10 |
| Docker Compose | >=1.25 |
| GoLang | >=1.18 |
Other container runtimes like Colima or Podman can be used as well. This document only regards Docker. Please adopt the docker-compose.yaml according to the host network modelling of your container runtime.
Overview
The Asset Gateway integrates with the backend services via HTTP REST APIs. The configuration is provided by the cfg-data/gateway-config.json file. The Asset Gateway can connect to one or more Asset links via gRPC.
The grpc-server-registry is provided by the Asset Gateway. All Asset links needs to register themself and will be looked up by the agents.
The SDK asset-link-sdk provides a default implementation of an Asset link.
Figure: Asset Gateway overview
How To Run on Linux Based Systems
Follow this step-by-step guide to set up your Asset Gateway and connect your first Asset link.
Asset Gateway
-
For requesting an IAH tenant or a product trial please contact the IAH Service Desk.
-
Download and extract the Docker Compose package for your target architecture on your hosting target e.g. by using:
$ tar -xvzf ./asset-gateway-<version>-<arch>.tar.gz
[...]
Note Please contact the IAH team if you are not able to download the package.
- Replace the gateway-config.json created while adding a new gateway in IAH inside the cfg-data/ folder of the extracted archive with your tenant specific configuration.
- To run your Asset Gateway execute:
$ ./run-local.bash
[>] Load container images...
Loaded image: cdm/discovery-agent:x.y.z
Loaded image: cdm/remote-access-agent:x.y.z
Loaded image: cdm/auth-proxy-agent:x.y.z
Loaded image: cdm/grpc-server-registry:x.y.z
[>] Starting docker-compose stack...
[+] Running 4/0-
✔ Container asset-gateway-grpc-server-registry-1 Recreated 0.0s
✔ Container asset-gateway-auth-proxy-agent-1 Recreated 0.0s
✔ Container asset-gateway-remote-access-agent-1 Recreated 0.0s
✔ Container asset-gateway-discovery-agent-1 Recreated 0.0s
Attaching to asset-gateway-auth-proxy-agent-1, asset-gateway-discovery-agent-1, asset-gateway-remote-access-agent-1, asset-gateway-grpc-server-registry-1
Adding an Asset link
- Clone the asset-link-sdk.
- Follow the steps provided by the asset-link-sdk documentation to start your Asset link and connect to the Asset Gateway.
- Schedule a discovery job with help of the IAH user interface to verify your local setup.
- Please refer to the asset-link-sdk documentation on how to customize an Asset link.
Note Please contact the IAH service desk team if you are not able to clone asset-link-sdk.
Using the provided Asset links
The compose stack does come with the following Asset links provided:
- Dummy (Hard coded values)
- SNMP (Simple Network Management Protocol)
Asset Links for SAT (SIMATIC Automation Tool) and PNAS (PROFINET Asset Service) can be provided on request. In that case, please contact the Industrial Asset Hub product management via Service Desk.
These Asset links can be started by providing a comma separated list of the AL to start:
./run-local.bash dummy,snmp
Configure the Asset links
All configurations have to be stored within the cfg-data/ folder. For information how to configure the Asset link please refer to the documentation of the specific Asset link.
Configure the provided Asset link SNMP
Please refer to the SNMP documentation.
How To Run on Virtualized Environments on Windows Systems
Up to now there is no native Windows support nor for the Asset Gateway or the Asset Links. For development purposes and as well for production deployments Windows targets can be utilized leveraging virtualization technologies. Frequent setups use Windows or 3rd party virtualization environments and host Linux operating systems on it. Docker for Windows is as well a good alternative to run the Asset Gateway on a Windows machine.
Another possibility ist to utilize Windows natively built in Subsystem for Linux.
This package comes with a helper scripts to setup the environment and Asset Gateway.
To get started use the powershell script run-local.ps1.
Note: This is an exemplary helper script tested on Windows 11 and comes with no liability
Note: Script execution policies from the hosting machine probably needs to be adapted
Set-ExecutionPolicy Bypass -Scope CurrentUser; .\run-local.ps1
It provides a menu like this:
"================ Main Menu ================"
1: Setup Windows Sub System for Linux (WSL)
2: Install WSL guest and Docker
3: Setup Asset Gateway
4: Register WSL to startup with the Windows machine
5: Update WSL
6: Stop Asset Gateway
7: Remove WSL guest from system
8: Open WSL '$guestOsDistro' shell
10: Exit
Troubleshooting
The behavior of the Asset Gateway can be observed by examining the container logs.
Scheduled Job Does not Start
The output of the auth-proxy-agent container contains the error string "client authentication failed". Please check your gateway-config.json file.
asset-gateway-auth-proxy-agent-1 | [...] oauth2: \"invalid_client\" \"client authentication failed\"
The log output shows an error strike "no such host". Please check your internet connection and gateway-config.json file.
asset-gateway-auth-proxy-agent-1 | [...] dial tcp: lookup samauth.us-east-1.sws.siemens.com on 127.0.0.11:53: no such host"
Scheduled Job Fails
The log output contains an error string "Query call failed for my-al Error: no service registered". Please check the name of your Asset link.
asset-gateway-discovery-agent-1 | [...] "message":"Query call failed for my-al Error: no service registered"}
Documentation reference
Download Specifications
A complete package of API specifications can be obtained here: API_Specs