Application Initialization & Command Line Options#

This guide describes configuring and running the all-devices-app executable.

The application builds its data model at runtime based on command-line arguments.

Prerequisite: Building from Source#

Before executing any commands, activate your build environment and compile the application from scratch:

source scripts/activate.sh
./scripts/build/build_examples.py --target linux-x64-all-devices-clang build

The compiled executable will be located at ./out/linux-x64-all-devices-clang/all-devices-app.

Startup Architecture#

When the application boots, it executes the following sequence:

Option Parsing: Reads CLI flags via AppOptions::GetOptions() to determine the required storage layer, network ports, and runtime endpoint composition.
Platform App Main Loop: Initializes the Matter POSIX/Platform server stack (AppMain()).
Endpoint Instantiation: For each --device, the runtime instantiates the device using DeviceFactory and registers it with the Interaction Model.

Core Runtime Composition#

Unlike static Matter targets, all-devices-app allows you to dynamically assemble your exact endpoint structure at boot using the --device option.

`--device <type>[:<endpoint>][,parent=<parentId>]`#

Instantiates a specific simulated device feature on the Matter server. This flag can be repeated multiple times to build composite or multi-endpoint topologies.

<type>: The registered runtime key (e.g., contact-sensor, dimmable-light, occupancy-sensor).
:<endpoint> (Optional): Assigns an explicit endpoint index. If omitted, the runtime automatically assigns an incrementing ID starting from 1.
,parent=<parentId> (Optional): Attaches this endpoint as a child of another endpoint, establishing a logical tree composition (such as attaching a Speaker to a parent Chime or building an Aggregator bridge).

[!TIP] This application inherits the Matter SDK’s complete baseline option parser. For the complete, live list of available network commissioning (--wifi, --ble-controller), operational binding (--port, --interface-id), descriptor (--discriminator, --vendor-id), and persistent storage (--KVS) arguments, execute the binary with --help:
./out/linux-x64-all-devices-clang/all-devices-app --help

Practical Operating Recipes#

Recipe 1: Booting a Clean Composite Tree Device#

When launching new multi-endpoint devices, always wipe your previous persistent storage to ensure the server doesn’t reload stale data model definitions:

# Safely wipe the default storage file
rm -rf /tmp/chip_all_devices_kvs

# Boot an explicit Chime on Endpoint 1 and attach a Speaker on Endpoint 2 as its child
./out/linux-x64-all-devices-clang/all-devices-app --device chime:1 --device speaker:2,parent=1

Recipe 2: Running Multiple Simulators Concurrently#

To launch multiple independent simulator processes side-by-side on the same host interface without socket or commissioning collisions, provide distinct UDP ports, storage paths, and Setup Discriminators:

# Boot Instance Alpha (Default settings)
./out/linux-x64-all-devices-clang/all-devices-app \
    --device occupancy-sensor:1 \
    --KVS /tmp/chip_kvs_alpha \
    --port 5540 \
    --discriminator 3840

# Boot Instance Beta (Isolated settings)
./out/linux-x64-all-devices-clang/all-devices-app \
    --device contact-sensor:1 \
    --KVS /tmp/chip_kvs_beta \
    --port 5541 \
    --discriminator 3841

Application Initialization & Command Line Options

Contents