Custom data structures in Key Value Database (KVD) app

CodeShepherd · ‎06-05-2024

Content

This article shows how to generate and register custom data structures via a flatbuffer schema file (FBS) for the ctrlX OS - Key Value Database (KVD) app.

Requirements

flatc (part of SDK for ctrlX AUTOMATION)
ctrlX CORE or ctrlX OS
ctrlX OS - Key Value Database app

Create flatbuffer schema file

Any text editor or development tool can be used to create an flatbuffer schema file (.fbs). See an example in the datalayer.provider.alldata example in the SDK for ctrlX AUTOMATION.

Compile flatbuffer schema file

Compile your flatbuffers schema file (.fbs) to a binary flatbuffers file (.bfbs) using the flatc compiler.

Download the flatc compiler directly from GitHub or download the latest release of the ctrlX Automation SDK. Inside the SDK the flatc compiler can be found here:
1. WINDOWS
  .\bin\oss.flatbuffers\win-msvc-x64\release\flatc.exe
2. LINUX
  ./bin/oss.flatbuffers/ubuntu22-gcc-x64/release/flatc
Add flatbuffers schema file (.fbs) to the folder including flatc
Compile your flatbuffers schema file (*.fbs):

Example:

flatc --schema --binary --bfbs-comments --bfbs-builtins --no-warnings -o . sampleSchema.fbs

This generates a binary flatbuffers file sampleSchema.bfbs in the current working directory.

Hint: This process can be automated, that user gets some feedback what is missing. See create_fbs_for_kvd.txt attached. Simply rename file to .bat or copy and past the text in to a executable file.

Register your flatbuffers

To register your own flatbuffers type upload your generated file and adapt the KVD configuration file nodes.json.

Upload the generate *.bfbs file to app data (active configuration) directory kvd/bfbs.
ctrlX OS - Web UI - KVD app data - bfbs
Configure a node of nodeClass Type and add it to the types section in the file kvd/nodes.json in app data (active configuration)
- Set the type to the name of the generated binary flatbuffers file (*.bfbs).
- Set the address of the type to the address on which instance nodes should refer to it
  Example:
  types/inertial-value
- Each change will be effective immediately. Wrong settings will lead to the unavailability of the whole kvd node in the data layer

Example: Custom flatbuffers

Type node of a custom flatbuffers type:

types: [
    {
        "address": "types/inertial-value",
        "type": "inertial-value.bfbs",
        "metadata": {
            "nodeClass": "Type"  
        }
    },
    ...
]

A variable node this type can be specified (value optional):

nodes: [
    {
        "address": "kvd/samples/variables/flatbuffers/inertial-value",
        "type": "types/inertial-value",
        "value": {
            "x": 1,
            "y": 2,
            "z": 3
        },
        "metadata": {
            "nodeClass": "Variable",
            "description": "This node is of the custom flatbuffers type 'types/inertial-value."
        }
    },
    ...
]

Custom data structures in Key Value Database (KVD) app