Skip to content

Latest commit

 

History

History
181 lines (112 loc) · 15.6 KB

README.md

File metadata and controls

181 lines (112 loc) · 15.6 KB
Raw

Tutorial: Create a Digital Twin Provider

Introduction

Digital Twin Provider: 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.

In this tutorial, you will leverage the code for your in-vehicle digital twin model that you have developed in Tutorial: Create an In-Vehicle Digital Twin Model with DTDL to create a digital twin provider. Additionally, you will learn how to register your digital twin provider with the In-Vehicle Digital Twin Service.

This tutorial references the code in the {repo-root-dir}/samples/tutorial directory. Relevant code snippets are explicitly highlighted and discussed to ensure a clear understanding of the concepts.

Prerequisites

1. Create an Ibeji Digital Twin Provider

In this section, you will learn how to develop a digital twin provider that communicates with its digital twin consumers via gRPC. It is important to note that digital twin providers in Ibeji are protocol-agnostic. This means they are not limited to gRPC, they can use other communication protocols.

The {repo-root-dir}/samples/tutorial directory contains code for the sample digital twin provider used in this tutorial. The {repo-root-dir}/digital-twin-model/src directory contains the in-vehicle digital twin model in Rust code that you have constructed in Tutorial: Create an In-Vehicle Digital Twin Model with DTDL along with additional signals that are not needed for this tutorial.

Throughout this tutorial, the sample contents in the {repo-root-dir}/samples/tutorial directory are referenced to guide you through the process of creating a digital twin provider.

1.1 Define Digital Twin Provider Interface

A digital twin provider needs an interface. The interface will expose operations that allow digital twin consumers to access the in-vehicle signals that your digital provider makes available.

Tip: A suggested approach for defining your digital twin provider is to adopt the perspective of a digital twin consumer. This requires consideration of the operations and their corresponding names for interacting with each in-vehicle signal and command. For example, for the digital twin provider sample interface, the specified operations are Get and Invoke.

The digital twin provider tutorial interface serves as an example of what a digital twin provider's interface could look like. Feel free to replicate these operation names, modify them, or even add new ones as per your requirements. These operations are non-prescriptive. It is up to the developers of the in-vehicle digital twin to come up with their own convention for the operations.

Sample Digital Twin Provider Interface

This section provides an example of a digital twin provider interface. To reiterate, you are free to use this interface as a starting point or you may come up with your own convention.

  1. Consider the in-vehicle signals ambient air temperature and is air conditioning active, as well as the command show notification that you defined in the Tutorial: Create an In-Vehicle Digital Twin Model with DTDL.

  2. Refer to the sample digital twin provider tutorial interface:

In this digital twin provider sample interface, the conventions that this interface enforces are as follows:

  • A digital twin consumer should utilize the Get operation to synchronously consume the ambient air temperature and the is air conditioning active in-vehicle signals.

  • A digital twin consumer should utilize the Invoke operation to send a show notification command.

When introducing additional capabilities, it is crucial to carefully select the operation(s) that best align with the behavior of each capability. This ensures a seamless integration and optimal performance of your system.

1.2 Implement the Operations of a Digital Twin Provider Interface

You have defined your digital twin provider interface.

The following lists out the flow for implementing the operations of a digital twin interface in the programming language of your choice:

  1. Choose a programming language that supports gRPC. gRPC is required to communicate with the In-Vehicle Digital Twin Service. This will be described further in 2. Register Digital Twin Provider with the In-Vehicle Digital Twin Service. This includes languages like Rust, Python, Java, C++ and Go.

    Note: Operations can be performed by various protocols. Some protocols require that the operation's interface contract is specified. For example in gRPC, the operation must be specified in a protobuf file. Operations are programming language and protocol agnostic. If you have a subscribe operation, you may want to use MQTT for publishing to digital twin consumers that have subscribed to your digital twin provider. Please see the Managed Subscribe Sample and Property Sample for Rust examples of a digital twin provider using MQTT.

  2. In your implementation, import the code for your in-vehicle digital twin model that you have developed in the Tutorial: Create an In-Vehicle Digital Twin Model with DTDL.

  3. Implement the operations that you have defined in your interface. This involves writing the logic for what should happen to each in-vehicle capability when each operation is called. If you are using the sample digital twin provider interface, you need to implement the functionality for the Get and Invoke operations.

  4. For each operation you implement, you can refer to an in-vehicle capability using the code for your in-vehicle digital twin model.

In order to translate your operations into code, it is important to understand the requirements of each operation.

Rust Sample Implementation of the Sample Interface

This section uses the sample digital twin provider interface that is defined in a protobuf file, and covers a sample Rust implementation of the synchronous Get and Invoke operations.

  1. Refer to the code for implementing the operations for the sample digital twin provider interface.

  2. There is an import statement for the Rust in-vehicle digital twin model that you have previously constructed in the Tutorial: Create an In-Vehicle Digital Twin Model with DTDL:

    use digital_twin_model::sdv_v1 as sdv;

  3. The implementation of the Get operation references the signals is air conditioning active and ambient air temperature:

    /// Get operation.
