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.
- Desktop (normal)
- Headless (virtual machine, etc)
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.
With --no-browser you get a link to the sign-in page to open in a browser on another machine.
remotive setup --no-browser
Follow the sign-in until the browser shows a verification code, then paste it into 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.
- 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
-
In recent kernels
linux-msft-wsl-6.18.20.1or newer, only VXCAN is missing, this can be added by runningbuild-vxcan-module.shwhich can be found here. -
You can rebuild the kernel as shown here, make sure to also include
vxcanand if you intend to attach hardware you need to select the proper driver inCAN USB interfaces --->. You are encouraged to select*overMto 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.