Skip to content

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. Adopt the docker-compose.yaml according to the host network modeling 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 need to register themselves and will be looked up by the agents.

The SDK asset-link-sdk provides a default implementation of an Asset link.

uml diagram

Figure: Asset Gateway overview

Discovery Workflow with Device Info API

During a discovery job the Discovery Agent first identifies devices and then handles each discovered device according to the asset schema the Asset Link provides. The Asset Link may return an asset that conforms either to the Inventory V2 asset schema or to the legacy Inventory V1 asset schema. The schema is determined by inspecting the functional_object_type_url property of the asset returned by DiscoverDevices():

  • Inventory V2 asset schema - functional_object_type_url is present. The Discovery Agent enriches the device with its detailed properties (device information) using the Connectivity-Suite DeviceInfoApi. This keeps device identification (DiscoverDevices) separate from device attributes (GetSupportedProperties / GetPropertyValues), and enables native datatype support (including booleans) without overloading the DeviceIdentifier message.
  • Inventory V1 asset schema - functional_object_type_url is not present. The Discovery Agent does not call the Device Info API. Instead, it posts the asset directly to Inventory using POST /v2/assets with the tryMigrate flag, so Inventory migrates the Inventory V1 payload to the Inventory V2 asset schema.

The workflow is as follows:

  1. The Discovery Agent calls DiscoverDevices() and receives the discovered devices including their connection parameters and device identifiers.
  2. For each discovered device, the Discovery Agent inspects the functional_object_type_url property to determine the asset schema (Inventory V2 asset schema if present, Inventory V1 asset schema if absent).
  3. For assets following the Inventory V2 asset schema:
  4. The Discovery Agent calls GetSupportedProperties(connection_parameters) to learn which properties the Asset Link can provide.
  5. The Discovery Agent retrieves the property values via GetPropertyValues(connection_parameters, keys). Keys are batched per device to reduce RPC overhead.
  6. The Discovery Agent aggregates the device identifiers and the device information (no transformation, only aggregation) and posts each complete asset to Inventory.
  7. For assets following the Inventory V1 asset schema, the Discovery Agent posts the asset to Inventory with POST /v2/assets?tryMigrate=true, letting Inventory migrate the Inventory V1 payload to the Inventory V2 asset schema.

uml diagram

Figure: Discovery workflow using the Device Info API

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

  1. Get your own IAH tenant by ordering the associated product in the Siemens Xcelerator Marketplace.
  2. Clone the Asset Gateway repository.
  3. Follow the steps provided by the Asset Gateway repository documentation to configure and onboard the Asset Gateway.
  1. Clone the asset-link-sdk.
  2. Follow the steps provided by the asset-link-sdk documentation to start your Asset link and connect to the Asset Gateway.
  3. Schedule a discovery job with help of the IAH user interface to verify your local setup.
  4. Refer to the asset-link-sdk documentation on how to customize an Asset link.

Note

Contact the IAH service desk team if you are not able to clone asset-link-sdk.

The compose stack comes with the following Asset links:

  • Default IP Scanner
  • Native OS Asset link
  • 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, contact the Industrial Asset Hub product management via Service Desk.

Start these Asset links by providing a comma-separated list of the AL to start:

./run-local.bash snmp,SAT

Store all configurations within the cfg-data/ folder. For information on how to configure the Asset link, refer to the documentation of the specific Asset link.

Refer to the SNMP documentation.

How To Run on Virtualized Environments on Windows Systems

There is no native Windows support for either the Asset Gateway or the Asset Links. For development and production deployments, use Windows targets with virtualization technologies. Common setups use Windows or third-party virtualization environments to host Linux operating systems. Docker for Windows is also a good alternative to run the Asset Gateway on a Windows machine.

Another possibility is to use the Windows natively built-in Subsystem for Linux.

This package comes with helper scripts to set up 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. Script execution policies from the hosting machine may need 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

Observe the behavior of the Asset Gateway 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". Check your gateway-config.json file.

asset-gateway-auth-proxy-agent-1      | [...] oauth2: \"invalid_client\" \"client authentication failed\"

The log output shows an error string "no such host". 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". 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

Device Builder Documentation

IAH Administrator

Http(s) Proxy

The asset gateway supports HTTP(S) proxy configuration for transporting requests. To use a proxy, set the httpProxy, httpsProxy and noProxy fields in the gateway configuration file.

Example for HTTPS proxy:

{
    "gatewayId": "<gateway_id>",
    "xfUrl": "https://gateway.<region>.sws.siemens.com/api/<app_name>-<app_tenant_name>/<app_version>",
    "registrationToken": "<jwt>",
    "httpsProxy": "https://proxy.example.com:8080"
}

Download Specifications

Download the complete package of API specifications here: API_Specs

Any questions left?

Ask the community