Project Eclipse Ibeji

• Introduction
• High-level Design
• Prerequisites
  • Install gcc
  • Install Rust
  • Install Protobuf Compiler
  • Install SDL2 library
  • Install dotnet-sdk library
  • Install MQTT Broker
• Cloning the Repo
• Building
  • Tokio Console Support
• Running the Tests
• Running the Samples
  • Property Sample
  • Command Sample
  • Mixed Sample
  • Seat Massager Sample
  • Streaming Sample
  • Using Chariott
• Running in a Container
• 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 hardware 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 hardware 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 metadata that allows Ibeji consumers to comprehend the nature of the capability, how to work with it and how it can be remotely accessed.

Prerequisites

We recommend the use of Ubuntu 22.04 for running the In-Vehicle Digital Twin Service. Other operating systems or versions of Ubuntu may encounter issues. We invite others to help us find and resolve any compatibility issues.

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 a 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

The toolchain version is managed by the rust-toolchain.toml file. If you do not have the correct toolchain installed on your system, it will automatically be installed when needed (for example, when running cargo build), so there is no need to install it manually.

Install Protobuf Compiler

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

sudo apt install -y protobuf-compiler

Install SDL2 library

You will need to install the libsdl2-dev library. This is used by the streaming sample to view images. Install the libsdl2-dev library by executing:

sudo apt install -y libsdl2-dev

Install dotnet-sdk library

You will need to install dotnet-sdk for the dtdl-tools crate. This can be done by executing:

sudo apt install -y dotnet-sdk-8.0

Install MQTT Broker

If you plan to run any of the samples that use MQTT, then you will need to install a MQTT Broker, like Mosquitto. Instructions for installing Mosquitto can be found here.

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

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.

Tokio Console Support

Ibeji has support for using the tokio console for advanced debugging. To enable this support, you need to build with the tokio_console feature enabled and with the tokio_unstable config flag for the rust compiler:

RUSTFLAGS="--cfg tokio_unstable" cargo build --features tokio_console

Read the tokio console documentation to learn how to install tokio console and how to run it.

Note that the tokio console will intercept trace-level logs, so these will not be visible when debugging with the tokio console.

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 Samples

There are currently four samples: one that demonstrates the use of a property, one that demonstrates the use of a command, one that demonstrates the mixed use of properties and commands and one that demonstrates the use of get/set for a seat massager.

The demos use config files and we have provided a templated version of each config file. These templates can be found in:

• {repo-root-dir}/core/invehicle-digital-twin/template
• {repo-root-dir}/samples/common/template

Configuration files will be loaded from the current working directory by default but an IBEJI_HOME environment variable can be used to change the base configuration directory to a different one:

IBEJI_HOME=/etc/ibeji ./invehicle-digital-twin

The above example tells invehicle-digital-twin to load configuration files from /etc/ibeji instead of using the current working directory.

Chariott may be used to discover the in-vehicle digital twin service. We will discuss how to enable this feature.

Property Sample

The following instructions are for the demo for the use of a property. This sample uses a MQTT Broker; please make sure that it is running.

Steps:

1. The best way to run the demo is by using three windows: one running the In-Vehicle Digital Twin, one running the Digital Twin Provider and one running the Digital Twin 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 Digital Twin Provider. The bottom window can be used for the Digital Twin Consumer.
   
2. 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}/target/debug
   
3. Create the three config files with the following contents, if they are not already there:
   
   ---- consumer_settings.yaml ----
   invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   ---- invehicle_digital_twin_settings.yaml ----
   invehicle_digital_twin_authority: "0.0.0.0:5010"
   
   ---- provider_settings.yaml ----
   provider_authority: "0.0.0.0:1883"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   
4. In the top window, run:
   
   ./invehicle-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.

Command Sample

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 Digital Twin Provider and one running the Digital Twin 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 Digital Twin Provider. The bottom window can be used for the Digital Twin Consumer.
   
2. 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}/target/debug
   
3. Create the three config files with the following contents, if they are not already there:
   
   ---- consumer_settings.yaml ----
   consumer_authority: "0.0.0.0:6010"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   ---- invehicle_digital_twin_settings.yaml ----
   invehicle_digital_twin_authority: "0.0.0.0:5010"
   
   ---- provider_settings.yaml ----
   provider_authority: "0.0.0.0:4010"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   
