PiSCSI DOCUMENTATION
man 1

piscsi

Emulates SCSI devices using the Raspberry Pi GPIO pins

PISCSI(1) General Commands Manual PISCSI(1)

piscsi — Emulates SCSI devices using the Raspberry Pi GPIO pins

piscsi [-b BLOCK_SIZE] [-c RASCTL_CONTROL] [-F FOLDER] [-L LOG_LEVEL[: ID[: LUN]]] [-n VENDOR:PRODUCT:REVISION] [-P ACCESS_TOKEN_FILE] [-p PORT] [-R SCAN_DEPTH] [-r RESERVED_IDS] [-s MICROSECONDS] [-t TYPE] [-z LOCALE] [-IDn[:u] FILE]

piscsi [-C TYPE] [-h]

piscsi [-v]

piscsi emulates a range of SCSI devices using the Raspberry Pi GPIO pins. It can also emulate SASI hard drives, which is a predecessor of SCSI.

In the arguments to PiSCSI, one or more SCSI or SASI (-IDn[:u]) devices can be specified. The number (n) after the ID identifier specifies the ID number for that device. The optional number (u) specifies the LUN (logical unit) for that device. The default LUN is 0. For SCSI: The ID is limited from 0-7. However, typically SCSI ID 7 is reserved for the "initiator" (the host computer). The LUN is limited from 0-31. SASI hard disks support LUNs 0-1 only.

Note: PiSCSI cannot be run in parallel with other applications that use the same GPIO pins, such as RaSCSI or SCSI2Pi.

Once PiSCSI starts, it will open a socket (default port is 6868) to allow external management commands. If another process is using this port, PiSCSI will terminate. Once PiSCSI has initialized, the scsictl utility can be used to send commands.

To quit PiSCSI, press Control + C. If it is running in the background, you can kill it using an INT signal.

The GPIO-facing tools select the board layout when they start. Use -C to select one of the following types:

For boards with initiator support.
For simpler boards that use fewer pins.
For the early GAMERnium.com board variant.

Note: As of PiSCSI v26.8.1, the AIBOM board variant is no longer supported.

Use the board's silkscreen or the Hardware Versions wiki page at https://github.com/PiSCSI/piscsi/wiki/Hardware-Versions to identify it. Selecting the wrong type can prevent devices from appearing on the SCSI bus.

The default is FULLSPEC. For example:

sudo piscsi -C STANDARD -r 7

piscsi, scsimon(1), scsiloop(1), scsidump(1), and sasidump(1) support this option. The type is fixed for the lifetime of the process; stop and restart a tool before choosing another mapping.

The supplied systemd service defaults to FULLSPEC. Override its PISCSI_CONNECTION_TYPE environment variable and restart the service to use a different mapping.

PiSCSI can emulate the following device types. The four letter code (case insensitive) can be passed to the -t option to select the device. A non-removable disk drive must be attached with an image file, while a removable disk drive can be attached either empty or with an image file. The other device types may require other parameters to attach, see the FILE argument documentation below.

SASI Hard Disk (takes image, non-removable)
SCSI Host Bridge (X68000 host bridge and Neptune-X compatible network adapter)
SCSI CD-ROM (CD-ROM or DVD-ROM drive, takes images, removable)
SCSI DaynaPort (DaynaPort SCSI/Link compatible network adapter)
SCSI Hard Disk (takes image, non-removable)
SCSI Host Services (used for special host services)
SCSI Printer (generic line printer)
SCSI Magneto-Optical Drive (takes image, removable)
SCSI Removable Hard Disk (takes image, removable)
SCSI Tape Drive (takes image, removable)

If the device type is not specified as described above, PiSCSI will determine the type of device based upon the file extension of the FILE argument.

Hard Disk image (generic, non-removable)
Hard Disk image (generic, non-removable, SCSI-1 compatibility mode)
Hard Disk image (generic, removable)
Hard Disk image (NEC compatible - only used with PC-98 computers)
Hard Disk image (Anex86 proprietary - only used with PC-98 computers)
Hard Disk image (T98Next proprietary - only used with PC-98 computers)
Hard Disk image (Apple compatible - typically used with Macintosh computers)
Hard Disk image (raw SASI HD image - typically used with X68000)
Magneto-Optical image (generic, typically used with NeXT, X68000, etc.)
CD-ROM or DVD-ROM image (ISO 9660 image)
CD-ROM or DVD-ROM image (ISO 9660 image)
CD-ROM or DVD-ROM image (ISO 9660 image)
CD-ROM or DVD-ROM image (ISO 9660 image, SCSI-1 compatibility mode)
Tape image (raw tape image containing non-block data)
Tape archive (tape block data in tar format)

