Linux X64

This guide is for 64-bit Intel and AMD computers running Ubuntu 24.04 LTS: desktop PCs, laptops, mini PCs and x64 single board computers such as LattePanda and UP boards. For a Raspberry Pi or another ARM board, use Raspberry-Pi.md instead.

Requirements

A 64-bit x64 computer (Intel or AMD).
Ubuntu 24.04 LTS (64-bit), the Desktop or the Server (headless) edition.
An internet connection.

Ubuntu 24.04 LTS is the only Linux distribution ARCx supports, on x64 and on ARM64 alike. Other distributions and other Ubuntu versions are not tested and are not supported.

You do not need to install .NET. It is included with ARCx.

Check the computer and the OS

Open a terminal (or connect with SSH) and run:

uname -m
grep -E '^(ID|VERSION_ID)=' /etc/os-release

It must print x86_64, ID=ubuntu and VERSION_ID="24.04". If uname -m prints aarch64, the computer is ARM; use Raspberry-Pi.md.

Install

Run these commands in a terminal:

# Install the system libraries ARCx uses (camera and computer vision, audio, graphics)
sudo apt update
sudo apt install -y unzip libicu74 libasound2t64 libjack-jackd2-0 libfontconfig1 libgl1 \
  libgtk-3-0t64 ocl-icd-libopencl1

# And the ones the Chromium browser windows use (web pages on the robot's own screen)
sudo apt install -y libnss3 libatk-bridge2.0-0t64 libcups2t64 libgbm1 libxkbcommon0 \
  libxcomposite1 libxdamage1 libxrandr2 libpango-1.0-0 libatspi2.0-0t64 fonts-dejavu-core

# Start in your home folder
cd ~

# Download ARCx
wget -nd https://synthiam.com/api/download/arcx/ARCx-Linux-64.zip

# Unzip it into a folder named ARCx
unzip ARCx-Linux-64.zip -d ARCx

# Go into the folder
cd ARCx

# Allow the ARCx program to run
chmod +x ARCx

# Start ARCx
./ARCx

If apt install reports that a package cannot be found, the OS is not Ubuntu 24.04. See Check the computer and the OS.

If ls inside ~/ARCx shows a single folder instead of the ARCx program, cd into that folder before running chmod and ./ARCx.

The zip file is no longer needed once it is unzipped. Delete it with rm ~/ARCx-Linux-64.zip.

Open the interface

ARCx prints its start-up messages in the terminal. Leave the terminal open; it is ARCx.

On the same computer

Open any browser and go to:

http://127.0.0.1:5000

On Linux, ARCx does not open the browser for you by default. You can turn that on in the ARCx preferences.

From another computer, phone or tablet

Start ARCx so it accepts connections from the network:

cd ~/ARCx
./ARCx -b http://0.0.0.0:5000

Find this computer's IP address:

hostname -I

On the other device, browse to http://<that-ip-address>:5000, for example http://192.168.1.30:5000.

