How to provide API in the Data Layer for your app

Introduction

This how to blog shows how easy it is to provide a API with a custom app on ctrlX OS. Just provide a interface in the ctrlX Data Layer and it is accessible by multiple ways. The ctrlX Data Layer has a built in REST API, therefore by providing your interface in the Data Layer, it is already accessible via REST. In addition, by just installing the OPC UA Server App it will also be available in OPC UA. And of course the interface in the Data Layer is accessible by all the other Apps running on the same device by Data Layer Access (for example from Node Red App or PLC App).

There are many samples (in different programming languages) in the ctrlX AUTOMATION SDK, which show how to provide data in the ctrlX Data Layer. This how to uses the C++ sample "datalayer.register-node" from the SDK to start, but modified it a little. In addition to just providing variables to the ctrlX Data Layer it is also possible to provide methods (or programs). This is defined in the metadata of the Data Layer Node. Its also possible to use scopes in the ctrlX Data Layer to restrict the access to the nodes provided for specific users.

The small example, which you can find attached provides one method in the ctrlX Data Layer (path: sample-cpp-registermethod/sqrt) which in case a client performs a write, calculates the square root. It also adds a scope to the ctrlX Data Layer, which can be used to restrict the access on this method for users.

Find more information

Prerequisites

Find the attached sample code at the end of this article.
Build it using the V1.20 SDK and App Build Environment and place it besides the other C++ samples at ctrlx-automation-sdk/samples-cpp. (see how to build a snap of the SDK)
To test the it install the snap on a ctrlX CORE (virtual) V1.20

See the output in the web interface

Try out the sqrt method in the Data Layer

Data Layer path: samples-cpp-registermethod-sqrt — Data Layer path: samples-cpp-registermethod/sqrt

Try out the same method via the REST Api

using the sqrt method via REST Api (in Swagger UI)

Some introduction to the code

1. Metadata in the metadata.csv

address;nodeClass;operations.read;operations.write;operations.create;operations.remove;operations.browse;description;descriptionURL;displayName;displayFormat;unit;references.readType;references.writeType;references.createType;comment
sample-cpp-registermethod/sqrt;Method;false;true;false;false;false;"gives back the square root of a float ";;;;;;types/datalayer/float32;;

2. onWrite() in the main.cpp (lines 83 - 96):

// Write function of a node. Function will be called whenever a node should be written.
  virtual void onWrite(const std::string &address, const comm::datalayer::Variant *data, const comm::datalayer::IProviderNode::ResponseCallback &callback) override
  {
      //method sqrt was called. now calculating the sqrt
      comm::datalayer::Variant resultVariant;
      if(data->getType() != comm::datalayer::VariantType::FLOAT32){
        callback(comm::datalayer::DlResult::DL_TYPE_MISMATCH, nullptr);
      }
      if(double(*data) <= 0){
        callback(comm::datalayer::DlResult::DL_TYPE_MISMATCH, nullptr);
      }
      double sqrtResult = sqrt(double(*data));
      resultVariant.setValue(sqrtResult);
      callback(comm::datalayer::DlResult::DL_OK, &resultVariant);
  }

3. creating of ctrlX Data Layer scope with client in main.cpp (lines 147 - 161)

comm::datalayer::Variant scopeVariant;
flatbuffers::FlatBufferBuilder builder;
auto str = builder.CreateString("sample-cpp-registermethod/**");
std::vector<flatbuffers::Offset<flatbuffers::String>> permissionR = {str};
auto scope = comm::datalayer::CreateScopeDirect(builder, 
                                            "datalayer.sqrt",
                                            "Use sqrt method", 
                                            "Allows you to use the sqrt method provided by register.datalayer.method",
                                            nullptr,
                                            nullptr,
                                            nullptr,
                                            &permissionR);
builder.Finish(scope);
scopeVariant.shareFlatbuffers(builder);
result = client->createSync("datalayer/security/scopes", &scopeVariant);