---
title: "Your first topology"
description: "Describe a small sample vehicle from two DBC files, instantiate three of its ECUs as mocks and RemotiveBrokers, then build, run, and view it in RemotiveStudio."
source: https://developer.remotivelabs.com/docs/get-started/first-topology
last_updated: 2026-11-20
---

# Your first topology

This guide takes you through the [workflow](https://developer.remotivelabs.com/docs/remotive-topology.md#workflow) with a minimal example: you describe the platform from two DBC files, choose three ECUs to run, build and run the topology, and inspect the vehicle and view live CAN signals in RemotiveStudio. It takes about 15 minutes.

Before you start, [install RemotiveTopology](https://developer.remotivelabs.com/docs/get-started/install.md) and make sure that `remotive topology subscription status` shows an active subscription.

You can also try cloning [`getting_started`](https://github.com/remotivelabs/remotivelabs-topology-examples/tree/main/getting_started) example which also includes a [behavioral model](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus/behavioral-models.md) and a simple [test](https://developer.remotivelabs.com/docs/remotive-topology/usage/test.md).

## The sample vehicle

The sample vehicle has a hazard light function that involves three ECUs on two CAN buses:

- The steering column control module (`SCCM`) sends the state of the hazard light button on `DriverCan`.
- The body control module (`BCM`) receives the button state and sends turn light requests on `BodyCan`.
- The front light control module (`FLCM`) receives the turn light requests and turns on the lights.

```mermaid
sequenceDiagram
    SCCM -->> BCM : HazardLightButton
    Note over SCCM, BCM: DriverCan
    BCM -->> FLCM : TurnLightControl
    Note over BCM, FLCM: BodyCan
```

## Set up the project

Create a folder for the project with this layout:

```
my-vehicle/
├── databases/
│   ├── body_can.dbc
│   └── driver_can.dbc
└── topology/
    ├── vehicle.platform.yaml
    └── main.instance.yaml
```

Download the two DBC files into `databases/`:

- [driver_can.dbc](https://developer.remotivelabs.com/files/remotive-topology/sample-vehicle/driver_can.dbc)
- [body_can.dbc](https://developer.remotivelabs.com/files/remotive-topology/sample-vehicle/body_can.dbc)

Then initialize a [workspace](https://developer.remotivelabs.com/docs/remotive-topology/concepts/workspace.md) in the project folder. Run all `remotive topology` commands in this folder:

```sh
cd my-vehicle
remotive topology workspace init
```

## Describe the platform

The platform describes which ECUs exist and how they communicate. Start with the information you already have, in this case the DBC files. This is the frame that `SCCM` sends in `driver_can.dbc`:

```
BO_ 100 HazardLightButton: 1 SCCM
 SG_ HazardLightButton : 0|1@1+ (1,0) [0|1] ""  BCM
```

It tells RemotiveTopology that `SCCM` sends the frame `HazardLightButton`, and that `BCM` receives its signal. In other words, there are two ECUs, `SCCM` and `BCM`, on the same CAN bus. The frame is also cyclic: the `GenMsgCycleTime` attribute at the end of the file says that it's sent every 50 ms.

In the same way, `body_can.dbc` has the frame `TurnLightControl`, which `BCM` sends to `DIM`, `FLCM`, `RLCM`, and `GWM`:

```
BO_ 103 TurnLightControl: 1 BCM
  SG_ LeftTurnLightRequest : 0|1@1+ (1,0) [0|1] ""  DIM, FLCM, RLCM, GWM
  SG_ RightTurnLightRequest : 1|1@1+ (1,0) [0|1] ""  DIM, FLCM, RLCM, GWM
```

A DBC file doesn't name the CAN bus it describes, so you name the channels in a platform file, `topology/vehicle.platform.yaml`:

```yaml
schema: remotive-topology-platform:0.18
channels:
  DriverCan:
    type: can
    database: ../databases/driver_can.dbc

  BodyCan:
    type: can
    database: ../databases/body_can.dbc
```

Paths are relative to the file that contains them. To see what RemotiveTopology understands from the platform, run:

```sh
remotive topology show platform topology/vehicle.platform.yaml
```

The output lists the two channels and the six ECUs from the DBC files, and which channels each ECU is connected to:

```mermaid
---
config:
  class:
    hideEmptyMembersBox: true
---
    classDiagram

    class SCCM
    class BCM
    class DIM
    class FLCM
    class RLCM
    class GWM

    class DriverCan {
        <<CAN bus>>
    }

    class BodyCan {
        <<CAN bus>>
    }

    SCCM -- DriverCan
    BCM -- DriverCan
    BCM -- BodyCan
    DIM -- BodyCan
    FLCM -- BodyCan
    RLCM -- BodyCan
    GWM -- BodyCan
```

Read more in [Describing the platform](https://developer.remotivelabs.com/docs/remotive-topology/concepts/platform.md).

## Instantiate the platform

You don't need to run the whole platform. The instance file chooses which ECUs to run and how each one is implemented. Create `topology/main.instance.yaml`:

```yaml
schema: remotive-topology-instance:0.18

platform:
  includes:
    - ./vehicle.platform.yaml

ecus:
  SCCM:
    mock: {}
  BCM:
    mock: {}
  FLCM: {}
```

This runs three ECUs:

- `SCCM` and `BCM` are [mocks](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus/mocks.md). A mock sends all cyclic frames that the ECU sends according to the DBC files, with default values. Your tests can then change the values. Together, mocks make up a restbus simulation: realistic traffic from the ECUs around the one you're interested in.
- `FLCM` has no implementation. RemotiveTopology runs a RemotiveBroker that's connected to `BodyCan` as `FLCM`, so you can see what `FLCM` receives.

`DIM`, `RLCM`, and `GWM` aren't listed, so they aren't part of the topology. Both channels are, since the listed ECUs are connected to them. To see the resolved instance, with the defaults that RemotiveTopology applies, run:

```sh
remotive topology show instance topology/main.instance.yaml
```

Read more in [Instantiating topology](https://developer.remotivelabs.com/docs/remotive-topology/concepts/instance.md).

### Choose a CAN driver

By default, CAN channels use [RemotiveBus](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/can.md#remotivebus) with SocketCAN, which is available on Linux and in WSL2 on Windows. On macOS, or if you haven't installed RemotiveBus, use UDP emulation instead. Create `topology/udp.instance.yaml`:

```yaml
schema: remotive-topology-instance:0.18

settings:
  can:
    default_driver: udp
```

Then add `-f topology/udp.instance.yaml` to the build command in the next step. With UDP emulation the frames are still encoded exactly as on a CAN bus, but you can't use SocketCAN tools such as `candump`. See [CAN channels](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/can.md).

## Build and run

Build the topology:

```sh
remotive topology build -f topology/main.instance.yaml --name my-vehicle output
```

This generates a Docker Compose file and the configuration for every RemotiveBroker in `output/my-vehicle`. Building needs a RemotiveTopology subscription, see [What needs a license](https://developer.remotivelabs.com/docs/remotive-topology.md#what-needs-a-license). Then start the topology and keep it running:

```sh
docker compose -f output/my-vehicle/docker-compose.yml up
```

The topology runs a RemotiveBroker for each ECU, a mock container for each mocked ECU, and a TopologyBroker that gives you access to all channels. See [What runs in a topology](https://developer.remotivelabs.com/docs/remotive-topology/concepts/runtime.md).

## View in RemotiveStudio

[RemotiveStudio](https://developer.remotivelabs.com/docs/remotive-studio.md) shows both the files and the running topology. Start it in the project folder:

```sh
remotive studio .
```

- Open **Files** and click `topology/main.instance.yaml` to see the instance as a tree, with the ECUs, mocks, and channels. See [Topology in RemotiveStudio](https://developer.remotivelabs.com/docs/remotive-studio/topology.md).
- Create a [dashboard](https://developer.remotivelabs.com/docs/remotive-studio/dashboard.md) with the `TurnLightControl` signals to chart them live.

## View traffic in RemotiveCLI

In a new terminal, list the namespaces. Each namespace is how an ECU sees a channel, named `<ECU>-<Channel>`:

```sh
remotive broker signals namespaces
```

Then subscribe to the turn light requests that `FLCM` receives from the `BCM` mock:

```sh
remotive broker signals subscribe \
  --signal FLCM-BodyCan:TurnLightControl.LeftTurnLightRequest \
  --signal FLCM-BodyCan:TurnLightControl.RightTurnLightRequest
```

The values are `0`, the defaults from the DBC file, and arrive every 50 ms. Press Ctrl-C to stop.

## Stop the topology

Press Ctrl-C in the terminal where the topology runs, then remove its containers and networks:

```sh
docker compose -f output/my-vehicle/docker-compose.yml down
```

Run `remotive topology build` again every time you change the platform or instance files.

## Next step

The mocks only send default values. Next, give the `BCM` behavior with a [behavioral model](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus/behavioral-models.md), and [write tests](https://developer.remotivelabs.com/docs/remotive-topology/usage/test.md) that control the mocks and check what the other ECUs receive.
