Setup Instructions

Table of Contents Raspberry Pi operating system installation Clone & build the PiSCSI software Installing required Linux packages Upgrading an existing installation to the latest Reviewing the PiSCSI service logs I have the software, what next?

Raspberry Pi operating system installation

Important: We distribute pre-configured Raspberry Pi OS images with PiSCSI ready to be used out of the box. Please find links on the Releases page.

If you have a WiFi-only Zero W / Zero 2, or want to avoid connecting an Ethernet cable to your Raspberry Pi, follow these steps to configure WiFi after flashing but before booting the OS for the first time.

The PiSCSI software has basic software requirements, and should work on any reasonably modern version of Linux that supports ARM and Raspberry Pi GPIO. However, development and testing for this project is done on the two last stable versions of Raspberry Pi OS (formerly called Raspbian), so full functionality is guaranteed presently on Raspberry Pi OS 11 (Bullseye) and 12 (Bookworm).

If you want to install the OS from scratch, follow the official Raspberry Pi OS installation instructions. Installing the desktop environment on your Raspberry Pi is not required to run PiSCSI, so it's recommended to choose Raspberry Pi OS Lite to save on disk space, memory, and CPU cycles.

Clone & build the PiSCSI software

The next step is to download the PiSCSI software from GitHub and build it.

1. Log into the Raspberry Pi.

1a. If you've installed Raspberry Pi OS with the desktop, open a terminal window.

1b. If you've installed Raspberry Pi OS Lite, ssh into your Raspberry Pi.

2. Install the git, libspdlog-dev, protobuf-compiler, and libpcap-dev packages. Git is used to clone the PiSCSI repository to your system so we can build the software. For more information on git, check this Wikipedia article. spdlog is a logging library which is used by the PiSCSI software. More information on spdlog can be found here.

sudo apt-get update && \
sudo apt-get install --yes \
git \
libspdlog-dev \
libpcap-dev \
rsyslog \
build-essential \
bridge-utils \
ca-certificates \
libprotobuf-dev \
protobuf-compiler \
libgmock-dev

3. The next step is to clone the PiSCSI Git repository, build the software, and install it on your Raspberry Pi. Enter the following commands in your terminal/ssh session.

cd ~  
git clone https://github.com/PiSCSI/piscsi.git  

4. Determine which board you have. The two common options are "STANDARD" or "FULLSPEC". Information on which model you have can be found at the Hardware Versions page. If you purchased your PiSCSI from Tindie, you will have version 2.2 or newer, which are all "FULLSPEC" boards. You can also check the silkscreen on the PiSCSI board for the version number. Enter the following commands in your terminal/ssh session.

Note: You can also use the easyinstall.sh script, that will automate all the steps described below for you. After cloning the repository on your Raspberry Pi, execute the following (defaults to FULLSPEC):

cd ~/piscsi
./easyinstall.sh

Or, if you have a STANDARD board:

cd ~/piscsi
./easyinstall.sh -c=STANDARD

If you don't use the script, here follows the manual steps to compile and install PiSCSI. If you have the FULLSPEC board (version 2.1 or newer) use this...

cd ~/piscsi/cpp 
make all CONNECT_TYPE=FULLSPEC 
sudo make install CONNECT_TYPE=FULLSPEC

If you have the STANDARD board (version 1.6 or older) use this...

cd ~/piscsi/cpp
make all CONNECT_TYPE=STANDARD
sudo make install CONNECT_TYPE=STANDARD

In the off-chance that you have one of the very early Japan-only RaSCSI board variants by Aibom or Gamernium, use one of the following instead:

CONNECT_TYPE=AIBOM
CONNECT_TYPE=GAMERNIUM

They have different GPIO pin outs than the mainstream boards, but function the same otherwise.

Note: Be sure to select the correct connection type in the above step. If you compile for STANDARD and have a FULLSPEC board, the PiSCSI software will not not behave properly, and you will not see images presented on the SCSI bus.

5. The last step is to restart the rsyslog daemon (which enables logging), configure systemd to start PiSCSI at boot, start the PiSCSI service, and verify that it is running.

sudo systemctl restart rsyslog
sudo systemctl enable piscsi # optional - if you want piscsi to start up at boot
sudo systemctl start piscsi
sudo systemctl status piscsi

6. If the above steps complete successfully, you are now done cloning and building the PiSCSI software.

Installing required Linux packages

To actually run the PiSCSI software, you may need to install Linux packages that the software depends on. Without those packages, the software will not run properly, and throw an error when you try to launch it.

If you use the easyinstall.sh script to install PiSCSI it will take care of installing the dependencies for you. But if you are installing manually, you will have to use the package manager on your Linux system to install the required packages yourself:

sudo apt-get update && sudo apt-get install git libspdlog-dev libpcap-dev genisoimage python3 python3-venv nginx libpcap-dev protobuf-compiler bridge-utils python3-dev libev-dev libevdev2 -y

Note that when moving to a major new version of PiSCSI there may have been new dependencies introduced, for instance when trying out develop after having used master. It is good practice to run the easyinstall.sh script again in these cases.

Upgrading an existing installation to the latest

As this project is still under active development, many of you will want to upgrade your existing PiSCSI software. That's super easy, just follow these steps.

Note: Performing the following will stop and restart the PiSCSI software. This will make your PiSCSI presented images disappear and re-appear on the SCSI bus when the service is stopped, and restarted.

If you have the FULLSPEC board (version 2.1 or newer) use this...

cd ~/piscsi
sudo systemctl stop piscsi
sudo apt-get update && sudo apt-get install git libspdlog-dev libpcap-dev genisoimage python3 python3-venv nginx libpcap-dev protobuf-compiler bridge-utils python3-dev libev-dev libevdev2 -y
git pull
cd ~/piscsi/cpp 
make clean
make all CONNECT_TYPE=FULLSPEC
sudo make install CONNECT_TYPE=FULLSPEC
sudo systemctl start piscsi
sudo systemctl status piscsi

If you have the STANDARD board (version 1.6 or older) use this...

cd ~/piscsi
sudo systemctl stop piscsi
sudo apt-get update && sudo apt-get install git libspdlog-dev libpcap-dev genisoimage python3 python3-venv nginx libpcap-dev protobuf-compiler bridge-utils python3-dev libev-dev libevdev2 -y
git pull
cd ~/piscsi/cpp 
make clean
make all CONNECT_TYPE=STANDARD
sudo make install CONNECT_TYPE=STANDARD
sudo systemctl start piscsi
sudo systemctl status piscsi

Reviewing the PiSCSI service logs

Logging for the PiSCSI daemon can be found in /var/log/piscsi.log

Once you've completed the steps above, you can confirm the daemon is running by checking /var/log/piscsi.log

pi@raspberrypi:~/piscsi/cpp $ cat /var/log/piscsi.log
Nov  5 08:52:40 rasp32 piscsi[32588]: SCSI Target Emulator PiSCSI version 23.11.01
Nov  5 08:52:40 rasp32 piscsi[32588]: Powered by XM6 TypeG Technology / Copyright (C) 2016-2020 GIMONS
Nov  5 08:52:40 rasp32 piscsi[32588]: Copyright (C) 2020-2022 Contributors to the PiSCSI Reloaded project
Nov  5 08:52:40 rasp32 piscsi[32588]: Connect type: FULLSPEC

If you see output similar to the above, the PiSCSI service has compiled without issue, and you've created and started the service successfully.

I have the software, what next?

With the above steps completed, we proceed to Connecting the PiSCSI. This document covers SCSI devices, termination and how to connect your PiSCSI device to a computer.