Skip to main content

Instantiating topology

In order to run a topology you need create an instance that describes what parts of the platform you want to run in your virtual environment. The instance also specifies what tests to run, optional ui and jupyter notebooks etc.

Platform subset​

Given a platform:

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

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

You need to specify both what platform to use and which ECUs to instantiate:

schema: remotive-topology-instance:0.2

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

ecus:
  BCM:

By default all channels that are connected to the ECU are instantiated. This means the resulting topology will be:

⚡ Notice how all the other ECUs are not instantiated!

You can optionally specify a subset of channels. For example this only includes a single channel:

schema: remotive-topology-instance:0.2

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

ecus:
  BCM:
    channels:
      DriverCan0:

This results in the following topology:

ECU configuration​

By default RemotiveTopology will instantiate ECUs by using RemotiveBroker as this is the default virtualization in RemotiveTopology. You can using any other virtualization tool as long as it can be containerized, see below.

The RemotiveBroker allows you to communicate as an ECU, for example using the correct IP address on a VLAN or using a CAN device. However, you need to control what behavior the RemotiveBroker should have. RemotiveTopology supports Behavioral models or mocks.

Notice that it is not required to specify a behavior, ie you can also control the RemotiveBroker either interactively or from your test case.

Behavioral models​

A behavioral model is a way to create a reusable component that emulates the behavior of a real ECU. It can receive and send messages.

To instantiate a behavioral model simply add the model to its ECU. Notice that an ECU can have multiple models, but each model must have a unique name.

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

When working with the RemotiveTopology framework you will refer to namespaces which represents your ECUs view on a channel. Namespaces are named <ECU>-<Channel>. If you are unsure about what namespaces exists you can start the topology instance and run:

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

Mock​

An ECU Mock is a simpler alternative to a Behavioral Model. A common usecase is providing a restbus that emulates an ECU so you can test a device in a realistic bus environment. A mock can also be used to verify that certain signals have been received.

By default a mock is created for all channels that the ECU is connected to:

ecus:
  FLCM:
    mock: {}

You can also specify what channels you want to mock. This is useful when combining mocks and behavioral models for the same ECU:

ecus:
  FLCM:
    mock:
      channels:
        DriverCan0:

Container​

Normally an ECU is instantiated using RemotiveBroker, but you can also use a custom container. This allows you to run any code as the ECU. For example to use a vsomeip implementation of an ECU:

ecus:
  ecu_a:
    container:
      dockerfile: ../../vsomeip.dockerfile
      volumes:
        - ../../config:/config_mapped
      working_dir: /vsomeip/build/examples
      command: "sh -c ./notify-sample"
      environment:
        - VSOMEIP_CONFIGURATION=/config_mapped/vsomeip-udp-service-ecu-a.json
        - VSOMEIP_APPLICATION_NAME=service-sample
        - VSOMEIP_LOGLEVEL=debug

Notice that the container will be started correctly connected to all ECU channels according to the platform, for example for ethernet the container will have the correct IP address.

Channel configuration​

CAN​

RemotiveTopology supports two ways of instantiating a CAN network:

  1. Using SocketCan
  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. However, SocketCan is only supported on Linux. On Mac and Windows you need to fallback to emulation. Notice that the UDP packets are still encoded in the same way as the real CAN frames, by using Ethernet PDUs.

SocketCan​

SocketCan is only available on Linux. In order to use this inside docker you need to run the provided DockerCAN service. For each channel you must specify what can device to use, for example to map candevice0 to channel DriverCan0 you need to specify:

channels:
  DriverCan0:
    type: can
    dev: candevice
    id: 0

Emulation using UDP​

Emulation using UDP is available on all platform and does not require any additional setup. For each channel specify:

channels:
  DriverCan0:
    type: can_over_udp

Another option is to use this setting for all can channels unless explicitly set:

settings:
  can:
    type: can_over_udp

Ethernet​

Ethernet does not require any configuration by default. However, to connect physical networks into the topology you need to configure which device should map into what channel. For example this is mapping eth1 device to the ETH channel:

channels:
  ETH:
    type: ethernet
    driver: macvlan
    device_name: eth1

This is using macvlan network driver.

Gateway​

By default docker will use the first ip address in the subnet as gateway. Sometimes you want to provide behavioral models or mocks using this ip address and it might be useful to have the gateway using a different ip address:

channels:
  ETH:
    type: ethernet
    gateway_ip: 10.1.1.192,

In general this is not needed.

Testbroker​

RemotiveTopology automatically assign a free ip address to the testbroker. If this assignment fails it might be necessary to specify a fixed ip address:

channels:
  ETH:
    type: ethernet
    testbroker_ip: 10.1.1.199,

In general this is not needed.

Additional containers​

RemotiveTopology also provides a way to run arbitrary containers inside the topology. These containers have access to RemotiveBroker and can therefore interact with ECUs in the topology.

A common usecase is to run testcases. By using an arbitrary container you can use whatever test framework you want:

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"

Profiles​

The containers can have one or more profiles. These correspond to profiles in docker compose, ie to run the tests above you simply start:

docker compose -f build/mytopology/docker-compose.yaml --profile tester up

When running tests it is useful to shut down the topology after the tests have completed using the flag --abort-on-container-exit:

docker compose -f build/mytopology/docker-compose.yaml --profile tester up --abort-on-container-exit

UI​

RemotiveTopology includes a web application that allows you to interact with the topology and inspect signals. To avoid running this in CI you need to trigger the profile: ui

docker compose -f build/mytopology/docker-compose.yaml --profile ui up

Then open http://localhost:8080 to access the user interface.

Settings​

CAN​

To emulate CAN using UDP for all CAN channels specify:

settings:
  can:
    type: can_over_udp

This setting is optional.

Dockerfiles​

To instantiate the mocks and behavioral models a dockerfile is needed. This dockerfile needs python and RemotiveTopology framework, but you can also add custom dependencies here.

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

Currently specifying mock is required, but python is optional since this can be configured as part of the Behavioral model.

RemotiveBroker​

RemotiveBroker can either be configured using instance.yaml or environment variables.

settings:
  remotivebroker:
    version: sha-cc5dc38
    license_file: ../../../LICENSE_FILE

Corresponding environment variables:

REMOTIVEBROKER_TAG=sha-cc5dc38
REMOTIVEBROKER_LICENSE=/path/to/LICENSE_FILE

Recommendation:

  • Version: Use instance.yaml to ensure that you have consistent behavior in all environments
  • License: Use REMOTIVEBROKER_LICENSE to avoid having LICENSE_FILE in your repository

Testbroker​

The testbroker needs to have access to all frames on all channels. To achieve this RemotiveTopology will automatically merge all necessary signaldatabases for use by the testbroker. However, it might be useful to explicitly set which signaldatabase that should be used by the testbroker, for example if you want to use ECU extracts for all ECUs but you also have a complete signaldatabase for the channel available.

settings:
  testbroker:
    channels:
      DriverCan0:
        database: ./special.dbc

These settings are optional.

UI​

You can configure details about the UI web application. It might be useful to specify a different port number. You can also change the profile, for example if you want to use ui profile for your custom containers.

settings:
  ui:
    port: 8080
    profile: ui

These settings are optional.