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.

tip

To understand how a topology will be instantiated you can use

remotive-topology show topology --resolve <filename>

This will show only the parts of the platoform that will be instantiated and any defaults that have been applied.

Platform subset​

Given a platform:

schema: remotive-topology-platform:0.4
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.4

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

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​

Channels must be configured when connecting to physical hardware or when connecting to software running outside the containerized environment.

CAN​

RemotiveTopology supports two ways of instantiating a CAN network:

  1. Using 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. However, SocketCan is only supported on Linux with DockerCAN installed. On Mac and 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.

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
    driver:
      type: dockercan
      device_name: candevice0

By default the channel is configured to connect to a device with the same name as the channel (but in lowercase), ie like this:

channels:
  MyChannel:
    type: can
    driver:
      type: dockercan
      device_name: mychannel
note

Notice that inside the docker container the device will be named based on channel name but with a 0 appended, ie in the default case it will be called mychannel0.

If you need a specific name inside the docker container you can specify peer:

channels:
  DriverCan0:
    type: can
    driver:
      type: dockercan
      device_name: candevice0
      peer: in-docker
note

Notice that even in this case 0 will be appended, ie the device will be called in-docker0.

Recommendations:

  • Avoid names such as can0 or can1
  • Rename physical devices to match your target architecture, eg sudo ip link set can0 name drivercan0
  • Inside the container try to use a name similar to the channel. This makes it easier to understand in a virtual context.

Emulation using UDP​

Emulation using UDP is available on all platform and does not require any additional setup. This works by using UDP multicast and encoding frames as Ethernet PDUs, ie signals are encoded the same ways when using CAN. Simply change this global setting:

settings:
  can:
    default_driver: udp

Optionally, you can specify this for each instance channel:

channels:
  DriverCan0:
    type: can
    driver:
      type: udp

Ethernet​

Ethernet does not require any configuration by default.

VLAN​

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:
      type: macvlan
      device_name: eth1

This is using macvlan network driver.

note

If the platform has defined a vlan this tag will be added automatically!

Bridge with iptables​

docker network create -d bridge \
  --subnet=198.0.0.0/24 \
  --gateway=198.0.0.252 \
  LowSafety
sudo iptables -I DOCKER 1 -d 198.0.0.22/32  -i gre1 -o br-ccea162a699d -c 0 0 -j ACCEPT
sudo iptables -I DOCKER 1 -s 198.0.0.22/32 -i br-ccea162a699d -o gre1 -j ACCEPT

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:
    default_driver: udp

This setting is optional, by default DockerCAN is used.

Docker​

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

settings:
  docker:
    mock:
      dockerfile: ../python-runner.dockerfile
    python: 
      dockerfile: ../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: v1.10.1
    license_file: ../../../LICENSE_FILE

Corresponding environment variables:

REMOTIVEBROKER_TAG=v1.10.1
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.