Raspberry Pi ARM64

These steps also work on other 64-bit ARM (ARM64) single board computers, such as Orange Pi and Rock Pi boards, as long as they run Ubuntu 24.04 LTS (64-bit).

Requirements

• A Raspberry Pi that can run a 64-bit OS: Pi 3, Pi 4, Pi 5 or Pi Zero 2 W. A Pi 4 or Pi 5 is recommended.
• Ubuntu 24.04 LTS (64-bit). Ubuntu Server suits a robot with no screen. Ubuntu Desktop needs a Pi 4 or Pi 5 with at least 4GB of memory.
• An internet connection.

Raspberry Pi OS is not supported. ARCx's computer vision library is built for Ubuntu 24.04 and needs system libraries that Raspberry Pi OS does not provide. On Raspberry Pi OS, ARCx starts but the camera shows no picture. Other Ubuntu versions, including 22.04 and 26.04, do not work either.

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

Install Ubuntu on the Pi

1. Open Raspberry Pi Imager on another computer.
2. Under Operating System, choose Other general-purpose OS > Ubuntu, then Ubuntu Server 24.04.x LTS (64-bit) or Ubuntu Desktop 24.04.x LTS (64-bit).
3. In the customisation settings, set the user name and password, the Wi-Fi network, and turn on SSH if the Pi will have no screen.
4. Write the card, put it in the Pi and start it. The first boot takes a few minutes.

Check the OS

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

grep -E '^(ID|VERSION_ID)=' /etc/os-release
dpkg --print-architecture

It must print ID=ubuntu, VERSION_ID="24.04" and arm64. If it shows anything else, reinstall the card with Ubuntu 24.04 LTS (64-bit) as described above.

Install

Run these commands in a terminal on the Pi:

# Install the system libraries ARCx uses (camera and computer vision, audio, graphics)
sudo apt update
sudo apt install -y unzip libicu74 libasound2t64 libfontconfig1 libgl1 \
  libjpeg-turbo8 libavcodec60 libavformat60 libavutil58 libswscale7 \
  libtiff6 libwebp7 libwebpdemux2 libwebpmux3 libtesseract5 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-ARM64.zip

# Unzip it into a folder named ARCx
unzip ARCx-Linux-ARM64.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 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-ARM64.zip.

Open the interface

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

On the Pi's own desktop

Open Firefox (or any browser) on the Pi 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 (headless Pi)

A Pi inside a robot usually has no screen. Start ARCx so it accepts connections from the network:

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

Find the Pi's IP address:

hostname -I

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

Warning: ARCx has no login. Anyone who can reach that address can control the robot and read or delete files on the Pi. 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, the Pi's UART) 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.

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

The user created by Raspberry Pi Imager during the Ubuntu install is usually already in dialout, video and audio, but not in input or render. A user you add later is in none of them. Run the command anyway; groups the user is already in are not affected.

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 Pi, 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. A Pi running ARCx headless or as a service needs the group to see any controller. 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. Bluetooth controllers are paired with bluetoothctl (scan on, pair, trust, connect) while the controller's pairing lights are flashing.

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.

Using the Pi's GPIO serial port (UART)

Ubuntu uses the Pi's TX/RX pins for a login console by default. To connect a controller to them instead of USB, turn the console off:

1. Open the kernel command line: sudo nano /boot/firmware/cmdline.txt
2. Remove console=serial0,115200 from the line (leave everything else on it, all on one line). Save with Ctrl+O, Enter, then exit with Ctrl+X.
3. Stop the login service on the port: sudo systemctl disable --now [email protected] [email protected]
4. Reboot.

The port then appears in ARCx as /dev/serial0.

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 a screen plugged into the Pi (HDMI, or the DSI touch display). 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. A Pi 4 or Pi 5 with 4GB or more is recommended: each window takes 100 to 200MB.

With Ubuntu 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).

Ubuntu Server, 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 leaves far more memory for the robot. ARCx places its windows and makes them fullscreen itself.

1. Install the X server:

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

2. 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.

3. 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 Pi'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 - which some Pi graphics driver setups cause - turn off GPU acceleration in Views, Browser Windows and press Restart.

Pis with little memory

On a Pi with 2 GB of RAM or less, Chromium and a video call can run it out of memory, and with swap on an SD card the whole Pi stops responding. Turn on One renderer process and Low end device mode in Views, Browser Windows and press Restart.

Start ARCx automatically when the Pi boots

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

1. 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"
   

2. Turn it on and start it:

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

Useful service commands:

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-ARM64.zip
unzip ARCx-Linux-ARM64.zip -d ARCx
rm ARCx-Linux-ARM64.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

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 Pi 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. A USB hub without its own power supply may not give the camera enough power.

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.