Skip to main content

Install RemotiveTopology

Prerequisites​

RemotiveTopology runs the topology with the help of docker containers that interact with each other. Thus, you need Docker engine. Make sure to follow the post install steps to be able to run docker without sudo. Notice that Docker Engine is free and open source, only Docker Desktop requires license and this isn't needed for RemotiveTopology. However, RemotiveTopology also supports Podman as an alternative, simply replace docker with podman in all instructions.

To develop behavioral models for RemotiveTopology, you need Python 3.10 or later.

On Windows you need to use WSL2, follow the instructions below to get started.

RemotiveTopology setup​

To use RemotiveTopology, your organization must have an active subscription. If your organization is already a customer of RemotiveLabs, a subscription is likely already in place. Access to the service requires logging in with your organizational credentials to verify the subscription.

Free 30 day trial: For new users who wish to evaluate RemotiveTopology, it’s possible to create a trial subscription. This trial provides temporary access to explore the features and capabilities of the service. Once the trial period expires, you need to contact RemotiveLabs to purchase a full subscription and continue using RemotiveTopology. Read more about RemotiveTopology free trial.

First install RemotiveCLI. Then:

Run remotive setup. It signs you in to RemotiveCloud, chooses a default organization and gets RemotiveTopology ready to use, for example by starting a trial if your organization has no subscription and downloading RemotiveTopology. It checks what's already in place and asks before it changes anything, so it's safe to run again.

Signing in uses a web browser. If there's no browser on the machine, such as a virtual machine or a docker container, use --no-browser. You still need a browser, just not on that machine.

Signing in opens a web browser on this machine.

remotive setup

Follow the sign-in in the browser until it says that you have signed in. Setup then continues in the terminal.

To keep your current account, default organization and container engine without being asked about them, run remotive setup --only-missing.

If your subscription has expired, or for pricing information and to discuss your specific requirements, reach out to RemotiveLabs sales.

Verify installation​

To verify that RemotiveTopology is correctly installed:

remotive topology version

This displays the current version of RemotiveTopology and the default versions that are used in runtime environments.

If remotive setup hasn't downloaded RemotiveTopology already, the first run downloads it, which takes a while. Later runs are much faster.

WSL2 in Windows​

At the moment prebuilt kernels for WSL doesn't include support for VCAN/VXCAN and SocketCAN drivers. Before following the Linux instructions you need to do some WSL2 specific setup, pick one of the 3 options.

  1. Use RemotiveLabs public prebuilt kernel located here. This kernel also contains all kernel drivers available upstream located in the sub menu. All modules are statically linked. To use the prebuilt kernel do
wsl --shutdown
edit C:\Users\YOURWINDOWSLOGINNAME\.wslconfig

Modify the path to the location of your kernel

[wsl2]
kernel=C:\\Users\\<yourwindowsloginname>\\vmlinux_static_usb_drivers
  1. In recent kernels linux-msft-wsl-6.18.20.1 or newer, only VXCAN is missing, this can be added by running build-vxcan-module.sh which can be found here.

  2. You can rebuild the kernel as shown here, make sure to also include vxcan and if you intend to attach hardware you need to select the proper driver in CAN USB interfaces --->. You are encouraged to select * over M to create a kernel where the modules are statically linked.

By experience you are advised to uninstall docker for desktop and instead use vanilla Ubuntu docker engine install instructions as shown here. Make sure to follow the post install steps to be able to run docker without sudo.

Once you get the kernel running follow all instructions for Linux.

If you need to attach real USB SocketCAN adapter to connect to a real CAN/LIN bus go here, Windows allows WSL2 to get passthrough access to the connected USB device.

RemotiveBus​

Installation instructions and more information can be found in the RemotiveBus documentation.

Podman​

remotive setup saves the container engine it sets up as the default for all remotive topology commands. To set up Podman, run:

remotive setup --container-engine podman

You can also set the environment variable REMOTIVE_CONTAINER_ENGINE to podman, which takes precedence over the saved choice:

