Skip to main content

Getting Started

In this example, the goal is to write a test that verifies whether the front light control module (FLCM) receives the correct signal when the hazard lights button is pressed. Pressing the hazard lights button triggers the Steering Column Control Module (SCCM) to send a message to the body control module (BCM), which contains the logic for forwarding the correct information to the light control modules.

To achieve this, we will:

  • Describe the platform
  • Write a behavioral model
  • Describe how to instantiate the model
  • Write test case that controls mocks for the HLCU and FLCM, to simulate inputs and outputs
  • Configure shared settings
  • Run the test case using Docker

Describe the platform​

The first steps when describing the platform is collecting all the information you already have. This can include signaldatabases such as DBC or complete ARXML files. In this example we will use a DBC file as it is fairly easy to understand.

Here is an extract from driver_can.dbc:

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

This includes quite a lot of information but from RemotiveTopology perspective it tells us:

  • SCCM is sending a CAN Frame called HazardLightButton
  • BCM is receiving this frame and reads the signal HazardLightButton (ON/OFF)

In fact, given this information RemotiveTopology understands that there exists two ECUs SCCM and BCM that are communicating on a CAN channel.

Similarly, given this extract from driver_can.dbc:

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

RemotiveTopology now understands that there exists 4 other ECUs DIM, FLCM, RLCM, GWM that also communicate with BCM.

Since the DBC files does not include information about what the CAN channels are called we need to add additional information using a RemotiveTopology platform.yaml file:

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

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

This tells RemotiveTopology the following:

  • This is a remotive-topology-platform file
  • There exist two CAN channels DriverCan0 and BodyCan0
  • driver_can.dbc can be used to decode signals on DriverCan0
  • body_can.dbc can be used to decode signals on BodyCan0

RemotiveTopology automatically loads the DBC files and now understands what ECUs exists in the topology.

This is all the information we need for the platform!

A Behavioral Model for the BCM​

The next step is to create a Behavioral Model

import asyncio
import logging

from remotivelabs.sim import ArgvParams, Context, Simulation, filters, message, subscribe
from remotivelabs.sim.config import RestBus


# We create a class to hold the logic for the behavioral model.
# It contains callback methods for different type of network
# messages. See below how these are used by the Simulation.
class BCM:
    """BCM handles incoming signals and transition lights between states"""

    async def on_hazard_light(self, signal: message.Signal, ctx: Context) -> None:
        # The input sent from the hazard light button. It will be 0.0 (OFF) or 1.0 (ON)
        hazard_signal = signal.payload

        # We configure the rest bus to send the same value
        # to the CAN bus, so the FLCM can pick it up.
        # In this simple example, we just turn the light on and off
        # depending on the signal. A more realistic simulation would
        # blink the lights
        ctx.rest_bus_context["TurnLightControl.RightTurnLightRequest"].update([float(hazard_signal)])
        ctx.rest_bus_context["TurnLightControl.LeftTurnLightRequest"].update([float(hazard_signal)])


async def main(avp: ArgvParams):
    logging.info("Starting BCM simulator")
    bcm = BCM()

    # The simulation is driving the simulation. We set it up with:
    # * A rest bus to send frames out on the BodyCan0 network. The rest bus will
    #   automatically find the correct frames to send in the signal database.
    # * A subscription that will call `BCM.on_hazard_light` when the appropriate signal arrives.
    async with Simulation(
        client_name="BCM",
        url=avp.url,
        rest_bus_config=RestBus(
            [filters.Sender("BCM-BodyCan0", "BCM")],
            delay_multiplier=avp.delay_multiplier,
        ),
        subscriptions=[
            subscribe.Signal(filters.Signal("BCM-DriverCan0", "HazardLightButton.HazardLightButton"), bcm.on_hazard_light),
        ],
    ) as simulation:
        await simulation


if __name__ == "__main__":
    # The command line argument parser from remotive labs will pick up the settings
    # from the generated topology
    args = ArgvParams.parse()
    logging.basicConfig(level=args.loglevel)
    asyncio.run(main(args))

