

parameter-service/v1

Overview

The parameter-service is a synchronous request/response communication broker. It must be used to read or modify data on a datasource. A datasource is a logical object such as a hardware device – like a SINUMERIK NCU.

This chapter includes two developer guides for using this service:

• Accessing information from a provider application as a client.
• Providing information from a datasource to client applications as a provider.

!!! Hint: Information how to configure an application instance can be found in the operator manual.

structural overview

The parameter-service provides a synchronous interface which enables reading and writing parameters on available datasources. You must use this service if you want your application to access parameters on a datasource instance in a request/response style.

Each application that produces data can implement the parameter-service to provide consumer applications with access to this data. Please refer to the APP-SDK documentation of the corresponding service library.

configuration schema

requiredDatasource

element	rule	type
access	required, shall not be empty	array of object
- accessType	required	string
- datapoints	optional, shall not be empty	array of object
-- address	required	string
-- datapointName	optional	string
-- meta	optional	object
-- description	optional	string

• datapoints: The contents of a subscription. Available datapoints may be defined by the provided datasource.

  • provided by: metaconfig
  • configured by: operator
  • used by: consumer application at runtime

• address: Data identifier, specific to the provided datasource. May be changed by the operator.

  • provided by: datasource
  • configured by: operator
  • used by: provided datasource and consumer application at runtime

• datapointName: Data identifier used to address a configured datapoint at application runtime. Must be unique.

  • provided by: metaconfig
  • used by: consumer application at runtime

• meta: Object for application-specific configuration. Can be changed by the operator depending on the application's documentation.

  • provided by: metaconfig
  • configured by: operator
  • used by: consumer application at runtime

• description: Descriptive text to support the operator during the configuration process based on the application's documentation. Can be removed after configuration.

  • provided by: metaconfig
  • used by: operator

providedDatasource

element	rule	type
protected	optional	string
address	required	object
- tcpPort	required	number
- containerId	required	string

• protected: Controls the access of parameters by client applications.

• address: TCP/IP address of the parameter-service.

example configurations

Default metaconfig files can be found within sample applications' package content in the AppSDK.

creating a consumer application

This section is the developer guideline for creating an application which uses the parameter-service.

getting started - create the configuration

An example metaconfiguration which requires "write" parameter access to a datasource could look like the following:

"datasourceConfig": { 
    "requiredDatasource":[{
        "datasourceId": "SINUMERIK_NCU1", 
        "type" : "SINUMERIK", 
        "services": { 
            "parameter-service/v1":{ 
                "access": [{ 
                    "accessType": "w", 
                    "datapoints": [{ 
                        "address":"some parameter" 
                    }] 
                }] 
            }
        } 
    }] 
}

require parameter access for reading

For SINUMERIK datasources offered by the SINUMERIK Adapter, you need to declare read access in your application's configuration. If usage of datasources other than the SINUMERIK Adapter is necessary, please refer to the respective provider application's documentation to determine the necessity for read access.

If you are not sure which application will provide access to the required datasource, it is a good idea to define all of your needs – including the read access. To do so, declare an "accessType":"r" object in the application metaconfig:

example:

"access": [{ 
    "accessType": "r", 
    "datapoints": [{ 
        "address":"some parameter" 
    }] 
}] 

!!! Hint: To configure a range of parameters, it is possible to configure only the root of the parameter address. Please refer to the “write parameter access” section for an example on that.

require parameter access for writing

For writing parameter access it is necessary to define the needed set of parameters. Ultimately, the provider application defines which parameter access for writing is restricted or protected, thus always consult the respective provider application's documentation.

To configure a range of parameters, you only need to write the root of the parameter's address.

example: The configured datapoint /Axis/Drive/AA_OFF also enables access to /Axis/Drive/AA_OFF_MODE[1] and /Axis/Drive/AA_OFF_MODE[2]

parameter access configuration using wildcards

Usually you do not know the settings of the machine with which your application will communicate. As such, the operator must specify the correct parameter address on application deployment (in the Insights Hub, for example). To support the operator, you may specify wildcards in your datapoint declaration. You should use the wildcards section in the datasource configuration for describing those.

See the two examples below.

"datasourceConfig": { 
    "wildcards": [ { 
        "key":"$index", 
        "description": "array index of the parameter" 
    }] 
} 

...

"access": [{ 
    "accessType": "r", 
    "datapoints": [{ 
        "address":"some parameter" 
    }] 
}]

Don’t forget to create a howto documentation to support the operator during the configuration process. Be aware that the operator must know which information he must use to specify the wildcards.

identify configured parameters

The datapointName and parameter address are not always synonymous, due to the fact that the operator may change the parameter address depending on the target machine. As such, the application may define a unique name for a datapoint by using the optional element datapointName.

example:

"datapoints": [{
    "address":"some generic address", 
    "datapointName":"MyParameter1" 
}]

attach specific configuration to parameters

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

example:

"datapoints": [{
    "address":"some generic address", 
    "meta":{"something":"important" }
}]

runtime parameter access

To implement runtime access to parameters in your consumer application, please refer to the corresponding interface documentation of the APP-SDK.

creating a provider application

register your datasource

Use the metaconfig file of the application to define and register the application as a data provider.

example 1: The below applicaton provides access to internal data.

"datasourceConfig": { 
    "providedDatasource":[{ 
        "type" : "camera", 
        "datasourceId" : "defaultDatasourceID", 
        "services": { 
            "parameter-service/v1":{ 
                "address":{ 
                    "tcpPort":80, 
                    "containerId":"sampleapp"
                }  
            }
        } 
    }] 
}

example 2: Your application offers individual parameters that should be readable and writable by client applications. You want to give the operator the responsibility of verifying consumer applications' write access to those parameters. To do so, set the "protected" attribute to write protection “w”.

"datasourceConfig": {
    "providedDatasource":[{ 
        "datasourceId" : "myAppDatasource1", 
        "type" : "myAppDatasource", 
        "services": { 
            "parameter-service/v1":{ 
                "protected":"w", 
                "address":{ 
                    "tcpPort":80, 
                    "containerId":"sampleapp"                 
                }
            } 
        } 
    }] 
}

interface specification

create parameter-service provider skeletons

Hint: Currently there is no APP-SDK support for providing an instance of the parameter-service/v1. Instead, the provider application must create its own server for a JSON-RPC interface.

The parameter-service/v1 communication is based on the JSON-RPC 2.0 protocol. SINUMERIK Edge provides a specification file which can be used by the libjson-rpc-cpp stub generator to create the server's skeleton files. With this method, you will get a set of callback functions for implementing the access functionality to your data.

Use this JSON interface definition to generate a parameter-service/v1 provider skeleton with the JSON-RPC stub compiler:

[
    {
        "name": "ReadDeviceParameter",
        "params": {
            "parameter": "string",
            "index": 0,
            "length": 1
        },
        "returns": {
            "return_code": 0,
            "return_value": {
                "value_type": 0,
                "value": [ "string[]" ]
            }
        }
    },
    {
        "name": "WriteDeviceParameter",
        "params": {
            "parameter": "string",
            "index": 0,
            "length": 0,
            "value": {
                "value_type": 0,
                "value": [ "string[]" ]
            }
        },
        "returns": {
            "return_code": 0,
            "return_value": true
        }
    },
    {
        "name": "ReadMultiDeviceParameter",
        "params": {
            "parameter": [ "string[]" ]
        },
        "returns": {
            "return_code": 0,
            "return_value": [
                {
                    "value_type": 0,
                    "value": [ "string[]" ]
                }
            ]
        }
    }
]

For usage, please look here: https://github.com/cinemast/libjson-rpc-cpp

JSON.RPC

JSON-RPC 2.0 Syntax Protocol definition please look here: http://www.jsonrpc.org/specification

interface objects

ReturnObject

Each service function returns a JSON ReturnObject, including the return code and a function-specific ParameterValueObject.

ReturnObject

{  
    "return_code": 0, 
    "return_value": {"ParameterValueObject"}
}

Return Codes

code range	explanation
0x0000 - 0x03ff	reserved for predefined return codes
0x0400 - 0x07ff	reserved for routing return codes
0x0800 - 0xffff	app specific datasource return codes

code (hex)	meaning	explanation
0x0	success
0x1	undefined error
0x2	permission denied
0x3	function or value is not supported	Occurs if a application calls a non-existing function or calls a function with a non-existent parameter

code (hex)	meaning	explanation
0x400	initialisation error	The Adapter Framework has an error while service initialisation
0x401	reserved
0x402	datasource not found	the specified datasourceId is not available
0x403	service not found	the called service is not provided by the specified datasource
0x404	parameter error	RPC error on function call
0x405	communication error	The datasource is available, but has an undefined network communication error
0x406	blocked	the request was blocked by firewall. Check your configuration.

!!! Attention: If the APP-SDK interface implementation is not used, take attention to handle JSON-RPC exceptions as well. They may replace the errorcodes 0x03 and 0x404.

ParameterValueObject

The interface offers a ParameterValueObject for the representation of a retrieved parameter value(s). As a datasource provider, you may define your own object. The listing below is simply an example format of the ParameterValueObject.

ParameterValueObject

{
    "value_type": 0, 
    "value": ["string[]"]
}

value types

code (hex)	meaning
0x0	invalid
0x1	boolean
0x2	char
0x3	uchar / byte
0x4	int
0x5	uInt
0x6	long
0x7	ulong
0x8	longlong
0x9	ulonglong
0xa	double
0xb	string
0xc	array of objects
0xd	datetime

diagnosis of configuration status

The actual routing configuration status can be reviewed at the local dashboard. Detailed documentation of this UI can be found here.

On configuration errors, you can find diagnostic log messages 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.