For example, if you want to specify an Apple-compatible HD image on ID 0, you can use the following command:
sudo piscsi -ID0 /path/to/drive/hdimage.hda

File extensions are case-insensitive. They select the default device type as described above, and some also enable compatibility handling or cause PiSCSI to read an image-format header. Most other hard disk images are raw block images and have no PiSCSI-specific on-disk header.

The .hda extension selects a generic hard disk with the INQUIRY identification “QUANTUM FIREBALL”. This compatibility identity allows Apple HD SC Setup on classic Mac OS to recognize and format the hard disk.

The .hdn, .hdi, and .nhd extensions select the PC-98 hard-disk implementation. It reports SCSI-1 CCS inquiry data and supplies PC-98 disk geometry in MODE SENSE pages.

.hdn is a raw NEC PC-9801-55-style image. PiSCSI treats its data as beginning at offset zero and uses a geometry of 512 bytes per sector, 25 sectors per track, and 8 heads.

.hdi is the Anex86 format. PiSCSI reads its 512-byte image header for the data offset, image size, sector size, and geometry.

.nhd is the T98Next format. PiSCSI requires the “T98HDDIMAGE.R0” signature in its header and reads the data offset and geometry from that header. For both formats, this metadata determines how PiSCSI accesses the payload; it is not interpreted as a PC-98 boot sector.

The .hdf extension selects a SASI hard disk, typically used with X68000 systems. It is a raw image, not a separately parsed HDF container. The default sector size is 256 bytes; use -b to select 256, 512, or 1024 bytes. SASI addressing limits an image to 2,097,152 blocks.

PiSCSI derives the capacity from the file length; it does not recognize capacity-specific HDF variants.

.hd1 and .is1 select SCSI-1 CCS compatibility for hard disks and CD-ROMs, respectively. .hdr selects a removable hard disk. .mos selects a removable magneto-optical disk; several common medium capacities have predefined geometry.

.iso, .cdr, and .toast select a read-only CD-ROM. PiSCSI inspects the beginning of the file to distinguish a raw Mode 1 CD image from a normal ISO image; CUE sheets are detected and rejected.

PiSCSI emulates two SCSI network interfaces: SCDP (DaynaPort) and SCBR (Host Bridge). For these devices, the FILE argument is not an image file; it selects a host networking profile with a complete mode and interface pair. For example, use “mode=bridge:interface=piscsi_bridge” or “mode=proxyarp:interface=wlan0”. The piscsi-network-profile(8) script configures the host-side profile before the network adapter is attached; see its manual page for setup instructions and examples.

SCDP is reverse engineered from the DaynaPort SCSI/Link Ethernet adapter and uses its drivers or compatible drivers. SCBR is reverse engineered from the Neptune-X Ethernet adapter and uses its drivers or compatible drivers, including the RASETHER driver from the RaSCSI project. SCBR also provides the X68000 host bridge, including its host file-system service and support for the RASCTL wire protocol.

The bridge profile connects the emulated adapter to a preconfigured wired Linux bridge and provides complete Ethernet service, including DHCP, AppleTalk, multicast, and non-IP Ethernet protocols. Configure this profile with a NetworkManager-managed Ethernet interface. It creates the piscsi_bridge bridge, which owns the physical Ethernet port, its address, and DHCP configuration. Attach an adapter using “mode=bridge:interface=piscsi_bridge”. SCDP can use the complete Ethernet service; the SCBR driver accepts only its own unicast frames and Ethernet broadcasts.

The proxyarp profile connects an emulated adapter to a NetworkManager-managed Wi-Fi uplink. Configure it with the Wi-Fi interface holding the Pi's IPv4 lease. This profile requires the parprouted and dhcp-helper packages. It provides IPv4 unicast and DHCP only; it is not an Ethernet bridge and does not support IPv6, AppleTalk, multicast, mDNS, or other non-IP Ethernet traffic. Attach an adapter using “mode=proxyarp:interface=wlan0”. The SCBR driver remains limited to its own unicast frames and Ethernet broadcasts.

