Add example run OTNS with OT-BR and Matter accessories. by francoismichel · Pull Request #784 · openthread/ot-ns

francoismichel · 2026-04-17T18:29:52Z

Here is an example allowing to run OT-BR in OTNS, routing over the infrastructure interface, and run simulated Matter nodes in the mesh. This allows real processes and real devices to communicate with simulated nodes (including Matter nodes) running in OTNS.

The README contains a tutorial. The Dockerfile currently uses a fork of OT-NS and a fork of Matter and applies a patch to these forks as well. Once these forks and patches get intergrated into the mainline repos, we will update this example accordingly.

google-cla · 2026-04-17T18:30:09Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

The README contains a tutorial. The Dockerfile currently uses a fork of OT-NS and a fork of Matter and applies a patch to these forks as well. Once these forks and patches get intergrated into the mainline repos, we will update this example accordingly.

gemini-code-assist

Code Review

This pull request introduces a Docker-based development environment for simulating Thread networks using OTNS, Matter, and OT-BR. It includes a multi-stage Dockerfile, a helper script for cross-platform execution, and detailed documentation. Review feedback identified a critical issue with an invalid Go version that would prevent the build, a potential configuration conflict caused by hardcoding the network interface name in the OTBR setup, and a suggestion to parameterize the Docker image name for better flexibility.

gemini-code-assist · 2026-04-17T18:32:23Z

+FROM ubuntu:24.04
+
+ARG TARGETARCH
+ARG GO_VERSION=1.26.2


The Go version 1.26.2 is invalid as it has not been released yet (the current stable version is 1.23.x). This will cause the wget command at line 80 to fail, preventing the Docker image from building.

ARG GO_VERSION=1.23.4

@francoismichel While I would ignore this comment :) , OTNS is built and tested for Go 1.23 currently. Maybe it doesn't matter much, but Go 1.23 may be sufficient.

I'm seeing this from https://go.dev/doc/devel/release#go1.26.minor :

go1.26.2 (released 2026-04-07) includes security fixes to the go command, the compiler, and the archive/tar, crypto/tls, crypto/x509, html/template, and os packages, as well as bug fixes to the go command, the go fix command, the compiler, the linker, the runtime, and the net, net/http, and net/url packages. See the Go 1.26.2 milestone on our issue tracker for details

I had to use a recent version of go because the go compiler had errors when cross-compiling from arm64 to amd64 that got fixed in the latest versions.

ok, resolving the comment

gemini-code-assist · 2026-04-17T18:32:23Z

+    INFRA_IF_NAME=eth0 WEB_GUI=1 NAT64=1 OTBR_MDNS=mDNSResponder ./script/bootstrap
+
+# Stub systemctl so setup doesn't try to start/enable services during docker build
+RUN ln -sf /bin/true /usr/local/bin/systemctl
+
+# Run setup to install binaries, DBus config, ot-ctl, etc.
+RUN HOME=/root && cd /home/otns/ot-br-posix && \
+    INFRA_IF_NAME=eth0 WEB_GUI=1 NAT64=1 OTBR_MDNS=mDNSResponder DOCKER=1 FIREWALL=0 ./script/setup


Hardcoding INFRA_IF_NAME=eth0 during the OTBR setup phase can cause issues when running the container on Linux hosts with --network host (as configured in run-docker.sh), where the primary network interface might not be named eth0. While the entrypoint script attempts to detect the backbone interface at runtime, the OTBR configuration generated during script/setup (e.g., agent options, firewall rules) may still contain hardcoded references to eth0.

Consider using a BUILD_ARG for the interface name or updating the configuration dynamically in the entrypoint script.

gemini-code-assist · 2026-04-17T18:32:23Z

+
+set -e
+
+IMAGE_NAME="framichel/otns-matter"


The IMAGE_NAME is hardcoded to a specific user's Docker Hub namespace (framichel/). For a generic example in the repository, it is better to use a more neutral name or allow it to be overridden via an environment variable.

Suggested change

IMAGE_NAME="framichel/otns-matter"

IMAGE_NAME="${OTNS_MATTER_IMAGE:-otns-matter}"

jwhui · 2026-04-17T18:36:28Z

@@ -0,0 +1,169 @@
+# OTNS + Matter + OT-BR Docker Environment


@Vyrastas , can you help review this README?

jwhui · 2026-04-17T18:36:55Z

@@ -0,0 +1,86 @@
+#!/bin/bash


Add standard OpenThread license header.

Done in b5f6bfc

jwhui · 2026-04-17T18:37:07Z

@@ -0,0 +1,408 @@
+# Dockerfile for OTNS + OT-BR + Matter all-clusters-app development environment


Add standard OpenThread license header.

Done in b5f6bfc

Vyrastas

Apologies for the delay in reviewing!

Vyrastas · 2026-04-21T18:08:54Z

+docker build -t otns-matter .
+```
+
+The build takes a long time (compiling OpenThread, Matter, OT-BR from source).


"Long time" is vague, can you provide a rough estimate of what to expect?

Also, you can drop the parentheses and do something like

"Because the build compiles OpenThread, Matter, and OT-BR from source, it may take up to X minutes."

Data point: In my case it was ~31 minutes (on a fast network, fast laptop)

Vyrastas · 2026-04-21T18:09:29Z

+
+## Run
+
+If you haven't built the image in the previous step, it will pull the image from Docker Hub.


Suggested change

If you haven't built the image in the previous step, it will pull the image from Docker Hub.

If you didn't build the image in the previous step, running will pull the image from Docker Hub.

Vyrastas · 2026-04-21T18:09:48Z

+
+## Using OTNS inside the container
+
+The entrypoint auto-detects the backbone interface and prints the recommended


Suggested change

The entrypoint auto-detects the backbone interface and prints the recommended

The entry point auto-detects the backbone interface and prints the recommended

Vyrastas · 2026-04-21T18:10:11Z

+otns -realtime -listen 0.0.0.0:9000 -otbr-backbone-if eth0
+```
+
+Or just type `otns` — the entrypoint sets up an alias with the right flags.


