Technical review from @tgonzalezorlandoarm (DevX Topo team)

matt-cossins · web-flow · commit 3160cf2e9201 · 2026-04-22T10:40:27.000+01:00
Suggest changes to the Topo Learning Path
diff --git a/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/_index.md b/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/_index.md
@@ -3,7 +3,7 @@ title: Deploy containerized workloads to Arm-based Linux targets with Topo
 
 description: Learn how to use Topo to detect device capabilities, select a compatible template, and deploy containerized workloads to Arm-based Linux targets over SSH.
 
-minutes_to_complete: 45
+minutes_to_complete: 30
 
 who_is_this_for: This is an introductory topic for embedded, edge, and cloud software developers who want to easily deploy containerized workloads to Arm-based Linux targets with Topo.
 
diff --git a/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/assess-compatibility.md b/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/assess-compatibility.md
@@ -8,6 +8,56 @@ layout: learningpathall
 
 ## Run Topo health checks
 
+### Prepare host environment
+
+Confirm that the required dependencies are available on the host by running this command in your host terminal:
+
+```bash
+topo health
+```
+
+The output should appear similar to the following:
+
+```bash
+Host
+----
+SSH: ✅ (ssh)
+Container Engine: ✅ (docker)
+
+Target
+------
+ℹ️ provide --target or set TOPO_TARGET to check target health
+```
+
+If Docker is missing, please use [Install Docker](https://learn.arm.com/install-guides/docker/).
+
+If SSH is missing, please use [Install SSH](https://learn.arm.com/install-guides/ssh/).
+
+## Prepare target environment
+
+Now that the host device is prepared, we will setup the target. On the host device, connect to your target with SSH.
+
+```bash
+ssh user@your-target
+```
+
+Once connected to the target, use the following commands to verify both Docker and `lscpu` are installed:
+
+```bash
+docker --version
+lscpu
+```
+
+The output should apear similar to the following:
+
+```output
+Docker version xx.x.x
+Architecture:             aarch64
+CPU(s):                   ...
+```
+
+### Prepare Topo for target
+
 We will now run a health check against your target. Run the following command from the terminal of your host device.
 
 If you are using your host device simultaneously as your target, use `topo health --target localhost`.
@@ -21,19 +71,22 @@ The output should appear similar to:
 ```output
 Host
 ----
-SSH: ✅
-Container Engine: ✅
+SSH: ✅ (ssh)
+Container Engine: ✅ (docker)
 
 Target
 ------
 Connectivity: ✅
-Container Engine: ✅
-Hardware Info: ✅
+Container Engine: ✅ (docker)
+Remoteproc Runtime: ✅ (remoteproc-runtime)
+Remoteproc Shim: ✅ (containerd-shim-remoteproc-v1)
+Hardware Info: ✅ (lscpu)
+Subsystem Driver (remoteproc): ✅ (m33, m0)
 ```
 
 A Topo health check confirms connectivity between the host and target, as well as the verifying the presence of dependencies such as docker.
 
-You should resolve any `❌` errors before moving on. Warnings (`⚠️`) can indicate optional capabilities you can add later. `ℹ️` provides other information. A `✅` confirms the presence of dependencies and no warnings or errors.
+You should resolve any `❌` errors before moving on. Warnings (⚠️) can indicate optional capabilities that may be needed in certain projects. `ℹ️` provides other information. A `✅` confirms the presence of dependencies and no warnings or errors.
 
 If you are using password-based SSH, you will likely see the `❌` error below:
 
@@ -48,9 +101,9 @@ This is because Topo requires key-based SSH. You can use the command specified a
 
 If using a Cortex-A + Cortex-M device, such as the i.MX 93, you may see a `⚠️` warning if `remoteproc-runtime` is not installed on the target.
 
-[`remoteproc`](https://docs.kernel.org/staging/remoteproc.html) is a Linux kernel framework for managing remote / auxiliary processors in a heterogeneous SoC. It allows the main CPU (e.g., Cortex-A) to load firmware on to the auxiliary processors (e.g., Cortex-M), start and stop them, and to communicate with them (e.g. using `rpmsg`).
+[`remoteproc`](https://docs.kernel.org/staging/remoteproc.html) is a Linux kernel framework for managing remote / auxiliary processors in a heterogeneous SoC. It allows the main CPU (e.g., Cortex-A) to load firmware on to the auxiliary processors (e.g., Cortex-M), start and stop them, and to communicate with them (e.g. using [`rpmsg`](https://docs.kernel.org/staging/rpmsg.html)).
 
-[`remoteproc-runtime`](https://github.com/arm/remoteproc-runtime) builds on this by adding a container-style (OCI) interface. This lets you package and manage firmware like container images using standard tools (e.g. Docker or containerd), even though the code runs as firmware on the Cortex-M. OCI (Open Container Initiative) defines open standards for container image formats and runtimes, ensuring compatibility across container tools.
+[`remoteproc-runtime`](https://github.com/arm/remoteproc-runtime) builds on this by adding a container-style (OCI - Open Container Initiative) interface. This lets you package and manage firmware like container images using standard tools (e.g. Docker or containerd), even though the code runs as firmware on the Cortex-M. [OCI](https://opencontainers.org/) defines open standards for container image formats and runtimes, ensuring compatibility across container tools.
 
 You can use Topo to install `remoteproc-runtime`. Run the following command from the host device:
 
@@ -62,7 +115,7 @@ Run the health command again to verify installation. Topo uses `remoteproc-runti
 
 ## Generate a target description
 
-In this step, you ask Topo to probe your target hardware and create a machine-readable YAML description.
+In this step, you ask Topo to probe your target and create a machine-readable YAML description of the hardware.
 
 On your host device, run:
 
@@ -121,7 +174,7 @@ An example output for an AWS Graviton instance is shown below:
   displays a lightbulb in either the on or off state. The lightbulb state is
   described by an LLM in any user-specified style.
 
-✅ topo-v9-cpu-chat | https://github.com/Arm-Examples/topo-v9-cpu-chat.git | main
+✅ topo-cpu-ai-chat | https://github.com/Arm-Examples/topo-cpu-ai-chat.git | main
   Features: SVE, NEON
   Complete LLM chat application optimized for Arm CPU inference.
 
diff --git a/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/deploy-workload.md b/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/deploy-workload.md
@@ -13,7 +13,7 @@ Choose one of the pre-existing templates that is compatible with your target har
 To use a template, we clone it from git on our host device by running the following command:
 
 ```bash
-topo clone template:topo-v9-cpu-chat
+topo clone https://github.com/Arm-Examples/topo-cpu-ai-chat.git
 ```
 
 If a template asks for build arguments, Topo prompts you interactively.
@@ -29,7 +29,7 @@ services:
     build:
       context: ./llama-inference
       args:
-        ENABLE_SVE: ON
+        ENABLE_SVE: OFF
         HF_MODEL: bartowski/Qwen_Qwen3.5-0.8B-GGUF
         HF_MODEL_FILE: ""
     ports:
@@ -45,7 +45,7 @@ services:
     build:
       context: ./simple-chat
       args:
-        ENABLE_SVE: ON
+        ENABLE_SVE: OFF
     depends_on:
       llama-server:
         condition: service_healthy
@@ -76,10 +76,10 @@ Changes can be made to the `compose.yaml` files to adjust arguments after the fa
 
 ## Deploy the app on the target
 
-On your host device, enter the project directory created by the `topo clone` command. In the case of the LLM chatbot, this directory is `topo-v9-cpu-chat`:
+On your host device, enter the project directory created by the `topo clone` command. In the case of the LLM chatbot, this directory is `topo-cpu-ai-chat`:
 
 ```bash
-cd topo-v9-cpu-chat/
+cd topo-cpu-ai-chat/
 ```
 
 Then use `topo deploy` to automatically build the container images on the host, transfer the images to the target via SSH, and start the application on the target:
@@ -112,4 +112,4 @@ Topo is packaged as a single executable with a `README.md` file. It is straightf
 
 Choose your preferred agent. If you do not have a CLI Agent pre-configured, you can follow our guides to [Install Codex](https://learn.arm.com/install-guides/codex-cli/), [Install Claude Code](https://learn.arm.com/install-guides/claude-code/), or [Install Gemini](https://learn.arm.com/install-guides/gemini/).
 
-Once your agent is ready, ensure you have setup your host and target to have the required dependencies. Then ask your agent to leverage Topo to deploy an application to your target device.
+Once your agent is ready, ensure you have setup your host and target to have the required dependencies. Then ask your agent to leverage Topo to deploy an application to your target device.
diff --git a/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/overview-and-setup.md b/content/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/overview-and-setup.md
@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## What is Topo?
 
-[Topo](https://github.com/arm/topo) is an open-source command-line tool, developed by Arm. Topo connects from a host device (e.g., your development laptop) to an Arm-based Linux target (e.g., a Raspberry Pi) over SSH, detects hardware capabilities, and allows the user to deploy compatible containerized workloads with ease. Topo builds container images on the host, transfers them to the target, and starts the services on the target. The public repository showcases several pre-built template workloads you can deploy, including a "Hello World" webpage, an LLM Chatbot, and a SIMD Benchmark comparing Scalar, Neon, and the Scalable Vector Extension (SVE).
+[Topo](https://github.com/arm/topo) is an open-source command-line tool, developed by Arm. Topo connects from a host device (e.g., your development laptop) to an Arm-based Linux target (e.g., a Raspberry Pi) over SSH, detects hardware capabilities, and allows the user to deploy compatible containerized workloads with ease. Topo builds container images on the host, transfers them to the target, and starts the services on the target. Building and deploying on target is also possible. Topo also showcases several sample templates defining workloads you can deploy, including a "Hello World" webpage, an LLM Chatbot, and a SIMD Benchmark comparing Scalar, Neon, and the Scalable Vector Extension (SVE).
 
 [Topo templates](https://github.com/arm/topo-template-format) are based on the [Compose Specification](https://github.com/compose-spec/compose-spec), extended with `x-topo` metadata that describes requirements such as CPU features and build arguments. The Compose Specification is a standard, YAML-based format for describing how to run multi-container applications. Instead of manually starting containers one-by-one, you define everything in a single file that includes which services to run, what images to use, how they connect, and what configuration they need.
 
@@ -18,11 +18,14 @@ The optional heterogeneous deployment with `remoteproc-runtime` requires a heter
 
 ## Why use Topo?
 
-Topo streamlines deploying pre-existing containerized workloads to new Arm-based Linux devices. Once a template is defined, use of Topo removes the need to deal with low-level setup and compatibility issues manually. Topo first assesses the system to identify processor features such as SVE or Neon on CPU, then advises which templates are appropriate for the device, before automating the deployment.
+Topo streamlines deploying containerized workloads to Arm-based Linux devices.
+If you have an heterogeneous device (e.g. Cortex-A + Cortex-M SoC such as the i.MX 93), Topo enables you to use it fully, deploying both firmware and application as containerized workloads through standard container tooling.
+
+Once a template is defined, use of Topo removes the need to deal with low-level setup and compatibility issues manually. Topo first assesses the system to identify processor features such as SVE or Neon on CPU, then advises which templates are appropriate for the device, before automating the end to end deployment, for which Topo deals with all the low-level instructions.
 
 Topo can also be leveraged by AI Agents to further streamline and automate.
 
-## Prepare host environment
+## Install Topo
 
 In this step, you install Topo on the host, along with other dependencies.
 
@@ -47,47 +50,6 @@ topo --help
 
 You should see an output confirming Topo is present, and describing the available commands.
 
-Confirm that the required dependencies are available on the host bu running these commands in your host terminal:
-
-```bash
-ssh -V
-docker --version
-```
-
-You should see an output confirming version numbers, for example:
-
-```output
-OpenSSH_x.x
-Docker version xx.x.x
-```
-
-If Docker is missing, please use [Install Docker](https://learn.arm.com/install-guides/docker/).
-
-If SSH is missing, please use [Install SSH](https://learn.arm.com/install-guides/ssh/).
-
-## Prepare target environment
-
-Now that the host device is prepared, we will setup the target. On the host device, connect to your target with SSH.
-
-```bash
-ssh user@your-target
-```
-
-Once connected to the target, use the following commands to verify both Docker and `lscpu` are installed:
-
-```bash
-docker --version
-lscpu
-```
-
-The output should apear similar to the following:
-
-```output
-Docker version xx.x.x
-Architecture:             aarch64
-CPU(s):                   ...
-```
-
 ## What you've completed and what's next
 
-You have now prepared both your host and target for use with Topo. In the next step, you will utilize Topo to probe your target device for features, assessing its compability with template containerized workloads.
+You have now installed Topo on your host. In the next step, you will utilize Topo to prepare your host machine and to probe your target device for features, assessing its compability with template containerized workloads.
