– Install

Docs: Install on an industrial PC

Mon, 01 Jan 0001 00:00:00 +0000

An industrial PC runs MCX-RTOS from its internal disk. To put the image there, you boot the controller from a USB imager stick that carries the image, and the stick writes it to the disk. It takes four parts; click one to jump to it.

Before you start

The Intel image and the imager stick image, both downloaded from the store: see Download.
An empty USB drive of at least 8 GB.
A keyboard and a display for the controller, or a network cable between your PC and the controller.

Create the imager stick

Warning

Writing the imager stick image erases everything on the USB drive.

Insert the USB drive into your PC, then write the imager stick image to it. Select the operating system of your PC:

Ubuntu writes the image with its Disks tool, through Disk Image Writer.

In your file manager, right-click the imager stick image (…mcx-clonezilla….img.xz) and choose Open With › Disk Image Writer.
In the Restore Disk Image window, set Destination to your USB drive. Check the size and name: the wrong choice erases another disk.
Press Start Restoring... and confirm.
When writing is done, Ubuntu mounts the ImageData partition of the stick.

Watch it as a video

Windows has no built-in tool to write a disk image, so you use a separate one such as Rufus.

Install and start the disk image writer.
Select your USB drive and the imager stick image (…mcx-clonezilla….img.xz). Check that you picked the USB drive: the wrong choice erases another disk.
Start writing and wait until it is done.
The stick now shows up as a drive called ImageData.

There is no tested procedure for macOS yet. Use an Ubuntu or Windows PC to create the stick.

Copy the image onto the stick

The stick has a partition called ImageData. The imager looks there for the images it can install.

Open the ImageData partition of the stick in your file manager.
Copy the Intel image (the .img.xz file) into it.
Eject the stick safely before you pull it out.

Boot the controller from the stick

Switch the controller off.
Insert the imager stick into a USB port of the controller.
Switch the controller on. It boots from the stick.

If it starts from its internal disk instead, enable booting from USB in the controller’s BIOSThe BIOS or UEFI setup is the firmware menu of a PC, where you choose which drive it starts from. You usually open it by pressing a key such as Del or F2 while the PC starts. , or pick the stick in its boot menu.

Watch the boot and install as a video

Open the imager terminal

You give the imager its commands in a terminal. Open it on the controller itself, or from your PC over the network:

Connect a keyboard and a display to the controller. After the stick has booted, the display shows the imager terminal, ready for a command. If it asks you to log in, use the user admin and the password vectioneer.

With SSHSSH (Secure Shell) opens a terminal on another computer over the network. Ubuntu, macOS and Windows 10 and later have the ssh command built in. you open the imager terminal from your PC, without a keyboard or display on the controller.

Connect your PC to the controller’s network port with a network cable.
Give your PC’s network adapter an address in the 192.168.2.x range, for example 192.168.2.10: see Configure your network.
Open a terminal on your PC and connect to the controller at controller_ip_addressThe IP address of your controller. In most cases 192.168.2.100.:
```
ssh admin@controller_ip_address
```
Log in with the password vectioneer. The terminal shows the imager’s welcome text.

Run mci-help for more information on the imager commands.

Install the image

The imager has two commands: mci restore writes an image from the stick to the controller’s disk, and mci backup saves the controller’s disk to the stick. To keep what is on the controller now, back it up first.

Warning

Installing the image erases everything on the disk you choose. Back up the controller first if you want to keep its current software or settings.

Start the install:
```
mci restore
```
Choose the image to install: the Intel image you copied into ImageData.
Choose the disk to install it on: the controller’s internal disk, usually /dev/sda. The disk must be at least as large as the image.
Wait until the imager is done, which takes a while. It ends with Done: and the partitions of the disk.
Check the output for errors.
Pull out the imager stick and restart the controller:
```
sudo reboot
```

The controller now starts MCX-RTOS from its disk.

A backup saves the controller’s disk as an image on the stick, so you can install it again later with mci restore. Make sure the stick has enough free space.

Start the backup:
```
mci backup
```
Choose the source disk: the controller’s internal disk, usually /dev/sda.
Choose the target directory on the stick. The imager offers a new directory named after the date and time, for example /mnt/usb/2026-01-06_15-44-42_mci-fsa-image.
```
Choose Source Device:
1) sda /dev/sda
...
Choose Target Image Directory:
1) /mnt/usb/2026-01-06_15-44-42_mci-fsa-image   (new directory)
...
Done
```
Wait until the imager shows Done.
Pull out the imager stick and restart the controller:
```
sudo reboot
```

