diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml index 60034e7..96c026a 100644 --- a/.github/workflows/deploy-docs.yaml +++ b/.github/workflows/deploy-docs.yaml @@ -10,6 +10,7 @@ on: - "**/*.svg" - "**/*.png" - "**/*.jpg" + - "docs/assets/**" workflow_dispatch: permissions: @@ -41,12 +42,10 @@ jobs: pip install mkdocs-awesome-pages-plugin pip install mkdocs-exclude pip install mkdocs-macros-plugin - pip install mkdocs-same-dir pip install pymdown-extensions pip install python-markdown-math pip install mdx-truly-sane-lists pip install plantuml-markdown - pip install mkdocs-mermaid2-plugin - name: Build with MkDocs run: mkdocs build --clean --verbose @@ -83,4 +82,3 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 - diff --git a/Makefile b/Makefile index 96ae185..ce90562 100644 --- a/Makefile +++ b/Makefile @@ -1,23 +1,24 @@ -# Makefile for Openadkit Document +# Makefile for Open AD Kit documentation # Installs required MkDocs packages and serves documentation -.PHONY: help prepare serve build clean +.PHONY: help prepare prepare-if-missing serve build clean # Default target help: - @echo "Openadkit Documentation - Available commands:" + @echo "Open AD Kit Documentation - Available commands:" @echo " make prepare Prepare Mkdocs development container" + @echo " make prepare-if-missing Reuse local image if present, otherwise build it" @echo " make serve Start development server on the built container" @echo " make build Build static documentation" @echo " make clean Clean build artifacts" # Serve documentation locally serve: - docker run -it --rm -p 8000:8000 -v $$(pwd):/app mkdocs-dev + docker run --rm -p 8000:8000 -v $$(pwd):/app mkdocs-dev # Build static documentation build: - docker run -it --rm -v $$(pwd):/app --user $$(id -u):$$(id -g) mkdocs-dev mkdocs build + docker run --rm -v $$(pwd):/app --user $$(id -u):$$(id -g) mkdocs-dev mkdocs build # Clean build artifacts clean: @@ -26,3 +27,11 @@ clean: # Install mkdocs dependencies prepare: docker build -f doc_env/Dockerfile -t mkdocs-dev . + +# Reuse an existing image when offline or when rebuilding is unnecessary +prepare-if-missing: + @if docker image inspect mkdocs-dev >/dev/null 2>&1; then \ + echo "Using existing mkdocs-dev image"; \ + else \ + docker build -f doc_env/Dockerfile -t mkdocs-dev .; \ + fi diff --git a/README.md b/README.md index 3e9a9d4..51498c1 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,9 @@ The Autoware Foundation is a voting member of the [SOAFEE (Scalable Open Archite Open AD Kit is a micro-service based project, which means that it is designed to be deployed on a variety of platforms with microservices architecture. Each component is designed to be independent and can be deployed on a variety of platforms. -- **Independent components** for sensing, perception, mapping, localization, planning, control, and visualization -- **Multi-platform deployment** supporting both amd64 and arm64 architectures -- **Service mesh integration** with configurable environment variables +- **Independent images** for sensing, perception, mapping, localization, planning, control, APIs, simulation, and visualization +- **Multi-platform deployment** supporting both amd64 and arm64 architectures +- **Configurable ROS 2 container deployments** with environment-driven composition ![Granular Components](docs/assets/images/granular-components.png) @@ -53,7 +53,7 @@ Open AD Kit leverages modern cloud native technologies to deliver scalable, port - **Seamless scaling** from development laptops to production edge devices - **Hybrid cloud support** bridging development and production environments -- **Container orchestration** ready for Kubernetes and similar platforms +- **Containerized runtimes** using Docker Compose, Docker Bake, and platform-specific integrations such as AutoSD ![Cloud Native](docs/assets/images/cloud-native.png) diff --git a/deployments/README.md b/deployments/README.md index f10d20f..3a3d5a9 100644 --- a/deployments/README.md +++ b/deployments/README.md @@ -6,4 +6,4 @@ This directory contains deployment configurations for **Open AD Kit**. Each fold - [Planning Simulation](./samples/planning-simulation): Simple Open AD Kit deployment that demonstrates the autoware **planning features** with planning simulation. - [Logging Simulation](./samples/logging-simulation): Simple Open AD Kit deployment that demonstrates the autoware **end-to-end functionality** with sensor simulation using rosbag. - **Demo deployment** configurations with specific use case scenarios. - - [Zenoh Bridge](./demos/zenoh-bridge): A demo of remote visualization with Zenoh bridge. See [Zenoh Bridge Document](openadkit-dev/docs/deployments/zenoh-bridge/index.md) for more details. + - [Zenoh Bridge](./demos/zenoh-bridge): A demo of remote visualization with Zenoh bridge. See the [Zenoh Bridge documentation](../docs/deployments/demos/zenoh-bridge/index.md) for more details. diff --git a/deployments/demos/zenoh-bridge/README.md b/deployments/demos/zenoh-bridge/README.md index 44a7185..d51c6e9 100644 --- a/deployments/demos/zenoh-bridge/README.md +++ b/deployments/demos/zenoh-bridge/README.md @@ -27,10 +27,9 @@ The project provides different deployment strategies to suit various testing nee ## Quick Start -We recommend using the Split Topology mode in the `local` directory: +We recommend using the Split Topology mode from this directory: ```bash -cd local ./edge.sh up -d ./cloud.sh up -d ``` diff --git a/deployments/demos/zenoh-bridge/docker-compose.yaml b/deployments/demos/zenoh-bridge/docker-compose.yaml index 675a12d..8532d7f 100644 --- a/deployments/demos/zenoh-bridge/docker-compose.yaml +++ b/deployments/demos/zenoh-bridge/docker-compose.yaml @@ -44,7 +44,7 @@ services: environment: - RMW_IMPLEMENTATION=rmw_cyclonedds_cpp - ROS_DOMAIN_ID=1 - - REMOTE_PASSWORD=o + - REMOTE_PASSWORD=openadkit - USE_SIM_TIME=true ports: - "0.0.0.0:6081:6080" diff --git a/deployments/samples/logging-simulation/README.md b/deployments/samples/logging-simulation/README.md index ee60d1c..19a2646 100644 --- a/deployments/samples/logging-simulation/README.md +++ b/deployments/samples/logging-simulation/README.md @@ -4,17 +4,25 @@ This sample deployment shows how to run Autoware Open AD Kit **logging simulatio ## Requirements -In order to run the logging simulation, you need to have the logging simulation **sample map** and **rosbag**. You can download them by running the following commands: +In order to run the logging simulation, you need the logging simulation **sample map**, **rosbag**, and the Autoware artifacts downloaded by `setup.sh --download-artifacts`. + +If `gdown` or `unzip` are not installed yet, install them first: + +```bash +sudo apt-get install -y python3-pip unzip +python3 -m pip install --user gdown +``` ### Sample Logging Map Download and unpack a logging simulation sample map that is used in this sample. -- You can also download [the map](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually. +- You can also download [the map](https://drive.google.com/file/d/1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI/view?usp=sharing) manually. ```bash -gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI' -unzip -d ~/autoware_map/ ~/autoware_map/sample-map-rosbag.zip +mkdir -p ~/autoware_map +gdown -O ~/autoware_map/sample-map-rosbag.zip 'https://docs.google.com/uc?export=download&id=1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI' +unzip -o -d ~/autoware_map ~/autoware_map/sample-map-rosbag.zip ``` > **Note**: This sample map(Copyright 2020 TIER IV, Inc.) is only for demonstration purposes. You can use your own map by following the [How-to Guide](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-maps/). @@ -23,15 +31,23 @@ unzip -d ~/autoware_map/ ~/autoware_map/sample-map-rosbag.zip Download and unpack a sample rosbag that is used for **sensor simulation** in this sample. -- You can also download [the rosbag](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually. +- You can also download [the rosbag](https://drive.google.com/file/d/1sU5wbxlXAfHIksuHjP3PyI2UVED8lZkP/view?usp=sharing) manually. ```bash -gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1sU5wbxlXAfHIksuHjP3PyI2UVED8lZkP' -unzip -d ~/autoware_map/ ~/autoware_map/sample-rosbag.zip +gdown -O ~/autoware_map/sample-rosbag.zip 'https://docs.google.com/uc?export=download&id=1sU5wbxlXAfHIksuHjP3PyI2UVED8lZkP' +unzip -o -d ~/autoware_map ~/autoware_map/sample-rosbag.zip ``` > **Note**: Due to privacy concerns, the rosbag(Copyright 2020 TIER IV, Inc.) does not contain image data, which will cause: Traffic light recognition functionality cannot be tested with this sample rosbag. Object detection accuracy is decreased. +### Autoware Artifacts + +This deployment mounts `${HOME}/autoware_data` into the sensing and perception containers. Download the artifacts ahead of time by following the [Getting Started](../../../docs/getting-started/index.md) guide: + +```bash +sudo ./setup.sh --download-artifacts +``` + ## Run the Deployment 1. Start the deployment by running the following command: @@ -46,7 +62,7 @@ unzip -d ~/autoware_map/ ~/autoware_map/sample-rosbag.zip http://localhost:6080/vnc.html ``` - Use the default password `openadkit` to access the visualizer. **It can take a few seconds to visualizer to start.** + Use the default password `openadkit` to access the visualizer. **It can take a few seconds for the visualizer to start.** > If your machine is on a remote server, you can access the visualizer by using its accessible IP address: > diff --git a/deployments/samples/planning-simulation/README.md b/deployments/samples/planning-simulation/README.md index 958c6a6..2497a92 100644 --- a/deployments/samples/planning-simulation/README.md +++ b/deployments/samples/planning-simulation/README.md @@ -4,7 +4,14 @@ This sample deployment shows how to run Autoware Open AD Kit **planning simulati ## Requirements -In order to run the planning simulation, you need to have the planning simulation **sample map**. You can download it by running the following commands: +In order to run the planning simulation, you need the planning simulation **sample map**. + +If `gdown` or `unzip` are not installed yet, install them first: + +```bash +sudo apt-get install -y python3-pip unzip +python3 -m pip install --user gdown +``` ### Sample Planning Map @@ -13,8 +20,9 @@ Download and unpack a planning simulation sample map that is used in this sample - You can also download [the map](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually. ```bash -gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd' -unzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip +mkdir -p ~/autoware_map +gdown -O ~/autoware_map/sample-map-planning.zip 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd' +unzip -o -d ~/autoware_map ~/autoware_map/sample-map-planning.zip ``` > **Note**: This sample map(Copyright 2020 TIER IV, Inc.) is only for demonstration purposes. You can use your own map by following the [How-to Guide](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-maps/). @@ -33,7 +41,7 @@ unzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip http://localhost:6080/vnc.html ``` - Use the default password `openadkit` to access the visualizer. **It can take a few seconds to visualizer to start.** + Use the default password `openadkit` to access the visualizer. **It can take a few seconds for the visualizer to start.** > If your machine is on a remote server, you can access the visualizer by using its accessible IP address: > diff --git a/doc_env/Dockerfile b/doc_env/Dockerfile index 83b41e4..82ba622 100644 --- a/doc_env/Dockerfile +++ b/doc_env/Dockerfile @@ -7,12 +7,10 @@ RUN pip install --no-cache-dir \ mkdocs-awesome-pages-plugin \ mkdocs-exclude \ mkdocs-macros-plugin \ - mkdocs-same-dir \ pymdown-extensions \ python-markdown-math \ mdx-truly-sane-lists \ - plantuml-markdown \ - mkdocs-mermaid2-plugin + plantuml-markdown EXPOSE 8000 diff --git a/doc_env/README.md b/doc_env/README.md index a12ba02..427aa28 100644 --- a/doc_env/README.md +++ b/doc_env/README.md @@ -1,17 +1,17 @@ -# Openadkit: Containerized MkDocs Development +# Open AD Kit: Containerized MkDocs Development -This document explains how to set up a containerized development environment for MkDocs in the Openadkit project using Docker and Makefile. The `doc_env/Dockerfile` and `Makefile` are designed to replicate the dependencies and configuration used in the project's GitHub Actions workflow, ensuring consistency between local development and CI/CD environments. +This document explains how to set up a containerized development environment for MkDocs in the Open AD Kit project using Docker and Makefile. The `doc_env/Dockerfile` and `Makefile` are designed to replicate the dependencies and configuration used in the project's GitHub Actions workflow, ensuring consistency between local development and CI/CD environments. ## TL;DR -In the Openadkit project **root directory**: +In the Open AD Kit project **root directory**: ```bash make prepare make serve ``` -Access the MkDocs development server at `http://localhost:8000`. To build the static site: +Access the MkDocs development server at `http://localhost:8000/openadkit/`. To build the static site: ```bash make build @@ -26,8 +26,9 @@ make build The `Makefile` simplifies common tasks for managing the MkDocs environment. Available commands: -- `make prepare`: Builds the Docker image with required MkDocs dependencies. -- `make serve`: Starts the MkDocs development server at `http://localhost:8000`. +- `make prepare`: Rebuilds the Docker image with required MkDocs dependencies. +- `make prepare-if-missing`: Reuses an existing `mkdocs-dev` image if present, otherwise builds it. +- `make serve`: Starts the MkDocs development server at `http://localhost:8000/openadkit/`. - `make build`: Generates the static site in the `site/` directory with correct permissions. - `make clean`: Removes the `site/` directory to clean up build artifacts. - `make help`: Displays available commands. @@ -36,7 +37,7 @@ Run `make help` to see all options. ## Setup and Usage -1. **Build the Docker Image** +1. **Prepare the Docker Image** Run the following command to build the Docker image: @@ -44,11 +45,13 @@ Run `make help` to see all options. make prepare ``` - This builds the `mkdocs-dev` image using the `doc_env/Dockerfile`, which includes: - - Base image: `python:3.11-slim` - - Installed MkDocs plugins: `mkdocs-material`, `mkdocs-awesome-pages-plugin`, `mkdocs-exclude`, `mkdocs-macros-plugin`, `mkdocs-same-dir`, `pymdown-extensions`, `python-markdown-math`, `mdx-truly-sane-lists`, `plantuml-markdown`, `mkdocs-mermaid2-plugin` - - Working directory: `/app` - - Exposed port: `8000` + This builds the `mkdocs-dev` image using the `doc_env/Dockerfile`, which includes: + - Base image: `python:3.11-slim` + - Installed MkDocs plugins: `mkdocs-material`, `mkdocs-awesome-pages-plugin`, `mkdocs-exclude`, `mkdocs-macros-plugin`, `pymdown-extensions`, `python-markdown-math`, `mdx-truly-sane-lists`, `plantuml-markdown` + - Working directory: `/app` + - Exposed port: `8000` + + Use `make prepare-if-missing` only when you intentionally want to reuse an existing local image, such as during offline verification. 2. **Run the Development Server** @@ -58,7 +61,7 @@ Run `make help` to see all options. make serve ``` - - Opens `http://localhost:8000` in your browser to view the live site. + - Opens `http://localhost:8000/openadkit/` in your browser to view the live site. - Changes to `docs/` or `mkdocs.yaml` trigger automatic reloading. - The current directory is mounted to `/app` in the container for live updates. @@ -86,18 +89,13 @@ Run `make help` to see all options. - **File Permissions**: The `make build` command uses `--user $(id -u):$(id -g)` to ensure the `site/` directory has the same ownership as your host user, avoiding permission issues on Linux systems. - **Customizing Plugins**: Update both `doc_env/Dockerfile` and `mkdocs.yaml` if additional MkDocs plugins are needed. -- **Optimizing Builds**: Use a `.dockerignore` file to exclude unnecessary files (e.g., `site/`, `.github/`) to reduce build time. Example `.dockerignore`: - ``` - .github/ - deployments/ - site/ - ``` - **Cleaning Up Docker**: Use `docker system prune` to remove unused images and containers. -- **Documentation**: Refer to `docs/dev/index.md` for additional development environment details. +- **Documentation Source**: The published documentation lives under `docs/` and is configured by `mkdocs.yaml`. ## Troubleshooting - **Permission Issues**: If the `site/` directory has incorrect permissions, ensure `make build` is used instead of directly running `docker run ... mkdocs build`. - **Port Conflicts**: If port `8000` is in use, stop other services or change the port mapping (e.g., `-p 8001:8000` in the `make serve` command by editing the `Makefile`). +- **Prepare Fails During Package Download**: If Docker cannot reach PyPI while building `mkdocs-dev`, rerun `make prepare` once network access is available. If you already have a suitable local image and only need to test docs content, use `make prepare-if-missing`. -For further assistance, consult the main `README.md` or open an issue in the Openadkit repository. \ No newline at end of file +For further assistance, consult the main `README.md` or open an issue in the Open AD Kit repository. diff --git a/docs/components/index.md b/docs/components/index.md index b8cb524..7904994 100644 --- a/docs/components/index.md +++ b/docs/components/index.md @@ -1,6 +1,6 @@ # Components -Open AD Kit is a component based project, which means that it is designed to be deployed on a variety of platforms with microservices architecture. Each **Autoware component** is designed to be independent and can be configured to work together to achieve a particular task, such as a simulation or a full autonomous driving stack. +Open AD Kit is a component-based project designed to run on a variety of platforms with containerized services. Each **Autoware function** remains independently deployable, while the published images group closely related functions together where that keeps the runtime layout simpler. ![Granular Components](../assets/images/granular-components.png) @@ -30,14 +30,10 @@ The planning component is responsible for planning the vehicle's path. Planning The control component is responsible for controlling the vehicle's actuators. Control component can be configured to use a variety of control algorithms, including **PID and MPC**. For more details, see the [Autoware control design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/components/control/). -### Vehicle +### Vehicle and System -The vehicle component is responsible for managing the vehicle's state. Vehicle component can be configured to use a variety of vehicle algorithms, including **vehicle state estimation and vehicle control**. For more details, see the [Autoware vehicle design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/components/vehicle/). +The `vehicle-system` image packages both the vehicle interface and system-level services used by the Open AD Kit deployments. On the functional side, the vehicle component manages vehicle-specific interfaces and state, while the system component provides health monitoring and related system services. For more details, see the [Autoware vehicle design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/components/vehicle/). ### API -The API component is responsible for providing [AD API](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/) interface for the vehicle's state. API component can be configured to enable/disable various interfaces. For more details, see the [Autoware Interface design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/interfaces/). - -### System - -The system component is responsible for managing the vehicle's system. System component can be configured to use a variety of system algorithms, including **system health monitoring and system error handling**. +The API component is responsible for providing [AD API](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/) interface for the vehicle's state. API component can be configured to enable or disable various interfaces. For more details, see the [Autoware Interface design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/interfaces/). diff --git a/docs/deployments/demos/zenoh-bridge/index.md b/docs/deployments/demos/zenoh-bridge/index.md index db4a2b4..173b274 100644 --- a/docs/deployments/demos/zenoh-bridge/index.md +++ b/docs/deployments/demos/zenoh-bridge/index.md @@ -1,8 +1,8 @@ -# OpenADKit Remote Visualization with Zenoh Bridge: Implementation Report and User Manual +# Open AD Kit Remote Visualization with Zenoh Bridge: Implementation Report and User Manual ## 1. Introduction -This document provides a comprehensive implementation guide and technical overview for the distributed architecture of the OpenADKit project. The core objective is to separate compute-intensive and lightweight components of an autonomous driving system, enabling deployment across different hardware. For example, the core Autoware software stack runs on the edge side (e.g., vehicle, or a powerful simulation server). Users can remotely visualize and manage Autoware from their laptops or a cloud-based management system. +This document provides a comprehensive implementation guide and technical overview for the distributed architecture of the Open AD Kit project. The core objective is to separate compute-intensive and lightweight components of an autonomous driving system, enabling deployment across different hardware. For example, the core Autoware software stack runs on the edge side (e.g., vehicle, or a powerful simulation server). Users can remotely visualize and manage Autoware from their laptops or a cloud-based management system. To achieve this, we utilize [Zenoh](https://zenoh.io/) as a high-performance, low-latency communication protocol, paired with the [`zenoh-bridge-ros2dds`](https://github.com/eclipse-zenoh/zenoh-plugin-ros2dds) tool to seamlessly connect two ROS 2 (Robot Operating System 2) environments isolated by Docker virtual networks. This manual covers architecture design, setup steps, system startup, and troubleshooting, providing complete operational guidance. @@ -85,7 +85,7 @@ graph TD end %% === External & Cross-Network Connections === - user[fa:fa-user User] -->|"HTTP (Port 6080)"| visualizer + user[fa:fa-user User] -->|"HTTP (Port 6081)"| visualizer edge_bridge -->|"Zenoh Protocol over zenoh_net
Connects to tcp/cloud_zenoh_bridge:7448"| cloud_bridge ``` diff --git a/docs/deployments/samples/index.md b/docs/deployments/samples/index.md index dffc6e3..c249702 100644 --- a/docs/deployments/samples/index.md +++ b/docs/deployments/samples/index.md @@ -2,5 +2,5 @@ Sample deployment configurations to help you get started. Recommended for **learning and development**. -- [Planning Simulation](planning-simulation/index.md) -- [Logging Simulation](logging-simulation/index.md) +- [Planning Simulation](planning-simulation/index.md) - Run the Autoware planning simulation with a sample map. +- [Logging Simulation](logging-simulation/index.md) - Run the Autoware logging simulation with a sample rosbag. diff --git a/docs/deployments/samples/logging-simulation/index.md b/docs/deployments/samples/logging-simulation/index.md index 6233ecd..9d2535b 100644 --- a/docs/deployments/samples/logging-simulation/index.md +++ b/docs/deployments/samples/logging-simulation/index.md @@ -1,69 +1,35 @@ # Autoware Open AD Kit Logging Simulation -This sample deployment shows how to run Autoware Open AD Kit **logging simulation**. +This sample deployment demonstrates the Open AD Kit logging simulation workflow. -## Requirements +## Source of Truth -In order to run the logging simulation, you need to have the logging simulation **sample map** and **rosbag**. You can download them by running the following commands: +The complete operational instructions for this deployment live alongside the deployment assets in [`deployments/samples/logging-simulation/README.md`](https://github.com/autowarefoundation/openadkit/blob/main/deployments/samples/logging-simulation/README.md). -### Sample Logging Map +That README covers: -Download and unpack a logging simulation sample map that is used in this sample. +- sample map and rosbag download and extraction +- required Autoware artifacts +- visualizer access +- startup and shutdown commands -- You can also download [the map](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually. +## Quick Start -```bash -gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI' -unzip -d ~/autoware_map/ ~/autoware_map/sample-map-rosbag.zip -``` - -> **Note**: This sample map(Copyright 2020 TIER IV, Inc.) is only for demonstration purposes. You can use your own map by following the [How-to Guide](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-maps/). - -### Sample Rosbag - -Download and unpack a sample rosbag that is used for **sensor simulation** in this sample. - -- You can also download [the rosbag](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually. +From `deployments/samples/logging-simulation/`: ```bash -gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1sU5wbxlXAfHIksuHjP3PyI2UVED8lZkP' -unzip -d ~/autoware_map/ ~/autoware_map/sample-rosbag.zip +docker compose --env-file logging-simulation.env up -d +docker compose --env-file logging-simulation.env up rosbag -d ``` -> **Note**: Due to privacy concerns, the rosbag(Copyright 2020 TIER IV, Inc.) does not contain image data, which will cause: Traffic light recognition functionality cannot be tested with this sample rosbag. Object detection accuracy is decreased. - -## Run the Deployment - -1. Start the deployment by running the following command: - - ```bash - docker compose --env-file logging-simulation.env up -d - ``` +Open the visualizer at: -2. Wait for the deployment to start for about 5 seconds and then open a browser to visualize the simulation and navigate to: - - ```bash - http://localhost:6080/vnc.html - ``` - - Use the default password `openadkit` to access the visualizer. **It can take a few seconds to visualizer to start.** - - > If your machine is on a remote server, you can access the visualizer by using its accessible IP address: - > - > ```bash - > http://:6080/vnc.html - > ``` - -3. To start the logging simulation, you should run the following command to play the rosbag: - - ```bash - docker compose --env-file logging-simulation.env up rosbag -d - ``` - -## Stop the Deployment +```text +http://localhost:6080/vnc.html +``` -Stop the deployment by running the following command: +To stop the deployment: ```bash docker compose --env-file logging-simulation.env --profile rosbag down -``` \ No newline at end of file +``` diff --git a/docs/deployments/samples/planning-simulation/index.md b/docs/deployments/samples/planning-simulation/index.md index db2f8b9..23fed73 100644 --- a/docs/deployments/samples/planning-simulation/index.md +++ b/docs/deployments/samples/planning-simulation/index.md @@ -1,50 +1,33 @@ # Autoware Open AD Kit Planning Simulation -This sample deployment shows how to run Autoware Open AD Kit **planning simulation**. +This sample deployment demonstrates the Open AD Kit planning simulation workflow. -## Requirements +## Source of Truth -In order to run the planning simulation, you need to have the planning simulation **sample map**. You can download it by running the following commands: +The complete operational instructions for this deployment live alongside the deployment assets in [`deployments/samples/planning-simulation/README.md`](https://github.com/autowarefoundation/openadkit/blob/main/deployments/samples/planning-simulation/README.md). -### Sample Planning Map +That README covers: -Download and unpack a planning simulation sample map that is used in this sample. +- sample map download and extraction +- visualizer access +- startup and shutdown commands -- You can also download [the map](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually. +## Quick Start + +From `deployments/samples/planning-simulation/`: ```bash -gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd' -unzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip +docker compose --env-file planning-simulation.env up -d ``` -> **Note**: This sample map(Copyright 2020 TIER IV, Inc.) is only for demonstration purposes. You can use your own map by following the [How-to Guide](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-maps/). - -## Run the Deployment - -1. Start the deployment by running the following command: - - ```bash - docker compose --env-file planning-simulation.env up -d - ``` - -2. Wait for the deployment to start for about 5 seconds and then open a browser to visualize the simulation and navigate to: +Open the visualizer at: - ```bash - http://localhost:6080/vnc.html - ``` - - Use the default password `openadkit` to access the visualizer. **It can take a few seconds to visualizer to start.** - - > If your machine is on a remote server, you can access the visualizer by using its accessible IP address: - > - > ```bash - > http://:6080/vnc.html - > ``` - -3. After you see the visualizer, you can start the autonomous driving simulation by following the [planning simulation instructions](https://autowarefoundation.github.io/autoware-documentation/main/demos/planning-sim/lane-driving/#2-set-an-initial-pose-for-the-ego-vehicle) in the Autoware documentation. +```text +http://localhost:6080/vnc.html +``` -## Stop the Deployment +To stop the deployment: ```bash docker compose --env-file planning-simulation.env down -``` \ No newline at end of file +``` diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 8b3d6a0..fa27598 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -4,7 +4,7 @@ - Docker Engine - NVIDIA Container Toolkit (Optional but highly recommended for sensing and perception tasks) -- Autoware artifacts (Optional but highly recommended for sensing and perception tasks) +- Autoware artifacts (Optional in general, but required for sensing and perception deployments such as Logging Simulation) > All the above requirements can be installed by running the **setup.sh** script. @@ -31,7 +31,9 @@ sudo ./setup.sh --download-artifacts ``` + > This step is required for deployments that mount `${HOME}/autoware_data`, including the Logging Simulation sample. + ## Next Steps -- [Running a sample deployment](../deployments/) -- [Learn more about the Open AD Kit components](../components/) +- [Running a sample deployment](../deployments/index.md) +- [Learn more about the Open AD Kit components](../components/index.md) diff --git a/docs/hardware/index.md b/docs/hardware/index.md index 8f67900..ed1f1ce 100644 --- a/docs/hardware/index.md +++ b/docs/hardware/index.md @@ -13,7 +13,10 @@ The Open AD Kit supports **amd64** and **arm64** architectures with the followin ## Tested Hardware - [ADLink AADP-AVA](https://www.adlinktech.com/products/Computer_on_Modules/COM-HPC-Server-Carrier-and-Starter-Kit/Ampere_Altra_Developer_Platform) -- [NVIDIA Jetson Orin](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-orin/) (TBD) + +## Planned Validation + +- [NVIDIA Jetson Orin](https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-orin/) ## Tested Cloud Instances diff --git a/docs/index.md b/docs/index.md index 1c2278f..d5e4e5a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Introduction -Open AD Kit adopts a modular, component-based architecture designed for flexibility, scalability, and platform independence. It leverages cloud-native principles and containerization to decompose the [Autoware Universe](https://github.com/autowarefoundation/autoware) into a collection of interoperable components. This approach allows developers to create customized autonomous driving (AD) systems by combining components to meet their specific needs. +Open AD Kit adopts a modular, component-based architecture designed for flexibility, scalability, and platform independence. It leverages cloud-native principles and containerization to decompose [Autoware](https://github.com/autowarefoundation/autoware) into a collection of interoperable components. This approach allows developers to create customized autonomous driving (AD) systems by combining components to meet their specific needs. ## Architecture @@ -16,50 +16,47 @@ Deployments are defined using container orchestration files (e.g., `docker-compo This modular structure allows users to start with a minimal deployment and incrementally add components and tools as their system evolves. -For more details, see the [Deployments](./deployments/). +For more details, see the [Deployments](./deployments/index.md). ## Components -The core functional components of the Open AD Kit are derived from the main **[Autoware Universe](https://github.com/autowarefoundation/autoware_universe)** project. Each component is packaged as an independent containerized component, responsible for a specific aspect of the autonomous driving pipeline. This modular approach provides flexibility in composing different AD systems by combining different components. +The core functional components of the Open AD Kit are derived from the main **[Autoware](https://github.com/autowarefoundation/autoware)** project. Each image packages a focused part of the autonomous driving pipeline, which makes it possible to compose different AD systems from a common container set. -The primary components include: +The primary images include: -- **Sensing**: Collects data from various sensors (Cameras, Lidars, Radars). -- **Perception**: Processes sensor data to detect and track objects in the environment. -- **Mapping**: Creates and maintains maps of the environment. -- **Localization**: Determines the vehicle's position within the map. -- **Planning**: Plans the vehicle's trajectory from its current location to a destination. -- **Control**: Sends commands to the vehicle's actuators to follow the planned trajectory. -- **Vehicle**: Manages the vehicle's internal state and interface. -- **System**: Provides system-level functionalities like health monitoring. +- **Sensing and Perception**: Collects and processes sensor data. +- **Localization and Mapping**: Manages maps and vehicle pose estimation. +- **Planning and Control**: Produces and follows the driving trajectory. +- **Vehicle and System**: Packages vehicle interfaces and system-level services in the `vehicle-system` image. - **API**: Offers an interface for external systems to interact with the vehicle. -- **Simulator**: Allows for testing the AD stack in a virtual environment with ad-hoc simulations. +- **Simulator**: Allows testing the AD stack in a virtual environment. +- **Visualizer**: Provides a browser-accessible RViz environment for remote inspection. -These components communicate with each other over a service mesh, allowing for flexible deployment and scaling. For more details, see the [Autoware components](./components/). +These images communicate through ROS 2 middleware, and some deployments bridge isolated environments with Zenoh. For more details, see the [Autoware components](./components/index.md). ## Tools In addition to the **Autoware components**, Open AD Kit provides essential tools for development, simulation, and visualization. These tools are also containerized and can be integrated into deployments as needed. -- **Scenario Simulator-TBD**: Allows for testing the AD stack in a virtual environment. It supports complex scenario-based simulations for validation and CI/CD. +- **Scenario Simulator**: Runs scenario-based simulations for validation, CI, and local development. -For more details, see the [Tools](./tools/). +For more details, see the [Tools](./tools/index.md). ## Supported Platforms -Open AD Kit supports a variety of platforms as **development** and **SOAFEE production** platforms. +Open AD Kit currently documents Ubuntu as the primary development host and AutoSD as the platform-specific deployment path available in this repository. EWAOL is planned but does not yet ship runnable assets here. ### Development platforms - Ubuntu 22.04, 24.04 -### SOAFEE Production platforms +### Platform-specific deployment paths -- [EWAOL](https://ewaol.docs.arm.com/en/kirkstone-dev/) - [AutoSD](https://docs.centos.org/automotive-sig-documentation/features-and-concepts/) +- [EWAOL](https://ewaol.docs.arm.com/en/kirkstone-dev/) (planned) -For more details, see the [Supported SOAFEE Platforms](./platforms/). +For more details, see the [Supported SOAFEE Platforms](./platforms/index.md). ## Supported Hardware -For detailed information on system requirements, tested hardware, and cloud instances, please refer to the [Hardware](./hardware/) section. +For detailed information on system requirements, tested hardware, and cloud instances, please refer to the [Hardware](./hardware/index.md) section. diff --git a/docs/platforms/autosd/planning-simulator/index.md b/docs/platforms/autosd/planning-simulator/index.md index 8425691..74037b3 100644 --- a/docs/platforms/autosd/planning-simulator/index.md +++ b/docs/platforms/autosd/planning-simulator/index.md @@ -5,5 +5,5 @@ This folder shows how to run and test scenario with containers managed by System ## Folder Structure * `aib`: automotive-image-builder manifest files to build an AutoSD image -* `components`: quadlet files to run Open Ad Kit inside container in an AutoSD image +* `components`: quadlet files to run Open AD Kit inside container in an AutoSD image * `docs`: extra documentation files, such as architecture diagrams diff --git a/docs/platforms/ewaol/index.md b/docs/platforms/ewaol/index.md index 5fea4a7..09d2db9 100644 --- a/docs/platforms/ewaol/index.md +++ b/docs/platforms/ewaol/index.md @@ -1,3 +1,9 @@ # EWAOL -Instructions on how to run Open AD Kit on EWAOL will be provided here (TBD). \ No newline at end of file +EWAOL is a planned Open AD Kit target, but this repository does not yet contain EWAOL-specific deployment assets, container orchestration files, or step-by-step runtime instructions. + +Current status: + +- AutoSD is the platform-specific workflow implemented in this repository today. +- EWAOL support is still being scoped. +- This page will be expanded once runnable EWAOL assets land in the tree. diff --git a/docs/platforms/index.md b/docs/platforms/index.md index 9b35734..86a7c5c 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -1,6 +1,6 @@ # Supported Platforms -As the Autoware Open AD Kit is the first [SOAFEE](https://www.soafee.io/) blueprint for the software defined vehicle ecosystem, it supports a variety of platforms as core SOAFEE platforms. +As the Autoware Open AD Kit is the first [SOAFEE](https://www.soafee.io/) blueprint for the software defined vehicle ecosystem, it tracks multiple platform directions. The repository currently contains runnable assets for AutoSD; EWAOL remains a documented target rather than an implemented one. Here is an explanatory blog post on the [benefits of open standards in automotive development](https://www.soafee.io/blog/2025/the-benefits-of-open-standards-in-automotive-development/). @@ -16,4 +16,4 @@ Instructions on how to build and deploy Open AD Kit on AutoSD can be found in th The Edge Workload Abstraction and Orchestration Layer (EWAOL) is a standards-based, container-centric framework for deploying and orchestrating applications on edge platforms, delivered via the `meta-ewaol` Yocto layer to build distribution images. It organizes the stack into user-defined containerized application workloads (deployed by end users), an EWAOL Linux filesystem that provides core services such as Docker, K3s, and Xen along with validation and development tooling, and platform-specific system software (firmware, bootloader, OS, and optional Xen) integrated from `meta-arm`, `meta-arm-bsp`, and `meta-virtualization`. EWAOL is the reference implementation for SOAFEE, extending cloud-native methods to automotive with an emphasis on real-time and functional safety. -Instructions on how to run Open AD Kit on EWAOL can be found in the [EWAOL folder](ewaol/index.md) (TBD). +The [EWAOL page](ewaol/index.md) currently captures project intent and status only. Runnable deployment instructions are still planned. diff --git a/docs/tools/index.md b/docs/tools/index.md index 0a692f1..083b5ea 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -2,6 +2,8 @@ Open AD Kit includes containerized third-party tools for testing, deploying, and managing autonomous driving systems. These tools complement the **Autoware components** and can be integrated into deployments as needed. -## Scenario Simulator - TBD +## Scenario Simulator -The [Tier IV Scenario Simulator](https://tier4.github.io/scenario_simulator_v2-docs/) is a tool that enables users to test their autonomous driving system in a virtual environment. It uses a scenario runner to run more complex simulations based on predefined scenarios. It is often run automatically for continuous integration purposes, but can also be run on a local machine. +The [Tier IV Scenario Simulator](https://tier4.github.io/scenario_simulator_v2-docs/) enables users to test their autonomous driving system in a virtual environment. It uses a scenario runner to execute more complex simulations based on predefined scenarios, and it can be used both in CI and on a local machine. + +The container entrypoint and supported environment variables are documented in the repository's [Scenario Simulator README](https://github.com/autowarefoundation/openadkit/blob/main/tools/scenario-simulator/README.md). diff --git a/platforms/README.md b/platforms/README.md index 9036ef1..9605fce 100644 --- a/platforms/README.md +++ b/platforms/README.md @@ -3,4 +3,4 @@ This directory contains platform specific deployment configurations for **Open AD Kit**. Each folder contains a README file with detailed instructions on how to deploy the deployment configuration for the specific platform. - [AutoSD](./autosd/README.md): How to build and deploy Open AD Kit components in AutoSD -- EWAOL (TBD): How to run Open AD Kit components on EWAOL +- EWAOL (planned): Target platform under discussion; runnable assets are not yet present in this repository diff --git a/tools/README.md b/tools/README.md index 0064057..b7cd13f 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,3 +1,5 @@ -# Open AD Kit Tools -TBD +# Open AD Kit Tools -This directory offers tools for Open AD Kit to make development and deployment easier. These tools are also containerized and can be integrated into deployments as needed. +This directory contains containerized tools that complement the core Open AD Kit images. + +- [Scenario Simulator](./scenario-simulator/README.md): Runs Tier IV Scenario Simulator in a container for scenario-based validation and local testing.