Installation

This page introduces how to install software on devices used in MagiClaw system, including the control box and iPhone.

Before starting the following steps, please ensure you get all devices ready. You can either prepare all hardware following the Hardware section, or buy them at this link.

Control Box

The control box runs program to control the gripper's grasping as well as receive data from the fingers, motor and iPhone. For a new control box, you need to initialize it with the following steps:

Flash Raspberry Pi OS

For a new control box, the first step is to flash Raspberry Pi OS on an SD card. Please follow the steps below:

1

Download Raspberry Pi Imager software by visiting official link.

2

Open Raspberry Pi Imager software.

3

Press CTRL + SHIFT + X on the keyboard to open OS Customisation settings.

Here you can set a hostname, set a password, enable SSH and more.

INFO

We recommend setting the username as pi, since the following steps and codes will use it as default.

4

Click CHOOSE DEVICE and select Raspberry Pi 5.

5

Click CHOOSE OS and select Raspberry Pi OS (64-bit).

6

Click CHOOSE STORAGE and select the connected SD card

7

Finally, click NEXT.

Please wait a few minutes until the flashing process is complete.

8

Eject the SD card and insert it into the Raspberry Pi 5. Then connect the power supply.

9

Update and upgrade

Copy

sudo apt update
sudo apt upgrade -y

Log in to Raspberry Pi OS via SSH

SSH (Secure SHell) provides secure access to a terminal session on your Raspberry Pi.

1

For Wi-Fi connection, click the Wi-Fi icon on the top right corner of the Raspberry Pi OS Desktop, select your Wi-Fi network and enter the password. For Ethernet connection, connect an ethernet cable from your router to the ethernet port of the control box.

2

Open a Terminal and run

Copy

sudo raspi-config

Select Interface Options -> SSH -> Yes to enable SSH server.

WARNING

Make sure the control box and your PC are connected to the same network.

3

Configure the connection settings on the PC. Open Terminal and run

Copy

# SSH by IP
ssh <username>@<ip address>
# SSH by hostname
ssh <username>@<hostname>.local

where <username> is the user name configured during flashing OS, <ip address> is the IP address of the control box which can be found on the router setting page or ifconfig on the control box, and <hostname> is the hostname also configured during flashing OS. Both of them are capable, just select your preferred way. Type yes for the following message

Copy

ECDSA key fingerprint is SHA256:XXXXXXX.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Then enter the password according to your settings. If you have successfully logged in to the Raspberry Pi OS, you will see the following output

Install MagiClaw

The magiclaw repository contains the code running on the control box. To install it, first clone the latest repository under ~/Documents/ directory:

cd $HOME/Documents
git clone https://github.com/asMagiClaw/magiclaw.git
cd magiclaw

The control box has a WiFi chip and will be set to AP mode, which requires legal wireless channels. Run

sudo raspi-config

Select Localisation Options -> WLAN Country, and the country supporting 5GHz channels.

Then run the setup.sh to install dependencies and configure system settings:

sudo chmod +x setup.sh
./setup.sh

After running successfully, reboot the control box.

Then open a terminal and install magiclaw:

cd $HOME/Documents/magiclaw
sudo chmod +x install.sh
./install.sh

This script will create a conda environment magiclaw, setting it to auto-activate, and install packages.

Install MagiClaw Dashboard

The MagiClaw Dashboard is a real-time web interface for controlling and monitoring the MagiClaw.

To set up the MagiClaw Dashboard, first clone the latest repository under ~/Documents directory:

cd $HOME/Documents
git clone https://github.com/asMagiClaw/magiclaw-dashboard.git
cd magiclaw-dashboard

Then, install the dashboard:

sudo chmod +x install.sh
./install.sh

asMagic App

The asMagic App is an intuitive app for robot teleoperation and multimodal data collection. It lets you:

• Control robots like arms, grippers, and quadrupeds with simple on-screen joysticks or gestures.

• Collect synchronized data from camera, IMU, AR tracking, and force sensors for research or training.

Whether for hands-on robot control or building datasets for learning, asMagic makes the process smooth, modern, and accessible.

What's Next?

If you have not finished the assembly, please follow this guide.

The Quickstart section introduces how to connect all devices and run the system.