export REMOTIVE_CONTAINER_ENGINE=podman

To verify that it works simply run:

remotive topology version

Editor setup​

RemotiveTopology uses YAML files to describe instances and platforms. It's strongly recommended that you configure RemotiveTopology json schema in your editor to make it easier to edit these files. There is also a separate recording json schema which is used when working with recordings.

Visual Studio Code​

Install Red Hat YAML plugin

Add the following to your settings.json:

"yaml.schemas": {
"https://files.remotivelabs.com/remotive_topology/topology-0.18.schema.json":
["*.instance.yaml", "*.platform.yaml"],
"https://files.remotivelabs.com/remotive_topology/recording-0.2.schema.json":
["*.recordingsession.yaml", "*.mapping.yaml"]
},

Usage​

Run the following to get further instructions:

remotive topology --help

See Your first topology for next steps.

Important​

It's important that you run all remotive topology commands at the root of your project folder. Read more about the RemotiveTopology workspace.

Troubleshooting​

If something doesn't work, run:

remotive doctor

It checks your installation, sign-in, container engine and, on Linux, RemotiveBus without changing anything, and says how to fix any problem it finds.

Example output on Linux
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component ┃ Check ┃ Status ┃ Version ┃ Details ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ RemotiveBus │ installation │ ✓ ok │ 0.11.3 │ provides docker/podman CAN, VCAN │
│ │ │ │ │ and VLAN networks (used by │
│ │ │ │ │ RemotiveTopology) │
│ │ service │ ✓ ok │ - │ daemon that creates the container │
│ │ │ │ │ CAN/VCAN/VLAN networks │
│ │ kernel module vcan │ ✓ ok │ - │ loaded - enables virtual CAN buses │
│ │ kernel module vxcan │ ✓ ok │ - │ loaded - enables tunneling CAN │
│ │ │ │ │ interfaces into containers │
│ │ kernel module can_gw │ ✓ ok │ - │ loaded - enables routing CAN │
│ │ │ │ │ frames between interfaces │
│ │ docker plugin socket │ - unknown (not required) │ - │ no permission to check │
│ │ │ │ │ /run/docker/plugins/remotivebus.s… │
│ │ │ │ │ (run doctor with sudo to verify) │
│ │ remotivebus group │ ✓ ok │ - │ lets rootless podman reach the │
│ │ │ │ │ RemotiveBus socket │
├──────────────────┼──────────────────────┼──────────────────────────┼─────────┼────────────────────────────────────┤
│ Container engine │ docker engine │ - missing (not required) │ - │ 'docker' is not in PATH │
│ │ podman engine │ ✓ ok │ 5.4.2 │ runs the RemotiveTopology │
│ │ │ │ │ containers │
│ │ podman compose │ ✓ ok │ 5.4.2 │ runs multi-container topologies │
├──────────────────┼──────────────────────┼──────────────────────────┼─────────┼────────────────────────────────────┤
│ Authentication │ credentials │ ✓ ok │ - │ credentials found for │
│ │ │ │ │ me@mycompany.com │
│ │ login │ ✓ ok │ - │ authenticated with the access │
│ │ │ │ │ token for │
│ │ │ │ │ me@mycompany.com │
│ │ organization │ ✓ ok │ - │ (my-company) My Company │
├──────────────────┼──────────────────────┼──────────────────────────┼─────────┼────────────────────────────────────┤
│ Wireshark │ wireshark │ ✓ ok │ - │ opens and views packet captures on │
│ │ │ │ │ this host │
│ │ dumpcap │ ✓ ok │ - │ streams remote captures to a │
│ │ │ │ │ desktop Wireshark │
│ │ wireshark group │ ✓ ok │ - │ lets your user capture packets │
│ │ │ │ │ without sudo │
└──────────────────┴──────────────────────┴──────────────────────────┴─────────┴────────────────────────────────────┘

If that doesn't solve the problem, contact RemotiveLabs support at support@remotivelabs.com. Include the output of remotive doctor.