If the firewall is turned on (Ubuntu's ufw, for example), allow the port:

sudo ufw allow 5000/tcp

Warning: ARCx has no login. Anyone who can reach that address can control the robot and read or delete files on this computer. Only do this on a network you trust.

Stop

Press Ctrl+C in the terminal where ARCx is running. Allow around 20 seconds for a clean shutdown.

Closing the browser does not stop ARCx. If you started ARCx over SSH, closing the SSH session stops it. To keep it running after you disconnect, run it as a service (below).

Give ARCx access to hardware

ARCx talks to cameras, microphones, speakers, serial devices (USB serial adapters, servo controllers) and game controllers as the user who runs it. Linux controls access to each kind of device with a group: a program can open a device only if its user is in the group that owns the device. On Ubuntu a new user is not in the serial port group, so ARCx cannot open a serial port until you add it.

Add the user to all the groups ARCx uses with one command:

sudo usermod -aG dialout,video,audio,input,render $USER

To add only the serial port group, the command is:

sudo usermod -a -G dialout $USER

Group	What it gives access to	Devices
`dialout`	Serial ports: USB serial adapters (FTDI, CH340, CP210x), Arduino and other USB microcontroller boards, servo controllers, motor controllers and lidars on a serial port, and built-in serial ports	`/dev/ttyUSB`, `/dev/ttyACM`, `/dev/ttyS*`
`video`	USB and built-in cameras	`/dev/video*`
`audio`	Sound cards, speakers and microphones	`/dev/snd/*`
`input`	Gamepads, joysticks and other input devices	`/dev/input/*`
`render`	The graphics processor (GPU), for GPU acceleration in browser windows and in robot skills that run AI models	`/dev/dri/renderD*`

While you are logged in to the Ubuntu desktop, the desktop session lets you use cameras, sound, controllers and the GPU without these groups. Serial ports are never included, and none of it applies when ARCx runs over SSH or as a service. Add all the groups so ARCx works the same way however it is started.

Things to know:

Always include -a. -a adds the groups to the ones the user is already in. Without it, usermod -G replaces all the user's groups, including sudo, and the user can no longer run administrator commands. -aG and -a -G do the same thing.
$USER is the user typing the command. If ARCx runs as a service under a different user, put that user name in its place, for example sudo usermod -aG dialout,video,audio,input,render robot.
The change takes effect at the next login. Log out and back in, or reboot. A terminal or SSH session that is already open keeps the old groups, so close it and connect again. If ARCx runs as a service, restart it so it picks up the new groups: sudo systemctl restart arcx.
To check, run groups. It lists the groups of the current session, so it shows the new ones only after you log in again. groups $USER lists the groups that are saved for the user, even before you log in again.

To see which group a device needs, list it with ls -l. The fourth column is the group:

ls -l /dev/ttyUSB0
# crw-rw---- 1 root dialout 188, 0 Oct  4 10:12 /dev/ttyUSB0

To find which port a USB serial device is on, run ls -l /dev/serial/by-id/. It lists each connected USB serial device by its name and shows the port (ttyUSB0, ttyACM0, ...) it uses.

The X display (browser windows)

There is no group for the X display. Access to it belongs to the user who started it, not to a group, so adding the user to video or any other group does not change it.

The kiosk display service in Browser windows accepts every user on the same computer, so nothing needs to be added.
The Ubuntu desktop's display belongs to the user who is logged in to it. Run ARCx as that same user and it can draw on it. If the ARCx service runs as a different user, allow that user from a terminal on the desktop: xhost +SI:localuser:<user name>. The permission ends when the desktop user logs out.

Gamepads and HID devices

Game controllers are read from /dev/input, which belongs to the input group added above. While you are logged in to the desktop, Ubuntu usually lets your session use a plugged-in controller anyway, but ARCx started over SSH or as a service needs the group. Views, Gamepads And HID in ARCx shows every controller it can see; if it shows none, the Diagnostics page says whether permission is the reason.

A robot skill that talks to a HID device directly (a custom USB board, a sensor, a button box) opens its /dev/hidraw* node, which only root can open by default. Give the input group access to that one device with a udev rule, using the vendor and product ID shown on the Gamepads And HID page (or by lsusb), in lowercase:

echo 'KERNEL=="hidraw*", ATTRS{idVendor}=="1234", ATTRS{idProduct}=="abcd", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-arcx-hid.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

Then unplug the device and plug it back in.

USB serial adapter disappears as soon as it is plugged in

On Ubuntu, the brltty package (support for braille displays) grabs some common USB serial chips, including the CH340/CH341, and the port vanishes. If you do not use a braille display, remove it:

sudo apt remove brltty

Then unplug the adapter and plug it back in. It appears as /dev/ttyUSB0 (or /dev/ttyACM0).

Browser windows

Robot skills and scripts can show web pages - a robot face, a dashboard, a video call, a kiosk screen - in Chromium windows on the monitors plugged into this computer. Views, Browser Windows in ARCx lists them and has a form to try one. Chromium ships inside ARCx; it only needs the system libraries from the Install step and an X display to draw on.

With a desktop

Nothing to set up. ARCx started from the desktop uses it, and an ARCx started as a service finds the desktop's display by itself (it looks for the X server on :0, which Ubuntu's desktop runs through XWayland).

Without a desktop (kiosk)

A desktop is not needed. A bare X server with no desktop, no window manager and no login screen is all a kiosk needs, and it uses far less memory. ARCx places its windows and makes them fullscreen itself.

Install the X server:

sudo apt install -y xserver-xorg xinit x11-xserver-utils

Start it at boot, on the screen, with the screen saver and power saving off. (To start it only when you need it instead, see Run the X server only when you need it.)

sudo tee /etc/systemd/system/arcx-display.service > /dev/null <<EOF
[Unit]
Description=X display for ARCx browser windows
After=systemd-user-sessions.service

[Service]
Type=simple
ExecStart=/usr/bin/Xorg :0 vt7 -nolisten tcp -s 0 -dpms
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now arcx-display

The screen turns black: that is the empty X server, waiting for a window. On a touch screen add -nocursor to the ExecStart line to hide the mouse pointer everywhere.

If ARCx runs as a service (below), add these two lines under [Unit] in /etc/systemd/system/arcx.service, so ARCx starts after the display, then sudo systemctl daemon-reload:
```
Wants=arcx-display.service
After=arcx-display.service
```

