ZuluSCSI™ Firmware
ZuluSCSI is a family of hardware devices that emulates Small System Computer Interface storage devices. This repository contains the firmware source code for these devices, as well as precompiled firmware, available via the releases page.
Image files on the SD card
ZuluSCSI stores drive images as files on a FAT32 or exFAT formatted SD card.
Use exFAT if any single image needs to exceed 4 GB — FAT32 cannot represent a file
larger than 4,294,967,295 bytes.
By default the firmware scans the root directory of the card. This can be changed,
and additional directories added, in zuluscsi.ini:
[SCSI]
Dir = "/" # directory scanned for images (default: root)
Dir1 = "/images" # up to Dir1...Dir9 additional directories
Directories and files whose "hidden" attribute is set are skipped. Files whose read-only attribute is set are exposed as write-protected SCSI devices.
Image filename format
<TT><ID>[<LUN>][_<BLOCKSIZE>][ any description ].<ext>
^^ ^ ^ ^
| | | +-- optional, decimal, after the first underscore
| | +--------- optional LUN digit (byte offset 3), can be omitted, only a single logical unit number, LUN 0 is currently supported.
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)
The type prefix, ID and LUN are read from fixed byte offsets in the filename, so
their positions matter. The block size is read from the first _ found anywhere in the name.
The media type can also be set in zuluscsi.ini, or directly by the file name or directory prefix.
Device type file name prefixes
| Prefix | Device type | Default block size | Notes |
|---|
HD | Hard disk (fixed) | 512 | Default when no other prefix matches |
CD | CD-ROM (optical) | 2048 | |
FD | Floppy | 512 | |
MO | Magneto-optical | 512 | |
RE | Generic removable | 512 | |
TP | Sequential / tape | 512 | |
ZP | Iomega Zip 100 | 512 | Image should be exactly 100,663,296 bytes |
NE | DaynaPORT network | — | Network-capable hardware only |
AM | Amiga WiFi network | — | Network-capable hardware only |
SN | PCM audio stream | — | Builds with audio streaming enabled only |
A file whose name does not begin with one of these prefixes is ignored entirely.
Block size
Everything after the first _ underscore character is parsed as a decimal number. Accepted range is
8 to 65536 bytes; values outside that range are ignored and the default for the device
type is used instead. The block size may also be set per-device in zuluscsi.ini,
which takes effect when the filename does not specify one.
Example file names
| Example file name | Result |
|---|
HD1.img | hard disk, ID 1, 512 byte blocks |
HD5.hda | hard disk, ID 5 |
HDA.hda | hard disk, ID 10 |
HD20_512.hda | hard disk, ID 2, LUN 0, 512 byte blocks |
CD3.iso | CD-ROM, ID 3, 2048 byte blocks |
CD3_512.iso | CD-ROM, ID 3, 512 byte blocks |
ZP4.img | Iomega Zip 100, ID 4 |
TP6 - backup.tap | tape, ID 6, SIMH .tap format |
HDn.img | hard disk on the SCA-supplied dynamic ID |
File extensions
For ordinary raw images the extension carries no meaning — .hda, .img, .bin,
.iso, .dsk and so on are all read identically. The device type comes from the
filename prefix, not the extension.
The following file name extensions are treated as special by the firmware:
| Extension | Meaning |
|---|
.rom | Program this image into microcontroller flash as a ROM drive |
.tap | SIMH tape format — only honoured on TP (sequential) devices |
.cue | Marks a BIN/CUE disc set; see the BIN/CUE section |
.cow | Copy-on-write image (kiosk use); writes are diverted to a .tmp overlay |
.ori | Kiosk-mode pristine master; copied over the live image at boot |
.vhd | VHD container — read as a Virtual Hard Disk (V1 only) container |
The following are skipped silently, so documentation and artwork can live alongside images:
.cue .txt .rtf .md .nfo .pdf .doc .ini .mid .midi .aiff .mp3 .m4a
.rom_loaded .rom_bkup .ori .tmp
These are skipped with a note in the log, because they are almost always an unextracted
download rather than an image:
.tar .tgz .gz .bz2 .tbz2 .xz .zst .z .zip .zipx .rar .lzh .lha
.lzo .lz4 .arj .dmg .hqx .cpt .7z .s7z .wav
Files whose name does not begin with a letter or digit are ignored. This is what keeps
macOS ._ resource forks and similar metadata from being mistaken for images.
Raw sector-range and partition access
Instead of a regular file, an IMGn entry in zuluscsi.ini can point directly at a
range of SD card sectors, bypassing the filesystem entirely:
[SCSI5]
IMG0 = RAW:0x00000000:0xFFFFFFFF # Whole SD card
Format is RAW:first_sector:last_sector, decimal or hex, with the end sector
automatically clamped to the SD card's actual size.
[SCSI5]
Partition = 3
A Partition = n references a raw partition by number instead of hand-computed
sector ranges, resolved from the SD card's own MBR or GPT partition table.
Consistent with the partition utilities, we count from 1!
Note: MBR supports at most 4 partitions (a hard limit of the MBR format
itself — logical/extended partitions beyond that are out of scope for
Partition), while GPT supports more — the exact number will depend on how many
partition-table entries a particular firmware chooses to read on a given Zulu
model, not on any per-model SD card limit. If you expect to need more than 4
partitions on a card, plan on GPT-partitioning it rather than MBR.
On boards with an SCA connector, Partition also works in the [SCSIn] section,
binding the partition to the dynamic SCA-supplied ID.
When creating raw partitions with a GPT-aware tool (e.g. gdisk),
consider setting their partition type GUID to
E5BF00BF-E1B8-4E16-945C-5AB326258BCC — a preliminary, not yet officially
adopted marker for "this is a ZuluSCSI raw partition." ZuluSCSI's own firmware
does not check this GUID for anything; the sole purpose is to stop other
operating systems that read/write the same SD card from recognizing the
partition as an ordinary data volume and interfere with it. Leave the SD card's
FAT32/exFAT boot volume itself as the standard 0700 ("Microsoft basic data")
type. Use e. g. da — Non-FS data — for MBR.
Partitions give best performance when they're aligned to the particular SD card's
recommended value. A card's alignment value is output on the Zulu's console at
at reboot time, or when a card is inserted. Use this value with e. g. gdisk to
set the desired alignment by issuing x (extra functionality) and l (set the
sector alignment value).
Image directories (swappable media)
Instead of a single file, a device can be pointed at a directory of images that are
cycled through with the eject button or the Control Board browser.
A directory in the scan root named with a type prefix and ID is picked up automatically:
CD0/ RE0/ MO0/ TP0/ FD0/ ZP0/ ... through ID F
and the n forms CDn/, REn/, MOn/, TPn/, FDn/, ZPn/ bind to the
dynamic SCA ID.
This can be overridden per device in zuluscsi.ini:
[SCSI0]
ImgDir = "MyDiscs"
Resolution order is: [SCSIn] ImgDir → [SCSI<ID>] ImgDir → dynamic HDn-style
directory → fixed HD<ID>-style directory. Only one image directory is used per
SCSI ID; if several would match, the first wins and the rest are logged and ignored.
Images inside the directory are ordered by case-insensitive name, and eject advances to
the next name, wrapping at the end.
Alternatively, images can be listed explicitly. These are cycled in the order given:
[SCSI1]
Type = 2
IMG0 = FirstCD.iso
IMG1 = SecondCD.iso
... # up to IMG99
Note that the explicit IMGx form and the plain prefixed-filename form do not support
the Control Board's browser-type selection or categories; ImgDir and the
HD0-style directories do.
CD-ROM images in BIN/CUE format
The .iso format for CD images only supports data track.
For audio and mixed mode CDs, two files are needed: .bin with data and .cue with the list of tracks.
To use a BIN/CUE image with ZuluSCSI, name both files with the same part before the extension.
For example CD3.bin and CD3.cue.
The cue file contains the original file name, but it doesn't matter for ZuluSCSI.
If the image consists of one .cue file and multiple .bin files, they need to be placed in a separate subfolder.
For example, create CD3 folder, then MyGame subfolder and put the .cue and .bin files there.
The .bin file names must then match the names specified in the .cue file.
Supported track types are AUDIO, MODE1/2048 and MODE1/2352.
Creating new image files
Alternatively, Empty image files can be created using operating system tools:
- Windows:
fsutil file createnew HD1.img 1073741824 (1 GB)
- Linux:
dd if=/dev/zero of=HD1.img bs=1G count=1 status=progress
- Mac OS X:
mkfile -n 1g HD1.img
If you need to use image files larger than 4GB, you must use an exFAT-formatted SD card, as the FAT32 filesystem does not support files larger than 4,294,967,295 bytes (4GB-1 byte).
ZuluSCSI firmware can create image files itself. To do this, create an empty text file with filename beginning with Create, such as Create 1024M HD40.txt.
The file will be created next time the SD card is inserted, and the status LED will flash rapidly while image file generation is in progress, the status of which can also be monitored in real-time via USB serial console.
For AS/400 AS400_DiskProfile= SCSI IDs (see below), a correctly-sized image is created automatically the same way, with no Create*.txt file needed — the size comes from the profile's own captured capacity.
AS/400 disk profiles
For AS/400 (System = "AS400_PPC" or "AS400_CISC"), multiple SCSI IDs can each emulate a different real DASD unit by setting AS400_DiskProfile = "<name>" in that ID's [SCSIn] section, naming a profile from as400_disk_definitions.txt. Those profiles are built into the firmware; copy the file (or your own version of it) to the SD card root only to add profiles or override built-in ones, since a profile on custom store takes priority over a built-in profile of the same name.
Note: The AS/400 platform extensively uses serial numbers to distinguish between devices. If another device with the same serial number is configured, even on separate SCSI-IDs, the machine recognizes only one of them. Hence the large count of disk profiles, until this issue is fixed.
See README-as400.md for more information about AS/400 specific configurations.
Log files and error indications
Log messages are stored in zululog.txt, which is cleared on every boot.
Normally only basic initialization information is stored, but switching the DBG DIP switch on will cause every SCSI command to be logged, once the board is power cycled.
The indicator LED will normally report disk access.
It also reports following status conditions:
- 1 fast blink on boot: One or more iImage files loaded successfully
- 3 fast blinks: No images found on SD card
- 5 fast blinks: SD card not detected
- Continuous morse pattern: firmware crashed, morse code indicates crash location
In crashes the firmware will also attempt to save information into zuluerr.txt.
Configuration file
Optional configuration can be stored in zuluscsi.ini.
If image file is found but configuration is missing, a default configuration is used.
An annotated example config file is available here: zuluscsi.ini.
Performance
Performance information for the various ZuluSCSI hardware models is documented separately, here
Hotplugging
The firmware supports hot-plug removal and reinsertion of SD card.
The status led will blink continuously when card is not present, then blink once when card is reinserted successfully.
It will depend on the host system whether it gets confused by hotplugging.
Any IO requests issued when card is removed will be timeouted.
Programming & bootloader
For ZuluSCSI Blaster and RP2040-based boards, the USB programming uses .uf2 format file that can be copied to the virtual USB drive that shows up in bootloader mode.
- There is a custom bootloader that loads new firmware from SD card on boot.
- Firmware update takes about 1 second, during which the LED will flash rapidly.
- When successful, the bootloader removes the update file and continues to main firmware.
- On ZuluSCSI Blaster and RP2040 boards, there is a "BOOTLDR" momentary-contact switch, which can be held down at initial power-on, to enable .uf2 firmware to be loaded.
For ZuluSCSI V1.1 and V1.2:
- Alternatively, ZuluSCSI V1.x can be programmed using USB connection in DFU mode by setting DIP switch 4.
- For ZuluSCSI V1.2 boards, there is a "BOOTLDR" momentary-contact switch, which can be held down at initial power-on, to enable DFU mode, needed for firmware recovery mode.
- The necessary programmer utility for Windows can be downloaded from GD32 website. On Linux and MacOS, the standard 'dfu-util' can be used. It can be installed via your package manager under Linux. On MacOS, it is available through MacPorts and Brew as a package.
- For ZuluSCSI V1.x boards, firmware can be flashed with the following command:
dfu-util --alt 0 --dfuse-address 0x08000000 --download ZuluSCSIv1_1_XXXXXX.bin
DIP switches
ZuluSCSI Blaster and RP2040 (Full Size) DIP switch settings are:
- INITIATOR: Enable SCSI initiator mode for imaging SCSI drives
- DEBUG LOG: Enable verbose debug log (saved to
zululog.txt)
- TERMINATION: Enable SCSI termination
Later (Rev2023a) ZuluSCSI RP2040 and all ZuluSCSI Blaster Full Size boards have a bootloader button instead of a DIP switch.
For ZuluSCSI V1.1, the DIP switch settings are as follows:
- DEBUG: Enable verbose debug log (saved to
zululog.txt)
- TERM: Enable SCSI termination
- BOOT: Enable built-in USB bootloader, this DIP switch MUST remain off during normal operation.
- SW1: Enables/disables Macintosh/Apple specific mode-pages and device strings, which eases disk initialization when performing fresh installs on legacy Macintosh computers.
For ZuluSCSI V1.2, the DIP switch settings at SW301 are as follows:
- TERM: Enable SCSI termination
- DEBUG: Enable verbose debug logging via USB serial console.
- DIRECT/RAW: when in the factory-default OFF position, the entirety of the SD card is exposed as a single block device, and the device type is defined by the setting of the rotary DIP switch at SW404.
- QUIRKS: Enables/disables Macintosh/Apple specific mode-pages and device strings, which eases disk initialization when performing fresh installs on legacy Macintosh computers.
ZuluSCSI Mini has no DIP switches, so all optional configuration parameters must be defined in zuluscsi.ini
Physical eject button for CDROM
CD-ROM drives can be configured to eject when a physical button is pressed.
If multiple image files are configured with IMG0..IMG9 config settings, ejection will switch between them.
Two separate buttons are supported and they can eject different drives.
[SCSI1]
Type=2 # CDROM drive
IMG0 = img0.iso
IMG1 = ...
EjectButton = 1
On ZuluSCSI V1.0 and V1.1 models, buttons are connected to J303 12-pin expansion header.
Button 1 is connected between PE5 and GND, and button 2 is connected between PE6 and GND.
Pin locations are also shown in this image.
On red ZuluSCSI Blaster and RP2040-based ZuluSCSI models, buttons are connected to the I2C pins.
Button 1 is connected between SDA and GND and button 2 is connected between SCL and GND.
On full-size models, the pins are available on expansion header J303 (image).
On compact model, pins are available on 4-pin I2C header J305 (image).
SCSI initiator mode
The full-size ZuluSCSI Blaster, ZuluSCSI RP2040, and Pico OSHW models support SCSI initiator mode for reading SCSI drives.
When enabled by the DIP switch, the ZuluSCSI Blaster/RP2040 will scan for SCSI drives on the bus and copy the data as HDxx_imaged.hda to the SD card.
LED indications in initiator mode:
- Short blink once a second: idle, searching for SCSI drives
- Fast blink 4 times per second: copying data. The blink acts as a progress bar: first it is short and becomes longer when data copying progresses.
The firmware retries reads up to 5 times and attempts to skip any sectors that have problems.
Any read errors are logged into zululog.txt.
Alternatively, if SD card is not inserted, the SCSI drive will be available to PC through USB connection.
The drive shows up as mass storage device (USB MSC).
Currently this primarily supports SCSI harddrives, but basic read access is supported for CD-ROM and other SCSI devices.
Depending on hardware setup, you may need to mount diode D205 and jumper JP201 to supply TERMPWR to the SCSI bus.
This is necessary if the drives do not supply their own SCSI terminator power.
ROM drive in microcontroller flash
The ZuluSCSI Blaster model supports storing up to 15.8 megabytes in flash, which can be used as a read-only bootable ROM drive.
All older ZuluSCSI RP2040 models support storing up to 1660kB image as a read-only drive in the flash chip on the PCB itself. This can be used as e.g. a boot floppy that is available even without SD card.
To initialize a ROM drive, name your image file as e.g. HD0.rom.
The drive type, SCSI ID and blocksize can be set in the filename the same way as for normal images.
On first boot, the LED will blink rapidly while the image is being loaded into flash memory.
Once loading is complete, the file is renamed to HD0.rom_loaded and the data is accessed from flash instead.
The status and maximum size of ROM drive are reported in zululog.txt.
To disable a previously programmed ROM drive, create empty file called HD0.rom.
If there is a .bin file with the same ID as the programmed ROM drive, it overrides the ROM drive.
There can be at most one ROM drive enabled at a time.
The ROM drive can be removed by creating a file without an extension and in all caps called CLEAR_ROM in the root directory of the SD card.
On successful removal the CLEAR_ROM file will be deleted, the ROM drive will no longer be enumerated on the SCSI bus, and the data zeroed out in flash.
Kiosk mode for museums or demonstration setups
The Kiosk mode is designed for vintage computer museums or other demonstration setups, where machines can be used by visitors but need to be easily restored to a pristine state.
At startup, all files with .ori extensions are copied to new volumes. For instance, HD10_512.hda.ori would be copied to HD10_512.hda.
Restoration takes a significant amount of time, so it should be used with small drives (it takes between 5 and 20 seconds to restore a 40MB hard drive depending on hardware). During the copy, the LED will blink with the pattern ON-OFF-ON-OFF-OFF. Each cycle corresponds to 5MB restored.
Alternatively, you can use the '.cow' extension (short for "Copy-On-Write"). With this option, there will be no copy at startup, but the write speed can suffer a bit, which is typically not an issue in museum setups. The '.cow' feature is not available for the ZuluSCSIv1_1_plus platform due to memory constraints. See Copy-On-Write documentation for more information and configuration options.
Rebooting the machine will not restore the files - you need to physically power-cycle the ZuluSCSI device.
Zulu Control Board
The Zulu Control Board is a small device which plugs into the I2C connector of the ZuluSCSI Blaster (Currently, that is the only supported board)
It features an OLED screen, a rotary encoder, and two push buttons.
This allows you to both control and visualize various aspects of the ZuluSCSI.
Note: There are no error screens. Error must still be inspected in the log files.
On power up a splash screen will display the current firmware version:
Then, depending on whether the initiator switch is on or off, it will go into either normal mode or initiator mode.
Start Up
There are various settings which can cause the ZuluSCSI to do tasks during startup. These are all long running and have dedicated progress screens.
If there is .rom image on the SD, then the image will be copied into ROM, this is what the progress screen will look like:
If there is a special create file on the SD, then an image will be created, this is what the progress screen will look like:
If there are images with the .ori extension for Kiosk mode, then they will be copied, this is what the progress screen will look like:
All these screen share common elements (from top to bottom)
- Title showing the operation, for Kiosk mode it shows how many files are to be copied
- The progress bar with % complete
- The filename being copied
- The rate of copy and the elapsed time
- The remaining bytes and remaining time
Once these have finished, the normal boot sequence will resume
Normal Mode
Assuming the initiator switch is off, then the splash screen will display the mode:
and assuming caching is turned on, for a few seconds, the caching building screen will appear
Once that is complete, the main screen will be displayed
Main Screen
(TODO: update image)
This screen displays an overview of the SCSI devices.
Top righr will show an SD card icon. (if the card is removed, the icon will have a little cross in it)
Each item displays:
- The SCSI ID
- An empty circle represents nothing is loaded, a solid circle represents a loaded image
- If an image is loaded, the type is displayed as an icon. e.g. ID 0 is a CD, IDs 1-3 and 5 are Hard Drives, and ID 6 is a Magneto-optical Disk in the picture above
- If the image is stored in the ZuluSCSI's ROM, then chip icon is displayed (ID 6 in the picture above)
Turning the rotary wheel will select a loaded image (a little arrow will be visible next to the image, in the above picture it's on ID 0)
If a device is not browsable and the eject button is pressed trying to browse it, the following pop up will be displayed:
Info Screen
Clicking the rotary button will display info about the selected device:
The following is on the screen:
- The type of the image is displayed as an icon, and the SCSI ID is in the top right.
- The file name (it scrolls if it's too long for the display)
- the folder name (it scrolls if it's too long for the display)
- Whether it can be browsed
- The filesize of the image
Pressing the User button will return to the Main Screen
Browser Type Screen
Depending on the way images are set up for browsing, some styles can have different browse modes.
If images are set up in config, either as:
- An ImgDir path is specified
- Use the standard folder naming of Device Type / SCSI ID. e.g. CD0 for cd images for SCSI ID 0
Then the browsing type can be selected. To do this, long-press the eject button
Other image browsing modes, i.e. IMGx and naming file with the Device Type / SCSI ID prefix e.g. CD0 cannot access the browser type screen or use categories
The first option is for the Folder-based Browser, which displays files and folders just like the structure on the SD card
The second option is for the Flat Browser, which flattens all files into a single list, removing the need to go into and out of folders (folder names are still displayed)
The remaining options are also Flat browser-based, but perform filtering based on the category (see category section)
Clicking either the eject or rotary button will go to the browser screen
Clicking user will return to the main menu
NOTE: The selected browse type is remembered for each SCSI ID. So, going to the browsing screen directly from the main menu will use the last selected browser type
Folder-based Browser
The following is on the screen:
- The type of the image is displayed as an icon, and the SCSI ID is in the top right.
- The file/folder name (it scrolls if it's too long for the display)
- the folder name (it scrolls if it's too long for the display)
- The filesize of the image
- The type (File or Folder) and which item number and total it is in this folder
Turning the rotary dial with select files and folders, the last item in the list for nested folders is a folder called ".." which, if selected, goes back a folder
Clicking either the eject or rotary button on a folder will go to the browser screen
Clicking either the eject on a file will load the image
Clicking user or long-pressing the rotary button in a nested folder will go back a directory, in the root folder, it will return to the main menu
During image loading, the following pop up will be displayed:
Flat Browser
The flat browser is very similar to the Folder Browser, but without:
- any of the folders displayed as selectable items
- the .. folder
Turning the rotary dial with select files
Clicking eject will load the image
Clicking user will return to the main menu
Categories
Categories provide a way of filtering images, this can be useful for large image sets.
There can be up to 10 categories per SCSI ID and are specifc to that SCSI ID.
Assume that there are images for a sampler, and that they can be divided into various categories, eg. Drums, Synths, Vocals and Guitars.
To set the categories, the following config should be added to the SCSI device (assume this is for SCSI ID 0 and the images will be in a folder called ISO1)
[SCSI0]
Type=2 # CDROM drive
ImgDir = "ISO1"
Cat0 = "dDrums"
Cat1 = "sSynths"
Cat2 = "vVocals"
Cat3 = "gGuitars"
The 4 categories are defined, and the first letter of the name is the code which represents that category (i.e Cat0, has a code of 'd' and a name of 'Drums')
Next, assume the following files are in the ISO1 folder:
Sample Disk {v}.iso
Drums 1 {d}.iso
Drums 2 {d}.iso
Licks {g}.iso
Various Samples {dsvg}.iso
The letters in the {} brackets represent which categories each file belongs to. so:
Sample Disk {v}.iso - is in the vocal category
Drums 1 {d}.iso - is in the drums category
Various Samples {dsvg}.iso - is in all 4 categories
So if you go to the Browser Type screen and select 'cat: drums', then the following 3 files would be browsable:
Drums 1 {d}.iso
Drums 2 {d}.iso
Various Samples {dsvg}.iso
Controls Summary
Main Screen:
- turning the
rotary dial will select a SCSI device
- click on
eject - this loads the browser screen
- click on the
rotary button - this goes to the info screen
- long click on
User - this will display the splash screen (same as on boot)
- long click on
eject - this loads the browser type screen
Info Screen:
- click on
user - returns to main screen
Browse Type Screen:
- click on
user - returns to main screen
- click on
eject or rotary button - go to the selected Browser screen
Browser Screen (Folder Mode):
- turning the
rotary dial will select a folder or file
- click on
user in a nested folder will go back a directory, in the root folder it will return to the main menu
- click on
eject or rotary button on the folder to navigate into that folder
- click on
eject on a file to load the image
Browser Screen (Flat Mode):
- turning the
rotary dial will select a file
- click on
user - returns to main screen
- click on
eject on a file to load the image
No SD screen:
- This screen has no controls.
Initiator Mode
Assuming the initiator switch is on, then the splash screen will display the mode:
and will the go to the scanning screen:
A circle with an X through it is the SCSI ID currently being scanned
Question marks are SCSI IDs which have no been checked yet
The empty circles are SCSI IDs which have been scanned
Once a drive is detected it will automatically go to the cloning screen:
Note: this is similar to the other copy screens with he exception that the file name is not displayed, but the total number of retires and errors (skipped sector) is displayed.
Once the cloning is complete, it will return to the scanning screen and display the cloned drive:
NOTE: There are no controls in Initiator mode, it is a viewing-only mode
Control Board Config
-
ControlBoardCache - Enables caching of images. This will greatly improve performance when there are many images. set this to 1 to enable. Enabling will cause some wear on the SD card as the cache is built every time the card is inserted, and there is a slight delay on load (generally 1-2secs for large file sets). So if browsing is laggy, enable this
-
ControlBoardReverseRotary - Some encoders work in the opposite direction, if you experience that, set this to 1
-
ControlBoardFlipDisplay - Rotates the screen 180 degrees. set this to 1 to flip
-
ControlBoardDimDisplay - if set to 1, then the screen will be a bit dimmer
-
ControlBoardScreenSaverTimeSec - Sets the seconds before the screen savers starts. 0 means screen saver is disabled
-
ControlBoardScreenSaverStyle - There are several screen savers, each ones uses more resources, so if you see a performance drop try a lower numbered one:
-
0 - Random selection (each time the screen saver starts, a random one will be selected)
-
1 - Blank screen
-
2 - DVD Style Random ZuluSCSI logo
-
3 - DVD Style Bouncing ZuluSCSI logo
-
4 - Horizontal Scrolling Icons
-
5 - Vertical Raining Icons
-
6 - Light speed
ZuluControl-firmware
See ZuluControl-firmware for the latest.
This is firmware that runs on a separate Pico W or 2W, or our custom wireless board, and communicates with the ZuluSCSI over the I2C interface. It provides a simple HTTP webserver that allows controlling images on removable devices.
The basic settings to get the HTTP webserver up and running are the following under the [WebUI] section in the zuluscsi.ini file.
[WebUI]
WiFiSSID = "your_ssid" # SSID for the WIFI network
WiFiPassword = "your_password" # Password for the WIFI network.
#Optional Static IPv4 Settings - fill in with your network settings
StaticIP = "192.168.1.42"
Netmask = "255.255.255.0"
Gateway = "192.168.1.1"
Access the IP with your favorite web browser, where you are able to control the ZuluSCSI, and media selection, over a web interface.
Project structure
- src/ZuluSCSI.cpp: Main portable SCSI implementation.
- src/ZuluSCSI_disk.cpp: Interface between SCSI2SD code and SD card reading.
- src/ZuluSCSI_log.cpp: Simple logging functionality, uses memory buffering.
- src/ZuluSCSI_config.h: Some compile-time options, usually no need to change.
- lib/ZuluSCSI_platform_platformName: Platform-specific code for each supported ZuluSCSI hardware platform.
- lib/SCSI2SD: SCSI2SD V6 code, used for SCSI command implementations.
- lib/minIni: Ini config file access library
- lib/SdFat_NoArduino: Modified version of SdFat library for use without Arduino core.
- utils/run_gdb.sh: Helper script for debugging with st-link adapter. Displays SWO log directly in console.
To port the code to a new platform, see README in lib/ZuluSCSI_platform_template folder.
Building
This codebase uses PlatformIO.
To build run the command:
pio run
Origins and License
This firmware is derived from two sources, both under GPL 3 license:
Main program structure:
- SCSI command implementations are from SCSI2SD.
- SCSI physical layer code is mostly custom, with some inspiration from BlueSCSI.
- Image file access is derived from BlueSCSI.
Major changes from BlueSCSI and SCSI2SD include:
- Separation of platform-specific functionality to separate directory to ease porting.
- Originally ported to GD32F205 and then RP2040 (See commit 858620f).
- Removal of Arduino core dependency, as it was not currently available for GD32F205.
- Buffered log functions.
- Simultaneous transfer between SD card and SCSI for improved performance.