///
/// # Arguments
/// * `request` - Get request.
async fn get(&self, request: Request<GetRequest>) -> Result<Response<GetResponse>, Status> {..}

  4. The implementation of the Invoke operation references the command show notification.

    /// Invoke operation.
///
/// # Arguments
/// * `request` - Invoke request.
async fn invoke(
    &self,
    request: Request<InvokeRequest>,
) -> Result<Response<InvokeResponse>, Status> {..}

2. Register Digital Twin Provider with the In-Vehicle Digital Twin Service

You have defined your digital twin provider interface, and you have implemented the functionality of each operation in the programming language of your choice.

You will need to register your digital twin provider with the In-Vehicle Digital Twin Service. This registration will make your digital twin provider discoverable by digital twin consumers through the In-Vehicle Digital Twin Service.

In-Vehicle Digital Twin Service: 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.

The following lists out the flow for registering a digital twin provider in the programming language of your choice:

  1. Refer to the interface of the In-Vehicle Digital Twin Service which is defined as a protobuf file.

  2. In the code for your digital twin provider, you will need to import an In-Vehicle Digital Twin Service gRPC client.

  3. Using the In-Vehicle Digital Twin Service gRPC client, you will need to define how to register your in-vehicle capabilities with the In-Vehicle Digital Twin Service. This involves calling the Register gRPC method with the gRPC client. Please see the sequence diagram for Register for more details.

  4. For each in-vehicle capability you register, you can refer to the in-vehicle capability with the code for your in-vehicle digital twin model.

2.1 Rust Sample Registration of a Digital Twin Provider

This section uses the sample digital twin provider interface, and covers a sample Rust implementation of a provider registering the signals ambient air temperature and is air conditioning active and the command show notification

  1. Refer to the main.rs file of the sample digital twin provider.

  2. One function of particular interest in the main.rs file is the register_entities function.

    /// Register the entities endpoints.
///
/// # Arguments
/// * `invehicle_digital_twin_uri` - The In-Vehicle Digital Twin URI.
/// * `provider_uri` - The provider's URI.
async fn register_entities(
    invehicle_digital_twin_uri: &str,
    provider_uri: &str,
) -> Result<(), Status> { .. }

The register_entities function in this Rust sample digital twin provider shows the process of registering with the In-Vehicle Digital Twin Service.

3. Add Managed Subscribe to Digital Twin Provider

Managed Subscribe: The managed subscribe sample shows how Ibeji can extend its functionality with modules to give providers and consumers more capabilities. This sample utilizes the 'Managed Subscribe' module to allow a consumer to get an MQTT subscription for the AmbientAirTemperature value of a vehicle at a specific frequency in milliseconds. The provider, signaled with the help of the module, will publish the temperature value at the requested frequency for each consumer on its own topic and once the consumer unsubscribes and disconnects it will stop publishing to that dynamically generated topic.

The current implementation of the Managed Subscribe Module expects to utilize the Agemo Service. This service currently requires the use of an MQTT broker for communication between publishers and subscribers.

Adding the Managed Subscribe module for your digital twin provider is optional. However, here are some reasons why you might want to consider using the Managed Subscribe module for your digital twin provider:

  • Efficient Data Management: Allows your digital twin provider to efficiently manage the data being sent to its digital twin consumers. Your digital twin provider only needs to publish data when there is a change, so it reduces unnecessary data transmission.

  • Customized Frequency: Digital twin consumers can specify the frequency at which they want to receive updates. This allows for more tailored data delivery and can improve a digital twin consumer's experience.

  • Automated Topic Cleanup: The feature automatically stops publishing to a topic once all the digital twin consumers have unsubscribed. This helps in resource optimization and ensures that data is not being sent to inactive digital twin consumers.

  • Scalability: Managed Subscribe can handle a large number of digital twin consumers, making it a good choice for your digital twin provider that is expected to have many digital twin consumers subscribed to it.

  • Enhanced Capabilities: The Managed Subscribe module extends the functionality of a digital twin provider.

If you decide to incorporate the Managed Subscribe module into your digital twin provider, please consult the Managed Subscribe interface, and the documentation for the Managed Subscribe sample for guidance. You will need to implement the proto methods that are defined in the Managed Subscribe interface. Since the interface is defined in a protobuf file, the Managed Subscribe module is program language agnostic.

3.1 Rust Sample Implementation of a Managed Subscribe Digital Twin Provider

Please refer to the sample Rust code for the Managed Subscribe Sample Provider to see an example of how to integrate the Managed Subscribe module into a digital twin provider. This sample Rust code contains an ambient air temperature signal, and does not include the in-vehicle signal is air conditioning active and the command show notification.

Next Steps