

information-service/v1

Overview¶

The information-service is a synchronous request/response communication interface that can be used to fetch specific types of information from a datasource. A datasource is a logical object such as a real hardware device – like a SINUMERIK NCU – or any other kind of provided data from an application.

The information-service itself does not determine the kind of information that is available to the consumer. Please refer to the corresponding documentation of the provided datasource to find out which information is available.

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.

Attention: This chapter only describes the generic functionality of this interface. The actual functionality (e.g. the kind of information it can fetch) depends on the available provider applications and connected datasources – thus its specific usage is described in the documentation of the suitable provider application.

configuration schema¶

requiredDatasource.services.information-service/v1

element	rule	type
reports	required	array of string, must not be empty

providedDatasource.services.information-service/v1

element	rule	type
reports	required	array of string, must not be empty
address	required	object
- tcpPort	required	int
- containerId	required	string

Example configurations¶

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

AppSDK package contend.

creating a consumer application¶

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

configure access to specific information¶

In SINUMERIK Edge, provider applications define the type of data available in their configuration's providedDatasource section.

Example: You want your application to fetch the alarm history from a device. The providedDatasource section of a provider application defines the "alarmList" as an available report via the information-service:

        "providedDatasource": [{ 
            "datasourceId": "sample_datasourceId", 
            "type" : "sample_type", 
            "services": { 
                "information-service/v1":{
                    "address": {
                        "tcpPort": 12345,
                        "containerId": "sample_provider"
                    },
                    "reports":["alarmList"]
                }
            }
        }]

To obtain access to this information, define the requirement in the requiredDatasource section of your application's configuration:

        "requiredDatasource": [{
            "datasourceId" : "sample_datasourceId", 
            "type" : "sample_type", 
            "services": { 
                "information-service/v1":{
                    "reports":["alarmList"]
                }
            }
        }]

access information using the APP-SDK¶

To request a configured report on runtime, your application must use an information-service instance provided by the APP-SDK library. Please refer to the corresponding interface documentation of the APP-SDK.

Attention: Reports returned by the information-service are specific to the provided datasource and report type. To find details about the format of a returned report, refer to the respective provider application's documentation.

creating a provider application¶

This section is the developer guideline for creating an application which provides reports with the information-service. A provider application can offer different kinds of information ( for example: version, status, history, snapshot, ...). As such, the application should implement an information-service to enable access to it.

1. name it:¶

A report in SINUMERIK Edge is defined as a generic blob of information, defined by datasource type and reportID. In the first step, you must name the provided report.

2. define it:¶

The format of a report must be defined in the application's documentation. It is always a good idea to define a strict schema for the returned report object.

3. declare it:¶

To enable access to the report, your metaconfig file must declare the available report and the runtime address of the information-service instance of your datasource.

Example metaconfig:

"datasourceConfig": {
    "providedDatasource": [{ 
        "datasourceId": "my camera", 
        "type" : "CAMERA", 
        "services": { 
            "information-service/v1":{ 
                "address":
                {
                    "tcpPort":44448,
                    "containerId": "cameraApp.mainContainer"
                },
                "reports":["snapshot"]
            }
        }
    }]
}

4. provide it:¶

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

The information-service/v1 communication is based on the JSON-RPC 2.0 protocol. SINUMERIK Edge is providing a specification file which can be used by the libjson-rpc-cpp stub generator to create the server's cpp 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 an information-service/v1 provider skelleton with the JSON-RPC stub compiler:

[
    {
        "name": "GetReport",
        "params": {
            "meta": "depending on the report_id - an additional possibility to specialize the request",
            "report_id": "an identification string which report is requested"
        },
        "returns": {
            "return_code": 0,
            "return_value": {}
        }
    } 
]

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 report specific object.

ReturnObject

{  
    "return_code": 0, 
    "return_value": { "the report object" }
}

ReturnCodes

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

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.

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 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.