diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..73db316 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,8 @@ +root = true + +[*] +charset = utf-8 +indent_style = space +indent_size = 2 +insert_final_newline = true +trim_trailing_whitespace = true diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..5ace460 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..4c3a4c1 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,20 @@ +name: Lint +on: + push: + branches: + - main + pull_request: +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Set up Git repository + uses: actions/checkout@v4 + with: + show-progress: '' + - name: markdownlint-cli2-action + uses: DavidAnson/markdownlint-cli2-action@v9 + with: + globs: | + **/*.md + #node_modules diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..899d937 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,3 @@ +default: true + +MD013: false diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..ea57ae4 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "DavidAnson.vscode-markdownlint", + "editorconfig.editorconfig" + ] +} diff --git a/README.md b/README.md index a80b0bb..a550e52 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,23 @@ - # Maestro Challenge 🚗💻🎶 + - [About](#about) - [Sample Scenarios](#sample-scenarios) - - [Provided Sample Scenario](#provided-sample-scenario) - - [Other Sample Scenarios](#other-sample-scenarios) + - [Provided Sample Scenario](#provided-sample-scenario) + - [Other Sample Scenarios](#other-sample-scenarios) - [Useful References for Creating and Enhancing Sample Scenarios](#useful-references-for-creating-and-enhancing-sample-scenarios) - - [In-Vehicle Stack](#in-vehicle-stack) - - [General](#general) - - [Eclipse Ankaios](#eclipse-ankaios) + - [In-Vehicle Stack](#in-vehicle-stack) + - [General](#general) + - [Eclipse Ankaios](#eclipse-ankaios) - [Getting Started](#getting-started) - - [Need to know](#need-to-know) - - [Prebuilt Container Images](#prebuilt-container-images) - - [Eclipse Ankaios Orchestrator](#eclipse-ankaios-orchestrator) - - [Eclipse BlueChi Orchestrator](#eclipse-bluechi-orchestrator) - - [Azure Subscription](#azure-subscription) + - [Need to know](#need-to-know) + - [Prebuilt Container Images](#prebuilt-container-images) + - [Eclipse Ankaios Orchestrator](#eclipse-ankaios-orchestrator) + - [Eclipse BlueChi Orchestrator](#eclipse-bluechi-orchestrator) + - [Azure Subscription](#azure-subscription) - [In-Vehicle Software Stack Overview](#in-vehicle-software-stack-overview) - [Projects Involved](#projects-involved) - - [In-Vehicle Software Stack](#in-vehicle-software-stack) - - [In-Vehicle Software Orchestrators](#in-vehicle-software-orchestrators) + - [In-Vehicle Software Stack](#in-vehicle-software-stack) + - [In-Vehicle Software Orchestrators](#in-vehicle-software-orchestrators) - [Hack Coaches](#hack-coaches) **Do you want to be the next maestro of the next generation of vehicle software? The time is now!** @@ -27,7 +27,7 @@ Imagine yourself as the **maestro**. You are not just writing code. You are comp **Come hack with us!** ![Maestro](docs/diagrams/orchestra_picture.jpg) ->Photo by Manuel Nägeli. +>Photo by [Manuel Nägeli](https://unsplash.com/@gwundrig?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash). ## About @@ -44,6 +44,7 @@ Here is a list of potential scenarios your team could develop. Feel free to inve ### Provided Sample Scenario #### Smart Trailer Scenario Overview + The system detects that a smart trailer is being connected to the vehicle. A signal is raised to the orchestrator to start up the necessary providers and applications to manage the smart trailer. These include a Digital Twin Provider, which exposes signals from the trailer to higher-level applications, and a Smart Trailer application, which consumes these signals. The provided smart trailer application prints the value of a property it subscribes to, the `TrailerWeight`. The first diagrams in the [Eclipse Ankaios](./eclipse-ankaios/README.md) and [Eclipse BlueChi](./eclipse-bluechi/README.md) depict this provided sample scenario. @@ -51,18 +52,23 @@ The first diagrams in the [Eclipse Ankaios](./eclipse-ankaios/README.md) and [Ec The in-vehicle-stack is started with Eclipse Chariott, Ibeji, Agemo, Freyja, and an Eclipse Mosquitto MQTT broker inside the orchestrator environment. #### Dynamic Orchestration + This use case demonstrates a simple example of dynamic orchestration. A [script](./in-vehicle-stack/scenarios/smart_trailer_use_case/scripts/) (one implemented for each orchestrator) will be run to monitor Ibeji and detect when the trailer is connected. The script will continuously poll for the "Trailer Connected" Digital Twin Provider, and print "NotFound" until it is started. You can simulate the trailer being connected to the vehicle by starting the ["Trailer Connected" Digital Twin Provider](./in-vehicle-stack/scenarios/smart_trailer_use_case/digital_twin_providers/trailer_connected_provider/). This provider will register itself with Ibeji, the script will detect this change, and start up the ["Trailer Properties" Digital Twin Provider](./in-vehicle-stack/scenarios/smart_trailer_use_case/digital_twin_providers/trailer_properties_provider/) and the [Smart Trailer Application](./in-vehicle-stack/scenarios/smart_trailer_use_case/applications/smart_trailer_application/). This shows a simple example of reacting to an event in the vehicle by starting up other workloads. #### Trailer Applications + The Trailer Properties Provider supports the ManagedSubscribe operation so that the Smart Trailer Application can specify that it wants to receive the `TrailerWeight` property's value every 10 seconds. Using the provided configuration, Freyja is configured to sync the `TrailerWeight` every 3 seconds to a mocked cloud endpoint (which will log the signal data on standard output). See the [Cloud Connectivity Doc](./docs/in-vehicle-stack/azure-cloud-connection.md) for instructions to synchronize signals to an Azure Digital Twins instance in the cloud. The [Digital Twin Model](./in-vehicle-stack/scenarios/smart_trailer_use_case/digital-twin-model/dtdl/trailer.json) defines the digital twin model for the trailer, which is used as a reference for the Digital Twin Providers and Applications. #### Run the use case + Once you've chosen an orchestrator and gone through their environment setup steps, please refer to [Ankaios's Dev Environment README](./eclipse-ankaios/README.md#startup-check-before-development) or [BlueChi's Dev Environment README](./eclipse-bluechi/README.md#running-the-smart-trailer-example-with-bluechis-devcontainer) for instructions on running this scenario. #### Hack Challenge - Extend the use case + Take a look at the source code for the Digital Twin Model, Digital Twin Providers, and Applications used in this example and add to them or use them as a reference to create your own! See the [references](#useful-references-for-creating-and-enhancing-sample-scenarios) to help guide you as well. When developing new workloads to run in the orchestrator environments, it is recommended to: + 1. Write the code for your workload in the language of your choice. 1. Build a container image for it. 1. Push it to a container registry. You can create an [Azure Container Registry](./docs/azure/azure_container_registry_instructions.md#aditional-information) with your [Azure Subscription](./docs/azure/azure_code_redeem_instructions.md) @@ -81,6 +87,7 @@ Here are a few suggested ways to extend this use case, but feel free to use your - Create your own application which leverages vehicle signals to implement a different use case, such as a data collector. ### Other Sample Scenarios + - Leverage OpenAI to enhance the vehicle’s user experience. You could develop an application that uses OpenAI’s GPT model to power an in-vehicle virtual assistant. - Consider using OpenAI to enhance our software orchestrators, effectively creating intelligent orchestrators! OpenAI could optimize workload placements across compute nodes and/or cloud based on factors such compute usage, memory usage, network coverage, and latency. @@ -92,6 +99,7 @@ Here are a few suggested ways to extend this use case, but feel free to use your This section offers guidance for creating a new sample scenario or extending the [Provided Sample Scenario](#provided-sample-scenario). While it does not provide a comprehensive list of resources, it aims to steer you in the right direction. If this section does not provide the guidance you need, please refer to the respective project’s documentation. See [Projects Involved](#projects-involved) for the project links. ### In-Vehicle Stack + If you are using the [In-Vehicle Stack](./in-vehicle-stack/README.md), these references may be useful. - [How do I override a configuration file for a service in the in-vehicle stack?](./docs/in-vehicle-stack/config-overrides.md) @@ -107,34 +115,39 @@ If you are using the [In-Vehicle Stack](./in-vehicle-stack/README.md), these ref > You will need to restart the smart trailer scenario. If you are using Eclipse Ankaios, please see [Workload Development](./eclipse-ankaios/README.md#workload-development) section. If you are using Eclipse BlueChi, please see the [Managing Workloads](./eclipse-bluechi/README.md#managing-workloads) section. ### General + This section contains general references that may provide guidance to the scenario you choose. #### Configuration Files + - [Which configuration files can I override?](./docs/in-vehicle-stack/config-overrides.md#how-to-override-configuration-for-in-vehicle-stack-containers) #### Ibeji + - [How do I create an in-vehicle digital twin model?](https://github.com/eclipse-ibeji/ibeji/blob/main/docs/tutorials/in_vehicle_model/README.md) > This helps you construct or enhance an in-vehicle digital twin model, and enables you to reference your in-vehicle digital twin model in your code. - [How do I create a digital twin provider or add additional capabilities to an existing provider?](https://github.com/eclipse-ibeji/ibeji/blob/main/docs/tutorials/provider/README.md) - > A digital twin provider exposes a subset of the in-vehicle's hardware capabilities. This enables digital twin consumers to utilize that subset. Also you may find that you want to add additional capabilities, such as a new in-vehicle signal, to an existing digital twin provider. When you add new capabilities to a provider, such as a new in-vehicle signal, you will need to update the mapping client's configuration or the mapping service that you are using with Freyja. See the [Freyja FAQ](#freyja) for more details. Please see the digital twin provider [smart trailer properties' source code](./in-vehicle-stack/scenarios/smart_trailer_use_case/digital_twin_providers/trailer_properties_provider/src/main.rs) for a digital twin provider example. - - [How do I build a container image for my digital twin provider?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/container/README.md#provider) - > You will need to build a container image if you are updating the smart trailer digital twin provider's source code or creating your own digital twin provider. - - [If my digital twin provider is running in a container, how do I override its configuration file?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/container/README.md#run) - > You do not need to rebuild the container image if you are overriding your digital twin provider's configuration file. - - [How do I use the Managed Subscribe module?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/managed_subscribe/README.md) - > Using the Managed Subscribe module and dynamic topics in your digital twin provider allows your digital twin consumers to specify the frequency at which they want to receive updates. Please see the digital twin provider [smart trailer properties' source code](./in-vehicle-stack/scenarios/smart_trailer_use_case/digital_twin_providers/trailer_properties_provider/src/main.rs) for an example. + > A digital twin provider exposes a subset of the in-vehicle's hardware capabilities. This enables digital twin consumers to utilize that subset. Also you may find that you want to add additional capabilities, such as a new in-vehicle signal, to an existing digital twin provider. When you add new capabilities to a provider, such as a new in-vehicle signal, you will need to update the mapping client's configuration or the mapping service that you are using with Freyja. See the [Freyja FAQ](#freyja) for more details. Please see the digital twin provider [smart trailer properties' source code](./in-vehicle-stack/scenarios/smart_trailer_use_case/digital_twin_providers/trailer_properties_provider/src/main.rs) for a digital twin provider example. + - [How do I build a container image for my digital twin provider?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/container/README.md#provider) + > You will need to build a container image if you are updating the smart trailer digital twin provider's source code or creating your own digital twin provider. + - [If my digital twin provider is running in a container, how do I override its configuration file?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/container/README.md#run) + > You do not need to rebuild the container image if you are overriding your digital twin provider's configuration file. + - [How do I use the Managed Subscribe module?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/managed_subscribe/README.md) + > Using the Managed Subscribe module and dynamic topics in your digital twin provider allows your digital twin consumers to specify the frequency at which they want to receive updates. Please see the digital twin provider [smart trailer properties' source code](./in-vehicle-stack/scenarios/smart_trailer_use_case/digital_twin_providers/trailer_properties_provider/src/main.rs) for an example. - [How do I create a digital twin consumer?](https://github.com/eclipse-ibeji/ibeji/blob/main/docs/tutorials/consumer/README.md) - > A digital twin consumer is a software entity that interfaces with the digital representation of the in-vehicle hardware components. Please see the digital twin consumer [smart trailer application's source code](./in-vehicle-stack/scenarios/smart_trailer_use_case/applications/smart_trailer_application/src/main.rs) for a digital twin consumer example. - - [How do I build a container image for my digital twin consumer?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/container/README.md#consumer) - > You will need to build a container image if you are updating the smart trailer digital twin consumer's source code or creating your own digital twin consumer. - - [If my digital twin consumer is running in a container, how do I override its configuration file?](./docs/in-vehicle-stack/config-overrides.md) - > You do not need to rebuild the container image if you are overriding your digital twin consumer's configuration file. + > A digital twin consumer is a software entity that interfaces with the digital representation of the in-vehicle hardware components. Please see the digital twin consumer [smart trailer application's source code](./in-vehicle-stack/scenarios/smart_trailer_use_case/applications/smart_trailer_application/src/main.rs) for a digital twin consumer example. + - [How do I build a container image for my digital twin consumer?](https://github.com/eclipse-ibeji/ibeji/blob/main/samples/container/README.md#consumer) + > You will need to build a container image if you are updating the smart trailer digital twin consumer's source code or creating your own digital twin consumer. + - [If my digital twin consumer is running in a container, how do I override its configuration file?](./docs/in-vehicle-stack/config-overrides.md) + > You do not need to rebuild the container image if you are overriding your digital twin consumer's configuration file. #### Chariott + - [How can I use the Service Discovery to register and discover other applications/services?](https://github.com/eclipse-chariott/chariott/blob/main/service_discovery/README.md) > An application can utilize Chariott's Service Discovery to register with the system and enable other applications to discover it through the Service Discovery system. This can also be used to discover other components in the in-vehicle-stack like Ibeji. #### Freyja + - [How do I configure new mappings for Freyja's in-memory mapping client?](https://github.com/eclipse-ibeji/freyja/blob/main/mapping_clients/in_memory_mock_mapping_client/README.md) > Adding a new in-vehicle signal requires you to configure a new mapping for that in-vehicle signal. - [How do I override the mapping configuration?](https://github.com/eclipse-ibeji/freyja/blob/main/docs/config-overrides.md) @@ -155,7 +168,8 @@ This section contains general references that may provide guidance to the scenar Please note that it is not necessary to use both software orchestrators. You can choose either one to implement your scenario. ### Need to know -- You need basic knowledge about containerization technologies and tools (e.g. Docker, Podman), but if you have not dealt with it yet, don't worry, just check out a little tutorial (https://docs.docker.com/get-started/) to get a basic understanding of containers and you are prepared. + +- You need basic knowledge about containerization technologies and tools (e.g. Docker, Podman), but if you have not dealt with it yet, don't worry, just check out a little tutorial () to get a basic understanding of containers and you are prepared. - Basic skills to deal with distributed systems ### Prebuilt Container Images @@ -185,6 +199,7 @@ We provide two software orchestrators, Ankaios and BlueChi, to orchestrate the i ## Projects Involved ### In-Vehicle Software Stack + - [Eclipse Agemo](https://github.com/eclipse-chariott/Agemo): Agemo incorporates a Pub Sub Service, a [gRPC](https://grpc.io/docs/what-is-grpc/introduction/) service that facilitates publish/subscribe operations for in-vehicle applications, including but not limited to Eclipse Ibeji and Eclipse Chariott. This service has the capability to register with Chariott, enhancing its discoverability by other applications such as Eclipse Ibeji. It offers dynamic creation and management of topics. - [Eclipse Chariott](https://github.com/eclipse-chariott/chariott): Chariott operates as a [gRPC](https://grpc.io/docs/what-is-grpc/introduction/) service, offering a unified interface for application interaction. Chariott enables [Service Discovery](https://github.com/eclipse-chariott/chariott/blob/main/service_discovery/README.md), allowing provider applications to promote their capabilities by registering with Chariott’s service registry. Consumer applications in need of specific resources and capabilities can discover them via Chariott’s service registry. @@ -194,11 +209,13 @@ We provide two software orchestrators, Ankaios and BlueChi, to orchestrate the i - [Eclipse Ibeji](https://github.com/eclipse-ibeji/ibeji): Ibeji is designed with the goal of enabling a digital depiction of the vehicle’s state and capabilities. It achieves this through an adaptable, open, and dynamic architecture that provides access to the vehicle’s hardware, sensors, and capabilities. This extensible framework allows for a comprehensive and accurate representation of the vehicle’s current status and potential functionalities. ### In-Vehicle Software Orchestrators + - [Eclipse Ankaios](https://eclipse-ankaios.github.io/ankaios): Ankaios provides workload and container orchestration for automotive High Performance Computing (HPC) software . While it can be used for various fields of applications, it is developed from scratch for automotive use cases and provides a slim yet powerful solution to manage containerized applications. It supports various container runtimes with Podman as the first one, but other container runtimes and even native applications can be supported. Eclipse Ankaios is independent of existing communication frameworks like SOME/IP, DDS, or REST API. - [Eclipse BlueChi](https://github.com/containers/bluechi): BlueChi is a systemd service controller intended for multi-node environments with a predefined number of nodes and with a focus on highly regulated ecosystems such as those requiring functional safety. Potential use cases can be found in domains such as transportation, where services need to be controlled across different edge devices and where traditional orchestration tools are not compliant with regulatory requirements. ## Hack Coaches + Who can be contacted for this challenge for questions. (Slack-handle) - Eclipse Agemo, Chariott, Ibeji and Freyja: Jordan Chiu (Slack handle: @Jordan Chiu) diff --git a/docs/azure/azure_code_redeem_instructions.md b/docs/azure/azure_code_redeem_instructions.md index d98a632..d2225ee 100644 --- a/docs/azure/azure_code_redeem_instructions.md +++ b/docs/azure/azure_code_redeem_instructions.md @@ -1,8 +1,8 @@ -# SDV Hackathon Azure Pass Code Instructions +# SDV Hackathon Azure Pass Code Instructions ## Azure Pass Codes -Each Hackathon Team will have at their disposal an Azure Pass Code to redeem and can use Azure to build their applications and solutions. +Each Hackathon Team will have at their disposal an Azure Pass Code to redeem and can use Azure to build their applications and solutions. You can find the Azure Promo Codes here [PromoCode](./SDV_hackathon_codes.xlsx). We have 20 promo codes available, 1 per each hackathon team with a cap spend of $150. @@ -11,4 +11,3 @@ Please ensure that only 1 Promo Code is used per Hackathon Team. As soon as you ## Azure Pass Code Redeem Instructions Each Hack Team will need to activate it before use. Instructions on how to redeem can be found here [Redeeming a Microsoft Azure Pass Promo Code](https://www.microsoftazurepass.com/Home/HowTo?Length=5). - diff --git a/docs/azure/azure_container_registry_instructions.md b/docs/azure/azure_container_registry_instructions.md index 50b6003..dd5602b 100644 --- a/docs/azure/azure_container_registry_instructions.md +++ b/docs/azure/azure_container_registry_instructions.md @@ -1,4 +1,4 @@ -# Azure Container Registry +# Azure Container Registry Azure Container Registry is a managed registry service based on the open-source Docker Registry 2.0 allowing you to create and maintain your container images in Azure. @@ -6,23 +6,26 @@ We have pre-built amd64 and arm64 container images for the in-vehicle software s ## Maestro Challenge Azure Container Registry -You can access the pre-built container images here: +You can access the pre-built container images here: + * sdvblueprint.azurecr.io You will be prompted for username and password to pull the pre-built container images. + * username: 5a3386a7-640d-4ec7-af9d-4009fd381a3b -> **Note** +> **Note** please contact the Maestro Hack Coaches for the password. -## How to use +## How to use You can pull the images using [Docker](https://docs.docker.com/engine/reference/commandline/pull/) or [Podman](https://docs.podman.io/en/latest/markdown/podman-pull.1.html) as shown below: When you run the below command, you will be prompted for username and password. Please use the username provided above and contact the Maestro Challenge hack coaches for the password. > **Podman** -``` + +```shell podman pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-agemo/pub-sub-service:0.1.0 podman pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-chariott/service-discovery:0.1.1 podman pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-ibeji/invehicle-digital-twin:0.1.0 @@ -33,7 +36,8 @@ podman pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-freyja/azure-cloud-conn ``` > **Docker** -``` + +```shell docker pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-agemo/pub-sub-service:0.1.0 docker pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-chariott/service-discovery:0.1.1 docker pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-ibeji/invehicle-digital-twin:0.1.0 @@ -43,9 +47,9 @@ docker pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-freyja/cloud-with-ibeji docker pull sdvblueprint.azurecr.io/sdvblueprint/eclipse-freyja/azure-cloud-connector:0.1.0 ``` -> **Note** +> **Note** Ensure you use the full domain name of the container registry. -## Aditional Information +## Additional Information -If you would like to know more about Azure Container Registry, extensive documentation and examples are available [Introduction to Container registries in Azure](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-intro) \ No newline at end of file +If you would like to know more about Azure Container Registry, extensive documentation and examples are available [Introduction to Container registries in Azure](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-intro) diff --git a/docs/in-vehicle-stack/azure-cloud-connection.md b/docs/in-vehicle-stack/azure-cloud-connection.md index fc891fb..a102fc8 100644 --- a/docs/in-vehicle-stack/azure-cloud-connection.md +++ b/docs/in-vehicle-stack/azure-cloud-connection.md @@ -1,9 +1,9 @@ -## In-Vehicle Stack with Cloud Connectivity +# In-Vehicle Stack with Cloud Connectivity The default in-vehicle stack is all local with no cloud connection. Follow the below steps to enable cloud connection with Azure Digital Twins using Eclipse Freyja. -### Create Azure Digital Twins Instance +## Create Azure Digital Twins Instance 1. Please refer to the following documentation to setup the Azure Digital Twins instance: [Automated Azure Digital Twins Setup for Smart Trailer Example](https://github.com/eclipse-ibeji/ibeji-example-applications/blob/main/cloud_connectors/azure/digital_twins_connector/README.md#automated-azure-digital-twins-setup-for-smart-trailer-example). This will create the Azure Digital Twins with the appropriate DTDL for the smart trailer use case. @@ -12,13 +12,13 @@ This will create the Azure Digital Twins with the appropriate DTDL for the smart [Open instance in Azure Digital Twins Explorer](https://learn.microsoft.com/en-us/azure/digital-twins/quickstart-azure-digital-twins-explorer#open-instance-in-azure-digital-twins-explorer) to get the url for your instance. Copy this url for later. -### Change In-Vehicle Stack to use Cloud-Connected Components +## Change In-Vehicle Stack to use Cloud-Connected Components The following changes will vary depending on which Orchestrator you are using. Broadly, we need to change the Freyja container image from the in-memory version to the cloud version and add a workload for the Azure cloud connector used by Freyja. -#### Eclipse Ankaios +### Eclipse Ankaios 1. Change the `digital_twin_cloud_sync` workload in [startupState.yaml](../../eclipse-ankaios/config/startupState.yaml) to point to the `cloud-with-ibeji` @@ -80,7 +80,7 @@ Connector to establish connection. Run: To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code to authenticate. ``` -2. Validate you have successfully logged in by re-running +1. Validate you have successfully logged in by re-running ```shell podman logs cloud-connector @@ -95,17 +95,20 @@ Connector to establish connection. Run: If you see the device code login text, wait 10 seconds and try the podman command again. -7. The In-Vehicle Stack is now initialized and connected to the cloud! +1. The In-Vehicle Stack is now initialized and connected to the cloud! -#### Eclipse BlueChi +### Eclipse BlueChi 1. In the BlueChi devcontainer, modify the `/usr/local/bin/bluechi-env-bootstrap` to remove `freyja` (this image includes the in-memory mock version of Freyja) and use `cloud-with-ibeji` and `azure-cloud-connector` services instead: - Add the following two lines: + ```shell systemctl start cloud-with-ibeji systemctl start azure-cloud-connector ``` + - Your complete file should now look like: + ```shell #!/bin/bash @@ -164,7 +167,7 @@ Connector to establish connection. Run: To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code to authenticate. ``` -2. Validate you have successfully logged in by re-running +1. Validate you have successfully logged in by re-running ```shell systemctl status azure-cloud-connector @@ -179,4 +182,4 @@ Connector to establish connection. Run: If you see the device code login text, wait 10 seconds and try the podman command again. -7. The In-Vehicle Stack is now initialized and connected to the cloud! +1. The In-Vehicle Stack is now initialized and connected to the cloud! diff --git a/docs/in-vehicle-stack/config-overrides.md b/docs/in-vehicle-stack/config-overrides.md index 7d8481e..61f0127 100644 --- a/docs/in-vehicle-stack/config-overrides.md +++ b/docs/in-vehicle-stack/config-overrides.md @@ -1,25 +1,25 @@ -## How to Override Configuration for In-Vehicle Stack Containers +# How to Override Configuration for In-Vehicle Stack Containers The following In-Vehicle Stack services have configuration that can be overridden: - Eclipse Agemo: - - [Configuration](https://github.com/eclipse-chariott/Agemo/blob/main/docs/config-overrides.md) + - [Configuration](https://github.com/eclipse-chariott/Agemo/blob/main/docs/config-overrides.md) - Eclipse Freyja: - - [Mapping Configuration](https://github.com/eclipse-ibeji/freyja/blob/main/mapping_clients/in_memory_mock_mapping_client/README.md) - - [Cloud Connector Configuration](https://github.com/eclipse-ibeji/ibeji-example-applications/blob/main/cloud_connectors/azure/digital_twins_connector/src/core/adt_instance_config.sample.json) + - [Mapping Configuration](https://github.com/eclipse-ibeji/freyja/blob/main/mapping_clients/in_memory_mock_mapping_client/README.md) + - [Cloud Connector Configuration](https://github.com/eclipse-ibeji/ibeji-example-applications/blob/main/cloud_connectors/azure/digital_twins_connector/src/core/adt_instance_config.sample.json) - Eclipse Ibeji: - - [In-Vehicle Digtial Twin Configuration](https://github.com/eclipse-ibeji/ibeji/blob/main/core/invehicle-digital-twin/template/invehicle_digital_twin_settings.yaml) - - [Managed Subscribe Configuration](https://github.com/eclipse-ibeji/ibeji/blob/main/core/module/managed_subscribe/template/managed_subscribe_settings.yaml) + - [In-Vehicle Digtial Twin Configuration](https://github.com/eclipse-ibeji/ibeji/blob/main/core/invehicle-digital-twin/template/invehicle_digital_twin_settings.yaml) + - [Managed Subscribe Configuration](https://github.com/eclipse-ibeji/ibeji/blob/main/core/module/managed_subscribe/template/managed_subscribe_settings.yaml) Please refer to the above links to determine what configuration files you would like to override. Then follow the steps below for the specific orchestrator you are using. -### Override In-Vehicle Stack configuration in Eclipse Ankaios +## Override In-Vehicle Stack configuration in Eclipse Ankaios -#### Prerequisites +### Prerequisites - Follow steps to setup the [Ankaios Development Environment](../../eclipse-ankaios/README.md#ankaios-maestro-challenge-development-environment) -#### Steps +### Steps 1. In the Ankaios devcontainer, open a terminal and create a directory under `/etc` to store the desired project configuration files: @@ -47,7 +47,7 @@ desired project configuration files: ``` 1. Populate the newly created configuration files with the configuration you wish to override using -any text editor. +any text editor. 1. Next, we need to pass the configuration into the containers. To do this, we will need to modify [startupState.yaml](../../eclipse-ankaios/config/startupState.yaml). This will be done by mounting the @@ -72,13 +72,13 @@ The In-Vehicle Stack service will now use your modified configuration. Note that changes will require a restart of the in-vehicle stack. You can restart the in-vehicle stack by following the steps for [Ankaios](../../eclipse-ankaios/README.md#startup-check-before-development). -### Override In-Vehicle Stack configuration in Eclipse BlueChi +## Override In-Vehicle Stack configuration in Eclipse BlueChi -#### Prerequisites +### Prerequisites - Follow steps to setup [Eclipse BlueChi](../../eclipse-bluechi/README.md) -#### Steps +### Steps 1. In the BlueChi devcontainer, open a terminal and create a directory under `/etc` to store the desired project configuration files: @@ -106,7 +106,7 @@ desired project configuration files: ``` 1. Populate the newly created configuration files with the configuration you wish to override using -any text editor. +any text editor. 1. Next, we need to pass the configuration into the containers. To do this, we will need to modify the `/etc/containers/systemd/.yml` file for your service (replace with your service name). This will be done by mounting the @@ -134,6 +134,7 @@ directory created in step 1 into the container using `volumeMounts`. You can see ``` - Refer to this volume in the "containers" section, for example: + ```yaml containers: - name: app @@ -147,3 +148,5 @@ directory created in step 1 into the container using `volumeMounts`. You can see The In-Vehicle Stack service will now use your modified configuration. Note that any configuration changes will require a restart of the in-vehicle stack. You can restart the in-vehicle stack by following the steps for [BlueChi](../../eclipse-bluechi/README.md#bootstrapping) cleanup and bootstrap again. + + diff --git a/eclipse-ankaios/README.md b/eclipse-ankaios/README.md index dc4d430..fd6b479 100644 --- a/eclipse-ankaios/README.md +++ b/eclipse-ankaios/README.md @@ -4,9 +4,7 @@ Don't feel like reading instructions? No problem, watch the video explaining the [![Eclipse Ankaios Development Environment Video](assets/ankaios-hackathon-youtube-image.png)](https://youtu.be/XQVlIctChkI) - -**Architectural Overview** - +## Architectural Overview ![Smart trailer blueprint](../docs/diagrams/ankaios.png) @@ -37,17 +35,16 @@ The following is provided inside the devcontainer: - Pre-configured Ankaios startup config [startupState.yaml](./config/startupState.yaml) - Automation scripts for starting and stopping all workloads of the challenge: - - run_maestro.sh - - shutdown_maestro.sh + - run_maestro.sh + - shutdown_maestro.sh -- REST API providing [resource usage statistics](#resource-usage-statistics) for the sample scenario about intelligent orchestrator +- REST API providing resource usage statistics for the sample scenario about intelligent orchestrator - Exposed port: - - 25551: for optionally using the Ankaios CLI outside of the devcontainer + - 25551: for optionally using the Ankaios CLI outside of the devcontainer - [Ankaios Control Interface dependencies](#ankaios-control-interface-dependencies) - All services are running in the host network meaning those can be accessed by `localhost:`. We recommend that you set the network mode to host for all your developed workloads as well. ## Ankaios Control Interface dependencies @@ -63,6 +60,7 @@ Those dependencies are needed for use-cases in which your app needs to use the [ ## Run devcontainer with VSCode ### Prerequisites + - [Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) extension installed in VSCode Open the subfolder containing this README file in VSCode: @@ -96,59 +94,70 @@ Before starting active development we recommend you start once Ankaios with the **Note:** If you have selected a sample scenario requiring resource usage statistics like cpu or memory usage, uncomment the `resource_monitor` config part in the Ankaios startup config [startupState.yaml](./config/startupState.yaml). If you are using MacOS, please remove the `--pid host` and `--cgroups enabled` parameters from the config part. For more details, see [here](../scenarios/intelligent_orchestrator_use_case/ankaios_resource_statistics_app/README.md). 1. Log in into the Microsoft container registry -```shell -podman login sdvblueprint.azurecr.io -``` + + ```shell + podman login sdvblueprint.azurecr.io + ``` 2. Start Ankaios with all workloads inside the startup config: -```shell -run_maestro.sh -``` + + ```shell + run_maestro.sh + ``` 3. Next, use the Ankaios CLI to verify that all initial workloads are up and running: -```shell -ank get workloads -``` + ```shell + ank get workloads + ``` 4. Verify that all initial workloads inside the startup config have execution state "Running". -The output looks similar to the following: -```shell - WORKLOAD NAME AGENT RUNTIME EXECUTION STATE - digital_twin_cloud_sync agent_A podman Running - digital_twin_vehicle agent_A podman Running - dynamic_topic_management agent_A podman Running - mqtt_broker agent_A podman Running - service_discovery agent_A podman Running -``` + The output looks similar to the following: + + ```shell + WORKLOAD NAME AGENT RUNTIME EXECUTION STATE + digital_twin_cloud_sync agent_A podman Running + digital_twin_vehicle agent_A podman Running + dynamic_topic_management agent_A podman Running + mqtt_broker agent_A podman Running + service_discovery agent_A podman Running + ``` 5. Only for the **Smart Trailer scenario**, do the following extra steps: - Inside the devcontainer, run the script `start_trailer_applications_ankaios.sh`: + ```shell start_trailer_applications_ankaios.sh ``` + - In another terminal window inside the devcontainer, add the following workload by using the Ankaios CLI to simulate the Smart Trailer connected signal: + ```shell ank run workload trailer_connected_provider --runtime podman --config $'image: sdvblueprint.azurecr.io/sdvblueprint/in-vehicle-stack/trailer_connected_provider:0.1.0\ncommandOptions: ["--network", "host", "--name", "trailer_connected_provider"]' --agent agent_A ``` + - Verify the output of the terminal window of the `start_trailer_applications_ankaios.sh` script. The output should look like the following: + ```shell Trailer is connected! Starting workloads to manage it Called Ankaios to start the Trailer Properties Digital Twin Provider and Smart Trailer Application Check Ankaios status with 'ank get workloads' ``` + - Check the execution states of the newly added workloads by using the Ankaios CLI. + ```shell ank get workloads ``` + - Run `podman logs -f smart_trailer_application` to check the sample data output of the Smart Trailer App. Feel free to check the logs of the other workloads too. 6. Stop Ankaios and clean up all workloads by running: -```shell -shutdown_maestro.sh -``` + ```shell + shutdown_maestro.sh + ``` ## Customizing Devcontainer @@ -170,6 +179,7 @@ After customizing the devcontainer, start the development of your workload apps. Start and stop all workloads according to the section [Startup check before development](#startup-check-before-development). Use the Ankaios ClI to check the workload states. For more details display the help of Ankaios CLI by running: + ```shell ank --help ``` @@ -196,3 +206,5 @@ The Ankaios agent logs can be viewed by executing the following command: ```shell tail -f /var/log/ankaios-agent_A.log ``` + + diff --git a/eclipse-bluechi/README.md b/eclipse-bluechi/README.md index cb2a046..8e6ba23 100644 --- a/eclipse-bluechi/README.md +++ b/eclipse-bluechi/README.md @@ -44,24 +44,29 @@ All services are accessible via `localhost:$port`. It is strongly recommended that you use the devcontainer with VSCode. -NOTE: You can build the development environment image yourself in case you are having trouble running it from this repository: https://github.com/odra/eclipse-bluechi-hackathon-image +NOTE: You can build the development environment image yourself in case you are having trouble running it from this repository: ## Run the devcontainer with VSCode ### Prerequisite + * Ensure that the [Remote Development extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) installed in VSCode * Upstream documentation: + * - * https://github.com/devcontainers/cli + * The following steps below uses the VSCode devcontainer extension. If you prefer, you can use [VSCode's devcontainer's CLI](https://github.com/devcontainers/cli) instead. 1. Login to the Azure's container registry to allow VSCode to pull the devcontainer image: + ```shell docker login sdvblueprint.azurecr.io ``` + 1. You can use the VSCode devcontainer extension to start your containerized development environment. + ```shell cd /maestro-challenge/eclipse-bluechi code . @@ -74,11 +79,13 @@ The following steps below uses the VSCode devcontainer extension. If you prefer, Upstream documentation: 1. Login to the Azure's container registry: + ```shell docker login sdvblueprint.azurecr.io ``` 1. Start the devcontainer by running: + ```sh docker run \ -d \ @@ -92,6 +99,7 @@ Upstream documentation: Ensure to replace `` with your own value. 1. Enter into the devcontainer and interact with BlueChi: + ```sh docker exec -it autosd-eclipse /bin/bash bluechictl list-units @@ -102,7 +110,9 @@ Upstream documentation: You need to bootstrap all the Eclipse services once you got your eclipse-bluechi devcontainer running. ### Starting all the services + 1. Inside your devcontainer, you will need to login to Azure's container registry to pull all required images: + ```sh podman login \ --username \ @@ -111,16 +121,21 @@ You need to bootstrap all the Eclipse services once you got your eclipse-bluechi ``` 2. Then it is time to start all services which can be done by executing the bootstrap script: + ```sh - $ bluechi-env-bootstrap + bluechi-env-bootstrap ``` + The above command will pull all the required images and start all services. ### Cleanup + 1. There is also a script to stop all services: + ```sh - $ bluechi-env-cleanup + bluechi-env-cleanup ``` + Keep in mind that stopping services will purge all the containers that are related to such services as well. Both the `bluechi-env-bootstrap` and `bluechi-env-cleaup` scripts are located in `/usr/local/bin/` in case you are interested in checking them out. @@ -145,6 +160,7 @@ needs two essential files: containing the workload definition. Example of `freyja.kube`: + ```kube # https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html [Kube] @@ -154,10 +170,12 @@ needs two essential files: # [Install] # WantedBy=default.target ``` + * `{SERVICE_NAME}.yaml`: A Kubernetes resource definition (either `v1.Pod` or `apps/v1.Deployment`) that describes the workload. Example of `freyja.yml`: + ```yaml --- apiVersion: apps/v1 @@ -220,13 +238,17 @@ You can also list all active containers by running `podman ps` and then `podman get logs from the container using podman. Replace `{CONTAINER_NAME_OR_ID}` with the container's name or ID. ## Running the Smart Trailer Example with BlueChi's devcontainer + Inside of the [devcontainer](#two-development-environments): + 1. Follow the instructions in [Starting All the Services](#starting-all-the-services) to start up the in-vehicle stack. 1. Run the script `start_trailer_applications_bluechi.sh` to monitor for the trailer to be connected. It can be found at `in-vehicle-stack/scenarios/smart_trailer_use_case/scripts/start_trailer_applications_bluechi.sh`. 1. In another terminal window inside the devcontainer, start the `trailer-connected` service to simulate the trailer being connected: + ```shell systemctl start trailer-connected ``` + 1. Verify the output in the terminal window of the `start_trailer_applications_bluechi.sh` script. You should see that two more services were started in response to the trailer being connected. 1. Use [Monitoring and Logs](#monitoring-and-logs) to check that the `smart-trailer` service is now receiving the value of the trailer weight every 10 seconds. 1. When you are ready to clean up, use the cleanup script mentioned in [Cleanup](#cleanup). diff --git a/in-vehicle-stack/README.md b/in-vehicle-stack/README.md index b5fc136..a4a9aba 100644 --- a/in-vehicle-stack/README.md +++ b/in-vehicle-stack/README.md @@ -1,19 +1,20 @@ -## In Vehicle Stack +# In Vehicle Stack This in-vehicle stack directory contains files related to the In-Vehicle Stack (Eclipse Chariott, Ibeji, Agemo, and Freyja). -### Interfaces +## Interfaces For simplicity for the hackathon, the files in the `interfaces` directory are copied from the main repositories. These protobuf files enable communication with the services. You can find the original files at the links below: + - [In-vehicle Digital Twin](https://github.com/eclipse-ibeji/ibeji/tree/main/interfaces/invehicle_digital_twin/v1) - [Managed Subscribe Module](https://github.com/eclipse-ibeji/ibeji/tree/main/interfaces/module/managed_subscribe/v1) for using Agemo - [Service Discovery](https://github.com/eclipse-chariott/chariott/tree/main/service_discovery/proto/core/v1) -### Compiling the interfaces +## Compiling the interfaces The `proto_build` directory provides the necessary files to compile the protobuf with Rust. If you would like to develop sample applications using Rust, you can use `cargo build -p interfaces`. If @@ -22,16 +23,16 @@ the language of your choice to generate clients for interacting with the service Note: If you choose Ankaios as your orchestrator, please add your dependencies into the [Dockerfile](../eclipse-ankaios/.devcontainer/Dockerfile). For Rust, you can just uncomment the prepared lines in the Dockerfile. -### Cloud Connection +## Cloud Connection Please refer to the [In-Vehicle Stack with Cloud Connectivity](../docs/in-vehicle-stack/azure-cloud-connection.md) for instructions on how to setup the In-Vehicle Stack to connect with Azure. -### Extending the Use Case +## Extending the Use Case Please see [Hack Challenge - Extend the use case](../README.md#hack-challenge---extend-the-use-case) for ideas on how to extend the smart trailer scenario. -### Configuration overrides +## Configuration overrides To override the configuration for one of the in-vehicle stack services, please follow [How to Override Configuration for In-Vehicle Stack Containers](../docs/in-vehicle-stack/config-overrides.md#how-to-override-configuration-for-in-vehicle-stack-containers). diff --git a/in-vehicle-stack/sample_trailer_connected_provider/README.md b/in-vehicle-stack/sample_trailer_connected_provider/README.md index ae00111..7b2ec19 100644 --- a/in-vehicle-stack/sample_trailer_connected_provider/README.md +++ b/in-vehicle-stack/sample_trailer_connected_provider/README.md @@ -38,4 +38,4 @@ Optionally cleanup and remove: ```shell podman rm sample_trailer_connected_provider -``` \ No newline at end of file +``` diff --git a/scenarios/intelligent_orchestrator_use_case/ankaios_resource_statistics_app/README.md b/scenarios/intelligent_orchestrator_use_case/ankaios_resource_statistics_app/README.md index 611e092..513762b 100644 --- a/scenarios/intelligent_orchestrator_use_case/ankaios_resource_statistics_app/README.md +++ b/scenarios/intelligent_orchestrator_use_case/ankaios_resource_statistics_app/README.md @@ -2,7 +2,7 @@ For challenges requiring resource usage statistics a workload application is provided that provides you some initial resource statistic values of the host the workload is running on. The statistics can be accessed via a REST API as JSON. -This image is public available: +This image is public available: ```shell docker pull ghcr.io/eclipse-ankaios/maestro_resource_monitor:0.1.0 @@ -58,4 +58,4 @@ You can also run the workload without Ankaios for testing, by running it with th ```shell docker run --rm -d --name resource_monitor --privileged --network host --pid host --name resource_monitor -p 25555:25555 /maestro_resource_monitor: -``` \ No newline at end of file +```