Why play back a recording​

Playback, also called open loop simulation, sends recorded vehicle data back onto the channels of a running topology as if the vehicle were there. Three things make that useful:

• Debugging. When something odd happens on a test drive, you can replay those 20 seconds as often as you like, pause on the frame where it goes wrong and look at it next to the front camera video.
• Developing against real data. A behavioral model or an app that consumes signals gets realistic input from a laptop, without a car or a test rig. You can also mix recorded data with a running topology (closed loop simulation), for example by feeding recorded GPS positions to an Android Automotive instance while the climate controls still respond.
• Regression testing. The same recording gives the same input every time, so a test case that runs against it in CI shows you when behavior changes.

Describe the drive as a recording session​

Everything starts with a recording session: a YAML file with the session's start and end time, the recording files, any video files, and a mapping from the recording equipment's device names to the platform's channels. RemotiveTopology reads CAN dumps and CSV in long format (timestamp, signal name, signal value). This example is taken from the docs:

schema: remotive-recording-session:0.2

name: Roundabout left turn
start_time: 1753865338s
end_time: 1753865361s

files:
  - location: ./candata.log
    type: recording
  - location: front.mp4
    name: front
    type: video
    start_time: 1753865335s

mapping:
  includes:
    - ../equipment.mapping.yaml

Some things to watch for:

• The mapping is what turns can0 on the logger into DriverCan in your platform. If the device names already match the channel names, you don't need one. If you keep the mapping in its own file, several recordings made with the same equipment can share it.
• Videos need a name (front, rear and so on). Dashboards pick videos by that name, so one dashboard works for every session from the same car. Set the video's start_time too: the camera rarely starts at the same moment as the logger. Use MP4 with H.264 and AAC, since RemotiveStudio runs in a browser.
• You can have several sessions that point at the same recording files, for example to cut out the interesting part of a long drive.

You don't have to write the file by hand: remotive topology recording-session create -f candump.log generates a session from one or more recording files, and recording-session recalculate updates its start and end time after you change file offsets. See Recording concepts for the details.

Start a topology to play it on​

Playback needs a running topology instance whose platform has every channel the mapping uses. The instance can have more channels than that, so a recording of only one bus works too. To get a simple instance with default settings and no behavioral models, generate it from the session, then build and run it:

remotive topology recording-session instantiate roundabout.recordingsession.yaml playback.instance.yaml
remotive topology generate -f playback.instance.yaml build
docker compose -f build/<instance>/docker-compose.yml --profile ui up

You don't need a new instance for every recording. If you recorded several drives with the same platform, you can use one instance to play all of them. The Usage page also shows how to add your own signals that aren't on the vehicle platform, such as emulated GPS, through a CSV file and an extra channel.

Watch it in RemotiveStudio​

Start RemotiveStudio in your workspace with remotive studio . and open a dashboard. The Add Panel picker has two groups. Use Open recording from the recordings group to load the session for playback, then add a Video panel for each camera. The video stays in sync with the signal timeline. Next to them, add the chart panels you need: a Time series for the signals you care about, a Trace for raw frames, a Map if the recording has latitude and longitude, or a Frame distribution to see which frames are sent most often.

One tip from experience: use only one dashboard tab. RemotiveStudio warns if it sees more than one dashboard running, and you may find that playback controls stop responding or videos don't play. The Add a panel page lists every panel type.

Control playback from the command line​

The same controls are in RemotiveCLI, which is handy from a script or when you only want to jump to the interesting moment. Offsets can be given in minutes, seconds, milliseconds or microseconds:

export REMOTIVE_RECORDING_SESSION_PATH=<recording session>

remotive broker playback open "$REMOTIVE_RECORDING_SESSION_PATH"
remotive broker playback play "$REMOTIVE_RECORDING_SESSION_PATH" --offset 10s
remotive broker playback pause "$REMOTIVE_RECORDING_SESSION_PATH"
remotive broker playback seek "$REMOTIVE_RECORDING_SESSION_PATH" --offset 15000ms
remotive broker playback repeat "$REMOTIVE_RECORDING_SESSION_PATH" --start-offset 10s --end-offset 20s
remotive broker playback status --stream

