ctrlX CORE web UI - API reference teaser.png

Using REST API of ctrlX CORE

CodeShepherd
Community Moderator
Community Moderator
Overview

This blog will show you how to use the REST API of a ctrlX CORE or a ctrlX COREvirtual to read out data of the ctrlX Data Layer. With this interface the control can also be configured and axis be commanded (see hints and the end).

Preparation
    • A real or a ctrlX COREvirtual control has to be connected to the network
    • An installation of the ctrlX MOTION app is needed for the following examples
    • Installation of a REST client is expected. In this Example Google Chrome extension YARC! is used
    • Make sure the browser is allowed to connect to the control via https by trusting its certificate
      Trust certificate of ctrlX OSTrust certificate of ctrlX OS
    • Optional: Installation of ctrlX WORKS. Please have a look at the corresponding documentation or video to see how to do this

Using REST (Representational State Transfer) API (Application Programming Interface)

1. Check connection

to your control with your network folder of windows or use our tool ctrlX WORKS. There all controls connected to your PC and their IPs are shown.

2. Authorize

The system is secure by design so to get access to the control you will always have to authorize your requests with a security token.

To get it send an https POST request to the authorization server of the ctrlX CORE (https://192.168.1.1/identity-manager/api/v1/auth/token). The payload has to be a permitted user and a password written as a JSON (JavaScript Object Notation) object. The standard ones are “boschrexroth” ({"name":"boschrexroth","password":"boschrexroth"}). 

The response will show the number 201 that means successfully created and includes a JSON object with the token of the type bearer.

REST API - get authorization token via YARCREST API - get authorization token via YARC

3. Use token

Get access to all data of the ctrlX CORE by adding it to the request header as "Authorization" changed to the format

 

 

 

"Bearer xxxxx..."

 

 

 

4. METADATA

To get to know which command can be used on which ctrlX Data Layer node additional information can be read out via a GET request of the type metadata. Exemplary the axs node of motion (https://192.168.1.1/automation/api/v1/motion/axs?type=metadata). Response is a JSON object including all information. Additionally the “Content-Type” “application/json” has to be added to the request header to tell the server how data should be interpreted.

Hint: read = GET, write = PUT, create = POST, delete = DELETE.
REST API - browse node via YARCREST API - browse node via YARC

5. BROWSE

To read all actual known axes in the ctrlX MOTION system by sending an https GET request of the type browse to the axes area of the motion (https://192.168.1.1/automation/api/v1/motion/axs?type=browse) to get to know which ones are available. Response is a JSON object including the type "arstring" and the list of axis names.
Send Browse RequestSend Browse Request

6. GET

Now send an https GET request to read out the actual values of the axis (https://192.168.1.1/automation/api/v1/motion/axs/Axis_1/state/values/actual/) found by browsing. Here the response contains a JSON object with all the data included.
REST API - get axis value via YARCREST API - get axis value via YARC

7. PUT

Now send an https PUT request to write a limit of the axis (https://192.168.1.1/automation/api/v1/motion/axs/Axis_1/cfg/lim/pos-min) found by browsing. As payload we have to hand over a JSON object with the data type and the value.
REST API - write axis limit via YARCREST API - write axis limit via YARC

8. POST

Now send an https POST request to create new axis "Axis_new" (https://192.168.1.1/automation/api/v1/motion/axs). ctrlX MOTION needs to be in configuration state. As payload we have to hand over a JSON object with the data type and the value.
REST API - create axis via YARCREST API - create axis via YARC

8. DELETE

Send an https DELETE request to the path https://192.168.1.1/automation/api/v1/motion/axs/Axis_new to remove an axis "Axis_new". ctrlX MOTION needs to be in configuration state.

REST API - remove axis via YARCREST API - remove axis via YARC

Notes
  • When using a ctrlX COREvirtual in port forwarding mode the address will change to https://localhost:PORT/... (PORT in standard is 8443)
  • REST = Representational State Transfer
    is a software architectural style that defines a set of constraints to be used for creating Web services.
  • API = Application Programming Interface
    is a computing interface to a software component or a system, that defines how other components or systems can use it.
  • JSON = JavaScript Object Notation
    is an open standard file format, and data interchange format, that uses human-readable text to store and transmit data.
  • The old version of the REST API is using v1.0 and the new one v1 in the corresponding links.
  • The validity time of the authorization token can be set via ctrlX OS web UI in the "Users & Permissions" area under "Session Policies". They will automatically expire with a control reboot.
  • A browse request can be send at any node of the ctrlX Data Layer.
  • A list of ctrlX COREs APIs can be found via its web UI or via addresshttps://<IP of control>/device-dashboard/api-reference 
    ctrlX CORE web UI - API reference and swaggerctrlX CORE web UI - API reference and swagger
  • Any standard browser is also using the REST API. With the developer tools, the used commands can be visualized.
    REST API in BrowserREST API in Browser
Related links
10 Comments
lg-lima
Established Member

Very useful info! Kudos 🤖

TK2588
Established Member

I think you have to add the port 8443 in the lastest software version to the URL:

https://localhost:8443/identity-manager/api/v1/auth/token

If yes, please adapt the description. Thank you!

 

CodeShepherd
Community Moderator
Community Moderator

This is only necessary when you run a ctrlX COREvirtual in port forwarding mode. Be aware that the port is freely chooseable in that case.

But thanks for the remark!

arjan_de_meijer
New Poster

Can you collaborate on this example by also putting data to the layer! Authentication and reading are possible; however, it does not want to put (new/updated) information to the data layer. For instance, create a simple int, float, bool to an arbitrary address in the data layer that does not already exist.

CodeShepherd
Community Moderator
Community Moderator

It is not possible to add nodes via REST interface anywhere you like. This functionality has to be provided by an app e.g. PLC, motion or customer apps. There it is possible to have node that supports creating subnodes like the "motion/axs". There you can post a string and subflows are generated by the app.

arjan_de_meijer
New Poster

@CodeShepherd, thanks for the quick response! Does this imply that the REST API's use case is mainly/only for reading the Data Layer information? I would assume a CRUD functionality of the REST API, but perhaps this is safer in terms of control!

 

CodeShepherd
Community Moderator
Community Moderator

The REST API itself provides this interface. But the function that will be executed when using https POST,PUT,GET (OnCreate, OnWrite, OnRead) and so on is implemented e.g. in C++ in the apps. The datalayer itself does not hold any data it is a broker. See FAQ for ctrlX Data Layer.

CodeShepherd
Community Moderator
Community Moderator

METADATA, PUT, POST commands and YARC favourite export added.

Sgilk
Contributor

Would it be possible to register a domain name and make an endpoint hosted on the core publically available on the internet?

CodeShepherd
Community Moderator
Community Moderator

@Sgilk This is a feature that has to be implemented in your router (or other device creating the internet connection) as the ctrlX CORE is only a network participant. Therefore a Dynamic DNS service could be used and the external requests must be routed to the control.

Must Read
Icon--AD-black-48x48Icon--address-consumer-data-black-48x48Icon--appointment-black-48x48Icon--back-left-black-48x48Icon--calendar-black-48x48Icon--center-alignedIcon--Checkbox-checkIcon--clock-black-48x48Icon--close-black-48x48Icon--compare-black-48x48Icon--confirmation-black-48x48Icon--dealer-details-black-48x48Icon--delete-black-48x48Icon--delivery-black-48x48Icon--down-black-48x48Icon--download-black-48x48Ic-OverlayAlertIcon--externallink-black-48x48Icon-Filledforward-right_adjustedIcon--grid-view-black-48x48IC_gd_Check-Circle170821_Icons_Community170823_Bosch_Icons170823_Bosch_Icons170821_Icons_CommunityIC-logout170821_Icons_Community170825_Bosch_Icons170821_Icons_CommunityIC-shopping-cart2170821_Icons_CommunityIC-upIC_UserIcon--imageIcon--info-i-black-48x48Icon--left-alignedIcon--Less-minimize-black-48x48Icon-FilledIcon--List-Check-grennIcon--List-Check-blackIcon--List-Cross-blackIcon--list-view-mobile-black-48x48Icon--list-view-black-48x48Icon--More-Maximize-black-48x48Icon--my-product-black-48x48Icon--newsletter-black-48x48Icon--payment-black-48x48Icon--print-black-48x48Icon--promotion-black-48x48Icon--registration-black-48x48Icon--Reset-black-48x48Icon--right-alignedshare-circle1Icon--share-black-48x48Icon--shopping-bag-black-48x48Icon-shopping-cartIcon--start-play-black-48x48Icon--store-locator-black-48x48Ic-OverlayAlertIcon--summary-black-48x48tumblrIcon-FilledvineIc-OverlayAlertwhishlist