Configuring AppSDK¶
In order to use AppSDK, we need a configuration file called "appconfig.json". Without this file, AppSDK will not work. We can supply this file to AppSDK in two separate locations.
- The first location is etc/runtime/config directory.
- The second location is the directory of executable file.
We can specify the configuration file in both directories but AppSDK will only use one of them. First, it will check “etc/runtime/config” directory. If the configuration file is not there it will check the directory that the executable file resides in. If it fails to locate "appconfig.json" file in both locations, it gives initialization error message and won’t work.
SINUMERIK Edge Platform uses metaconfig file which is provided during application publish as an input to create appconfig.json. appconfig.json contains same sections with metaconfig file. But as a result of platform processing, a difference occurs between metaconfig and appconfig.json. In AppSDK package, sample appconfig.json files are provided to use during development by Development Environment.
remark Please check Create the Metaconfig section in developer manual for more information regarding usage of configuration fields
Sample Application Configuration¶
{
"appoutput": {
"system_service" : false,
"machineConfig": {
"subscriptions": {
"sinumerik_hf_data": {
"source": "communicationAdapter",
"quality": "hf",
"payload": [
{
"sinumerikUid": "hf_data",
"period": 2
}
]
},
"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": {
"connectionstring": "rnd:localhost:1883",
"credentials": {
"username": "databus_username_agent",
"password": "databus_password_agent"
},
"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",
"services" : {
"parameter-service/v1" : {
"access" : [
{
"accessType" : "w",
"datapoints" : [
{
"address" : "sft2.ncu1.v1"
}
]
}
],
"sessionId" : "sft2"
}
},
"type" : "SINUMERIK"
}
]
},
"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.
Application Name¶
Path Application Name >>
Type: Object, Mandatory
Example
{
"appoutput": {
"rest of the config file"
}
}
The application name is not needed within the application program or any other part of "appconfig.json" file. In the sample "appconfig.json" file, the application name is used in the permissions and subscriptions section as a convenience but in reality, the application name is not bounded to subscriptions or permissions. The application name and subscription name can be totally different. (But for each subscription there should be a permission with the same name. Detailed information regarding permissions and subscriptions is provided in the following sections of this document.)
system_service¶
Path Application Name >> system_service
Type Boolean,Mandatory
machineConfig¶
Path Application Name >> machineConfig
Type Object
Usage
While creating appconfig.json from the metaconfig, SINUMERIK Edge Platform will add additional subscriptions to this area for internal usage of the platform services.
This object is required to define databus subscriptions. The subscriptions will be discussed in the following section.
Example
"subscriptions": {
"sinumerik_hf_data": {
"source": "communicationAdapter",
"quality": "hf",
"payload": [
{
"sinumerikUid": "hf_data",
"period": 2
}
]
},
}
subscriptions¶
Path Application Name >> machineConfig >> subscriptions
Type Object, Mandatory
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 >> message_id
Type: object
Example
"sinumerik_hf_data": {
"source": "communicationAdapter",
"quality": "hf",
"payload": [
{
"sinumerikUid": "hf_data",
"period": 2
}
]
},
source¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> source
Type string, Mandatory
Example
"source": "communicationAdapter",
quality¶
Path Application Name >> machineConfig >> subscriptions >> message_ID> quality
Type string, Mandatory
Example
"quality": "hf",
payload¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> payload
Type array
Example
json
"payload": [
{
"sinumerikUid": "hf_data",
"period": 2
}
]
sinumerikUid¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> Payload >> sinumerikUid
Type string, Mandatory
Example
"sinumerikUid": "hf_data",
# period¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> Payload >> period
Type integer, Mandatory
json
"period": 2
Usage
isCloudMessage¶
Path Application Name >> machineConfig >> subscriptions >> message_id>> isCloudMessage
Type Boolean, Optional
Example
"isCloudMessage":true
databusConfig¶
Path Application Name >> databusConfig
Type Object, Mandatory
Usage
SINUMERIK Edge Platform will also add necessary permissions to this area for the additional subscriptions which are defined in machineConfig section for internal usage of the platform services
Example
"databusConfig": {
"connectionstring": "rnd:localhost:1883",
"credentials": {
"username": "databus_username_agent",
"password": "databus_password_agent"
},
"permissions": [
{
"source": "communicationAdapter",
"quality": "quality_all",
"permission": "read"
},
{
"source": "appoutput",
"quality": "quality_all",
"permission": "write"
}
]
},
connectionstring¶
Path Application Name >> databusConfig >> connectionstring
Type String, Mandatory
Usage
connectionstring should be set differently depending on the scenario.
First scenario Your application runs directly on local pc for development purposes without any container.
When you are running your application without containerizing it, it should connect to Databus container running inside Development Environment. In this scenario your application runs outside of Development Environment(runs directly on host machine) and since your application on host, not inside any container, you can only connect to Databus through its mapped port. In this case your connectionstring should be rnd:localhost:1883
Second scenario Your application runs on local pc but inside container.
If you execute your application inside container, since your application has to use docker-compose network(Development Environment network), inside this docker-compose network containers can resolve each others with container name. This also means that your application can resolve Databus container with its name. In this case rnd:databus:1883 should be used.
Third scenario Your application runs on SINUMERIK Edge
If application runs on SINUMERIK Edge connectionstring always must be rnd:databus.indapp-net.industrialedge.io:8883
Setting port as 8883 provides TLS encryption for databus communication of applications. For backward compatibility, it is also possible to set port number 1883, as rnd:databus.indapp-net.industrialedge.io:1883. In this case no TLS encryption is applied.
Example
"connectionstring": "rnd:localhost:1883"
credentials¶
Path Application Name >> databusConfig >> credentials
Type object, Mandatory
Usage
We don't need to set "username" and "password" fields in a local machine. For SINUMERIK Edge, we also don't need to set it since Databus automatically generates it for the application.
From the application developers side, we can just leave it as it is .
Example
"credentials": {
"username": "databus_username_agent",
"password": "databus_password_agent"
},
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 in metaconfig.
Example
{
"source": "communicationAdapter",
"quality": "quality_all",
"permission": "read"
}
cloudUploadConfig¶
Path Application Name >> cloudUploadConfig.
Type object, optional
containersConfig¶
Path Application Name >> containersConfig
Type object, Mandatory
loggingConfig¶
Path Application Name >> loggingConfig
Type object, Mandatory
Example
"loggingConfig": {
"appender": "JOURNAL_APPENDER",
"severity": "INFO"
},
lifecycleConfig¶
Path Application Name >> lifecycleConfig
Type object, Mandatory
specificConfig¶
Path Application Name >> specificConfig
Type object, Mandatory
Example
{
"specificConfig": {
"specificArray" : ["item0", "item1", "item2"],
"specificDecimal" : 10,
"specificString" : "sample value"
}
}
datasourceConfig¶
Path Application Name >> datasourceConfig
Type object
In order to access available dataSources (like SINUMERIK Adapter), you have to use the datasourceConfig. This section can not be used directly in the appconfig of the application, without reconfiguring the communication gateways and datasource providing applications as well. Thats why the datasourceConfig section should always be configured in the metaconfig. Please refer to the metaconfig documentation for details.
eventConfig¶
Path Application Name >> eventConfig
Type object
Example
{
"eventConfig": {
"subscribedEvents": [
{
"name": "OnAppShutdown",
"waitSeconds": 30
},
{
"name": "OnConfigChange"
}
]
}
}
Any questions left?
Except where otherwise noted, content on this site is licensed under the The Siemens Inner Source License - 1.1.