repeat loops a part of the recording, which is useful while you change a behavioral model and want the same few seconds over and over. Run it with --clear to stop the loop. Every command takes --url if your broker isn't on http://localhost:50051. All options are in the RemotiveCLI manual.

For regression tests, playback can also be controlled from code, for example from a test case running in its own container in the topology, and the topology can be shut down when the tests are done (see Running). To try all of this without a recording of your own, the examples include a Tesla Model 3 drive with two CAN buses and four camera videos.

What sniffing gives you​

Sniffing means listening to a bus without taking part in it. You see every frame that ECUs send, with timestamps, which is exactly what you want when you're asking questions like "does the BCM actually send the turn signal frame when I flip the stalk?" or "how often does this frame show up?"

What you don't get from the wire is meaning. A CAN frame is an ID and up to 8 bytes (64 for CAN FD). Which bits are vehicle speed, and how to scale them, lives in a signal database such as a DBC. So sniffing is really two jobs: capture the raw frames, then decode them.

Setup: get the bus onto a SocketCAN interface​

Everything below assumes Linux, because it relies on SocketCAN. Once your CAN adapter shows up as a network interface, standard tooling such as candump from can-utils works against it. The RemotiveTopology docs recommend giving the interface a name that matches your architecture rather than can0:

sudo ip link set can0 name drivercan0

That small habit pays off later, when you have three adapters plugged in and need to remember which one is on the driver CAN.

If the traffic you want to look at comes from containers, for example behavioral models in a topology, RemotiveBus can expose it on the host. A vcan network with a host_device creates a virtual CAN interface on the host, so you can sniff simulated traffic with the same tools you use on a real vehicle:

type: vcan
device: mybus
host_device: myhostbus   # Name of the virtual CAN interface to create on the host

To go the other way and let containers use a physical bus, use type: can with host_device pointing at the adapter. Note that Docker appends a 0 to the device name inside the container.

Capturing traffic​

With the interface up, start with a live look:

candump drivercan0

Once you've confirmed frames are flowing, log them to a file instead. candump -l writes a candump-<date>.log file in the current directory, in the "CAN dump" format that both RemotiveTopology and RemotiveCloud read. Drive the scenario you care about, then stop it with Ctrl+C.

Before you do anything else with the log, check it with RemotiveCLI. If a colleague needs the capture in another format, the same tool converts between .log, .asc and .blf:

remotive tools can validate candump-2026-09-03_101500.log --print-to-terminal
remotive tools can convert candump-2026-09-03_101500.log drive.blf

Both commands are described in the RemotiveCLI reference.

Making sense of what you captured​

Now for the decoding. In RemotiveTopology, the signal database belongs to a channel in your platform. A DBC doesn't say which bus it describes, so you name the channel yourself (platform docs):

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

Next, wrap the log in a recording session, and add a recording mapping that connects the interface name in the log to the platform channel:

remotive topology recording-session create -f candump-2026-09-03_101500.log drive.recordingsession.yaml

schema: remotive-recording-mapping:0.1

devices:
  drivercan0: DriverCan

If you named the interface the same as the channel, you can skip the mapping: a default mapping from same-name devices is created automatically. Then create an instance for playback, generate it and start it with the UI profile, as described in recordings usage:

remotive topology recording-session instantiate drive.recordingsession.yaml drive.instance.yaml
remotive topology generate -f drive.instance.yaml build
docker compose -f build/<instance>/docker-compose.yml --profile ui up

In RemotiveStudio, the Signal view lists every frame and signal in the DBC, with unit, factor/offset and named values, which is handy for finding the signal you're after. Then build a dashboard with a few panels, with an Open recording panel to play back the log:

• Frame distribution shows which frames are on the bus and how often. A frame that's missing, or one far more frequent than expected, is often the first clue.
• Trace is the decoded version of candump: timestamp, frame ID, frame name and raw bytes, with signal values when you expand a row.
• Time series plots the signals themselves, so you can see that brake pedal position goes up just before vehicle speed goes down.

Other ways to look at the same data​