While being a simplified example, the structure is common to most kinds of behavioral models. We will go through everything in more detail, but note a few things:

  • There are two main parts, the model logic and the main setup code.
  • The file will be run as a program and some information from the topology instance will be passed in as command line parameters. There is a ready utility class, ArgvParams, to parse these into a data class.
  • The model is driven by a Simulation. This is a central class for behavioral models. It will handle the actual network traffic and information from the signal databases. In this case, it sets up a rest bus for sending data on the "BodyCan0" network as well as a subscription for incoming data on the "DriverCan0" network.
  • The logic of the model is in the BCM class. Representing the model as a class creates a nice encapsulation.

Instantiate the BCM model​

In RemotiveTopology you create a topology by by combining one or more instance.yaml files. Each file can contain one or more ECUs or other settings. In this case we need to instantiate our Behavioral Model for the BCM ECU:

schema: remotive-topology-instance:0.4

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

ecus:
  BCM:
    models:
      bcm:
        type: python
        include: ../ecus
        main: bcm

This tells RemotiveTopology the following:

  • This is a remotive-topology-instance file
  • The platform should be included from the file we created above
  • Instantiate the ECU BCM and start a behavioral model called "bcm". This is written in a python module called "bcm"

The file structure should now look like this:

getting_started
├── databases
│   ├── body_can.dbc
│   └── driver_can.dbc
├── ecus
│   └── bcm
│       ├── __init__.py
│       └── __main__.py
└── topology
    ├── bcm.instance.yaml
    └── topology.platform.yaml

Try viewing the resulting topology:

$ remotive-topology show topology --resolve examples/getting_started/topology/bcm.instance.yaml

This shows:

---
schema: remotive-topology-instance:0.4
platform:
  channels:
    BodyCan0:
      can_physical_channel_name: BodyCan0
      database: /data/examples/getting_started/databases/body_can.dbc
      type: can
    DriverCan0:
      can_physical_channel_name: DriverCan0
      database: /data/examples/getting_started/databases/driver_can.dbc
      type: can
  ecus:
    BCM:
      channels:
        BodyCan0:
        DriverCan0:
channels: {}
ecus:
  BCM:
    channels:
      BodyCan0:
      DriverCan0:
    models:
      bcm:
        include: /data/examples/getting_started/ecus
        main: bcm
        type: python

Notice:

  • Only ECUs included in the instance are visible in the resolved platform, in this case BCM. It will also include channels that are either included in the instance or used by the included ECUs.
  • There are no channels specified in the instance. This is because we still need to specify how the channels should be instantiated.

Writing a Test Case​

The following is a minimal testcase that checks that the lights turn on when pressing the hazard light button:

import asyncio
from typing import AsyncIterator

import pytest
import pytest_asyncio
from remotivelabs.topology.remote_ecu import RemoteECU, SignalProperties


@pytest_asyncio.fixture()
async def broker_url(request: pytest.FixtureRequest) -> AsyncIterator[str]:
    # Get broker URL from the command line
    yield request.config.getoption("broker_url")


@pytest.mark.asyncio
async def test_light_turns_on_when_hazard_button_is_pressed(broker_url: str):
    # Connect to the ECUs to handle input and output
    async with RemoteECU("SCCM", broker_url=broker_url) as sccm, RemoteECU("FLCM", broker_url=broker_url) as flcm:
        # Wait for the mocks to start
        await sccm.assert_alive()
        await flcm.assert_alive()

        # We start sending the new signal. Note how we can
        # control the mock from the test case directly.
        await sccm.update_restbus([SignalProperties(id="HazardLightButton.HazardLightButton", value=1.0)])

        # Wait a little bit for the message to propagate to the FLCM
        await asyncio.sleep(0.5)

        # Read the last value from the FLCM. We read two different signals
        values = await flcm.request_latest_values(["TurnLightControl.RightTurnLightRequest", "TurnLightControl.LeftTurnLightRequest"])

        # Check that both front turn lights are requested to turn on.
        assert values["TurnLightControl.RightTurnLightRequest"] == 1.0
        assert values["TurnLightControl.LeftTurnLightRequest"] == 1.0