The profile script manages only the named PiSCSI NetworkManager connections and /etc/piscsi/network.conf. Applying or removing a profile may interrupt host connectivity; see piscsi-network-profile(8) for its usage and examples. Always provide both mode and interface; the retired inet parameter and comma-separated interface lists are not supported.

BLOCK_SIZE
The optional block size. SASI hard disks support 256, 512, or 1024 bytes per sector and default to 256 bytes. Other disk devices support 512, 1024, 2048, or 4096 bytes and default to 512 bytes.
TYPE
Select the board connection type for this process. See CONNECTION TYPE for the available mappings and their appropriate boards.
RASCTL_CONTROL
Enable the unauthenticated RASCTL compatibility control channel on SCBR host bridges. The default is “off”. Use “media” to permit listing and media-management commands, or “full” to additionally permit PiSCSI and system shutdown commands. Only enable this option when all SCSI initiators are trusted.
FOLDER
The default folder for image files. For files in this folder no absolute path needs to be specified. The folder must already exist. The initial default folder is '/var/lib/piscsi/images'.
Show a help page.
LOG_LEVEL[: ID[: LUN]]
The piscsi log level (trace, debug, info, warning, error, off). The default log level is 'info' for all devices unless a particular device ID and an optional LUN was provided.
VENDOR:PRODUCT:REVISION
Set the vendor, product and revision for the device, to be returned with the INQUIRY data. A complete set of name components must be provided. VENDOR may have up to 8, PRODUCT up to 16, REVISION up to 4 characters. Padding with blanks to the maximum length is automatically applied. Once set the name of a device cannot be changed.
ACCESS_TOKEN_FILE
Enable authentication and read the access token from the specified file. The access token file must be owned by root and must be readable by root only.
PORT
The piscsi server port, default is 6868.
SCAN_DEPTH
Scan for image files recursively, up to a depth of SCAN_DEPTH. Depth 0 means to ignore any folders within the default image folder. Be careful when using this option with many sub-folders in the default image folder. The default depth is 1.
RESERVED_IDS
Comma-separated list of IDs to reserve. Pass an empty list in order to not reserve anything.
MICROSECONDS
Minimum execution time for SCSI commands in microseconds. Default is 50 for SCSI and 100 for SASI. Higher values may be needed for some older SCSI initiators to work properly.
TYPE
The optional case-insensitive device type (see list of type codes above). If no type is specified for devices that support an image file, piscsi tries to derive the type from the file extension.
Display the piscsi version.
LOCALE
Sets the default locale for client-facing error messages. The client can override the locale.
n[: u] FILE
n is the SCSI or SASI ID number (0-7). u is the optional LUN (logical unit): 0-31 for SCSI and 0-1 for SASI. The default LUN is 0.

FILE is the name of the image file to use for a SCSI or SASI mass storage device. For devices that do not support an image file (SCBR, SCDP, SCLP, SCHS) the filename may have a special meaning or a dummy name can be provided. For SCBR and SCDP it selects the host networking profile; see NETWORK INTERFACES. For SCLP it is the print command to be used and a reservation timeout in seconds, e.g. "cmd=lp -oraw %f:timeout=60".

Launch PiSCSI with no emulated drives attached:

piscsi

Launch PiSCSI with an Apple hard drive image as ID 0 and a CD-ROM as ID 2

piscsi -ID0 /path/to/harddrive.hda -ID2 /path/to/cdimage.iso

Launch PiSCSI with a removable SCSI drive image as ID 0 and the raw device file /dev/hdb (e.g. a USB stick) and a DaynaPort network adapter as ID 6:

piscsi -ID0 -t scrm /dev/hdb -ID6 -t scdp daynaport

Launch PiSCSI with a DaynaPort on the preconfigured wired bridge:

piscsi -ID6 -t scdp mode=bridge:interface=piscsi_bridge

For a configured Wi-Fi proxy-ARP uplink named wlan0:

piscsi -ID6 -t scdp mode=proxyarp:interface=wlan0

To create an empty, 100MiB HD image, use the following command:

dd if=/dev/zero of=/path/to/newimage.hda bs=512 count=204800

In case the fallocate command is available a much faster alternative to the dd command is:

fallocate -l 104857600 /path/to/newimage.hda

scsictl(1), scsimon(1), scsidump(1)

Full documentation is available at: <https://www.piscsi.com>

August 30, 2026 PiSCSI