If you'd rather not set up a platform, you can upload the log to RemotiveCloud, either by drag and drop or with remotive cloud recordings upload. It matches the recording against the signal databases in your project and suggests the best fit. And for Ethernet traffic between containers, including SOME/IP, Edgeshark and Wireshark let you inspect each connection in a running topology.

Whichever route you take, the idea is the same: capture first, keep the raw log, and let the signal database do the decoding. The log stays useful long after the drive is over.

A tester container in the instance​

RemotiveTopology lets you add your own containers to an instance, next to the ECUs. The nice part for CI is that a test runner can be one of them: it starts inside the topology, on the same networks as everything else, and reaches the TopologyBroker by name. Put it behind a profile so it only runs when you ask for it:

containers:
  tester:
    profiles: [tester]
    build:
      dockerfile: ../../../python-runner.dockerfile
    volumes:
      - ../tests:/app
    working_dir: /app
    command: "pytest --broker_url=http://topology-broker.com:50051 -s -vv"

The Dockerfile only needs Python and your test dependencies: pytest, pytest-asyncio and the remotivelabs-topology package. Profiles map straight to docker compose profiles, so the tester stays out of the way when you start the topology without --profile tester to poke at it by hand.

One thing to check before moving to a hosted runner: CAN channels default to RemotiveBus, which needs to be installed on the host. If you don't need SocketCAN in CI, switch the instance to UDP emulation, which works anywhere without extra setup:

settings:
  can:
    default_driver: udp

Writing the tests​

Tests use the RemotiveTopology framework, the Python library you also write behavioral models with. A small conftest.py turns the --broker_url option from the container command into a BrokerClient fixture. The default points at localhost:50051, which is where the broker is forwarded when you run the topology interactively, so the same tests run from your editor too:

# tests/conftest.py
import pytest_asyncio
from remotivelabs.broker import BrokerClient


def pytest_addoption(parser):
    parser.addoption("--broker_url", default="http://localhost:50051")


@pytest_asyncio.fixture
async def broker_client(request):
    async with BrokerClient(url=request.config.getoption("--broker_url")) as client:
        yield client

A test then subscribes to frames in a namespace (named <ECU>-<Channel>) and waits for the signal values it expects. This one is adapted from the testing examples in the API docs:

# tests/test_hazard_lights.py
from remotivelabs.broker import BrokerClient
from remotivelabs.topology.testing.frames import capture_frames


async def test_hazard_light_sequence(broker_client: BrokerClient) -> None:
    async with capture_frames(
        (broker_client, "HazardLightControlUnit-DriverCan0"),
        frames=["HazardLightButton"],
    ) as cap:
        await cap.wait_for_signal_values(
            "HazardLightButton",
            "HazardLightButton.HazardLightButton",
            values=[0, 1, 0],
            timeout=5.0,
        )

The tests are async, so set asyncio_mode = auto in your pytest configuration (or mark them with @pytest.mark.asyncio). If you're unsure which namespaces exist, start the topology and run remotive broker signals namespaces --url http://localhost:50051.

Credentials for the runner​

Running a topology checks your organization's RemotiveTopology subscription, and a CI job shouldn't do that with someone's personal login. Create a service account with the RemotiveTopology Executor role instead:

remotive cloud service-accounts create ci-runner --role org/topologyRunner --project <project id>
remotive cloud service-accounts tokens create --service-account ci-runner --project <project id>
remotive cloud auth print-access-token --account <email for service account>
remotive cloud organizations list

Store the token as a repository secret, REMOTIVE_CLOUD_AUTH_TOKEN, and the organization uid as REMOTIVE_CLOUD_ORGANIZATION. If you run with a RemotiveBroker license file, keep it out of the repository: store it as a secret too and point REMOTIVEBROKER_LICENSE at it.

The workflow​

With that in place, the job is four steps: install the RemotiveCLI, generate the topology, start it with the tester profile, and clean up.

# .github/workflows/topology-tests.yml
name: Topology tests
on: [pull_request]