Suggested change

Or just type `otns` — the entrypoint sets up an alias with the right flags.

Or just type `otns` — the entry point sets up an alias with the correct flags.

Vyrastas · 2026-04-21T18:12:45Z

+
+- **FTD nodes** — regular Thread Full Thread Devices
+- **OTBR nodes** — Thread Border Routers (with border routing and SRP server)
+- **Matter nodes** — Matter all-clusters-app devices running over Thread


Can you use code font for instances of all-clusters-app?

Vyrastas · 2026-04-21T18:15:32Z

+- Advertise an OMR prefix in Thread network data
+- Run an SRP server and advertise it in Thread network data
+
+(Requires `-otbr-backbone-if` to be set to a valid interface.)


You can remove the parentheses and just have a normal sentence here

This requires -otbr-backbone-if to be set...

Vyrastas · 2026-04-21T18:16:25Z

+
+### 2. Install chip-tool
+
+The chip-tool is used to commission and control Matter accessories. You can either install it from snap or build it from source.


When referring to a binary / command, use code font, so snap should be in code font

Vyrastas · 2026-04-21T18:16:39Z

+The binary will be at `out/linux-x64-chip-tool/chip-tool`.
+For arm64 hosts, replace `x64` with `arm64`.
+
+### 3. Commission and control a Matter lightbulb


Suggested change

### 3. Commission and control a Matter lightbulb

### 3. Commission and control a Matter light bulb

Vyrastas · 2026-04-21T18:17:12Z

+4. Add as many other nodes as you want: click on "router" or type `add router`
+   in the OTNS CLI
+5. Monitor the announced services from the Linux VM (outside the container) using `avahi-browse -a`.
+   Wait until a `_matterc._udp` service shows up, meaning that the Matter node has registered its SRP service on the OTBR node. Once that is donem you can start pairing and controlling the accessory.


Suggested change

Wait until a `_matterc._udp` service shows up, meaning that the Matter node has registered its SRP service on the OTBR node. Once that is donem you can start pairing and controlling the accessory.

Wait until a `_matterc._udp` service shows up, meaning that the Matter node has registered its SRP service on the OTBR node. Once that is done you can start pairing and controlling the accessory.

Please also adjust the line breaks here for readability

Vyrastas · 2026-04-21T18:17:56Z

+./chip-tool onoff read on-off 1234 1
+```
+
+The `1234` is the node ID (assigned during pairing), it must be different for every matter node. The `1` is the endpoint ID. It is always `1` for every node.


Adjust line breaks for readability please

Added instructions to remove 'docker.io' prefix from image tag.

EskoDijk · 2026-04-23T08:08:33Z

@francoismichel Could we also add early on in the README, something like:
if you got the Docker image as a tar.gz file, then first load it in Docker using

docker load < matter-otbr-example-docker.tar.gz

francoismichel force-pushed the matter-otbr-example branch from 6e1a84a to 9f48bef Compare April 17, 2026 18:32

gemini-code-assist Bot reviewed Apr 17, 2026

View reviewed changes

jwhui requested a review from Vyrastas April 17, 2026 18:36

jwhui reviewed Apr 17, 2026

View reviewed changes

add OTNS license headers

b5f6bfc

Vyrastas requested changes Apr 21, 2026

View reviewed changes

Francois Michel and others added 4 commits April 22, 2026 16:43

add automation script and update README to show how to use it

499ad97

Update README.md

6f38cfb

Update README with Docker image tagging instructions

fa0e29d

Added instructions to remove 'docker.io' prefix from image tag.

Fix typo in README.md regarding Docker image tagging

6b9ecab

Clarify optional loading of existing image in README

2993095

	IMAGE_NAME="framichel/otns-matter"
	IMAGE_NAME="${OTNS_MATTER_IMAGE:-otns-matter}"

		@@ -0,0 +1,408 @@
		# Dockerfile for OTNS + OT-BR + Matter all-clusters-app development environment


		## Run

		If you haven't built the image in the previous step, it will pull the image from Docker Hub.

	If you haven't built the image in the previous step, it will pull the image from Docker Hub.
	If you didn't build the image in the previous step, running will pull the image from Docker Hub.


		## Using OTNS inside the container

		The entrypoint auto-detects the backbone interface and prints the recommended

	The entrypoint auto-detects the backbone interface and prints the recommended
	The entry point auto-detects the backbone interface and prints the recommended

	Or just type `otns` — the entrypoint sets up an alias with the right flags.
	Or just type `otns` — the entry point sets up an alias with the correct flags.


		### 2. Install chip-tool

		The chip-tool is used to commission and control Matter accessories. You can either install it from snap or build it from source.

	### 3. Commission and control a Matter lightbulb
	### 3. Commission and control a Matter light bulb

	Wait until a `_matterc._udp` service shows up, meaning that the Matter node has registered its SRP service on the OTBR node. Once that is donem you can start pairing and controlling the accessory.
	Wait until a `_matterc._udp` service shows up, meaning that the Matter node has registered its SRP service on the OTBR node. Once that is done you can start pairing and controlling the accessory.

Conversation

francoismichel commented Apr 17, 2026

Uh oh!

google-cla Bot commented Apr 17, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Vyrastas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EskoDijk commented Apr 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants