# Installation

This page introduces how to install software on each device used in MagiClaw system, including the control box, Metafinger dev board, and iPhone. 

Before starting the following steps, please ensure you get all devices ready. You can either prepare all hardware following the [Hardware](/magiclaw-docs/documentation/hardware/overview.md) section, or buy them at this link.

## Control Box

Coming soon.

### 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:

**Step 1.** Download **Raspberry Pi Imager** software by visiting [**official link**](https://www.raspberrypi.org/software/).

**Step 2.** Open Raspberry Pi Imager software.

<figure><img src="/files/6awxbAytHf1LwcVHXVKi" alt=""><figcaption></figcaption></figure>

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

<div><figure><img src="/files/O66zQWZQ46kfp83Cr9YD" alt=""><figcaption></figcaption></figure> <figure><img src="/files/ZfYUlPFZCR2v2odiraA8" alt=""><figcaption></figcaption></figure></div>

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

{% hint style="info" %}

### **INFO**

We recommend setting the username as `pi`, since the following steps and codes will use it as default.
{% endhint %}

**Step 4.** Click **CHOOSE DEVICE** and select **Raspberry Pi 5**.

<figure><img src="/files/VEiHp044ePfVRoLiKwDT" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/WGTQIQboxCMQkrFHt08h" alt=""><figcaption></figcaption></figure>

**Step 5.** Click **CHOOSE STORAGE** and select the connected SD card.

**Step 6.** Finally, click **NEXT**.

<figure><img src="/files/BxbrhztjQD9IwRCnkdaJ" alt=""><figcaption></figcaption></figure>

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

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

**Step 8.** Update and upgrade:

```bash
sudo apt update
sudo apt upgrade -y
```

### Log in to Raspberry Pi OS via SSH

SSH (**S**ecure **SH**ell) provides secure access to a terminal session on your Raspberry Pi.&#x20;

{% hint style="info" %}

### **INFO**

If you have enabled SSH using Raspberry Pi Imager, you can skip steps 1 and 2.
{% endhint %}

**Step 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.

**Step 2.** Open a Terminal and run

```bash
sudo raspi-config
```

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

<div><figure><img src="/files/Q63Rpw3hGnKduGWTXw4t" alt=""><figcaption></figcaption></figure> <figure><img src="/files/N58lrtXhZ4mZxS5D5vNs" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}

### **WARNING**

Make sure the control box and your PC are connected to the same network.
{% endhint %}

**Step 3.** Configure the connection settings on the PC. Open Terminal and run

```bash
# 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

```bash
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

<figure><img src="/files/a9Cpiun7riB1PHAfu4FB" alt=""><figcaption></figcaption></figure>

### Install MagiClaw

The [magiclaw](https://github.com/asMagiClaw/magiclaw) repository contains the code running on the control box. To install it, first clone the latest repository under `~/Documents/` directory:

```bash
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

```bash
sudo raspi-config
```

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

<div><figure><img src="/files/gPFrgH0yNCSMTFdRgrMv" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Xm9BM0tGE9UW5IdXu2ev" alt=""><figcaption></figcaption></figure></div>

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

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

After running successfully, reboot the control box.

{% hint style="info" %}

### **INFO**

The `setup.sh` changes the `hostname` of the control box according to the mac address of the Ethernet port. For example, if the mac address is `xx:xx:xx:xx:12:34`, the `hostname` will be `rpi-1234`.&#x20;

The WiFi chip is modified into AP mode, which means other devices can connect to the control box through the 5GHz WiFi whose name is the same as the `hostname`, and the password is `12345678`.
{% endhint %}

Then open a terminal and install `magiclaw`:

```bash
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:

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

Then, install the dashboard:

```bash
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.

{% embed url="<https://apps.apple.com/cn/app/magiclaw/id6661033548>" %}

<figure><img src="/files/a05ZM0k59x6fPFtald14" alt="" width="375"><figcaption></figcaption></figure>

## What's Next?

If you have not finished the assembly, please follow [this guide](/magiclaw-docs/documentation/hardware/assembly-guide.md).&#x20;

The [Quickstart](/magiclaw-docs/documentation/getting-started/quickstart.md) section introduces how to connect all devices and run the system.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://magiclaw.gitbook.io/magiclaw-docs/documentation/magiclaw/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.