The backup is a directory of filesystem archives, not a raw disk image. mci restore can install it, but a virtual machine such as QEMU cannot start from it.

Make a raw disk image for QEMU

A raw disk image is one file with the whole disk in it, which QEMU can start. You make it by restoring the backup into an empty image file on the stick. The stick needs room for the backup and for the full image file, 6 GB in this example.

Go to the stick and check it is mounted:
```
cd /mnt/usb
ls -lart
```
Create an empty 6 GB image file:
```
truncate -s 6G temp.img
```

Attach it as a loop device and see which one it got:

sudo losetup -fP temp.img
losetup -a

/dev/loop1: []: (/mnt/usb/temp.img)

Back up the controller as above with mci backup, if you have not done so yet.
Restore the backup into the loop device. Use the loop device from step 3:
```
mci restore -d /dev/loop1
```

Check that the loop device now has partitions:

lsblk

NAME     MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
loop1      7:1    0     6G  0 loop
├─loop1p1 259:2    0    34M  0 part
└─loop1p2 259:3    0     6G  0 part

Detach the loop device:
```
sudo losetup -d /dev/loop1
```

Check the partition table of the image file:

fdisk -l temp.img

Disklabel type: gpt

Device     Start      End  Sectors Size Type
temp.img1   2048    71615    69568  34M EFI System
temp.img2  71616 12582847 12511232   6G Linux filesystem

temp.img is now a raw disk image. You can start it in QEMU: see Run a virtual machine.

Next: Step 2: connect your PC.

Docs: Install on a Raspberry Pi

Mon, 01 Jan 0001 00:00:00 +0000

A Raspberry Pi runs MCX-RTOS from its microSD card. You write the image to the card on your PC with Raspberry Pi Imager, let the image use the whole card, and put the card in the Pi. For a Raspberry Pi Compute Module, which has built-in storage instead of a card, see Install on a Compute Module.

Before you start

The Raspberry Pi image, downloaded from the store: see Download.
A microSD card and a card reader for your PC.

Write the image to the card

Warning

Writing the image erases everything on the SD card.

Download Raspberry Pi Imager for your operating system from raspberrypi.com/software and install it.
Insert the SD card into your PC and open Raspberry Pi Imager. The labels below are those of the version in the screenshots; newer versions word them differently.
Press CHOOSE OS, scroll down and choose Use custom. Select the Raspberry Pi image you downloaded.
Press CHOOSE STORAGE and select the SD card.
Press WRITE. Raspberry Pi Imager warns that all data on the card will be erased; press YES to go on.
Wait until writing and verifying are done.

Use the whole card

The image only fills part of the card. Grow its second partition to the end of the card, so MCX-RTOS can use all of it. This uses GPartedGParted is a free partition editor for Linux. It resizes, moves and creates partitions on a disk. on a Linux PC.

Install GParted, for example with sudo apt install gparted on Ubuntu, and open it.
At the top right, select the SD card. Select its second partition and press (Resize/Move).
Set New size (MiB) to the maximum and press Resize/Move.
Press (Apply All Operations) to apply the change to the card.
Eject the SD card, put it in the Raspberry Pi and switch the Pi on.

Connect to the Raspberry Pi

A standard Raspberry Pi has one network port, and MCX-RTOS uses it for the EtherCAT network. You reach the controller over Wi-Fi, or through a second wired network adapter such as a USB-to-Ethernet adapter.

Without a second adapter, the Raspberry Pi opens its own Wi-Fi network. This needs a Raspberry Pi model with Wi-Fi.

On your PC, connect to the Wi-Fi network of the controller, for example mcx-fa3c06, with the password vectioneer.
The controller’s address on that network is 192.168.0.1. Use it wherever these pages say controller_ip_addressThe IP address of your controller. In most cases 192.168.2.100..

To join the controller to an existing Wi-Fi network instead, or to change its access point, see Network configuration.

Note

On a wired connection to a Raspberry Pi, ARP sometimes has to be switched on first: sudo ifconfig eth0 arp.

Next: Step 2: connect your PC.

Docs: Run a virtual machine

Mon, 01 Jan 0001 00:00:00 +0000