jobs:
  topology-tests:
    runs-on: ubuntu-latest
    env:
      REMOTIVE_CLOUD_AUTH_TOKEN: ${{ secrets.REMOTIVE_CLOUD_AUTH_TOKEN }}
      REMOTIVE_CLOUD_ORGANIZATION: ${{ secrets.REMOTIVE_CLOUD_ORGANIZATION }}
    steps:
      - uses: actions/checkout@v4

      - name: Install RemotiveCLI
        run: pipx install remotivelabs-cli

      - name: Generate topology
        run: remotive topology generate -n mytopology -f topology/mytopology.instance.yaml build

      - name: Run tests
        run: >
          docker compose -f build/mytopology/docker-compose.yml --profile tester
          up --abort-on-container-exit --exit-code-from tester

      - name: Clean up
        if: always()
        run: docker compose -f build/mytopology/docker-compose.yml --profile tester down

--abort-on-container-exit is what makes this work in CI: when pytest finishes, the tester container exits and docker compose stops the rest of the topology. Adding --exit-code-from tester, a plain docker compose option, makes the step's exit code pytest's, so a failing test fails the job. The down step runs even after a failure, so the runner is left clean.

Generate runs on every job, and that's on purpose: the generated files are completely overwritten each time, and any change to the platform or instance files needs a new generate anyway. Don't commit build/.

When it goes red​

Most failures are easier to read in the container logs than in the pytest output alone. Add a step with if: failure() that runs docker compose -f build/mytopology/docker-compose.yml logs before the clean-up, and you get the behavioral models' and brokers' side of the story too. The Docker tips page has more commands for following logs per service.

To reproduce locally, run the same generate, then start the topology without the tester profile, as described in Running a topology, and run pytest from your editor against localhost:50051. Same tests, same topology, just with a debugger attached.

What a restbus is for​

A restbus simulates "the rest of the bus": every frame your device under test expects from ECUs that aren't there. Most of these frames are cyclic, so the simulation has to keep sending them at the right cycle time, or the device starts logging timeouts and falling back to safe states.

In RemotiveTopology this usually starts with an ECU mock. A mock is the simpler alternative to a behavioral model: it doesn't decide anything on its own, it just provides a restbus that emulates the ECU, and something else (often a test case, today it's us) decides what it sends. If the code that controls a mock gets complicated, that's a sign it should become a behavioral model instead.

Setting up the restbus​

Start from a platform with a CAN channel, and instantiate the ECU you want to stand in for with a mock. The instance docs use a body controller on two CAN buses; mocking it on just one of them looks like this:

schema: remotive-topology-instance:0.15

platform:
  includes:
    - ./topology.platform.yaml

ecus:
  BCM:
    mock:
      channels:
        DriverCan0:

Leave out channels (mock: {}) to mock the ECU on every channel it is connected to. Then generate the topology and start it in interactive mode, so it keeps running while you work, as described in Running a topology:

remotive topology generate -f mytopology.instance.yaml build
docker compose -f build/mytopology/docker-compose.yml up

The broker inside the topology is forwarded to http://localhost:50051. Each ECU's view of a channel is a namespace named <ECU>-<Channel>, so here it's BCM-DriverCan0. If you're unsure, list them:

remotive broker signals namespaces --url http://localhost:50051

Now tell the broker which frames to send. The remotive broker restbus commands follow a simple workflow: add, start, update, and stop or reset. Pick a frame from your signal database (the signal view in RemotiveStudio is a quick way to browse them); BodyStatus below is a stand-in name:

remotive broker restbus add --frame BCM-DriverCan0:BodyStatus --cycle-time 100
remotive broker restbus start --namespace BCM-DriverCan0

--cycle-time is in milliseconds and overrides the cycle time from the database; leave it out to use the database value. add --start registers and starts in one go.

Building the dashboard​

Start RemotiveStudio on the workspace that holds your topology files, as in Getting started:

remotive studio .

The dashboard needs a running topology to connect to; without one it shows "RemotiveTopology unavailable". Create a dashboard from the Topology sidebar panel, then use Add Panel to add panels. For a restbus, three are useful:

• Frame distribution shows which frames arrive and how often, so you can see at a glance that the restbus is running and at roughly the cycle time you asked for.
• Trace shows each frame as it arrives, with its raw bytes, and the signal values when you expand a row.
• Time series plots the signals you select, which is where you'll see your changes.

