# Control Box

This page introduces the control box, connecting other devices together for data streaming and power support. The core module is Raspberry Pi 5 equipped with a CAN FD HAT board. There are two CAN interfaces to connect to the gripper, and an RJ45 interface to connect to the local network.

## Preview

{% embed url="<https://my1261625.autodesk360.com/g/shares/SH286ddQT78850c0d8a4dcdc23eeca8782a0?mode=embed>" %}
MagiClaw control box
{% endembed %}

## Specifications <a href="#specifications" id="specifications"></a>

<table><thead><tr><th width="200">Parameters</th><th>Description</th></tr></thead><tbody><tr><td>Module</td><td>Raspberry Pi 5 8GB</td></tr><tr><td>CPU</td><td>Arm Cortex-A76, 2.4GHz quad-core 64-bit</td></tr><tr><td>GPU</td><td>VideoCore VII</td></tr><tr><td>Memory</td><td>8GB SDRAM</td></tr><tr><td>Power Supply</td><td>24V/5A DC via XT30</td></tr><tr><td>Wi-Fi</td><td>Dual-band 802.11ac</td></tr><tr><td>Bluetooth</td><td>Bluetooth 5.0/ BLE</td></tr><tr><td>Storage</td><td>1 x microSD card slot, with support for high-speed SDR104 mode</td></tr><tr><td>Ethernet</td><td>1 x RJ45 (1000 Mbps)</td></tr><tr><td>Display Output</td><td>2 x micro HDMI ports (4Kp60)</td></tr><tr><td>USB</td><td>2 x USB 3.0, 2 x USB 2.0</td></tr><tr><td>CAN</td><td>2 x CAN (XT30 2+2)</td></tr><tr><td>Dimensions (W x D x H)</td><td>91mm * 61mm * 38mm</td></tr><tr><td>Weight</td><td>153g</td></tr><tr><td>Operating Temperature</td><td>0 ~ 45℃</td></tr></tbody></table>

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

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

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

## Log in to Raspberry Pi OS via VNC

