How to use ctrlX I/O Engineering API with Python

Overview

This blog shows how to operate ctrlX I/O Engineering using the Python programming language in a development environment. The ctrlX I/O Engineering API is used to generate and edit ctrlX OS - EtherCat Master IO configurations that are used in automatic commissioning.

Individual examples are executed and explained, so you can see how the communication with the interface works in Python including sample code.

A documentation of the API can be accessed in the ctrlX I/O Engineering:

Prerequisites

Programming environment (for example Visual Studio Code)
Python library "requests":
```
pip install requests 
```
Running ctrlX I/O Engineering application on the engineering PC

Implementation

Communication is established between the programming environment and the ctrlX I/O Engineering API by http protocol using the requests library.

Hint: read = GET, write = PUT, create = POST, delete = DELETE

1. Attach predefined configuration or hardware

A code example in Python to add the S20 _EC_BK bus coupler and the S20 bus coupler stations to EtherCAT Master.

A post request is sent to the REST API with the predefined configuration in JSON format. The REST API recognizes the command and executes it and then sends back a response. The response can then be displayed in the terminal. Have a look at the comments in the code.

#the required libraries 
import requests
import json
#the Bus coupler (S20_EC_BK) is defined as dictionaries. This corresponds to the JSON format. 
S20_EC_BK={
  "name": "S20_EC_BK",
  "elementType": "Device",
  "children": [
    "S20_DI_16_1",
    "S20_DO_16_1"
  ],
  "elementProperties": {
    "build": {
      "excludeFromBuild": False,
      "external": False,
      "enableSystemCall": False,
      "linkAlways": False,
      "compilerDefines": ""
    }
  },
  "deviceInfo": {
    "name": "S20-EC-BK, IndraControl S20 EtherCAT Buskoppler",
    "vendor": "Bosch Rexroth AG",
    "deviceType": 65,
    "id": "24_00293C6000000001",
    "version": "Revision=16#00000001",
    "orderNumber": "S20-EC-BK",
    "description": "EtherCAT Slave imported from Slave XML: S20-EC-BK_019.XML Device: S20-EC-BK, IndraControl S20 EtherCAT BuskopplerS20-EC-BK, IndraControl S20 EtherCAT Buskoppler"
  }}
S20_DI_16_1={
    "name": "S20_DI_16_1",
  "elementType": "Device",
  "children": [],
  "elementProperties": {
    "build": {
      "excludeFromBuild": False,
      "external": False,
      "enableSystemCall": False,
      "linkAlways": False,
      "compilerDefines": ""
    }
  },
  "deviceInfo": {
    "name": "S20-DI-16/1, IndraControl S20-Digital-Eingabemodul, 16 Eingaenge, 24 V DC, 1-Leiter-Anschlusstechnik",
    "vendor": "Bosch Rexroth AG",
    "deviceType": 68,
    "id": "24_000200D6_DI_TERM_293C60",
    "version": "0",
    "orderNumber": "S20-DI-16/1",
    "description": "EtherCAT Module imported from Slave XML: S20-EC-BK_019.XML Device: S20-DI-16/1, IndraControl S20-Digital-Eingabemodul, 16 Eingaenge, 24 V DC, 1-Leiter-Anschlusstechnik"
  }}
S20_DO_16_1={
  "name": "S20_DO_16_1",
  "elementType": "Device",
  "children": [],
  "elementProperties": {
    "build": {
      "excludeFromBuild": False,
      "external": False,
      "enableSystemCall": False,
      "linkAlways": False,
      "compilerDefines": ""
    }
  },
  "deviceInfo": {
    "name": "S20-DO-16/1, IndraControl S20-Digital-Ausgabemodul, 16 Ausgaenge, 24 V DC, 500 mA, 1-Leiter-Anschlusstechnik",
    "vendor": "Bosch Rexroth AG",
    "deviceType": 68,
    "id": "24_000200D7_DO_TERM_293C60",
    "version": "0",
    "orderNumber": "S20-DO-16/1",
    "description": "EtherCAT Module imported from Slave XML: S20-EC-BK_019.XML Device: S20-DO-16/1, IndraControl S20-Digital-Ausgabemodul, 16 Ausgaenge, 24 V DC, 500 mA, 1-Leiter-Anschlusstechnik"
  }}
daten=S20_EC_BK
url='http://localhost:9003/io/engineering/api/v2/devices/%2FDevice/ethercatmaster' #Url of ctrlX I/O Engineering under ethercatmaster
response = requests.post(f'{url}',json=daten)# a post request is sent to the REST API with daten as JSON (S20_EC_BK)
print(f" 1- {response}") # to see the Response from the REST API 
daten=S20_DI_16_1
url='http://localhost:9003/io/engineering/api/v2/devices/%2FDevice/ethercatmaster/S20_EC_BK' #Url of ctrlX I/O Engineering under S20_EC_BK
response = requests.post(f'{url}',json=daten)# a post request is sent to the REST API with daten (S20_DI_16_1)
print(f" 2- {response}")
daten=S20_DO_16_1
url='http://localhost:9003/io/engineering/api/v2/devices/%2FDevice/ethercatmaster/S20_EC_BK' # Url of ctrlX I/O Engineering under S20_EC_BK
response = requests.post(f'{url}',json=daten)# a post request is sent to the REST API with daten (S20_DO_16_1)
print(f" 3- {response}") # to see the Response from the REST API

The response in the terminal is "201", which means created.

3. Delete a module from an existing configuration

ctrlX IO Engineering - example project - deleted

Simply send a delete request with the targeted URL to the REST API. In this example the S20_DI_16_1 module is deleted from the configuration.

#the required libraries 
import requests
import json

url1='http://localhost:9003/io/engineering/api/v2/devices/%2FDevice/ethercatmaster/S20_EC_BK/S20_DI_16_1'# the url of the S20_DI_16_1
response = requests.delete(url1) # sent a delete requests to the REST API 
print(response)

The response in the terminal is "200". This means the command was executed.

4. Save the opened project

A code example in Python to save the opened project at a specific location. The path and the project name can be modified.

import requests
import json
projectSaveAs={
  "jobType": "ProjectJob",
  "jobParameters": {
    "action": "Save",
    "path": "D:\\mine\\My_IO_Projects\\My_project_Test.project" #the path and the project name
  }
}
url='http://localhost:9003/io/engineering/api/v2/jobs'# the url of the jobs commando
response = requests.post(url,json=projectSaveAs) 
print(response)