---
title: "Virtual ECUs"
description: "Run production ECU software as a virtual ECU (vECU) in a RemotiveTopology instance, with its own interfaces and IP addresses on SocketCAN and Ethernet, and debug it."
source: https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus/virtual-ecus
last_updated: 2026-11-20
---

# Virtual ECUs

A virtual ECU (vECU) is the production software of an ECU running without its hardware, in some cases the same binary that runs on the target. In RemotiveTopology a virtual ECU runs in a container, connected to the channels of the ECU. Your tests then run against the software your team ships, not against a model of it.

Virtual ECUs are typically your Device Under Test (DUT). You use [mocks](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus/mocks.md) and [behavioral models](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus/behavioral-models.md) to create a simulated environment where your tests can run.

## Connecting a vECU

A vECU typically doesn't use the RemotiveBroker gRPC APIs. Instead you should use SocketCAN or POSIX sockets directly. Sometimes you need to replace part of the Basic Software (BSW) with code that can run on Linux and for example directly use SocketCAN. Some implementations have this support built-in, for example OpenBSW. Contact [support@remotivelabs.com](mailto:support@remotivelabs.com) if you need assistance with this step.

If your vECU is built as an FMU, then you can run it directly using RemotiveTopology [FMU](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus/fmu.md) support.

## Containerize the ECU software

Build an image with the ECU software and what it needs to run. For example, a Linux build of a `BCM` application:

```dockerfile
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y iproute2 can-utils && rm -rf /var/lib/apt/lists/*
COPY build/bcm /opt/bcm/bin/bcm
CMD ["/opt/bcm/bin/bcm"]
```

`iproute2` and `can-utils` aren't needed by the software, but they make it much easier to [debug](#debug-a-virtual-ecu) the container.

Then replace the implementation of the ECU in the instance with the container:

```yaml
ecus:
  BCM:
    container:
      build:
        dockerfile: ../bcm/Dockerfile
      command: /opt/bcm/bin/bcm --can drivercan --can bodycan
```

The container properties are described in the [container schema](https://developer.remotivelabs.com/apis/json/topology#oneOf_i1_containers_additionalProperties). They mirror the service properties in Docker Compose.

If the software is built for another CPU architecture than your computer, set `platform`, for example `platform: linux/arm64`, and Docker emulates it. Emulation is slower than running natively.

## Network interfaces

The container gets one network interface for each channel of the ECU. Your software needs to know the names of the interfaces, and on Ethernet also the IP addresses.

### CAN and LIN

On CAN, the virtual ECU uses SocketCAN, so the channel must use the [RemotiveBus driver](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/can.md#remotivebus). [UDP emulation](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/can.md#emulation-using-udp) sends CAN frames as UDP packets and doesn't provide a SocketCAN interface. RemotiveBus is available on Linux and in WSL2 on Windows. On macOS, run RemotiveTopology in a Linux virtual machine.

The interface name inside the container is the `device` of the channel, or the lowercase channel name if `device` isn't set. Set it explicitly, so the command line of the software doesn't depend on the default:

```yaml
channels:
  BodyCan:
    type: can
    driver:
      type: remotivebus
      config:
        type: vcan
        device: bodycan
```

Linux limits interface names to 15 characters. See [Naming devices](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/can.md#naming-devices).

On a LIN channel, RemotiveBroker transports LIN frames inside CAN frames, see [LIN channels](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/lin.md). A virtual ECU on a LIN channel must use the same encoding.

### Ethernet

On an Ethernet channel the container gets the IP address of the ECU, as set with `host` in the [platform](https://developer.remotivelabs.com/docs/remotive-topology/concepts/platform.md#ethernet-channel) or in ARXML. The software can bind to that address like on the target. To see the addresses that the instance uses, run `remotive topology show instance`.

- With the default Docker bridge driver, look up the interface by its IP address, for example with `ip addr` in the container.
- With the [RemotiveBus driver](https://developer.remotivelabs.com/docs/remotive-topology/usage/channels/ethernet.md#vlan), set `device` to choose the name of the interface, for example `eth0.10`. The container gets a trunk interface and a VLAN subinterface. If the software handles VLAN tags itself, [skip the VLAN subinterface](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus.md#vlan-trunk-interface).

For example, a `GWM` that runs a vsomeip SOME/IP application:

```yaml
ecus:
  GWM:
    container:
      build:
        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
```

## Testing a virtual ECU

There's no RemotiveBroker for the ECU, so there are no `<ECU>-<Channel>` namespaces for it. Test it through what the other ECUs see, the same way you test hardware:

- Control the input through the namespaces of the ECUs that send to it, for example a mock of `SCCM` on `SCCM-DriverCan`.
- Check the output in the namespaces of the ECUs that receive from it, for example `FLCM-BodyCan`, or in the TopologyBroker namespace of the channel, for example `topology-BodyCan`, which decodes all traffic on the channel.
- On Ethernet, use a [test access point (TAP)](https://developer.remotivelabs.com/docs/remotive-topology/usage/test/tap.md) to observe traffic between ECUs that don't use a broker.

Tests written this way also work for a behavioral model of the ECU and for the hardware. See [Writing tests](https://developer.remotivelabs.com/docs/remotive-topology/usage/test.md).

## Debug a virtual ECU

Find the name of the service of the virtual ECU in the generated Docker Compose file:

```sh
docker compose -f output/my-vehicle/docker-compose.yml config --services
```

Then:

- Follow its output with `docker compose -f output/my-vehicle/docker-compose.yml logs -f <service>`.
- Open a shell in it with `docker compose -f output/my-vehicle/docker-compose.yml exec <service> sh`, and check the interfaces with `ip addr` or the CAN traffic with `candump bodycan`.
- Capture its traffic with [Wireshark and Edgeshark](https://developer.remotivelabs.com/docs/remotive-topology/usage/run/wireshark.md).

To run the software under a debugger, run it on your computer instead of in a container. Mark the ECU as [external](https://developer.remotivelabs.com/docs/remotive-topology/usage/ecus.md#external-ecus) and make the channels visible on the host, with `host_device` on CAN channels using RemotiveBus. Then start the software from your development environment, connected to the host interfaces, while the rest of the topology runs in containers. This only works on Linux, where the host has the SocketCAN interfaces.

```yaml
ecus:
  BCM:
    external: {}

channels:
  BodyCan:
    type: can
    driver:
      type: remotivebus
      config:
        type: vcan
        device: bodycan
        host_device: bodycan
```