A virtual machine runs MCX-RTOS on your own PC, so you can try Motorcortex without controller hardware. It has no EtherCAT devices, so the application must run in simulation mode. On Ubuntu you run it in QEMU; on Windows in VirtualBox.

Before you start

The image for your virtual machine, downloaded from the store: see Download. QEMU takes the Intel disk image, VirtualBox the .ova file.
A PC whose processor supports virtualization, with at least 8 GB of memory.

Set up the virtual machine

Select the operating system of your PC:

QEMUQEMU is a free program that runs a virtual machine. With KVM, the virtualization built into the Linux kernel, the virtual machine runs at close to the speed of your PC. starts the Intel disk image as a virtual machine. Three scripts do the work: one starts QEMU, and two set up and remove the network between your PC and the virtual machine.

How the virtual machine reaches your PC

QEMU connects the virtual machine to a TAP deviceA TAP device is a virtual network port on your PC. What QEMU sends into it comes out of the virtual machine’s network card, and the other way round. , tap0. The script network-up.sh adds tap0 to a bridge, br0, and gives your PC the address 192.168.2.15 on it. The controller in the virtual machine has the fixed address 192.168.2.100, so your PC reaches it at controller_ip_addressThe IP address of your controller. In most cases 192.168.2.100. without further network settings. When QEMU stops, network-down.sh removes the bridge again.

If your PC also has a network adapter on 192.168.2.x, for example to a real controller, disconnect it while the virtual machine runs. Otherwise your PC does not know which of the two to use.

Check that your PC supports virtualization

The scripts need Ubuntu 20.04 or later; they are tested on 22.04 and 24.04. The virtual machine takes 4 GB of memory and four processor cores.

Check that the processor supports virtualization. A number greater than 0 means it does:
```
egrep -c '(vmx|svm)' /proc/cpuinfo
```
Check that KVM can be used. kvm-ok comes with the cpu-checker package:
```
sudo apt install cpu-checker
kvm-ok
```
```
INFO: /dev/kvm exists
KVM acceleration can be used
```
If it cannot be used, switch on Intel VT-x or AMD-V in the BIOS of your PC.

Install QEMU

Install QEMU with KVM, and OVMF, the UEFI firmware the image starts with:

sudo apt update
sudo apt install -y qemu-system-x86 qemu-kvm ovmf bridge-utils net-tools

Get the scripts

Download the three scripts into the folder that holds the Intel disk image:
- start-qemu-mcx-image.sh: starts QEMU
- network-up.sh: sets up the bridge
- network-down.sh: removes the bridge

Make them executable:

chmod +x start-qemu-mcx-image.sh network-up.sh network-down.sh

Start the virtual machine

In that folder, start the script with the name of the image file:
```
./start-qemu-mcx-image.sh mcx-image-mcx-intel.rootfs-2026.05.1-0-g34c0e28-20260508091432.wic
```
The script uses sudo, so it asks for your password. If only a compressed .wic.xz or .wic.gz file is there, the script unpacks it first and keeps the compressed file.
The virtual machine starts in the same terminal: QEMU shows its console there instead of in a window.
When MCX-RTOS has started, log in from a second terminal on your PC, with the password vectioneer:
```
ssh admin@controller_ip_address
```

To stop the virtual machine, run sudo poweroff in it, or press Ctrl+A and then X in the QEMU terminal.

What the QEMU command does

start-qemu-mcx-image.sh ends with this command:

sudo qemu-system-x86_64 \
    -drive file="$BASE_NAME",format=raw,if=virtio \
    -m 4096 \
    -bios /usr/share/ovmf/OVMF.fd \
    -cpu Skylake-Client \
    -smp cores=4 \
    -enable-kvm \
    -netdev tap,id=net0,ifname=tap0,script=network-up.sh,downscript=network-down.sh \
    -device virtio-net-pci,netdev=net0 \
    -nographic

Option	What it does
`sudo`	TAP networking needs root rights
`qemu-system-x86_64`	The QEMU emulator for 64-bit Intel and AMD processors
`-drive file=…,format=raw,if=virtio`	The disk image as a raw disk, on a fast virtio disk controller
`-m 4096`	4096 MB of memory for the virtual machine
`-bios /usr/share/ovmf/OVMF.fd`	Start with UEFI firmware instead of a legacy BIOS
`-cpu Skylake-Client`	Show the virtual machine a Skylake-generation Intel processor
`-smp cores=4`	Four processor cores
`-enable-kvm`	Use KVM, so the virtual machine runs at close to native speed
`-netdev tap,…`	The network through `tap0`, set up by `network-up.sh` and removed by `network-down.sh`
`-device virtio-net-pci,netdev=net0`	A virtio network card on that network
`-nographic`	No window: the console runs in the terminal

