Project Ibeji

• Introduction
• High-level Design
• Prerequisites
  • Install gcc
  • Install Rust
  • Install Protobuf Compiler
• Cloning the Repo
• Developer Notes
  • JSON-LD Crate
  • DTDL Parser
• Building
• Running the Tests
• Running the Demo
• Trademarks

Introduction

Eclipse Ibeji aims to provide the capability to express a digital representation of the vehicle state and its capabilities through an extensible, open and dynamic architecture that provides access to the vehicle hardware, sensors and capabilities.

High-level Design

Ibeji's architecture has an In-Vehicle Digital Twin Service at its core. The In-Vehicle Digital Twin Service captures all of the vehicle's primary capabilities and makes them available to Ibeji consumers. Another component in Ibeji's architecture is the Provider. A vehicle may have one or more providers. A provider exposes a subset of the vehicle's primary capabilities by registering them with the In-Vehicle Digital Twin Service. Once registered with the In-Vehicle Digital Twin Service they can in turn be offered to Ibeji consumers. Each capability includes meta data that allow Ibeji consumers to comprehend the nature of the capability, how to work with it and how it can be remotely accessed.

Prerequisites

Install gcc

Rust needs gcc's linker, so you will need to install it. To install gcc, do the following:

sudo apt install gcc

Install Rust

At this point in time, you will need to use the nightly release of Rust. While it is not ideal to rely on a nightly release, we should be able to rely on the stable release of Rust sometime in the not too distant future when some of the Rust crates that we use can all rely on it as well. To install Rust, do the following:

sudo apt update
sudo apt install -y snapd
sudo snap install rustup --classic
rustup toolchain install nightly
rustup default nightly

If you have already installed Rust, but you are using another release, then you can switch to the nightly release by running the following commands:

rustup toolchain install nightly
rustup default nightly

Install Protobuf Compiler

You will need to install the Protobuf Compiler. This can be done by executing:

sudo apt install -y protobuf-compiler

Cloning the Repo

The repo has two submodules opendigitaltwins-dtdl and iot-plugandplay-models that provide DTDL context files and DTDL samples file. To ensure that these are included, please use the following command when cloning Ibeji's github repo:

git clone --recurse-submodules https://github.com/eclipse-ibeji/ibeji

Developer Notes

JSON-LD Crate

Ideally, we should be using the json_ld 0.6.1 crate, which takes its source from here. However, it currently has a build issue that is discussed here. To work around this issue you will need to use git clone to obtain the source from here and checkout its "resolve-issue-40" branch. It should be cloned to a directory that is a sibling to ibeji.

DTDL Parser

There is no existing DTDL Parser for Rust, so we have provided a minimalistic one for DTDL v2 that is based on the JavaScript DTDL Parser.

Building

Once you have installed the prerequisites, go to your enlistment's root directory and run:

cargo build

This should build all of the libraries and executables.

Running the Tests

After successfully building Ibeji, you can run all of the unit tests. To do this go to the enlistment's root directory and run:

cargo test

Currently, we have no integration tests or end-to-end tests.

Running the Demo

There are currently two demos: one that demonstrates the use of a property and one that demonstrates the use of a command.

The following instructions are for the demo for the use of a property.

Steps:

1. The best way to run the demo is by using three windows: one running the In-Vehicle Digital Twin, one running the Provider and one running a Consumer. Orientate the three windows so that they are lined up in a column. The top window can be used for the In-Vehicle Digital Twin. The middle window can be used for the Provider. The bottom window can be used for a Consumer.
   
2. In each window run the following command too set the DTDL_PATH environment variable. Make sure that you replace "{repo-root-dir}" with the repository root directory on the machine where you are running the demo.
   
   export DTDL_PATH="{repo-root-dir}/ibeji/opendigitaltwins-dtdl/DTDL;{repo-root-dir}/ibeji/dtdl;{repo-root-dir}/ibeji/samples/property/dtdl"
   
3. In each window change directory to the directory containing the build artifacts. Make sure that you replace "{repo-root-dir}" with the repository root directory on the machine where you are running the demo.
   
   cd {repo-root-dir}/ibeji/target/debug
   
4. In the top window, run:
   
   ./in-vehicle-digital-twin
   
5. In the middle window, run:
   
   ./property-provider
   
6. In the bottom window, run:
   
   ./property-consumer
   
7. Use control-c in each of the windows when you wish to stop the demo.

The following instructions are for the demo for the use of a command.

Steps:

1. The best way to run the demo is by using three windows: one running the In-Vehicle Digital Twin, one running the Provider and one running a Consumer. Orientate the three windows so that they are lined up in a column. The top window can be used for the In-Vehicle Digital Twin. The middle window can be used for the Provider. The bottom window can be used for a Consumer.
   
2. In each window run the following command too set the DTDL_PATH environment variable. Make sure that you replace "{repo-root-dir}" with the repository root directory on the machine where you are running the demo.
   
   export DTDL_PATH="{repo-root-dir}/ibeji/opendigitaltwins-dtdl/DTDL;{repo-root-dir}/ibeji/dtdl;{repo-root-dir}/ibeji/samples/command/dtdl"
   
3. In each window change directory to the directory containing the build artifacts. Make sure that you replace "{repo-root-dir}" with the repository root directory on the machine where you are running the demo.
   
   cd {repo-root-dir}/ibeji/target/debug
   
4. In the top window, run:
   
   ./in-vehicle-digital-twin
   
5. In the middle window, run:
   
   ./command-provider
   
6. In the bottom window, run:
   
   ./command-consumer
   
7. Use control-c in each of the windows when you wish to stop the demo.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.