ARCx finds the display on :0 by itself. To use another one, set it in Views, Browser Windows.

To turn the screen to portrait, run DISPLAY=:0 xrandr --output HDMI-1 --rotate left (the output name is listed by DISPLAY=:0 xrandr), or add it as an ExecStartPost= line to the display service.

Run the X server only when you need it

The service above runs the X server from every boot. To try browser windows first, or to use the screen only now and then, install the X server (step 1) and start it from the command line instead - over SSH works too:

# Start the X server in the background (asks for your password first)
sudo -b Xorg :0 vt7 -nolisten tcp -s 0 -dpms > /dev/null 2>&1

# Then start ARCx as usual; it finds the display on :0 by itself
cd ~/ARCx
./ARCx

sudo is needed because Xorg only lets a user sitting at the computer's own keyboard start it, not a user connected over SSH. -b sends it to the background once the password is typed, so the same terminal can start ARCx. Start the X server before ARCx, so ARCx finds the display. -nocursor works here too.

To stop the X server when you are done:

sudo pkill -x Xorg

The screen goes back to the text console (press Ctrl+Alt+F1 if it stays black). Nothing is set to run at boot, so the X server does not come back until you start it again.

If a window does not appear

Open Diagnostics in ARCx. The Browser Windows section says whether a display was found, and lists any system library Chromium could not load (install it with apt). If windows open but stay black or blank, turn off GPU acceleration in Views, Browser Windows and press Restart.

Computers with little memory

On a computer with 2 GB of RAM or less, Chromium and a video call can run it out of memory, and with swap on slow storage the whole computer stops responding. Turn on One renderer process and Low end device mode in Views, Browser Windows and press Restart. Turning off GPU acceleration saves a little more.

Start ARCx automatically when the computer boots

Run ARCx as a systemd service so it starts at boot, keeps running when you disconnect, and restarts if it stops unexpectedly.

Create the service. Paste this whole block into the terminal as the user who will run ARCx (it fills in your user name and home folder):

sudo tee /etc/systemd/system/arcx.service > /dev/null <<EOF
[Unit]
Description=ARCx robot software by Synthiam
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME/ARCx
ExecStart=$HOME/ARCx/ARCx -b http://0.0.0.0:5000
Restart=on-failure
RestartSec=5
TimeoutStopSec=60

[Install]
WantedBy=multi-user.target
EOF

To open a project on start-up, add -f and the project path to the ExecStart line, in double quotes because the folder name has a space:

ExecStart=/home/<you>/ARCx/ARCx -b http://0.0.0.0:5000 -f "/home/<you>/ARCx Data/My Projects/MyRobot.arcx"

Turn it on and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now arcx

Useful service commands:

Command	What it does
`sudo systemctl status arcx`	Is ARCx running?
`journalctl -u arcx -f`	Watch the ARCx console output live (Ctrl+C to stop watching)
`sudo systemctl stop arcx`	Stop ARCx
`sudo systemctl restart arcx`	Restart ARCx
`sudo systemctl disable arcx`	Stop starting ARCx at boot
`top -H -p $(pgrep -of ARCx)`	Show only ARCx, one line per thread (press q to quit)

On Ubuntu Desktop, if sound works when you run ./ARCx from a terminal but not from the service, the desktop's audio server is only available inside a logged-in session. Either turn on automatic login (Settings > System > Users > Automatic Login), or start ARCx from the desktop session instead of from a service. Ubuntu Server has no desktop audio server and plays sound directly, so this does not apply.

Update

When the interface shows that an update is available:

# Stop ARCx (press Ctrl+C in its terminal), or if it runs as a service:
sudo systemctl stop arcx

# Remove the old program folder. Your projects are in ~/ARCx Data and are not touched.
cd ~
rm -rf ~/ARCx

# Download and unzip the new version
wget -nd https://synthiam.com/api/download/arcx/ARCx-Linux-64.zip
unzip ARCx-Linux-64.zip -d ARCx
rm ARCx-Linux-64.zip
chmod +x ~/ARCx/ARCx

# Start it again, or if it runs as a service:
sudo systemctl start arcx

Removing the old folder first, rather than unzipping over it, makes sure no files from the old version are left behind.

Uninstall

# If you set up the service
sudo systemctl disable --now arcx
sudo rm /etc/systemd/system/arcx.service
sudo systemctl daemon-reload

# Remove the program
rm -rf ~/ARCx

# Optional: remove your projects, settings and installed robot skills
rm -rf ~/"ARCx Data"

Troubleshooting

