Skip to main content

Your first topology

This guide takes you through the 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 and make sure that remotive topology subscription status shows an active subscription.

You can also try cloning getting_started example which also includes a behavioral model and a simple test.

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.

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/:

Then initialize a workspace in the project folder. Run all remotive topology commands in this folder:

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:

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:

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:

Read more in Describing the platform.

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:

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. 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:

remotive topology show instance topology/main.instance.yaml

Read more in Instantiating topology.

Choose a CAN driver​

By default, CAN channels use 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:

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.

Build and run​

Build the topology:

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. Then start the topology and keep it running:

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.

View in RemotiveStudio​

RemotiveStudio shows both the files and the running topology. Start it in the project folder:

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.
  • Create a dashboard 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>:

remotive broker signals namespaces

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

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:

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, and write tests that control the mocks and check what the other ECUs receive.