VNC (**V**irtual **N**etwork **C**omputing) provides secure access to a desktop screen share on your Raspberry Pi. Raspberry Pi OS includes [wayvnc](https://github.com/any1/wayvnc). This provides a VNC server that you can enable in your device preferences. Before you can use VNC on your Raspberry Pi, you must enable the VNC server.

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

```bash
sudo raspi-config
```

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

<div><figure><img src="/files/Q63Rpw3hGnKduGWTXw4t" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Q63Rpw3hGnKduGWTXw4t" 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 2**. Download and launch [RealVNC](https://www.realvnc.com/en/connect/download/viewer/) on your PC.&#x20;

**Step 3.** enter the IP address of the control box.&#x20;

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

**Step 4.** When prompted for a username and password, enter your credentials.

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

**Step 5.** Click the "OK" button to authenticate with the VNC server. If your credentials are correct, RealVNC should open a window containing the desktop of the control box.

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

## Hardware Usage

### Power

The control box is equipped with a 24V (XT30) power interface, making it suitable for the servo motor in the gripper.

### Display

The control box provides two micro HDMI ports (4K60), and the right one is the default port for display.

### Ethernet

The control box provides an RJ45 port with up to 1000Mbps, which is the only way to communicate with other control boxes or PCs by connecting to a local network.

### USB

The control box has a total of 4 USB ports: 2 USB 3.0 ports, and 2 USB 2.0 ports. Their arrangement order is consistent with the default settings of Raspberry Pi 5.

### WiFi

The WiFi chip of the control box is set to AP mode for connecting Metafinger and iPhone, so it cannot be used to connect to any other WiFi. It is set at 5GHz to achieve high data bandwidth. The default name is consistent with the hostname, and the default password is 12345678.

Here we provide several steps to set the WiFi to AP mode.

{% hint style="info" %}

### **INFO**

All steps below are included in the `setup.sh` in [Installation](/magiclaw-docs/documentation/magiclaw/installation.md). If you have already run the bash file successfully, you can skip the following part.
{% endhint %}

Step 1. Open a Terminal and run

```bash
sudo raspi-config
```

Select `Localisation Options -> WLAN Country` and set the legal wireless channels.

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

**Step 2.** Install hostapd, dhcpcd, and dnsmasq by running the following command

```bash
sudo apt install hostapd dhcpcd5 dnsmasq
```

**Step 3.** Then open `/etc/hostapd/hostapd.conf`, and add

```
interface=wlan0
driver=nl80211
ssid=rpi5_5g
hw_mode=a
ieee80211n=1
ieee80211ac=1
require_ht=1
require_vht=1
wmm_enabled=1
country_code=US
ht_capab=[HT40-][HT40+][SHORT-GI-40][DSSS_CCK-40]
channel=149
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=12345678
wpa_key_mgmt=WPA-PSK
wpa_pairwise=CCMP
rsn_pairwise=CCMP
```

{% hint style="warning" %}

### **WARNING**

It's necessary to use different `ssid` for different devices when you are using more than one. We recommend using the `hostname` as `ssid`.
{% endhint %}

**Step 4.** Open `/etc/default/hostapd` and modify `DAEMON_CONF` as

```
DAEMON_CONF="/etc/hostapd/hostapd.conf"
```

**Step 5.** Open `/etc/dhcpcd.conf`, and add

```
interface wlan0
    static ip_address=192.168.4.1/24
    nohook wpa_supplicant
```

**Step 6.** Open `/etc/dnsmasq.conf`, and add

```
interface=wlan0
dhcp-range=192.168.4.2,192.168.4.254,255.255.255.0,24h
```

**Step 7.** Disable `NetworkManager` for `wlan0` by opening or creating a new file `/etc/NetworkManager/conf.d/10-ignore-wlan0.conf`, and add

```
[keyfile]
unmanaged-devices=interface-name:wlan0
```

**Step 8.** Start `wlan0` by running

```bash
sudo ip link set wlan0 up
```

**Step 9.** Stop and restart all services by running the following command

```bash
sudo systemctl unmask hostapd
sudo systemctl unmask dhcpcd
sudo systemctl unmask dnsmasq
sudo systemctl enable hostapd
sudo systemctl enable dhcpcd
sudo systemctl enable dnsmasq
sudo systemctl start hostapd
sudo systemctl start dhcpcd
sudo systemctl start dnsmasq
sudo systemctl restart NetworkManager
```

**Step 10.** View `wlan0` interface by running

```bash
ifconfig
```

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

{% hint style="info" %}
**INFO**

If `wlan0` doesn't have IPV4 address, try to reboot the control box.
{% endhint %}

**Step 10.** If devices connected to Raspberry Pi 5, check them by running

```
arp -a
```

{% hint style="info" %}
**INFO**

To test network bandwidth between MagiClaw-RPI5 and connected devices, you can use `iperf3`, etc.
{% endhint %}

{% hint style="warning" %}

### **WARNING**

For some system reasons, Raspberry Pi OS may lose UI. To solve this problem, just install the `raspberrypi-ui-mods` by

{% code fullWidth="false" %}

```bash
sudo apt install raspberrypi-ui-mods
```

{% endcode %}
{% endhint %}

### CAN

The control box is equipped with two CAN ports (XT30 2+2). Since the Raspberry Pi does not support CAN, we use a CAN controller (MCP2518FD) with SPI interface and a transceiver to complete CAN function.

Here we demonstrate sending data from CAN0 to CAN1. First, connect the signal lines of CAN0\_H to CAN1\_H and CAN0\_L to CAN1\_L. Then, open terminal and install `can-utils`:

```bash
sudo apt install can-utils
```

Open a `Terminal 1` and enter the following command to receive data from `CAN0`:

```bash
candump can0
```

Open a `Terminal 2` and enter the following command to receive data from `CAN1`:

```bash
cansend can1 000#11.22.33.44
```

Then you will see

The output voltage of XT30 2+2 theoretically equals the current DC input voltage of the control box. Since the voltage of the servo motor used in the gripper needs to be 24V, it is important to ensure the input voltage of the control box is also 24V. If you want to know more details, you can refer to the schematic.

Here we provide several steps to set the CAN bus.

{% hint style="info" %}

### **INFO**

All steps below are included in the `setup.sh` in [Installation](/magiclaw-docs/documentation/magiclaw/installation.md). If you have already run the bash file successfully, you can skip the following part.
{% endhint %}

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

```bash
sudo raspi-config
```

Select `Interfacing Options -> SPI -> Yes` to enable the SPI interface

<div><figure><img src="/files/SmfaltF0rBoeROUctECB" alt=""><figcaption></figcaption></figure> <figure><img src="/files/XqK4A4MrfPpGvNraPF6N" alt=""><figcaption></figcaption></figure></div>

**Step 2.** Open `/boot/firmware/config.txt`, and add

```
# CAN
dtparam=spi=on
dtoverlay=spi1-3cs
dtoverlay=mcp251xfd,spi0-0,interrupt=25
dtoverlay=mcp251xfd,spi1-0,interrupt=24
```

Step 3. If you have modified the WiFi AP mode, open `/etc/dhcpcd.conf`, and add

```
denyinterfaces can0
denyinterfaces can1
```

Then restart Raspberry Pi 5 by running

```bash
sudo reboot
```

**Step 3.** Set the baud rate, working mode, whether to enable FD and configure the size of the transmission buffer of CAN by

```bash
sudo ip link set can0 up type can bitrate 1000000 dbitrate 8000000 restart-ms 1000 berr-reporting on fd on
sudo ip link set can1 up type can bitrate 1000000 dbitrate 8000000 restart-ms 1000 berr-reporting on fd on
sudo ifconfig can0 txqueuelen 65536
sudo ifconfig can1 txqueuelen 65536
```

{% hint style="warning" %}

### **WARNING**

If `Segmentation Fault` occurs, please upgrade the system kernel version.
{% endhint %}

**Step 4.** View CAN interface by running

```bash
ifconfig
```

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

**Step 5.** To setup CAN interface on boot, create `/etc/systemd/system/can-setup.service` and add

```
[Unit]
Description=Setup CAN interfaces on boot
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/setup_can.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

Create `/usr/local/bin/setup_can.sh`, and add

```
#!/bin/bash

# can0
sudo ip link set can0 up type can bitrate 1000000 dbitrate 8000000 restart-ms 1000 berr-reporting on fd on
sudo ifconfig can0 txqueuelen 65536

# can1
sudo ip link set can1 up type can bitrate 1000000 dbitrate 8000000 restart-ms 1000 berr-reporting on fd on
sudo ifconfig can1 txqueuelen 65536
```

After saving, grant execution permission to `/usr/local/bin/setup_can.sh`

```bash
sudo chmod +x /usr/local/bin/setup_can.sh
```

Start `can-setup.service` by running

```bash
sudo systemctl enable can-setup.service
sudo systemctl start can-setup.service
```

Then, the CAN interface will be automatically set up for next time on boot.

### FAN

The control box is equipped with a [Raspberry Pi official active cooler](https://www.raspberrypi.com/products/active-cooler/). We recommend modifying the fan settings in `/boot/firmware/config.txt` like:

```
# FAN
dtparam=cooling_fan=on
dtparam=fan_temp0=36000,fan_temp0_hyst=2000,fan_temp0_speed=90
dtparam=fan_temp1=40000,fan_temp1_hyst=3000,fan_temp1_speed=150
dtparam=fan_temp2=52000,fan_temp2_hyst=4000,fan_temp2_speed=200
dtparam=fan_temp3=58000,fan_temp3_hyst=5000,fan_temp3_speed=255
```

where `fan_temp` indicates the trigger temperature that will turn on the fan (unit in 0.001 ℃), `fan_temp_hyst` indicates the temperature reduction that turns off the fan (unit in 0.001 ℃), and `fan_temp_speed` indicates the fan speed (from 0 to 255).

## Conda Environment

Since Raspberry Pi OS Bookworm, users can not install libraries directly into the system version of Python. Instead, install libraries into a virtual environment (venv or conda). Here we select `miniconda` as the package manager for Python.&#x20;

**Step 1.** Create a new directory named `miniconda3` in your home directory

```bash
mkdir -p $HOME/miniconda3
```

**Step 2.** Download the Linux Miniconda installation script for your chosen chip architecture and save the script as `miniconda.sh` in the miniconda3 directory

```bash
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh -O $HOME/miniconda3/miniconda.sh
```

**Step 3.** Run the `miniconda.sh` installation script in silent mode using bash

```bash
bash $HOME/miniconda3/miniconda.sh -b -u -p $HOME/miniconda3
```

**Step 4.** Remove the `miniconda.sh` installation script file after installation is complete

```bash
rm $HOME/miniconda3/miniconda.sh
```

**Step 5.** Close and reopen your terminal application or refresh it by running the following command

```bash
source $HOME/miniconda3/bin/activate
```

**Step 6.** Initialize conda on all available terminals by running the following command

```bash
conda init --all
```

Now the installation is completed and you can reopen the terminal to see whether `conda` is available.

## Bill of Materials

<table><thead><tr><th>Part</th><th>Specifications</th><th data-type="number">Quantity</th><th>Price (per unit)</th><th data-type="content-ref">Link</th></tr></thead><tbody><tr><td>Raspberry Pi 5</td><td>8GB RAM</td><td>1</td><td>$ 80.00</td><td><a href="https://www.raspberrypi.com/products/raspberry-pi-5">https://www.raspberrypi.com/products/raspberry-pi-5</a></td></tr><tr><td>Active cooler</td><td>/</td><td>1</td><td>$ 5.00</td><td><a href="https://www.raspberrypi.com/products/active-cooler">https://www.raspberrypi.com/products/active-cooler</a></td></tr><tr><td>CAN FD HAT</td><td>FR4 PCB</td><td>1</td><td></td><td><a href="https://drive.google.com/drive/folders/19F8H1RqCAxRgz1h4FWdsLfYDqneX_fME">https://drive.google.com/drive/folders/19F8H1RqCAxRgz1h4FWdsLfYDqneX_fME</a></td></tr><tr><td>Box top</td><td>PLA</td><td>1</td><td>$ 1.40</td><td><a href="https://drive.google.com/file/d/12quL-Dj-PJM7OAjD0IO_KfcSMj32AWrF/view">https://drive.google.com/file/d/12quL-Dj-PJM7OAjD0IO_KfcSMj32AWrF/view</a></td></tr><tr><td>Box base</td><td>PLA</td><td>1</td><td>$ 0.32</td><td><a href="https://drive.google.com/file/d/1ic2yr6rujSRu-10FT54M8eySFhSwJ5_4/view">https://drive.google.com/file/d/1ic2yr6rujSRu-10FT54M8eySFhSwJ5_4/view</a></td></tr></tbody></table>

## CAD Models

STEP files of all 3D-printed parts are provided on [Google Drive](https://drive.google.com/drive/folders/1eggZ7Y-1Vx3dt_DY61oJZzGpe7rARkbe). A 3mf file is also provided for 3D printing at .

## PCB Files

All PCB files are provided on [Google Drive](https://drive.google.com/drive/folders/1mc9lSpiDtNvdcgDzfH82Sd2DmDS5u5pC), including schematic, gerber, bom, etc.


---

# 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/hardware/controller.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.