4. In the top window, run:
   
   ./invehicle-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.

Mixed Sample

The following instructions are for the demo for the mixed use of commands and properties.

Steps:

1. The best way to run the demo is by using three windows: one running the In-Vehicle Digital Twin, one running the Digital Twin Provider and one running the Digital Twin 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 Digital Twin Provider. The bottom window can be used for the Digital Twin Consumer.
   
2. 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}/target/debug
   
3. Create the three config files with the following contents, if they are not already there:
   
   ---- consumer_settings.yaml ----
   consumer_authority: "0.0.0.0:6010"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   ---- invehicle_digital_twin_settings.yaml ----
   invehicle_digital_twin_authority: "0.0.0.0:5010"
   
   ---- provider_settings.yaml ----
   provider_authority: "0.0.0.0:4010"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   
4. In the top window, run:
   
   ./invehicle-digital-twin
   
5. In the middle window, run:
   
   ./mixed-provider
   
6. In the bottom window, run:
   
   ./mixed-consumer
   
7. Use control-c in each of the windows when you wish to stop the demo.

Seat Massager Sample

The following instructions are for the demo for a seat massager.

Steps:

1. The best way to run the demo is by using three windows: one running the In-Vehicle Digital Twin, one running the Digital Twin Provider and one running the Digital Twin 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 Digital Twin Provider. The bottom window can be used for the Digital Twin Consumer.
   
2. 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}/target/debug
   
3. Create the three config files with the following contents, if they are not already there:
   
   ---- consumer_settings.yaml ----
   consumer_authority: "0.0.0.0:6010"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   ---- invehicle_digital_twin_settings.yaml ----
   invehicle_digital_twin_authority: "0.0.0.0:5010"
   
   ---- provider_settings.yaml ----
   provider_authority: "0.0.0.0:4010"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"
   
   
4. In the top window, run:
   
   ./invehicle-digital-twin
   
5. In the middle window, run:
   
   ./seat-massager-provider
   
6. In the bottom window, run:
   
   ./seat-massager-consumer
   
7. Use control-c in each of the windows when you wish to stop the demo.

Streaming Sample

The following instructions are for the demo for streaming.

Steps:

1. The best way to run the demo is by using three windows: one running the In-Vehicle Digital Twin, one running the Digital Twin Provider and one running the Digital Twin 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 Digital Twin Provider. The bottom window can be used for the Digital Twin Consumer.
   
2. 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}/target/debug
   
3. Create the three config files with the following contents, if they are not already there:
   
   ---- streaming_consumer_settings.yaml ----
   invehicle_digital_twin_uri: "http://0.0.0.0:5010"

number_of_images: 20
   
   ---- invehicle_digital_twin_settings.yaml ----
   invehicle_digital_twin_authority: "0.0.0.0:5010"
   
   ---- streaming_provider_settings.yaml ----
   provider_authority: "0.0.0.0:4010"
invehicle_digital_twin_uri: "http://0.0.0.0:5010"

image_directory: "<<chariott-repo-root>>/examples/applications/simulated-camera/images"
4. In the top window, run:
   
   ./invehicle-digital-twin
   
5. In the middle window, run:
   
   ./streaming-provider
   
6. In the bottom window, run:
   
   ./streaming-consumer
   
7. Use control-c in each of the windows when you wish to stop the demo.

Using Chariott

If you want the digital twin consumers and digital twin providers for each demo to use Chariott to discover the URI for the In-Vehicle Digital Twin Service, rather than having it statically provided in their respective config file, then do the following before starting each demo:

1. Clone a copy of Chariott from GitHub (https://github.com/eclipse-chariott/chariott).
2. Build Chariott
3. Run Chariott:
   
   cargo run -p service_discovery
   
4. In each of the the config files, add the setting:
   
   chariott_uri: "http://0.0.0.0:50000"
   
5. In the consumer's config file and the provider's config file, remove the setting for invehicle_digital_twin_uri, so that the chariott_uri will be used to find the In-vehicle Digital Twin URI.
   

Running in a Container

Please refer to Ibeji Containers for information on how build and run the In-Vehicle Digital Twin Service or the Sample Applications in a container.

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.