To add these test into our topology we add another instance.yaml file:

schema: remotive-topology-instance:0.4

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

ecus:
  FLCM:
    mock: {}

  SCCM:
    mock: {}

Notice:

  • Tests are running inside a generic docker container. You can use whatever framework you want!
  • Tests are using a profile which means they are optional when running the instance.
  • Since the tests are written using mocks we need to instantiate these.

Settings​

Before running the tests it is necessary to define some settings for how to instantiate the topology. These settings can potentially be used across all our topology instances:

schema: remotive-topology-instance:0.4

settings:
  docker:
    mock:
      dockerfile: ../../../python-runner.dockerfile
    python:
      dockerfile: ../../../python-runner.dockerfile

  remotivebroker:
    version: v1.10.1
    license_file: ../../../LICENSE_FILE

This tells RemotiveTopology:

  • dockerfiles to use for the various containers. You can use this to add custom dependencies if needed.
  • version of RemotiveBroker to use. We recommend that this is specified to ensure that tests are run using the exact same behavior over time.
  • Where your RemotiveTopology license is located.

Instantiating CAN​

RemotiveTopology supports two ways of instantiating a CAN network:

  1. RemotiveLabs DockerCAN driver for SocketCAN (default)
  2. Emulation using UDP (by broadcasting ethernet PDUs)

SocketCAN is needed to connect to physical hardware and to use standard CAN tooling such as candump. SocketCAN is the natural way to implement CAN and is therefore the default setting in RemotiveTopology.

⚠️ SocketCAN is only supported on Linux with RemotiveLabs DockerCAN driver. On Mac/Windows you need to fall back to emulation. Notice that the UDP packets are still encoded in the same way as the real CAN frames, by using Ethernet PDUs.

To make this example run on all platforms we can use CAN over UDP. This is configured by adding the following instance.yaml:

schema: remotive-topology-instance:0.4

settings:
  can:
    default_driver: udp

Running the tests​

To run the tests we need to configure in what environment the tests should run. This is done using yet another instance.yaml:

schema: remotive-topology-instance:0.4

includes:
  - ./bcm.instance.yaml
  - ./tester.instance.yaml
  - ./settings.instance.yaml

This means that we:

  • instantiate the bcm behavioral model we created
  • specify what tests to run
  • use shared settings

Notice:

  • By including all the dependencies we ensure that the tests run in the environment which we intend.
  • Since we are testing a behavioral model and not real ECU software or hardware we can use CAN emulation.
  • We can easily run the same tests using real hardware simply by replacing the bcm instance and configuring CAN devices instead of emulation.

To run the topology we generate the runtime environment:

$ cd remotivelabs-ecu-simulations
$ remotive-topology generate -f examples/getting_started/topology/test-bcm-model.instance.yaml --name getting_started build
Generated topology at: build/getting_started

On Linux we use SocketCan which is the default.

Then to run the tests:

docker compose -f build/getting_started/docker-compose.yml --profile tester up --abort-on-container-exit

You can run the tests several times. Once you are done we recommend cleaning up the docker resources:

docker compose -f build/getting_started/docker-compose.yml --profile tester down

Resulting topology​

This is the topology we created in this example:

Steps Forward​

There are several ways of moving forward from what we have here:

  1. We can add more ECUs that are involved by turn signals. The signal stalk ECU, the infotainment console, etc. Since these models are sending real network traffic, it is possible to verify that the correct data is sent to the correct endpoints.
  2. By adding more test cases, we can create a test suite that verifies that all the parts in the topology work together.
  3. The included ECUs can be "upgraded" to higher fidelity models, such as FMUs or Synopsis Silver. It's even possible to use real hardware in the topology as long as everything is running on the correct networks.