Skip to main content

API reference

Siemens S7 connector programming specifications

Abstract

FairCom provides specific API actions to configure the Siemens S7 connector using FairCom Edge

FairCom provides specific API actions to configure the Siemens S7 connector. Be sure to enable the Siemens S7 service before requesting data from a Siemens S7 server.

Examples

Note

The FairCom createInput JSON action is used to define the specifics of a connector device and the desired data.

{
  "authToken": "<yourAuthTokenHere>",
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "mySiemensS7",
    "serviceName": "siemensS7",
    "settings": {
      "ipAddress": "127.0.0.1",
      "rack": 0,
      "slot": 2,
      "dataCollectionIntervalMilliseconds": 5000,
      "propertyMapList": [
        {
          "propertyPath": "flag1",
          "memoryArea": "db",
          "dataBlockNumber": 1,
          "offset": 0,
          "dataType": "word"
        }
      ]
    },
    "tableName": "siemensS7Table"
  }
}
{
  "authToken": "<yourAuthTokenHere>",
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "mysiemensS7",
    "serviceName": "siemensS7",
    "settings": {
      "ipAddress": "127.0.0.1",
      "rack": 0,
      "slot": 2,
      "packageSize": 500,
      "dataCollectionIntervalMilliseconds": 1000,
      "dataCollectionBufferCount": 5,
      "propertyMapList": [
        {
          "propertyPath": "status",
          "memoryArea": "db",
          "dataBlockNumber": 1,
          "offset": 0,
          "amount": 1,
          "dataType": "bit",
          "bitPosition": 3
        },
        {
          "propertyPath": "nerrors",
          "memoryArea": "db",
          "dataBlockNumber": 1,
          "offset": 2,
          "amount": 3,
          "dataType": "doubleword"
        },
        {
          "propertyPath": "temperature",
          "memoryArea": "db",
          "dataBlockNumber": 1,
          "offset": 20,
          "amount": 2,
          "dataType": "real"
        }
      ]
    },
    "databaseName": "ctreeSQL",
    "ownerName": "admin",
    "tableName": "siemensS7Table",
    "retentionPolicy": "autoPurge",
    "retentionPeriod": 30,
    "retentionUnit": "day",
    "metadata": {
    }
  }
}

A response to a request is "0" when successful. A non-zero value response indicates an error occurred.

Successful response

{
    "result": {},
    "requestId": "00000007",
    "errorCode": 0,
    "errorMessage": ""
}

Error response

Not yet available.

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Note

See createInput for "params" properties that are common to all connectors.

Table 1. Siemens S7 specific connector "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

serviceName

specifies which type of input to create

Required

string

"siemensS7"

settings

specifies properties needed to configure the data source of the input.

Required - No default value

array of objects

settings
.dataCollectionBufferCount

specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table.

This option combines multiple data collection events and inserts them into the integration table as one MQTT message.

If this value is more than 1, the connector converts each set of collected data into a JSON object and adds the object to an array inside a JSON document. When the count is reached, the connector writes the JSON document to the source_payload field of a record it inserts into the integration table.

Optional

integer

1 to 65535

settings
.dataCollectionIntervalMilliseconds

specifies how often in milliseconds the connector requests data.

Optional: 10000

integer

0 to 2147483647

settings
.ipAddress

specifies the PLC/Equipment IPV4 Address.

Required - No default value

string

settings
.packageSize

specifies the package size in bytes used to communicate with the PLC. 

Higher numbers allow the connector to retrieve more data in fewer requests.

Optional. If not specified, the PLD PDU size is used.

integer

240 to 960

settings
.propertyMapList

specifies which data the connector requests and where to put it in the generated JSON.

Required - No default value

array of objects

settings
.propertyMapList
.amount

specifies the number of consecutive "dataType" values the connector retrieves.

The connector retrieves 3 one-byte values when "amount" is 3 and "dataType" is "byte".  

The connector retrieves 2 four-byte values when "amount" is 2 and "dataType" is "real".

If "dataType" is "bit", "amount" must be 1 because the connector retrieves one 8-bit byte for each bit. See "bitPosition".

Optional: 1

integer

1 to 65535

settings
.propertyMapList
.bitPosition

If "dataType":"bit" , "bitPosition" defines which of the eight zero-based bits to read from the byte the connector retrieves.

Optional 0

integer

0 to 7

settings
.propertyMapList
.dataBlockNumber

specifies the number of the Data Block memory area where the connector retrieves data.

It is ignored unless "memoryArea":"db".

Required if "memoryArea":"db"

integer

1 to 65535

settings
.propertyMapList
.dataType

specifies the data type of memory retrieved by the connector.

If "memoryArea":"ct", "dataType" must be "counter"

If "memoryArea":"tm", "dataType" must be "timer".

Required - No default value

string enum

"bit"

inside a byte

"byte"

8-bit integer

"ubyte"

unsigned 8-bit integer

"word"

16-bit integer

"uword"

unsigned 16-bit integer

"doubleword"

32-bit integer

"udoubleword"

unsigned 32-bit integer

"real"

32-bit float

"counter"

16-bit integer

"timer"

16-bit integer

settings
.propertyMapList
.memoryArea

specifies the type of memory area where the connector retrieves data.

Required - No default value

string enum

"pe"

Process Inputs

"pa"

Process Outputs

"mk"

Flags "Merkers"

"db"

Data Block

"ct"

Counters

"tm"

Timers

settings
.propertyMapList
.offset

specifies the offset to the starting byte in the memory area where the connector retrieves data.

Required - No default value

integer

0 to 4294967296

settings
.propertyMapList
.propertyPath

specifies the JSON path where the connector stores collected data.

Example: "prop1.prop2"

Required - No default value

string

settings
.rack

specifies the PLC Rack number.

Required - No default value

integer

0 to 7

settings
.slot

specifies the PLC Slot number.

Required - No default value

integer

1 to 31



How to horizontally scroll a table

To scroll the table right or left, mouse over the table, hold down shift , and move the mouse wheel down or up.