Configuring Application¶
Every edge application should provide a metaconfig file during publish to Insights Hub. In this section of the document, you will find essential information to configure your application.
Sample Metaconfig¶
{
"system_service" : false,
"machineConfig": {
"subscriptions": {
"DestinationApp_message_data": {
"source": "DestinationApp_message_source",
"quality": "btss",
"payload": [
{
"sinumerikUid": "DestinationApp_message",
"period": 2
}
]
},
"upload2cloud": {
"source": "appoutput",
"quality": "hf",
"payload": [
{
"sinumerikUid": "ENC1_POS|1",
"period": 2
},
{
"sinumerikUid": "ENC1_POS|2",
"period": 2
},
{
"sinumerikUid": "ENC1_POS|3",
"period": 2
}
],
"isCloudMessage": true
}
}
},
"databusConfig": {
"credentials": {
"username": "",
"password": ""
},
"permissions": [
{
"source": "DestinationApp_message_source",
"quality": "quality_all",
"permission": "write"
},
{
"source": "communicationAdapter",
"quality": "quality_all",
"permission": "read"
},
{
"source": "appoutput_message_source",
"quality": "quality_all",
"permission": "read"
},
{
"source": "appoutput",
"quality": "quality_all",
"permission": "write"
}
]
},
"datasourceConfig": {
"requiredDatasource" : [
{
"datasourceId" : "SINUMERIK_NCU1",
"type" : "SINUMERIK",
"services" : {
"parameter-service/v1" : {
"access" : [
{
"accessType" : "w",
"datapoints" : [
{
"address" : "sft2.ncu1.v1"
}
]
}
],
"sessionId" : "sft2"
},
"subscription-service/v1":{
"subscriptions": [{
"messageId": "sinumerik_hf_data",
"messageName":"sinumerik_hf_data",
"quality": "hf",
"datapoints": [
{ "address": "ENC1_POS|1"},
{ "address": "ENC1_POS|2"},
{ "address": "ENC1_POS|3"},
{ "address": "ENC2_POS|1"},
{ "address": "ENC2_POS|2"},
{ "address": "ENC2_POS|3"}
]
}]
}
}
}
]
},
"cloudUploadConfig":
{
"name": "appOutputCloudUploadConfig",
"description": "a description",
"dataPoints": [
{
"name": "ENC1_POS_1",
"description": "ENC1_POS_1",
"unit": "%",
"dataType": "DOUBLE",
"dataPointData": {
"sinumerikUid": "ENC1_POS|1"
}
},
{
"name": "ENC1_POS_2",
"description": "ENC1_POS_2",
"unit": "%",
"dataType": "DOUBLE",
"dataPointData": {
"sinumerikUid": "ENC1_POS|2"
}
},
{
"name": "ENC1_POS_3",
"description": "ENC1_POS_3",
"unit": "%",
"dataType": "DOUBLE",
"dataPointData": {
"sinumerikUid": "ENC1_POS|3"
}
}
]
},
"containersConfig": {
},
"lifecycleConfig": {
},
"loggingConfig": {
"appender": "JOURNAL_APPENDER",
"severity": "INFO"
},
"specificConfig": {
"specificArray": [
"item0",
"item1",
"item2"
],
"specificDecimal": 10,
"specificString": "sample value"
}
}
Note
Objects that are labeled as mandatory, required only when their parent objects are provided.
system_service¶
Path Application Name >> system_service
Type Boolean,Mandatory
Usage
This flag is used by system applications. Since it has no significance for the application developer, it should be set as false.
Example
"system_service": false,
machineConfig¶
Path Application Name >> machineConfig
Type Object
Usage If you use the datasource configuration to subscribe to databus messages of a datasource providing application - like the SINUMERIK adapter, the machine Config section will be configured automatically. If your application does not have further needs then receiving data messages out of datasourceConfig section, you can skip the configuration of the machineConfig.
This object is required to define databus subscriptions. The subscriptions will be discussed in the following section.
Sample
"machineConfig": {
"subscriptions": {
"DestinationApp_message_data": {
"source": "DestinationApp_message_source",
"quality": "btss",
"payload": [
{
"sinumerikUid": "DestinationApp_message",
"period": 2
}
]
}
}
}
subscriptions¶
Path Application Name >> machineConfig >> subscriptions
Type Object, Mandatory
Usage
To read data from databus, subscription element should be defined like in the example below.
Example
"subscriptions": {
"sinumerik_hf_data": {
"source": "communicationAdapter",
"quality": "hf",
"payload": [
{
"sinumerikUid": "hf_data",
"period": 2
}
]
},
}
Now let's move on to the next section and look into the detail of subscription elements.
MessageID¶
Path Application Name >> machineConfig >> subscriptions >>
Type: object
Usage:
The "MessageID" is the custom name of an object in the "subscriptions" object. In the example below, it has been set as "DestinationApp_message_data". "MessageID" is also used in the application program when creating a "Producer" or "Consumer" object.
Example
"DestinationApp_message_data": {
"source": "DestinationApp_message_source",
"quality": "btss",
"payload": [
{
"sinumerikUid": "DestinationApp_message",
"period": 2
}
]
}
Attention:
The "MessageID" must be unique in the application config. If a combination of machineConfig and datasourceConfig is used, then messageNames in the subscriptionService must be handled as additional MessageID's.
source¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> source
Type string, Mandatory
Usage
The application developer should give a correct source name in order to read data from the source. If the application developer wants to send HF data, the receiving application should use the same source name in its "appconfig.json" file.
Example
"source": "communicationAdapter",
quality¶
Path Application Name >> machineConfig >> subscriptions >> message_ID> quality
Type string, Mandatory
Usage:
Quality has two different options. One of them is hf and the other one is high_performance.
Example
"quality": "hf",
payload¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> payload
Type array
Usage Payload is an array which contains data point addresses ("sinumerikUid") and periods related to these data points. From the side of the application developer, period is not important. But the data point address is a very important concept.
For each subscription we can create multiple data points and in the application program we can send or receive data by using these data points that we set.
Example
json
"payload": [
{
"sinumerikUid": "DestinationApp_message",
"period": 2
}
]
sinumerikUid¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> Payload >> sinumerikUid
Type string, Mandatory
Example
"sinumerikUid": "hf_data",
Usage
"TimeseriesUploader" uses "sinumerikUid" to decide if incoming payload is meaningful or not, depending on "isCloudMessage" flag.
period¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> Payload >> period
Type integer, Mandatory
Example
json
"period": 2
Usage
isCloudMessage¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> isCloudMessage
Type Boolean, Optional
Example
"isCloudMessage":true
Usage
If data will be sent to Insights Hub, the application developer should set this flag as "true".
databusConfig¶
Path Application Name >> databusConfig
Type Object
Usage
Includes the required parameters that enable AppSDK to use Databus.
Example
"databusConfig": {
"connectionstring": "rnd:databus.databus.indapp-net.industrialedge.io:8883",
"credentials": {
"username": "",
"password": ""
},
"permissions": [
{
"source": "communicationAdapter",
"quality": "quality_all",
"permission": "read"
},
{
"source": "appoutput",
"quality": "quality_all",
"permission": "write"
}
]
}
connectionstring¶
Path Application Name >> databusConfig >> connectionstring
Type String, Optional
Usage
It should be set as below to be able to connect your application to databus on SINUMERIK Edge. If it is not defined, it will be set as "rnd:databus.databus.indapp-net.industrialedge.io:8883" by default during configuration time on the box.
Note
Port 8883 is used in below connectionString which provides TLS encryption in databus communication. For backward compatibility, port 1883 can also be used.
"connectionstring": "rnd:databus.databus.indapp-net.industrialedge.io:8883"
credentials¶
Path Application Name >> databusConfig >> credentials
Type object, Mandatory
Usage This section used while the application is authenticating to databus.
But app developer should not edit this section since authentication information automatically generated when the application deployed to SINUMERIK Edge.
Example
"credentials": {
"username": "",
"password": ""
},
permissions¶
Path Application Name >> databusConfig >> permissions
Type object, Mandatory
Remark The permissions section will be configured automatically if you use the datasourceConfig for databus configuration.
Usage
For each subscription created in machineConfig section, the permissions should be defined here. In this "permissions" section we can set the permission type as "read", "write" or "readwrite".
Example
{
"source": "communicationAdapter",
"quality": "quality_all",
"permission": "read"
}
cloudUploadConfig¶
Path Application Name >> cloudUploadConfig.
Type object, optional
Usage
Consists of a name, description and data points that are intended to upload to Insights Hub.name and description fields can be any arbitrary value.
Elements of dataPoints:
{
"name": "ENC1_POS_1",
"description": "ENC1_POS_1",
"unit": "%",
"dataType": "DOUBLE",
"dataPointData": {
"sinumerikUid": "ENC1_POS|1"
}
}
Data points are the representation of data is intended to upload into Insights Hub. Name and description fields change depending on how data will be seen on data aspect.
name and description attributes are required and their values is up to user preference.
unit attribute is fixed and its value should be "%"
dataType attribute is required and its value should match with data type in Insights Hub aspect
dataPointData is the part that matches uploading data point with Insights Hub aspect. sinumerikUid should be same with the data in the subscription part of your machine config.
For example in order to use data point above your subscriptions object should contain following subscription
"ArbitraryMessageId": {
"source": "Application Name",
"quality": "hf",
"payload": [
{
"sinumerikUid": "ENC1_POS|1",
"period": 2
}
],
"isCloudMessage": true
}
containersConfig¶
Path Application Name >> containersConfig
Type object, Mandatory
Usage
Reserved for development purposes. We can leave this section blank.
loggingConfig¶
Path Application Name >> loggingConfig
Type object, Mandatory
Usage
Sets the appender type and severity level for the application.
You can use apppenders for setting logging location. The severity is for the levels of logging. Below appender types and severity levels can be used.
Appender Types
| Name | Description |
|---|---|
| CONSOLE_APPENDER | Appender for printing logs only to console. |
| FILE_APPENDER | Appender for uploading the logs to a file, which is on the same directory with the application. Also prints the logs to console. |
| JOURNAL_APPENDER | Appender for uploading the logs only to journald. |
| SYSLOG_APPENDER | Appender for uploading logs to journald with their system time. Also prints the logs to console. |
Log Severity
For logging levels, the "severity" variable under application configuration file changes the usage of "Logger". In "Logger" class, you must define the log's level, which you want to print. Severity changes the availability of those levels. For the severity variable, the following levels are available:
Depending on the severity level defined in the application configuration file, the availability of the logging functions changes. Different functions are available with different severity levels. For logging functionality function calls are described in AppSDK language specific documentation.
| Name | Description |
|---|---|
| "INFO" | This level enables the logging for all levels except Debug level. |
| "DEBUG" | This level enables the usage of all logging levels. |
| "WARN" | This is the level for printing only warnings and errors. |
| "ERROR" | This level is only for error messages. |
Example
"loggingConfig": {
"appender": "JOURNAL_APPENDER",
"severity": "INFO"
},
lifecycleConfig¶
Path Application Name >> lifecycleConfig
Type object, Mandatory
Usage Reserved for development purposes. We can leave this section blank.
specificConfig¶
Path Application Name >> specificConfig
Type object
Usage
"specificConfig" section is reserved for the application's specific needs. The application developer can use this section freely. Content is not important for AppSDK as long as specific config section is a valid json object. The application developer can use "getSpecificConfig()" method to access this object.
Example
{
"specificConfig": {
"specificArray" : ["item0", "item1", "item2"],
"specificDecimal" : 10,
"specificString" : "sample value"
}
}
datasourceConfig¶
In order to access data of available datasources, "datasourceConfig" section of "appconfig.json" needs to be configured properly.
"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. Most known datasource providing application is the SINUMERIK adapter.
Every service has its own custom settings and configuration. Please refer to the corresponding service documentation of the supported services to get details about the configuration.
Hint: You can find the documentation about available services in the Section Data access.
Every service has its own custom settings and configuration. Please refer to the corresponding service documentation of the supported services to get details about the configuration.
Identify datasources Each datasource is identified by a unique name - the datasourceId. The name can be changed to the needs of the installed instance. If an application should provide more datasources, this application must not relay on the datasourceId as identifier in the appconfig - it can be different to the metaconfig. Use the optional element "meta" or the "type" string instead.
eventConfig¶
Path Application Name >> eventConfig
Type object
Usage
If you want to receive "OnAppShutdown" and "OnConfigChange" events, you need to add following fields to metaconfig file "eventConfig" section as below.
Example
{
"eventConfig": {
"subscribedEvents": [
{
"name": "OnAppShutdown",
"waitSeconds": 30
},
{
"name": "OnConfigChange"
}
]
}
}
Platform to EdgeApp Message Types¶
"OnAppShutdown" event is received before application is restarted. When application gets event it waits for "waitSeconds", then app will be restarted. If this event was not registered, restart will be done without any event sent to application. This event is sent to application to notify app to perform necessary operations before shutting down.
"OnConfigChange" event is received in case of a specific config change. If this event was not registered, application will be restarted without sending any event. When this event is defined in "eventConfig", "OnConfigChange" event will be sent to application and application will not be restarted. In this case, application should reload its updated its application configuration.
webserverConfig¶
Path Application Name >> webserverConfig
Type Object
Usage
If your Indapp is meant to use reverse proxy, your configuration file should include a "webserverConfig" field below.
Example
{
"webserverConfig": {
"enable": true,
"reverseProxyForward": {
"name": "<officialappname>",
"base": "/<officialappname>/",
"to": "http://<container_name>.<officialappname>[.proxy-net.industrialedge.io]:<port>/",
"requestParams":[
{
"name": "X-AppBaseUrl",
"value": "$MW_PROXY_BASE"
},
{
"name": "X-Logged-In-User",
"value": "$MW_USER_NAME"
}
]
}
}
}
Any questions left?
Except where otherwise noted, content on this site is licensed under the The Siemens Inner Source License - 1.1.