Problem	Fix
`Permission denied` when running `./ARCx`	Run `chmod +x ARCx` in the ARCx folder.
`cannot execute binary file: Exec format error`	This is the wrong build for the computer. Check with `uname -m`; an `aarch64` computer needs the ARM64 build in Raspberry-Pi.md.
`No such file or directory` when running `./ARCx`	You are not in the folder that contains the `ARCx` program. Run `ls` and `cd` into the right folder.
ARCx exits at start-up with an error that mentions ICU, fontconfig or a missing `.so` library	Re-run the `apt install` line from the Install step. If apt cannot find the packages, the OS is not Ubuntu 24.04.
The camera shows no picture and the log says `Unable to load shared library 'OpenCvSharpExtern'`	Re-run the `apt install` line from the Install step, then run `ldd ~/ARCx/libOpenCvSharpExtern.so \| grep "not found"` to list anything still missing.
No sound or microphone, and the log says `PortAudio could not be initialized` and `libjack.so.0: cannot open shared object file`	The audio library needs the JACK client library. Run `sudo apt install libjack-jackd2-0` and restart ARCx. This does not start a JACK server; ARCx still plays sound through ALSA. Run `ldd ~/ARCx/libportaudio.so \| grep "not found"` to list anything still missing.
ARCx exits straight away with an address or port error	Another program is already using port 5000, or another copy of ARCx is running (check `sudo systemctl status arcx`). Stop the other copy, or use another port: `./ARCx -b http://0.0.0.0:5001`
Another device cannot connect	Check that ARCx was started with `-b http://0.0.0.0:5000`, that the firewall allows port 5000, that you used the IP from `hostname -I`, and that both devices are on the same network.
A serial port, camera or microphone is missing or gives "access denied"	Add your user to the hardware groups (see Give ARCx access to hardware) and log out and back in. For a USB serial adapter that vanishes, see the `brltty` note.
No cameras are listed, or `v4l2-ctl --list-devices` says `Failed to open /dev/video0: Permission denied`	The user that runs ARCx cannot open the camera. See A USB camera is not detected.
No sound or microphone, and `aplay -l` says `no soundcards found`	The user that runs ARCx cannot open the sound card. See No sound or microphone.
Start-up log	`~/ARCx Data/Logs`

A USB camera is not detected

ARCx lists a USB camera only if the user that runs ARCx can open the camera's /dev/video* device. To see what the system detects, install the camera tools and list the cameras:

sudo apt install -y v4l-utils
v4l2-ctl --list-devices

Each camera should be listed with its /dev/video* devices. Most USB cameras have two; the first one carries the video.

If it prints Failed to open /dev/video0: Permission denied, add your user to the video group:

sudo usermod -aG video $USER

Log out and back in (or reboot). The change does not apply to a terminal or SSH session that is already open. If ARCx runs as a service, restart it with sudo systemctl restart arcx. Run groups to check that video is listed, then run v4l2-ctl --list-devices again.

If it still says Permission denied, run ls -l /dev/video*. The devices should belong to the video group (crw-rw----+ 1 root video ...). If they belong to a different group, add a rule that gives them to video, then unplug the cameras and plug them back in:

echo 'SUBSYSTEM=="video4linux", GROUP="video", MODE="0660"' | sudo tee /etc/udev/rules.d/99-video.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

If there are no /dev/video* devices at all, the camera was not recognised. Run lsusb to check that it is listed, and try another USB port or cable.

No sound or microphone

When ARCx is started over SSH or as a service, it can use the sound card only if its user is in the audio group. (A user logged in to the Ubuntu desktop gets access through the desktop session, so sound can work from a desktop terminal but not over SSH.) To check, install the sound tools and list the sound cards as your user and as root:

sudo apt install -y alsa-utils
aplay -l
sudo aplay -l

If aplay -l prints no soundcards found but sudo aplay -l lists cards, add your user to the audio group:

sudo usermod -aG audio $USER

Log out and back in (or reboot). If ARCx runs as a service, restart it with sudo systemctl restart arcx. Run groups to check that audio is listed.

If sudo aplay -l does not list any cards either, the sound hardware was not recognised. For a USB speaker or microphone, run lsusb to check that it is listed.

To test the speaker and the microphone:

# Play a test sound ("Front Left, Front Right")
speaker-test -c 2 -t wav -l 1

# Record 5 seconds from the microphone, then play it back
arecord -d 5 -f cd /tmp/test.wav
aplay /tmp/test.wav

If the cards are listed but nothing plays, run alsamixer. Press F6 to choose the card, press M on any channel marked MM to unmute it, and raise the volume with the arrow keys. With more than one card, add -D plughw:<card>,<device> to speaker-test, arecord or aplay to test a specific one, using the numbers from aplay -l or arecord -l.