VirtualBox runs the Motorcortex appliance, the .ova file from the store. The virtual machine talks to your PC over a host-only networkA host-only network is a virtual network between your PC and its virtual machines only. It does not reach other computers. , which you set up once.

Install VirtualBox

Download VirtualBox for Windows from virtualbox.org and open the .exe file.
In the setup wizard, press Next.
Press Next twice, to keep the default features, install location and shortcuts.
The wizard warns that your network connections are interrupted for a moment. Press Yes.
Press Install. When Windows asks whether to install the device software, press Install.
Press Finish.

Add the host-only network

Open VirtualBox, go to File and open Host Network Manager....
Press Create. VirtualBox adds a VirtualBox Host-Only Ethernet Adapter.
In the DHCP Server column, tick Enable for the new adapter and press Apply.

Change the host-only adapter settings in Windows

In Windows, open Network Connections.
Right-click the connection of the VirtualBox Host-Only Ethernet Adapter and choose Properties.
Untick VirtualBox NDIS6 Bridged Networking Driver and press OK.
Restart the connection: right-click it, choose Disable, then Enable.

Import the Motorcortex appliance

In VirtualBox, go to File and choose Import Appliance....
At File, choose the .ova file you downloaded and press Next.
In Appliance settings, press Import.
Connect the virtual machine to the host-only network. Select it, press Settings and open Network. On Adapter 1, set Name to VirtualBox Host-Only Ethernet Adapter and press OK.

If the name does not show up in the list, restart VirtualBox and try again.

Start the virtual machine

In VirtualBox, select the Motorcortex virtual machine and press Start. It takes a few seconds to start.
The console shows the address of the virtual machine next to eth0, for example 192.168.56.111.
Log in with the user admin and the password vectioneer.

This address takes the place of controller_ip_addressThe IP address of your controller. In most cases 192.168.2.100. everywhere: in your browser, over SSH and when you deploy packages. Check the connection from a terminal on your PC, with the address from your console:

ssh admin@192.168.56.111

The virtual machine does not start: VERR_PATH_NOT_FOUND

VirtualBox can fail to start the machine with this error:

Failed to load the NVRAM store from the file (VERR_PATH_NOT_FOUND).
Can't attach Nvram Storage driver (VERR_PATH_NOT_FOUND).
Result Code:
E_FAIL (0X80004005)

Rename the virtual machine, for example from Motorcortex 2024.01 to Motorcortex 2024, and start it again.

This is the older way to run MCX-RTOS on Ubuntu. QEMU is the recommended one. VirtualBox runs the Motorcortex appliance, the .ova file from the store, and talks to your PC over a host-only networkA host-only network is a virtual network between your PC and its virtual machines only. It does not reach other computers. .

Install VirtualBox

Download the VirtualBox .deb package for your Ubuntu version from virtualbox.org and install it.
Open VirtualBox. Go to File › Tools and open Network Manager.
Press Create, then Properties.
On the DHCP Server tab, tick Enable Server and press Apply.

Import the Motorcortex appliance

In VirtualBox, go to File and choose Import Appliance....
Choose the .ova file you downloaded and press Finish.

Start the virtual machine

In VirtualBox, select the Motorcortex virtual machine and press Start. It takes a few seconds to start.
The console shows the address of the virtual machine next to eth0, for example 192.168.56.111.
Log in with the user admin and the password vectioneer.

ssh admin@192.168.56.111

To use a real controller again, switch the host-only network off with sudo ifconfig vboxnet0 down. Switch it back on with sudo ifconfig vboxnet0 up.

The virtual machine does not start: VERR_PATH_NOT_FOUND

VirtualBox can fail to start the machine with this error:

Failed to load the NVRAM store from the file (VERR_PATH_NOT_FOUND).
Can't attach Nvram Storage driver (VERR_PATH_NOT_FOUND).
Result Code:
E_FAIL (0X80004005)

Rename the virtual machine, for example from Motorcortex 2024.01 to Motorcortex 2024, and start it again.

There is no tested procedure for macOS yet. To build a VirtualBox machine from scratch instead of importing the .ova file, see Virtual machine full configuration.

Next: Step 2: connect your PC.