Use the signal selection button to pick signals for the time series panel. A new dashboard is a draft until you click Save As; it's then stored as a .dashboard.json file in your workspace, so you can commit it next to the topology and open it again from the Files sidebar.

Changing values while it runs​

With frames flowing, change what the restbus sends. update sets the values it emits from now on; give several comma-separated values and the restbus loops over them. For example, a door signal that reads open on every fourth value:

remotive broker restbus update --signal BCM-DriverCan0:DoorOpen:0,0,0,1

Use --initial for values that should be sent once before the loop starts. The time series panel follows along as soon as the new values go out, and the trace panel shows what changed in the raw bytes. To pause, run stop; the configuration stays, so start picks up where you left off. remove --frame drops a single frame, and reset clears everything for a namespace.

Here the dashboard is the place you watch, and the terminal next to it is where you turn the knobs. The same restbus can be controlled from code, too: the RemotiveTopology framework is a Python library for writing test cases and behavioral models against the same namespaces, which is where to go once a sequence of update commands starts to feel like a script.

What an FMU is and when you would use one​

A Functional Mock-up Unit is a packaged simulation model, following the FMI standard, that many modeling tools can export. It's a zip file with a model description (the inputs, outputs and default experiment settings) and the compiled model.

In RemotiveTopology, an FMU is one of the supported kinds of behavioral model, next to plain Python and Synopsys Silver. A behavioral model emulates the behavior of a real ECU, so an FMU is a good fit when the behavior you need already exists as a physics or control model: vehicle dynamics, a battery, a thermal system, or the classic bouncing ball. Instead of hard-coding values in a mock, the model reacts to what's on the bus and produces realistic outputs.

Prerequisites​

You need a working RemotiveTopology setup, as described in Install: Docker (or Podman), RemotiveCLI with an active subscription, and Python 3.10 or later for behavioral models.

The FMU support lives in the remotivelabs-topology package behind an extra, since it pulls in fmpy and numpy:

pip install remotivelabs-topology[fmu]

Then the FMU itself. The framework drives the model one step at a time, so it needs to be:

