

S7adapter¶

Introduction¶

The S7adapter is an application used to connect the SINUMERIK Edge to a S7 device and provide data and access to SINUMERIK Edge applications.

Structural overview¶

In this chapter, the provided features of the S7adapter are documented. General information about configuration and usage of the datasource services are documented in the service documentation:

parameter-service/v1

Please refer to the APP-SDK documentation for the corresponding service, which can be found here.

In addition, refer to the APP-SDK delivery for example applications.

parameter-service¶

The S7adapter provides access to a datasource of type S7Device.

Addressing S7 data¶

Area	Operand	Bit	Byte	Word	Double word
Input	E / I	Ey.x	EBy	EWy	EDy
Output	A / O / Q	Ay.x	ABy	AWy	ADy
Merker	M	My.x	MBy	MWy	MDy
Datablock	DB	DBz.DBXy.x	DBz.DBBy	DBz.DBWy	DBz.DBDy

S7adapter-specific return codes¶

Code (hex)	Code (dec)	Meaning	Explanation
0x800	2048	Parameter or index not found	Check the S7 address syntax and the available data on the connected S7 device
0x801	2049	Convert error	The received value could not be converted into the required type.
0x804	2052	Connection error - wait for machine connect	The S7adapter cannot connect to the S7 device.
0x805	2053	Parameter or value is not supported	Either parameter is out-of-range or a wrong datatype has been given. Wrong usage of index or length function parameter.
0x806	2054	Initialisation error	Internal services are not initialized correctly.
0x808	2056	Function exists but is not implemented	This function is not implemented.
0x80A	2058	invalid array length	The given parameter value array does not fit to the given parameter length.

!!! Hint: In case of an received errorcode, the value object may contain additional error information.

Provided value types¶

The S7adapter utilizes the ParameterValueObject which is defined by the AdapterFramework library. This object represents a parameter value and its type. The "value_type" describes the original data type and needs to be used for decoding. See the table below for a list of value types. The "value" is always encoded as an array of strings.

Value Types¶

code (hex)	code (dec)	meaning
0x0	0	Invalid
0x1	1	Bit
0x3	3	Byte
0x5	5	Word
0x7	7	DoubleWord
0xc	12	Array of objects

Hint: Depending on the S7 controler implementation, strings are in most cases represented as ASCII coded byte arrays.

Function reference¶

This section describes the S7adapter's specific usage of the ParameterValueObject.

ReadDeviceParameter¶

Read a single parameter from the machine.

Parameter:

parameter	Datatype	Description
parameter	String	The unique name of the parameter that is requested. Please refer to the Addressing S7 data section.
index	Integer	Not used – value must be set to 0.
length	Integer	Optional parameter to read datablocks. Reads the given amount of data in the defined datatype.

returns: ReturnObject<ParameterValueObject>

Remarks: - length must be in range of 1 and 100000 otherwise you will get a not supported error - a request for datatype 'Bit' needs a fix length of 1, otherwise you will get a not supported error

Returns a ParameterValueObject. For array access, you will receive an array of values with the same valuetype. Different valuetypes in one array are currently not supported. The "value_type" represents the type of the elements inside the "value" array.

On error, the ParameterValueObject provides "value_type" equals "0" which means "invalid". The "value" array contains the detailed error code and name of the requested "parameter" with format error:<code>|param:<parameter>.

ReadMultiDeviceParameter¶

Consistent reading of multiple parameters in the same timeslice is not supported. You will always get the return code 0x808.

WriteDeviceParameter¶

Write a value to the machine via the provided parameter.

Parameter:

parameter	datatype	Description
parameter	String	The unique name of the parameter that is requested. Please refer to the Addressing S7 data section.
index	Integer	Not used – value must be set to 0.
length	Integer	Optional parameter to write datablocks. Write the given amount of data in the defined datatype. The given length must fit to the given values array length.
value	ParameterValueObject	The value object to write (including the type of value). Attention: The given value_type in the ParameterValueObject must match the target value type which is specified by the parameter address string (see provided value types and Addressing S7 data). The value can be coded in boolean, decimal or hexadecimal style - see value encoding.

returns: ReturnObject<bool>

Returns a bool. The return_value will be true if the write operation is successful.

Value encoding¶

The write parameter function allows different encoding styles for given values.

encoding style	allowed examples	not allowed
boolean	1 ; 0 ; true ; false	TRUE ; False
decimal	12345	-1 ; 1.5 ; 1,5 ; out of range (see Addressing S7 data)
hexadecimal	0xab ; 0xAB	AB ; ab ; out of range (see Addressing S7 data)

Firewall permissions¶

The WriteDeviceParameter function filters parameter access with a whitelist. All parameter write requests will be denied unless they are whitelisted. Consumer applications need to use an accessType configuration of "w" to grant writing access to the required parameters.

configuration¶

The S7adapter provides access to a datasource of type S7Device. To enable access to a S7 device, the connection information must be configured in the S7adapter application instance. This configuration is done in the "meta" object of the datasource instance.

To establish a connection to a S7 device, the IP address, Rack ID and Slot number must be configured. The default configuration is:

Rack	Slot
0	2

In most setups, the default configuration should be valid. It should also fit for a connection to the PLC of a SINUMERIK NCU.

example configuration

{
    "datasourceConfig": 
    { 
        "providedDatasource":[
        { 
            "datasourceId": "PLC", 
            "type" : "S7Device",
            "meta":
            {
                "ipAddress":"192.168.0.1",
                "rack":0,
                "slot":2
            },
            "services": 
            { 
                "parameter-service/v1":{
                    "protected": "w"
                }
            }
        }]
    }
}

Attention: Do not change any configuration in the providedDatasource section besides the "meta" object and the datasourceId.

declare required access to an S7 device¶

To declare the need of accessing a S7 device, the metaconfig of the application must use the requiredDatasource section. Information about configuration and usage of the parameter-service is documented in the service documentation parameter-service/v1

example configuration

{
    "datasourceConfig": 
    { 
        "requiredDatasource":[
        { 
            "datasourceId": "PLC", 
            "type" : "S7Device",
            "services": 
            { 
                "parameter-service/v1":{
                    "access":[{
                        "accessType":"r",
                        "datapoints":[
                            {"address":""}
                        ]
                    }]
                }
            }
        }]
    }
}

use symbolic addressing¶

It is possible to configure a symbol table of TIA portal into an application by using the naming feature of datapoints.

For example:

In TIA Portal a list of variables is defined. In the screenshot you can see an input I0.0 with the name "door".

To use the symbolic name "door" in your application, you can use the datapointName in your metaconfiguration file. Please review the configuration example. The application should now use the datapointName in the APP-SDK API for accessing the parameters. Please review the APP-SDK documentation for that.

{
    "datasourceConfig": 
    { 
        "requiredDatasource":[
        { 
            "datasourceId": "PLC", 
            "type" : "S7Device",
            "services": 
            { 
                "parameter-service/v1":{
                    "access":[{
                        "accessType":"r",
                        "datapoints":[
                            {
                                "address":"I0.0",
                                "datapointName":"door"
                            }
                        ]
                    }]
                }
            }
        }]
    }
}

Now, the application can be configured for different machines, using the door sensor on different input addresses, without changing the application code.

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.