

Datasource configuration

Datasources¶

The SINUMERIK Edge enables the development of applications that require or provide a connection to a datasource. For example, an application can require the axis position of a SINUMERIK NCU.

A datasource is defined by its type. The type identifies the addressing schema and payload format of the datasource. If an application provides a datasource of type "SQL" and another application provides a datasource of type "SQL", those applications can be connected. On an EdgeBox, datasources are connected to applications by a unique datasourceId. The datasourceId is specified by the operator (user) during configuration.

A "datasourceConfig" object consists of "providedDatasource" and "requiredDatasource" objects.

Inside requiredDatasource objects, we define the requirements of the application which wants to access data of a datasource.
Inside providedDatasource objects, we define available data which is provided for other applications by the defined services.

In order to access data of other available datasources, "datasourceConfig" section of metaconfig needs to be configured properly.

Schema


wildcards	array of object	optional, may be empty
- key	string	required
- description	string	optional
- rule	string	optional
requiredDatasource	array of object	optional, may be empty
- datasourceId	string	required, has to fit to a provider
- type	string	required
- meta	object	optional
- services	object	required, shall not be empty
providedDatasource	array of object	optional, may be empty
- datasourceId	string	required, can be used by a consumer
- type	string	required
- meta	object	optional
- services	object	required, shall not be empty

datasource: Logical object, abstracting an available source of data. Can be used as representation for an external connected device or application internal data storage.
wildcards: The wildcards section does not have any functional meaning. It can be understood as an documentation section, helping the operator to configure application specific data addresses. Must not be changed. Can be removed after configuration.
- provided by: metaconfig
- used by: operator to configure datasource services
providedDatasource: Configuration object of a data providing application. Used to configure datasource specific settings and define provided data access interfaces.
requiredDatasource: Configuration object of data consuming applications. Used to configure access to a datasource providing application.
datasourceId: Instance ID of a datasource object. Can be changed by the operator. Must be unique for all providedDatasource objects in one Edgebox instance. Must be used to connect data consuming applications to data.
- provided by: metaconfig
- configured by: operator
- used by: configuration process
type: Defines the type of a datasource. This type also defines the datasource specific data contract - meaning the supported data payload schemas. Must not be changed.
- provided by: metaconfig
- used by: operator and configuration process
meta: Object for datasource specific configuration. Can be changed by the operator, specific to the applications documentation.
- provided by: metaconfig
- configured by: operator
- used by: application at runtime

Example configurations¶

Sample applications inside AppSDK delivery contain sample meta_config files. Below link describes where to find sample applications mentioned:

AppSDK package content.

Consumer Application¶

When building the application with the indapp build tool from APP-SDK, a default metaconfig file will be generated. This file includes an example configuration for defining a requirement to access data of a SINUMERIK. Copy the “requiredDatasource” config section out of the “example” directly into the datasourceConfig object of your application to get a preconfigured configuration.

example meta configuration, generated by indapp build:

"datasourceConfig": {
        "requiredDatasource": [{ 
            "datasourceId": "SINUMERIK_NCU1", 
            "type" : "SINUMERIK", 
            "services": { 
                 . . .

To declare the requirement for data access, the application must also define the required service. There are several communication services for datasources available:

parameter-service/v1: for single synchronous request to parameters
information-service/v1: for single synchronous request to status information and reports
subscription-service/v1: for asynchronous data subscription and event notifications

Hint: The datasourceConfig section of datasource providing applications gives you information about the available data. Those applications must also provide information about addressing and using of the provided data.

Provider Application¶

Data providing applications can provide new types of datasources.

example: application provides access to data of a SINUMERIK

"datasourceConfig": { 
    "providedDatasource": [{ 
        "datasourceId": "SINUMERIK_NCU1", 
        "type" : "SINUMERIK", 
        "services": { . . .

Although the datasourceId is a mutable identifier for the datasource, the datasource's type defines addressing schema for datapoints and the payload format. Please review all available datasource types before creating a new one. If you need to create a new datasource type, please provide a detailed documentation for:

addressing schema
value format

example: This example metaconfiguration will create a new datasource type "SQL_database". The application's developers shall define the interface for addressing datapoints and using the returned message format.

"datasourceConfig": 
{ 
    "providedDatasource":
    [{ 
        "type" : "SQL_database"
    }]
}

Datasource specific configuration¶

You can use the datasourceConfig "meta" element to include additional datasource-specific information or configuration. This will be copied to the appconfig file at configuration time.

example: This application uses the meta object to configure the IP-Address of a connected device.

{
  "datasourceConfig": {
    "providedDatasource": [
      {
        "datasourceId": "DATASOURCE_01",
        "type": "SAMPLE_DATA",
        "meta": {"IP-Address":"192.0.0.1"}
      }
    ]
  }
}

Wildcards¶

At development time, the specific configuration of a connected machine is not known. Because of that it is not always possible to predefine the required data completely in the metaconfig file. Usually you do not know the settings of the machine with which your application will communicate. The configuration must be modified at configuration time when an instance of the application is installed to a specific environment. To support the operator to configure the application instance, you may specify wildcards in your metaconfiguration file.

Attention: Wildcards are ment to support the operator to configure the application. There should be understood as part of the applications documentation.

For example: Define a wildcard "$Channel" with a description text: "The channel number of the required data.".

This wildcard can now be used by the underlaying services of this datasource. metaconfig includes a subscription to a parameter which uses this wildcard: "/machine/someparam[$Channel]". When configuring the application instance, the operator must replace the $Channel wildcard with a number.

{
  "datasourceConfig": {
    "wildcards": [{ 
        "key": "$Channel", 
        "description" : "The channel number of the required data.", 
    }]
  }
}

example wildcards

wildcard	description	value rule
$parameter	Any string that describes a parameter. Please refer to the documentation for a set of available parameters.	text
$id	The array index of the parameter.	numeric
{[$id]}	Byte offset of the parameter.	numeric
[$SQL]	SQL Syntax to address one value in the database.	text

Diagnose¶

The actual configuration status can be reviewed at the local dashboard. To do so, refer to the AdapterFramework Systemapp UI. Detailed documentation of this UI can be found here.

On configuration errors, you can find diagnostic logmessages in the exenia logfiles.

Any questions left?

Ask the community

Except where otherwise noted, content on this site is licensed under the The Siemens Inner Source License - 1.1.