• an FMI 2.0 or 3.0 Co-Simulation FMU,
• configured with a fixed step size and no internal solver,
• carrying a defaultExperiment in its model description (that's where the step size is read from).

If the FMU doesn't support co-simulation or lacks a default experiment, loading it fails with an error straight away, which is a nice early warning.

Loading the FMU from Python​

The entry point is FMUSimulation. Give it a path, and it reads the model description, instantiates the FMU and resets it to its initial state:

from pathlib import Path

from remotivelabs.topology.fmu import FMUSimulation

fmu = FMUSimulation(Path("speed_model.fmu"))
fmu.print()  # dump model information and variables

print(fmu.step_size)
print(fmu.input_var_names)
print(fmu.output_var_names)

print() is the first thing I run on any new FMU: it shows the variable names you'll need in the next step. The step size comes from the default experiment, but you can override it with FMUSimulation(path, step_size=0.01).

Each call to await fmu.step() advances the simulation by one step, applies the current inputs and returns the outputs. You can also set an input directly with fmu.set_input_value("name", value); it sticks for all future steps, and an unknown name raises a ValueError.

Mapping FMU inputs and outputs to signals​

The FMUBehavioralModel class connects an FMUSimulation to the topology. Inputs are described with an InputMapping, a nested dictionary from namespace, to frame, to signal, to FMU input name. Namespaces are named <ECU>-<Channel>, as described in Instantiating a topology.

In this example (the ECU, frame and variable names are made up), the FMU gets its accelerator_pedal input from a signal on ChassisCan0:

from remotivelabs.topology.fmu import InputMapping

input_mapping: InputMapping = {
    "SpeedModel-ChassisCan0": {
        "PedalStatus": {
            "AcceleratorPedalPosition": "accelerator_pedal",
        },
    },
}

Whenever a matching frame arrives, the model writes the signal value to the FMU input. Values outside the signal's min and max from the signal database are ignored, so a bad frame doesn't push the model into nonsense.

Outputs go the other way. FMUSimulation takes an on_output callback that runs after every step with a dictionary of output values. A simple way to put them on the bus is to let a restbus send the ECU's frames and update their signals from the callback:

from remotivelabs.topology.namespaces import filters
from remotivelabs.topology.namespaces.can import CanNamespace, RestbusConfig

chassis_can = CanNamespace(
    "SpeedModel-ChassisCan0",
    broker_client,
    restbus_configs=[RestbusConfig([filters.SenderFilter(ecu_name="SpeedModel")])],
)

async def on_output(outputs):
    await chassis_can.restbus.update_signals(("VehicleSpeed", outputs["vehicle_speed"]))

Running it as part of a topology​

Putting it together, the model script looks much like any other behavioral model. run_forever() starts a ticker at the FMU's step size, steps the simulation on every tick and handles inputs and control requests at the same time:

import asyncio
from pathlib import Path

from remotivelabs.broker import BrokerClient
from remotivelabs.topology.cli.behavioral_model import BehavioralModelArgs
from remotivelabs.topology.fmu import FMUBehavioralModel, FMUSimulation
from remotivelabs.topology.namespaces import filters
from remotivelabs.topology.namespaces.can import CanNamespace, RestbusConfig


async def main(args: BehavioralModelArgs):
    async with BrokerClient(url=args.url, auth=args.auth) as broker_client:
        chassis_can = CanNamespace(
            "SpeedModel-ChassisCan0",
            broker_client,
            restbus_configs=[RestbusConfig([filters.SenderFilter(ecu_name="SpeedModel")])],
        )

        async def on_output(outputs):
            await chassis_can.restbus.update_signals(("VehicleSpeed", outputs["vehicle_speed"]))

        fmu = FMUSimulation(Path("speed_model.fmu"), on_output=on_output)

        async with FMUBehavioralModel(
            "SpeedModel",
            fmu=fmu,
            input_mapping={
                "SpeedModel-ChassisCan0": {
                    "PedalStatus": {"AcceleratorPedalPosition": "accelerator_pedal"},
                },
            },
            broker_client=broker_client,
            namespaces=[chassis_can],
        ) as bm:
            await bm.run_forever()


if __name__ == "__main__":
    asyncio.run(main(BehavioralModelArgs.parse()))

A bonus you get for free: when the model receives a reboot request, it resets the FMU to its initial state along with the restbuses, so a test can start every case from a known state.

In the instance file, the model is added to its ECU like any Python behavioral model:

ecus:
  SpeedModel:
    models:
      speed_model:
        type: python
        include: ../ecus
        main: speed_model

The container that runs Python models needs the fmu extra installed, so add it to the image or Dockerfile you configure under settings.docker.python. Then generate and start the topology as usual:

remotive topology generate -f mytopology.instance.yaml build
docker compose -f build/mytopology/docker-compose.yml up

If the signals don't show up, check the namespace names first:

remotive broker signals namespaces --url http://localhost:50051

Where to go next​

• Instantiating a topology: behavioral models, mocks and Docker settings.
• Running a topology: generating, interactive mode and running tests.
• API and client library: the full Python API reference, including the fmu module.
• Examples: the examples repository, a good place to start from a working setup.

What named values are​

Many signals don't carry a measurement. They carry a state: a door is open or closed, a gear is in park or drive, a lamp is off, on or failing. On the bus these states are plain integers, and the signal database maps each integer to a name. In a DBC file this is the value table for the signal; ARXML and LDF have their own ways of describing the same thing. Think of it as an enum attached to a signal.

RemotiveLabs calls these mappings named values. They come straight from the signal databases your topology references (DBC, ARXML, LDF, Fibex, see the supported file formats), so you don't define them anywhere else. If the database has them, you can use them.

Finding named values in RemotiveStudio​

The quickest way to see what a database defines is the Signal view in RemotiveStudio:

1. Open the file tree with Files and click your .instance.yaml, .platform.yaml, or a database file directly.
2. Click the bar-chart icon in the segmented control at the top of the topology viewer.
3. Find the frame you care about. The search bar filters both frames and signals.
4. Click the frame row to expand its signals. Each signal shows its unit, min/max, factor and offset, receivers, and its named values.

The first time you open the Signal view, RemotiveStudio indexes the signal databases, so give it a moment on large ARXML files. Today the Signal view covers CAN and LIN signals.

This is also a good way to check a database before you write code against it. If you expect GearPosition to have named values and the Signal view shows none, the database you're using doesn't have them, and no code will fix that.

Reading named values from Python​

The RemotiveBroker Python API exposes the mapping on every SignalInfo in two directions: named_values maps raw integers to names, and value_names maps names back to integers. Here is a small script, adapted from the API docs, that prints both for one signal. The DriverCan namespace and the GearData.GearPosition signal are examples; use your own.

import asyncio
from remotivelabs.broker import BrokerClient

async def main() -> None:
    async with BrokerClient(url="http://127.0.0.1:50051") as broker_client:
        info = await broker_client.get_signal_info("GearData.GearPosition", "DriverCan")
        if info is None:
            raise SystemExit("Signal not found in DriverCan")
        print(info.named_values)  # raw value -> name, e.g. {0: "PARK", 3: "DRIVE"}
        print(info.value_names)   # name -> raw value, e.g. {"PARK": 0, "DRIVE": 3}

if __name__ == "__main__":
    asyncio.run(main())

If you're not sure which namespaces exist on a running topology, list them first:

remotive broker signals namespaces --url http://localhost:50051

When you subscribe, you can have the client decode values for you. Pass decode_named_values=True to subscribe_frames, and integer values that have a mapping arrive as their names in frame.signals:

stream = await broker_client.subscribe_frames(
    ("DriverCan", ["GearData"]),
    decode_named_values=True,
)
async for frame in stream:
    print(frame.signals)  # {"GearData.GearPosition": "DRIVE", ...}

To write a state, look up the raw value with value_names and publish that integer:

from remotivelabs.broker import WriteSignal

await broker_client.publish(
    ("DriverCan", [WriteSignal(name="GearData.GearPosition", value=info.value_names["PARK"])]),
)

The same lookup works when you set restbus signals with RestbusSignalConfig.set(...). If you write behavioral models or tests with the RemotiveTopology framework, you're using the same broker client underneath, so SignalInfo.named_values and value_names are available there too.

Common pitfalls​

• The value type changes. With decode_named_values=True, a signal that used to be an int becomes a str. Code that compares with == 3 or does arithmetic on the value silently stops matching. Pick one style per script and stick to it.
• Not every value has a name. Only integers that appear in the mapping are decoded. A value outside the table, such as a reserved or error code, still arrives as an int, so handle both types, or look values up yourself with info.named_values.get(value, value).
• Decoding is off by default. subscribe_frames doesn't decode unless you ask, and the frame handlers in the RemotiveTopology framework take a decode_named_values argument that is also off by default. If you see numbers where you expected names, check this first.
• Names belong to a database. Two databases can map the same signal differently, for example a channel DBC and an ECU extract. Check the Signal view for the topology you actually run, and look names up with value_names instead of hard-coding the integers.
• Typos fail late. info.value_names["Park"] raises a KeyError when the database says PARK. Copy names from the Signal view rather than from memory.

Named values are a small feature, but they make logs, dashboards and test assertions much easier to read. For more on the APIs, see APIs and client libraries.

The example topology​

We start with a platform that has two CAN channels, each described by a DBC file. DBC files don't say which channel they describe, so the platform file names the channels and points each one at its database:

# topology.platform.yaml
schema: remotive-topology-platform:0.15
channels:
  DriverCan0:
    type: can
    database: ../databases/driver_can.dbc

  BodyCan0:
    type: can
    database: ../databases/body_can.dbc

That's the whole file, but it describes more than it seems to. The ECUs come from the DBCs: SCCM and BCM are on DriverCan0, and BCM, DIM, FLCM, RLCM and GWM are on BodyCan0. BCM sits on both buses.

On top of that we write an instance, which says which part of the platform to run. Here we want BCM with a Python behavioral model, and FLCM as a mock:

# main.instance.yaml
schema: remotive-topology-instance:0.15

platform:
  includes:
    - ./topology.platform.yaml

ecus:
  BCM:
    models:
      bcm:
        type: python
        include: ../ecus
        main: bcm
  FLCM:
    mock: {}

Looking at it from the terminal​

Before opening any UI, I like to ask the CLI what it sees. Both files live in topology/, next to databases/ and ecus/. Set up a workspace at the root of the project first, so relative includes like ../databases resolve the same way from every subfolder:

cd my_project
remotive topology workspace init

Then show the platform:

remotive topology show platform topology/topology.platform.yaml

This prints the platform as platform.yaml, with everything the DBCs added filled in. Each ECU lists the channels it's connected to, and each ECU channel gets a database too, because that's the database the ECU uses to decode signals. If an ECU name isn't what you expected, this is where you find out, before you write an instance that refers to it.

For the instance, use show instance:

remotive topology show instance topology/main.instance.yaml

This shows only the parts of the platform that are instantiated, plus any defaults that were applied. In our case, SCCM, DIM, RLCM and GWM are gone. BCM keeps both channels, because by default an ECU gets every channel it's connected to. FLCM's mock covers every channel FLCM is on, which here is just BodyCan0.

A few options are handy here:

• --full-platform shows the full platform, not just the instance-specific parts.
• --check checks the topology.
• --json switches the output from YAML to JSON, and -o writes it to a file, which is useful if you want to diff the resolved instance between two branches.

Opening it in RemotiveStudio​

YAML is precise, but a tree is quicker to read. RemotiveStudio comes with RemotiveCLI and starts from the same workspace:

remotive studio .

Open Files in the sidebar and click topology.platform.yaml. The topology viewer has three modes, chosen with the segmented control at the top:

• Tree view shows the platform as two top-level groups, Channels and ECUs. Expand BodyCan0 to see the five ECUs on it, or expand BCM to see that it's on both buses. Click a node to open its details, such as channel type, database path and connected ECUs.
• YAML view shows the resolved topology, with includes merged. It's read-only, and roughly what remotive topology show platform prints.
• Signal view is a searchable table of every frame in the topology's CAN and LIN databases. Click a frame to see its signals, with units, min and max values, receivers and named values.

Now open main.instance.yaml. The instance tree has the same channels and ECUs, cut down to what the instance runs, and adds instance-level entries such as the bcm behavioral model. Comparing the two trees side by side is the fastest way I know to check that an instance contains what I meant it to.

Studio opens DBC, ARXML, LDF and Fibex files directly too, by converting them to .platform.yaml first. Clicking an ECU extract is a quick way to see what's in it before you include it anywhere.

Tips for larger platforms​

Real platforms are rarely one file. They're usually a top-level platform.yaml that includes subsystems:

schema: remotive-topology-platform:0.15
includes:
  - ./lighting.platform.yaml
  - ./climate.platform.yaml
  - ./driver.platform.yaml

Some things that help when there are many of them:

• Show each subsystem on its own first. If lighting.platform.yaml looks right by itself, you've narrowed down where a problem in the combined platform can be.
• Use the tree view's search bar instead of expanding everything. "Collapse all" helps when you've lost track.
• Studio doesn't pick up edits to topology files until you reload the browser tab. The CLI always reads the files fresh, so it's the better choice while you're editing.
• If a command complains about a missing ECU, run show platform on the file that should define it. It's often a spelling difference between two databases.

Where to go next​

• Describing the platform: DBC, ARXML, LDF and platform.yaml includes.
• Instantiating topology: choosing ECUs and channels, models and mocks.
• Topology in RemotiveStudio and its tree view.
• Workspace and the remotive topology show reference.

What to expect​

Posts are hands-on and to the point. Expect topics like connecting simulation models to a topology, working with signals from Python, and building dashboards in RemotiveStudio.

When a post covers something you'll come back to, we link to the matching page in the docs, which is where the reference material lives.

Code, not slides​

Most posts include code you can copy and run:

remotive --help

If you build something with RemotiveLabs and want to share it, reach out on GitHub.