(WIP) Enabling of Knowledge Layer

cdsp/information-layer/README.md

@@ -0,0 +1,44 @@
+This directory contains files related to the [Information Layer](https://en.wikipedia.org/wiki/DIKW_pyramid) of the Central Data Service Playground.
+
+# Information Layer Playground components
+   - [Database-Handlers](./handlers)
+   - [Database-Router](./router)
+
+# Setting up a CDSP Information Layer
+Setting up an information layer in the CDSP involves running a [Database-Router](./router), which is technically a configurable Websocket server that enables northbound connections for WebSocket clients, such as a [Knowledge Layer Connector](../knowledge-layer/README.md), to read, subscribe, and write data. The WebSocket server is connected to a database, which can be selected before starting the web server. Southbound feeders write data to the database in a predefined semantic format, such as [VSS](https://github.com/COVESA/vehicle_signal_specification).  
+
+## Installation of Database-Handler
+
+Please follow installation instructions of the chosen [handler](./handlers/).
+
+## [Installation of Database-Router](./router/README.md#Install)
+
+# Running "Hello World" example
+
+The Hello World example in our case is quite simple. We feed an updated value for the HVAC ambient air temperature into the database and we check afterwards in the logs if the DB-router creates a Websocket update message for it.
+
+## Choose and prepare your Database
+
+### Realm
+- Ensure that in your [ATLAS cloud](https://cloud.mongodb.com/) app there is a vehicle *document* with an `_id: 1234567` in a collection named *Vehicles*.
+- Ensure that this document as well contains VSS data. At the moment only 1 data point is supported, namely `Vehicle.Cabin.HVAC.AmbientAirTemperature`. Here you can see how the vehicle document within the *Vehicles* should look like in ATLAS:
+
+  ```
+  _id: 1234567 (Int64)
+  Vehicle_Cabin_HVAC_AmbientAirTemperature: 6 (Double)
+  ```
+
+### IoTDB
+- Not yet supported
+
+## [Start](./router/README.md#Run) the Database Router
+
+## Look out for the Websocket Server message in the console
+Now you can changed the value of `Vehicle_Cabin_HVAC_AmbientAirTemperature` in ATLAS cloud to let's say `23`. After changing you should immediately see this line in console:
+
+```
+the value of "Vehicle_Cabin_HVAC_AmbientAirTemperature" changed to 23
+```
+
+## Connect your own Websocket Client
+Connect your own websocket client by connecting to `ws://localhost:8080`

cdsp/information-layer/handlers/README.md

@@ -0,0 +1,4 @@
+# Handlers
+
+- [IotDB](./iotdb)
+- [RealmDB](./realmdb)

cdsp/information-layer/handlers/handler.js

@@ -0,0 +1,35 @@
+class Handler {
+    authenticateAndConnect(sendMessageToClients) {
+        throw new Error("Method 'authenticateAndConnect' must be implemented.");
+    }
+
+    handleMessage(message, ws) {
+        switch (message.type) {
+            case 'read':
+                this.read(message, ws);
+                break;
+            case 'write':
+                this.write(message, ws);
+                break;
+            case 'subscribe':
+                this.subscribe(message, ws);
+                break;
+            default:
+                ws.send(JSON.stringify({ error: 'Unknown message type'}))
+        }
+    }
+
+    read(message, ws) {
+        throw new Error('Read method not implemented, yet!')
+    }
+
+    write(message, ws) { 
+        throw new Error('Write method not implemented, yet!')
+    }
+
+    subscribe(message, ws) {
+        throw new Error('Subscribe method not implemented, yet!')        
+    }
+}
+
+module.exports = Handler;

cdsp/information-layer/handlers/iotdb/README.md

@@ -0,0 +1 @@
+tbd

cdsp/information-layer/handlers/iotdb/src/iotdb-handler.js

@@ -0,0 +1 @@
+// TODO: STUB implementation of subscribe, write and read interface methods.g

cdsp/information-layer/handlers/realmdb/.gitignore

@@ -0,0 +1,12 @@
+# MongoDB Realm
+mongodb-realm/
+
+# Node.js
+node_modules/
+package-lock.json
+
+# Credentials Config File
+config.js
+
+# MAC
+**/.DS_Store

cdsp/information-layer/handlers/realmdb/README.md

@@ -0,0 +1,41 @@
+This directory contains the RealmDB Handler as Node.js application. As [RealmDB](https://www.mongodb.com/docs/atlas/device-sdks/sdk/node/) is an embedded database, the RealmDB Handler directly embedds the RealmSDK which creates the [RealmDB database](https://github.com/realm/realm-js) file(s) automatically in the working directory during runtime of RealmDB Handler.
+
+# Installation
+
+Execute within `realmdb` directory
+
+```bash
+npm install
+```
+
+# Configure RealmDB
+
+Before the Database-Router can start the RealmDB Handler without any errors you need to configure the RealmSDK before.
+
+## Create a ATLAS Cloud instance
+
+To get APIKey and AppID you need to setup a [ATLAS cloud](https://cloud.mongodb.com/) instance and App Services. There is a free Tier solution (Status as of May 29, 2024) and you will find a lot of documentation in the internet how to set up everything.
+
+## Configure of a RealmDB Handler
+
+Create `config/config.js` with the following format, replacing the app id and the api key with yours.
+
+```js
+module.exports = {
+  realmAppId: "your-realm-AppId",
+  realmApiKey: "your-realm-ApiKey",
+};
+```
+
+> **_IMPORTANT:_** Do not commit this file to github!
+
+## Configure an example vehicle
+
+Change the VIN (Vehicle Identification Number) of the example vehicle in [vehicle-config](./config/vehicle-config.js).
+The default VIN is `1234567`.
+If you do not want to change it ensure, that in your ATLAS cloud instance there is a vehicle _document_ with an `_id: 1234567` in a collection named `Vehicles`.
+More infos how to run an example together with ATLAS cloud you can find [here](../readme.md#case-1-you-choosed-realm-as-database).
+
+## Starting the RealmDB handler
+
+You do not need to start RealmDB Handler manually. It is started by the DB-Router like described [here](../../router/README.md#Install).

cdsp/information-layer/handlers/realmdb/config/vehicle-config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  Vin: 1234567,
+};
+

cdsp/information-layer/handlers/realmdb/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "realmdb_handler",
+  "version": "1.0.0",
+  "description": "Realm database handler",
+  "main": "realmdb_handler.js",
+  "dependencies": {
+    "realm": "^12.9.0",
+    "uuid": "^9.0.1"
+  }
+}

cdsp/information-layer/handlers/realmdb/src/realmdb_handler.js

@@ -0,0 +1,132 @@
+const Realm = require("realm");
+const Handler = require('../../handler')
+const config = require("../config/config");
+//const vehicleConfig = require("../config/vehicle-config"); // Import vehicle config file
+const { v4: uuidv4 } = require("uuid"); // Importing UUID generator
+
+const MediaElementSchema = {
+  primaryKey: "_id",
+  name: "Vehicles",
+  properties: {
+    _id: "int",
+    Vehicle_Cabin_HVAC_AmbientAirTemperature: "double",
+  },
+};
+
+const app = new Realm.App({ id: config.realmAppId });
+const credentials = Realm.Credentials.apiKey(config.realmApiKey);
+
+const realmConfig = {
+  schema: [MediaElementSchema],
+  path: "myrealm12.realm",
+  sync: {
+    user: null, // will be assigned after authentication
+    flexible: true,
+    error: (error) => {
+      console.error("Realm sync error:", error);
+    },
+  },
+};
+
+class RealmDBHandler extends Handler {
+  constructor() {
+    super();
+    this.realm = null;
+    this.sendMessageToClients = null;
+  }
+
+  async authenticateAndConnect(sendMessageToClients) {
+    try {
+      this.sendMessageToClients = sendMessageToClients;
+      const user = await app.logIn(credentials);
+      console.log("Successfully authenticated with Realm");
+
+      realmConfig.sync.user = user;
+      this.realm = await Realm.open(realmConfig);
+      console.log("Realm connection established successfully");
+
+      const MediaElements = this.realm.objects("Vehicles").subscribe();
+      console.log(MediaElements); // TODO: Is it necessary to log this?
+    } catch (error) {
+      console.error("Failed to authenticate with Realm:", error);
+    }
+  }
+
+  async read(message, ws) {
+    try{
+      const objectId = message.data.Vin; // Retrieve objectId from config file
+      const mediaElement = this.realm.objectForPrimaryKey("Vehicles", objectId);
+      console.log(mediaElement);
+      if (mediaElement) {
+        const response = {
+          type: "read_response",
+          data: mediaElement,
+        };
+        ws.send(JSON.stringify(response));
+      } else {
+        ws.send(JSON.stringify({ error: 'Object not found' }));
+      }
+    } catch (error) {
+      console.error("Error reading object from Realm:", error);
+      ws.send(JSON.stringify({ error: 'Error reading object' }));
+    }
+  }
+
+  async write(message, ws) {
+    // Implement write logic for RealmDB
+  }
+
+  async subscribe(message, ws) {
+    const sendMessageToClient = (message) => {
+      ws.send(JSON.stringify(message));
+    };
+
+    try {
+      const objectId = message.data.Vin;
+      console.log(`Subscribing element: ${objectId}`)
+      const mediaElement = await this.realm.objectForPrimaryKey("Vehicles", objectId);
+      console.log(mediaElement);
+
+      if (mediaElement) {
+        const websocketId = String(objectId);
+        mediaElement.addListener((mediaElement, changes) =>
+          this.onMediaElementChange(mediaElement, changes, websocketId)
+        );
+        sendMessageToClient({ success: `Subscribed to changes for object ID ${objectId}` })
+      } else {
+        sendMessageToClient({ error: "Vehicles collection not found for subscription"});
+      }
+    } catch (error) {
+      console.error("Error subscribing to object changes in Realm:", error);
+      sendMessageToClient({ error: 'Error subscribing to object changes' });
+    }
+  }
+
+  onMediaElementChange(mediaElement, changes, websocketId) {
+    if (changes.deleted) {
+      console.log(`MediaElement is deleted: ${changes.deleted}`);
+    } else {
+      changes.changedProperties.forEach((prop) => {
+        console.log(`* the value of "${prop}" changed to ${mediaElement[prop]}`);
+
+        // Generate a meaningful UUID for WebSocket response
+        const uuid = uuidv4();
+
+        const message = {
+          type: "update",
+          tree: "VSS",
+          id: websocketId, // Use the WebSocket server ID
+          uuid: uuid, // Use generated UUID
+          dateTime: new Date().toISOString(),
+          node: {
+            name: prop, // Sending the property name as node name
+          value: mediaElement[prop], // Sending the property value as node value
+          },
+        };
+        this.sendMessageToClients(message);
+      });
+    }
+  }
+}
+
+module.exports = RealmDBHandler;

cdsp/information-layer/router/.gitignore

@@ -0,0 +1,10 @@
+# MongoDB Realm
+mongodb-realm/
+
+# Node.js
+node_modules/
+package-lock.json
+.env
+
+# MAC
+**/.DS_Store

cdsp/information-layer/router/README.md

@@ -0,0 +1,20 @@
+With this component one can configure which database it shall connect to.
+
+> [!WARNING]
+> As the configuration capability is not yet implemented, RealmDB is hard coded as a database!
+
+# Install
+
+Execute in this directory:
+
+```bash
+npm install
+```
+
+# Run
+
+Start router by executing in [src](./src/) directory the command:
+
+```bash
+node websocket-server.js
+```

cdsp/information-layer/router/config/config.js

@@ -0,0 +1,14 @@
+const dotenv = require('dotenv');
+dotenv.config();
+
+const getHandlerType = () => {
+  const handlerType = process.env.HANDLER_TYPE;
+  if (!handlerType) {
+    throw new Error('Handler type must be specified as an ENV variable.');
+  }
+  return handlerType.toLowerCase();
+};
+
+module.exports = {
+  getHandlerType,
+};

cdsp/information-layer/router/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "websocket-server",
+  "version": "1.0.0",
+  "description": "WebSocket server",
+  "main": "websocket-server.js",
+  "scripts": {
+    "start": "node websocket-server.js"
+  },
+  "dependencies": {
+    "ws": "^7.4.6"
+  }
+}