Rabbit Hole Computing - User contributions [en]

ZuluSCSI Operations Guide

2025-06-14T20:30:59Z

Mbalmer: /* Updating the Firmware */

= This page is still a work in progress. Sections marked with a [[File:Warning.png|frameless|32x32px]] icon are still in the process of being edited and finalized. =

== Setting Up Your ZuluSCSI ==

=== Unboxing ===
When you first receive your ZuluSCSI, depending on the options you ordered, you should receive the following:

* ZuluSCSI RP2040 Compact, ZuluSCSI Blaster, or ZuluSCSI 1.2 board
* Plastic board carrier
* 2x ¼" 4-40 screws
* microSD card or full-size SD card
* DAC board (ZuluSCSI Blaster only)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below, based on the type of board you have.
{| class="wikitable"
|+
!ZuluSCSI RP2040 Compact
!ZuluSCSI Blaster RP2350B
!ZuluSCSI 1.2
|-
|[[File:ZSCSI compact labeled.png|frameless]]
|[[File:ZSCSI Blaster labeled.png|frameless]]
|[[File:ZSCSI1.2 Labeled.png|frameless]]
|}
* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive; see below).
* '''50-pin male IDC connector:''' Plug your SCSI bus cable into this. The connector is keyed, but some SCSI cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''BOOTLDR button:''' Used in the firmware flashing process; see below.
* '''USER button:''' Reserved for future use.
* '''Termination and Initiator jumpers (Compact only):''' Populate these footprints with standard 0.1" header, solder them down, and then use a standard jumper cap to switch on the ZuluSCSI Compact's termination capabilities or enable initiator mode.
* '''DIP Switch Block (ZuluSCSI Blaster only):''' Used to enable initiator mode, termination, or debug mode.
* '''I2S Accessory Header (ZuluSCSI Blaster only):''' If you purchased the optional I2S DAC for CD audio capability, insert it here.
* '''Device type selector switch (ZuluSCSI 1.2 only):''' Use this rotary switch to select the type of device the ZuluSCSI is meant to emulate here. This switch is only active when switch 2 on the Settings DIP switch block is set to '''off.'''
* '''SCSI ID Dip Switch (ZuluSCSI 1.2 only):''' Use this set of switches to set the device's SCSI ID.
* '''Device Settings Switch block (ZuluSCSI 1.2 only):''' Use these switches to control termination, debug mode, "quirks" mode (for some Macintosh devices) and whether the entirety of the SD card is exposed as a single block device, or whether the device reads the SD card for image files and emulates multiple devices dependent on filename (as with other ZuluSCSI devices).

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==

=== ZuluSCSI Blaster or ZuluSCSI RP2040 Compact ===
* '''Switch 1:''' Turn Initiator mode on or off.
** On the RP2040 Compact, this is controlled by the jumper at <code>J310</code> on the board in the lower right.
* '''Switch 2:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the port on the device with this switch on, it will also print the debug log over the cable via the microcontroller's internal serial connection.
** On the RP2040 Compact, this is controlled by setting <code>Debug = 1</code> in the <code>zuluscsi.ini</code> file on the SD card itself.
* '''Switch 3:''' Enable or disable SCSI termination as needed.
** On the RP2040 Compact, this is controlled by the jumper at <code>J311</code> in the center of the board.

=== ZuluSCSI 1.2 ===
If you have a ZuluSCSI 1.2, the block of '''four''' DIP switches at <code>SW301</code> control various aspects of how the device responds in the system:

* '''Switch 1:''' Toggle Macintosh "Quirks" mode. On some legacy Macs, it helps if the device responds with specific things when the system calls upon it during a fresh installation. If your Mac responds erratically or doesn't behave properly with the device in the system, try turning this switch ON before anything else.
* '''Switch 2:''' Direct/Raw mode vs. standard mode. If this switch is left in its default OFF position, then the entire SD card is exposed to the system as a single block device and allows your SCSI interface card to manage it, based on the settings of <code>SW403</code> and <code>SW404</code>.
** The block of '''three''' DIP switches at <code>SW403</code> are used for setting your SCSI ID. If all three switches are off, the board's SCSI ID is 0. Turn switch 1 on to add 1 to the device ID, switch 2 to add 2, and switch 3 to add 4. If all three are on, the SCSI ID is 7.
** The rotary switch at <code>SW404</code> controls how the ZuluSCSI responds to your SCSI interface card when it queries it. Each position on the switch causes it to respond as a different device and will register differently:
*** Position 0 (straight up): Hard disk
*** Position 1: Optical drive
*** Position 2: Floppy disk
*** Position 3: Other generic removable block device
*** Position 4: Magneto-optical disk drives
*** Position 5: Seagate ST32430N Hawk HDD
*** Position 6: Sequential magnetic tape drives
*** Positions 7, 8, 9: Reserved

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not responding
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.
** If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use an SD card larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB. The card can be of any size as long as the card has an SDHC or SDXC classification badge. There is no upper limit for how large the card is (the maximum size supported by the SDXC specification is 2 TB, for example) however, you may notice slowdowns on the device if you store large numbers of individual files of any size in any single folder.

The device ''will not read'' SD cards formatted using the GPT (GUID Partition Map) method. If you try to use a card formatted with this method, the Activity LED will blink 5 times with the card inserted, indicating that the card's presence is being detected, but that it is unresponsive.

To make use of your ZuluSCSI, place disk image files in the root folder of the SD card and name them based upon the device and SCSI ID you want them to occupy on the bus. Your filename should follow the format <code>xxy.img</code>, where <code>x</code> is a two-character code representing the device to be emulated, and <code>y</code> is a number representing the SCSI ID number you intend the device to take, from 0 to 7.

If you're emulating other devices on the ZuluSCSI, use the following two-character prefixes for your images depending on the device you want it to be:

* <code>HD</code>: Hard disk
* <code>CD</code>: Optical drive
* <code>FD</code>: Floppy disk
* <code>MO</code>: Magneto-optical
* <code>RE</code>: Generic removable device
* <code>TP</code>: Sequential tape
* <code>ZP</code>: Zip-100 or Zip-250 drive

For example, if you want the ZuluSCSI to emulate a three-device system containing two hard disks at IDs 3 and 4 and a single optical drive at ID 6, copy your images over and name them <code>HD3.img</code>, <code>HD4.img</code>, and <code>CD6.iso</code> inside the root folder of the card.

[[File:Info.png|frameless|32x32px]] Images can also be stored in folders, but will not be accessible by the device unless you name the folder using the format described above. This is handy when you want to cycle images on a particular device, like floppy disks or CDs.

=== Creating empty disk images ===
The ZuluSCSI can also create empty disk images for you. To do this, create a '''zero-length text file''' named using the following format:

<code>Create <size> <device type><SCSI ID>.txt</code>

<code><size></code> should be a value in the format <code>xxxY</code>, where '''xxx''' is a number and '''Y''' is a letter representing the magnitude of that number. For example, <code>20M</code> would be 20 megabytes, <code>20G</code> would be 20 gigabytes, <code>20K</code> would be 20 kilobytes, etc.

<code><device type></code> is a two-letter code corresponding to the device type desired above. Currently, only rewritable image types are supported, meaning the <code>HD</code>, <code>FD</code>, <code>MO</code>, <code>TP</code>, and <code>ZP</code> device types are supported.

<code><SCSI ID></code> is a number from 0 to 7 indicating the SCSI ID number that the device should occupy when the image is fully written and ready.

An example filename to create a 1024-megabyte hard disk drive at SCSI ID 4 would be <code>Create 1024M HD4.txt</code>.

Copy the text file to the root folder of your SD card, place the card in the ZuluSCSI and turn it on. The ZuluSCSI will initialize and mount any existing images first, and then get to work creating your empty image file. The access LED will flash continuously during image creation and, in the case of very large images, can take some time to complete.

==== Creating zero-length text files ====
On Windows, use a program like Notepad or Notepad++, create a new file, and immediately save it on the SD card with the desired filename.

On Linux-based machines or Macs running OS X, open a Terminal window, and then type <code>touch <filename.txt></code> and then copy the resulting file to the SD card.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware in three different ways.

==== Using a ZIP file ====
ZuluSCSI boards running firmware '''v2024.12.03''' or later can be updated by simply placing a ZIP file downloaded from the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github releases page].

Download the <code>ZuluSCSI-FW_YYYY-MM-DD-universalFW.zip</code> file from the repository (where <code>YYYY</code>, <code>MM</code>, and <code>DD</code> represent the year, month, and date of release) directly to the SD card you're using, place the card back into the ZuluSCSI and turn on the system. The ZuluSCSI will take care of extracting and applying the firmware update on its own and, unless the system's boot time is exceptionally fast, the firmware update should apply in time for the system BIOS to catch the change.

==== Using the SD card ====
The ZuluSCSI can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluSCSI is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluSCSI.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluSCSI.
# Power the system back on. The ZuluSCSI will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluSCSI and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluSCSI so it can become ready.
# When the firmware update process finishes, the ZuluSCSI will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB or USB-C port into a host computer, this is the traditional way to update RP2040 and RP2350B-based devices.

# Power down the system the ZuluSCSI is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluSCSI, attach the other end of the cable to the MicroUSB port on the ZuluSCSI. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluSCSI.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluSCSI to its host, if you removed it in step 1.

== Troubleshooting [[File:Warning.png|frameless|32x32px]] ==
Some simple things to check before you dive deeper:

* Make sure that there are no devices contending for the same ID number on the bus. Typically, the host device on a system is identified as ID 7, so avoid using ID 7 where possible.

ZuluIDE INI Configuration

2025-05-25T07:37:56Z

Mbalmer: set table alignments

== Before You Edit Anything ==
In the vast majority of use cases, many people don't need to change the options in the INI file. Most of the options presented here will work perfectly well with their defaults; the only time most options need to be changed is where a specific use case requires it or if there is a particular problem with the way the device is performing.

The most recent version of the base INI file can be found at the [https://github.com/ZuluIDE/ZuluIDE-firmware/blob/main/zuluide.ini ZuluIDE Github repo.]

Settings of type '''On/Off''' are set using a <code>1</code> or a <code>0</code>, with a 1 meaning the feature is enabled, while a 0 means the feature is disabled.

Settings of type '''string''' require a string enclosed in double quotation marks.

Settings of type '''int''' require an integer, usually corresponding to a particular mode number.

Settings with a default listed as '''unset''' should remain commented out unless needed.

=== <code>[IDE]</code> section ===
{| class="wikitable"
|+
!Setting
!Type
!Effect
!Default
|-
|<code>debug</code>
|style="text-align:center"; |on/off
|If <code>1</code>, enables writing a debug log to <code>zululog.txt</code>. '''This overrides the DIP switch setting.'''
|style="text-align:center"; |off
|-
|<code>enable_usb_mass_storage</code>
|style="text-align:center"; |on/off
|If <code>1</code>, allows direct access to the microSD card's filesystem via the USB port. This does '''not''' allow access to the image currently loaded by the ZuluIDE.
|style="text-align:center"; |off
|-
|<code>eject_button</code>
|style="text-align:center"; |on/off
|If <code>1</code>, sets the eject button's GPIO pin to pin 14; if <code>0</code>, sets the eject button's GPIO pin to pin 11 (the default)
|style="text-align:center"; |off
|-
|<code>ignore_prevent_removal</code>
|style="text-align:center"; |on/off
|Set this to <code>0</code> to force the ZuluIDE to respect the host device's ability to prohibit media ejection. When on, the ZuluIDE will allow you to eject an image at any time, regardless of the circumstances.
|style="text-align:center"; |on
|-
|<code>has_drive1</code>
|style="text-align:center"; |on/off
|Uncomment and set this to <code>0</code> to forcibly tell the ZuluIDE that there is no secondary drive attached to the same IDE channel that the ZuluIDE is using. '''Only use this option if the ZuluIDE claims in the debug log that a secondary drive is present when the ZuluIDE is the only device on that IDE channel and the ZuluIDE is set as the primary drive.'''
|style="text-align:center"; |Unset
|-
|<code>max_udma</code>
|style="text-align:center"; |int
|Set the maximum UltraDMA mode to use. Set to <code>-1</code> to disable UltraDMA modes entirely.
|style="text-align:center"; |<code>0</code>
|-
|<code>max_pio</code>
|style="text-align:center"; |int
|Set the maximum programmed I/O mode to use. Maximum supported PIO mode on the ZuluIDE RP2040 is mode 3.
|style="text-align:center"; |<code>3</code>
|-
|<code>max_blocksize</code>
|style="text-align:center"; |int
|Maximum number of bytes in a single transfer block.
|style="text-align:center"; |<code>4096</code>
|-
|<code>device</code>
|style="text-align:center"; |string '''without quotes'''
|Set the device type to emulate. Valid choices are:

* <code>CDROM</code> for optical drives
* <code>Zip100</code> for 100MB Zip drives
* <code>Zip250</code> for 250MB Zip drives (experimental)
* <code>Removable</code> for generic removable media
* <code>HDD</code> for fixed-disk mode
|style="text-align:center"; |<code>CDROM</code>
|-
|<code>atapi_vendor</code>
|style="text-align:center"; |string
|Report a specific vendor string to the system BIOS when operating as an ATAPI device (i.e., optical drives). Maximum length 8 characters.
|style="text-align:center"; |<code>ZuluIDE</code>
|-
|<code>atapi_product</code>
|style="text-align:center"; |string
|Report a specific product name string to the system BIOS when operating as an ATAPI device (i.e., optical drives). Maximum length 16 characters.
|style="text-align:center"; |<code>CDROM</code>
|-
|<code>atapi_version</code>
|style="text-align:center"; |string
|Report a specific product version string to the system BIOS when operating as an ATAPI device (i.e., optical drives). Maximum length 4 characters.
|style="text-align:center"; |<code>1.0</code>
|-
|<code>ide_model</code>
|style="text-align:center"; |string
|Report a specific model name to the system BIOS when operating as an IDE device (i.e., hard disks). Maximum length 40 characters.
|style="text-align:center"; |
|-
|<code>ide_serial</code>
|style="text-align:center"; |string
|Report a specific serial number to the system BIOS when operating as an IDE device (i.e., hard disks). Maximum length 20 characters.
|style="text-align:center"; |
|-
|<code>ide_revision</code>
|style="text-align:center"; |string
|Report a specific revision code to the system BIOS when operating as an IDE device (i.e., hard disks). Maximum length 8 characters.
|style="text-align:center"; |
|-
|<code>reinsert_media_after_eject</code>
|style="text-align:center"; |on/off
|If set to <code>1</code>, the ZuluIDE will automatically re-mount the most recently ejected image. Handy for cases where the system auto-ejects media without your input.
|style="text-align:center"; |<code>0</code>
|-
|<code>reinsert_media_on_inquiry</code>
|style="text-align:center"; |on/off
|If set to <code>1</code>, the ZuluIDE will automatically re-mount the most recently ejected image when it receives either an ATA <code>IDENTIFY_DEVICE</code> command or <code>IDENTIFY_PACKET_DEVICE</code> command.
|style="text-align:center"; |<code>0</code>
|-
|<code>reinsert_media_on_sd_insert</code>
|style="text-align:center"; |on/off
|If set to <code>1</code>, the ZuluIDE will automatically re-mount the most recently used image when an SD card is inserted. The most recently used image is stored directly as a filename in the <code>zululast.txt</code> file in the root folder of the SD card.
|style="text-align:center"; |<code>1</code>
|-
|<code>set_not_ready_on_insert</code>
|style="text-align:center"; |on/off
|Set this to <code>1</code> to have the next ATAPI command report with a "not ready" response when the loaded image file is changed. Some systems and/or OSes need this to properly handle a media change.
|style="text-align:center"; |<code>0</code>
|-
|<code>init_with_last_used_image</code>
|style="text-align:center"; |on/off
|Set this to <code>1</code> to cause the ZuluIDE to automatically re-mount the last-used image on powerup.
|style="text-align:center"; |<code>1</code>
|-
|<code>ignore_command_interrupt</code>
|style="text-align:center"; |on/off
|When set to <code>1</code>, the ZuluIDE will ignore any command that interrupts one that is currently executing.
|style="text-align:center"; |<code>0</code>
|-
|<code>atapi_intrq</code>
|style="text-align:center"; |on/off
|When set to <code>1</code>, the ZuluIDE will enable the <code>INTRQ</code> signal during a <code>PACKET</code> command. This is normally left disabled. '''Only enable this if support directs you to.'''
|style="text-align:center"; |<code>0</code>
|-
|<code>cylinders</code>
|style="text-align:center"; |int
| rowspan="3" |Specify number of cylinders, heads, and sectors for rigid disk emulation. '''All three''' of these parameters must be set for the ZuluIDE to use them, otherwise the ZuluIDE will make a best guess based on the size of the image file and report that best guess to the BIOS when queried.
|style="text-align:center"; rowspan="3" |unset
|-
|<code>heads</code>
|style="text-align:center"; |int
|-
|<code>sectors</code>
|style="text-align:center"; |int
|-
|<code>access_delay</code>
|style="text-align:center"; |int
|Add an extra delay (in milliseconds) before responding to commands issued by the host system.
|style="text-align:center"; |<code>0</code>
|-
|<code>max_volume</code>
|style="text-align:center"; |int
|Volume level used when decoding Redbook audio through the optional I2S audio interface. Valid range is <code>0</code> to <code>100</code>.
|style="text-align:center"; |<code>100</code>
|}

=== <code>[UI]</code> section ===
The options in this section require either the optional hardware interface, or require a Pi Pico W to be mounted to the optional Audio & Pico Shield.
{| class="wikitable"
|+
!Setting
!Type
!Effect
!Default
|-
|<code>wifissid</code>
|style="text-align:center"; |string
|Set the SSID to connect to to present the HTML interface.
|style="text-align:center"; |unset
|-
|<code>wifipassword</code>
|style="text-align:center"; |string
|Set the password to the SSID above.
|style="text-align:center"; |unset
|-
|<code>rotary_encoder_ticks</code>
|style="text-align:center"; |int
|Number of detents before the controller board registers a turn of the rotary encoder. Earlier versions of the hardware interface protocol used <code>4</code> for this value, current firmware sets this to <code>1</code> by default.
|style="text-align:center"; |<code>1</code>
|}

ZuluIDE INI Configuration

2025-05-25T07:30:12Z

Mbalmer: Added current INI file options.

== Before You Edit Anything ==
In the vast majority of use cases, many people don't need to change the options in the INI file. Most of the options presented here will work perfectly well with their defaults; the only time most options need to be changed is where a specific use case requires it or if there is a particular problem with the way the device is performing.

The most recent version of the base INI file can be found at the [https://github.com/ZuluIDE/ZuluIDE-firmware/blob/main/zuluide.ini ZuluIDE Github repo.]

Settings of type '''On/Off''' are set using a <code>1</code> or a <code>0</code>, with a 1 meaning the feature is enabled, while a 0 means the feature is disabled.

Settings of type '''string''' require a string enclosed in double quotation marks.

Settings of type '''int''' require an integer, usually corresponding to a particular mode number.

Settings with a default listed as '''unset''' should remain commented out unless needed.

=== <code>[IDE]</code> section ===
{| class="wikitable"
|+
!Setting
!Type
!Effect
!Default
|-
|<code>debug</code>
|on/off
|If <code>1</code>, enables writing a debug log to <code>zululog.txt</code>. '''This overrides the DIP switch setting.'''
|off
|-
|<code>enable_usb_mass_storage</code>
|on/off
|If <code>1</code>, allows direct access to the microSD card's filesystem via the USB port. This does '''not''' allow access to the image currently loaded by the ZuluIDE.
|off
|-
|<code>eject_button</code>
|on/off
|If <code>1</code>, sets the eject button's GPIO pin to pin 14; if <code>0</code>, sets the eject button's GPIO pin to pin 11 (the default)
|off
|-
|<code>ignore_prevent_removal</code>
|on/off
|Set this to <code>0</code> to force the ZuluIDE to respect the host device's ability to prohibit media ejection. When on, the ZuluIDE will allow you to eject an image at any time, regardless of the circumstances.
|on
|-
|<code>has_drive1</code>
|on/off
|Uncomment and set this to <code>0</code> to forcibly tell the ZuluIDE that there is no secondary drive attached to the same IDE channel that the ZuluIDE is using. '''Only use this option if the ZuluIDE claims in the debug log that a secondary drive is present when the ZuluIDE is the only device on that IDE channel and the ZuluIDE is set as the primary drive.'''
|Unset
|-
|<code>max_udma</code>
|int
|Set the maximum UltraDMA mode to use. Set to <code>-1</code> to disable UltraDMA modes entirely.
|<code>0</code>
|-
|<code>max_pio</code>
|int
|Set the maximum programmed I/O mode to use. Maximum supported PIO mode on the ZuluIDE RP2040 is mode 3.
|<code>3</code>
|-
|<code>max_blocksize</code>
|int
|Maximum number of bytes in a single transfer block.
|<code>4096</code>
|-
|<code>device</code>
|string
'''without quotes'''
|Set the device type to emulate. Valid choices are:

* <code>CDROM</code> for optical drives
* <code>Zip100</code> for 100MB Zip drives
* <code>Zip250</code> for 250MB Zip drives (experimental)
* <code>Removable</code> for generic removable media
* <code>HDD</code> for fixed-disk mode
|<code>CDROM</code>
|-
|<code>atapi_vendor</code>
|string
|Report a specific vendor string to the system BIOS when operating as an ATAPI device (i.e., optical drives). Maximum length 8 characters.
|<code>ZuluIDE</code>
|-
|<code>atapi_product</code>
|string
|Report a specific product name string to the system BIOS when operating as an ATAPI device (i.e., optical drives). Maximum length 16 characters.
|<code>CDROM</code>
|-
|<code>atapi_version</code>
|string
|Report a specific product version string to the system BIOS when operating as an ATAPI device (i.e., optical drives). Maximum length 4 characters.
|<code>1.0</code>
|-
|<code>ide_model</code>
|string
|Report a specific model name to the system BIOS when operating as an IDE device (i.e., hard disks). Maximum length 40 characters.
|
|-
|<code>ide_serial</code>
|string
|Report a specific serial number to the system BIOS when operating as an IDE device (i.e., hard disks). Maximum length 20 characters.
|
|-
|<code>ide_revision</code>
|string
|Report a specific revision code to the system BIOS when operating as an IDE device (i.e., hard disks). Maximum length 8 characters.
|
|-
|<code>reinsert_media_after_eject</code>
|on/off
|If set to <code>1</code>, the ZuluIDE will automatically re-mount the most recently ejected image. Handy for cases where the system auto-ejects media without your input.
|<code>0</code>
|-
|<code>reinsert_media_on_inquiry</code>
|on/off
|If set to <code>1</code>, the ZuluIDE will automatically re-mount the most recently ejected image when it receives either an ATA <code>IDENTIFY_DEVICE</code> command or <code>IDENTIFY_PACKET_DEVICE</code> command.
|<code>0</code>
|-
|<code>reinsert_media_on_sd_insert</code>
|on/off
|If set to <code>1</code>, the ZuluIDE will automatically re-mount the most recently used image when an SD card is inserted. The most recently used image is stored directly as a filename in the <code>zululast.txt</code> file in the root folder of the SD card.
|<code>1</code>
|-
|<code>set_not_ready_on_insert</code>
|on/off
|Set this to <code>1</code> to have the next ATAPI command report with a "not ready" response when the loaded image file is changed. Some systems and/or OSes need this to properly handle a media change.
|<code>0</code>
|-
|<code>init_with_last_used_image</code>
|on/off
|Set this to <code>1</code> to cause the ZuluIDE to automatically re-mount the last-used image on powerup.
|<code>1</code>
|-
|<code>ignore_command_interrupt</code>
|on/off
|When set to <code>1</code>, the ZuluIDE will ignore any command that interrupts one that is currently executing.
|<code>0</code>
|-
|<code>atapi_intrq</code>
|on/off
|When set to <code>1</code>, the ZuluIDE will enable the <code>INTRQ</code> signal during a <code>PACKET</code> command. This is normally left disabled. '''Only enable this if support directs you to.'''
|<code>0</code>
|-
|<code>cylinders</code>
|int
| rowspan="3" |Specify number of cylinders, heads, and sectors for rigid disk emulation. '''All three''' of these parameters must be set for the ZuluIDE to use them, otherwise the ZuluIDE will make a best guess based on the size of the image file and report that best guess to the BIOS when queried.
| rowspan="3" |unset
|-
|<code>heads</code>
|int
|-
|<code>sectors</code>
|int
|-
|<code>access_delay</code>
|int
|Add an extra delay (in milliseconds) before responding to commands issued by the host system.
|<code>0</code>
|-
|<code>max_volume</code>
|int
|Volume level used when decoding Redbook audio through the optional I2S audio interface. Valid range is <code>0</code> to <code>100</code>.
|<code>100</code>
|}

=== <code>[UI]</code> section ===
The options in this section require either the optional hardware interface, or require a Pi Pico W to be mounted to the optional Audio & Pico Shield.
{| class="wikitable"
|+
!Setting
!Type
!Effect
!Default
|-
|<code>wifissid</code>
|string
|Set the SSID to connect to to present the HTML interface.
|unset
|-
|<code>wifipassword</code>
|string
|Set the password to the SSID above.
|unset
|-
|<code>rotary_encoder_ticks</code>
|int
|Number of detents before the controller board registers a turn of the rotary encoder. Earlier versions of the hardware interface protocol used <code>4</code> for this value, current firmware sets this to <code>1</code> by default.
|<code>1</code>
|}

Basic Usage

2025-05-20T05:42:30Z

Mbalmer: /* File Naming on the ZuluSCSI */

== SD Card Preparation ==
Both the ZuluSCSI and ZuluIDE devices utilize either SD or microSD cards to load disk images. Your SD card should be formatted either as FAT32 or exFAT '''(not NTFS)''' on at least one partition, if your card has more than one. Cards you use with the device need to fit the following criteria:

* Card must be labeled as either SDXC or SDHC
* MBR or DOS partition type (not GPT)
* No size limitations (see below)

Note that certain older cards (typically manufactured before 2008 and usually 4GB or smaller) will fail to be detected by the device. This is not the fault of the device; it's a speed limitation of the SD card itself. There is no known upper limit to the size of card you can use in the device, and has been tested with 256GB, 400GB, and larger cards that are currently available for sale.

===== File Naming on the ZuluSCSI =====
Create or copy a single valid disk image file into the root directory of your SD card and rename it based on the device you want it to serve as. If the image is a hard drive, name it <code>HDx.img</code> or <code>HDx.hda</code>, and replace the '''x''' in the filename with the desired SCSI ID number, which is a unique number between 0 and 6 (i.e., <code>HD4.img</code> for a hard drive assigned as unit 4 on the SCSI bus). The image will automatically be configured and placed on the SCSI bus.

For optical media images, name image files as <code>CDx.iso</code> or <code>CDx.img</code>, again replacing the '''x''' in the filename with the SCSI ID number. Any image loaded here will be automatically configured by the device as a SCSI-attached optical drive with a standard 2048-byte sector size. If your disc image is in BIN/CUE format, place it in a folder named <code>CDx</code>, again, replacing the '''x''' with the SCSI ID number you want to use. File names inside the folder should conform to the typical BIN/CUE standard where each BIN file shares a common name with the cue sheet and has its track number appended to the filename.

If you need to create a blank image and don't have an app, the ZuluSCSI has a provision to do so in firmware: Using any text editor, create a 0-length file and name it based on the properties you want the resulting drive to have. For example, <code>Create 1024M HD0.txt</code> will create a 1 GB blank image file, rename it as <code>HD0.img</code>, and then mount the image file. While the ZuluSCSI is creating the image file, the LED will flash repeatedly.

===== File Naming on the ZuluIDE =====

File names on the ZuluIDE are far less restricted, but are still limited to only a few formats. Files ending in <code>.iso</code> or <code>.bin/cue</code> are automatically loaded as optical media images, while images ending in any ''other'' extension not on the [[ZuluIDE File Ignore List|Ignored List]] are treated as other generic removable media, Zip disks, or hard drive images. The type of device the ZuluIDE is configured as defaults to an optical drive, but can be changed with some [[ZuluIDE INI Settings|INI settings]] loaded from the SD card at power-on.

Attach your device to its bus, attach power, turn the system on, and let the device work its magic!

For specifics, see the [[ZuluSCSI Operations Guide]] or the [[ZuluIDE Operations Guide|ZuluIDE Operations Guide.]]

File:ZSCSI Blaster labeled.png

2025-04-16T22:27:11Z

Mbalmer: Mbalmer uploaded a new version of File:ZSCSI Blaster labeled.png

ZSCSI Blaster labeled

ZuluSCSI Operations Guide

2025-04-16T22:24:05Z

Mbalmer:

= This page is still a work in progress. Sections marked with a [[File:Warning.png|frameless|32x32px]] icon are still in the process of being edited and finalized. =

== Setting Up Your ZuluSCSI ==

=== Unboxing ===
When you first receive your ZuluSCSI, depending on the options you ordered, you should receive the following:

* ZuluSCSI RP2040 Compact, ZuluSCSI Blaster, or ZuluSCSI 1.2 board
* Plastic board carrier
* 2x ¼" 4-40 screws
* microSD card or full-size SD card
* DAC board (ZuluSCSI Blaster only)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below, based on the type of board you have.
{| class="wikitable"
|+
!ZuluSCSI RP2040 Compact
!ZuluSCSI Blaster RP2350B
!ZuluSCSI 1.2
|-
|[[File:ZSCSI compact labeled.png|frameless]]
|[[File:ZSCSI Blaster labeled.png|frameless]]
|[[File:ZSCSI1.2 Labeled.png|frameless]]
|}
* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive; see below).
* '''50-pin male IDC connector:''' Plug your SCSI bus cable into this. The connector is keyed, but some SCSI cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''BOOTLDR button:''' Used in the firmware flashing process; see below.
* '''USER button:''' Reserved for future use.
* '''Termination and Initiator jumpers (Compact only):''' Populate these footprints with standard 0.1" header, solder them down, and then use a standard jumper cap to switch on the ZuluSCSI Compact's termination capabilities or enable initiator mode.
* '''DIP Switch Block (ZuluSCSI Blaster only):''' Used to enable initiator mode, termination, or debug mode.
* '''I2S Accessory Header (ZuluSCSI Blaster only):''' If you purchased the optional I2S DAC for CD audio capability, insert it here.
* '''Device type selector switch (ZuluSCSI 1.2 only):''' Use this rotary switch to select the type of device the ZuluSCSI is meant to emulate here. This switch is only active when switch 2 on the Settings DIP switch block is set to '''off.'''
* '''SCSI ID Dip Switch (ZuluSCSI 1.2 only):''' Use this set of switches to set the device's SCSI ID.
* '''Device Settings Switch block (ZuluSCSI 1.2 only):''' Use these switches to control termination, debug mode, "quirks" mode (for some Macintosh devices) and whether the entirety of the SD card is exposed as a single block device, or whether the device reads the SD card for image files and emulates multiple devices dependent on filename (as with other ZuluSCSI devices).

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==

=== ZuluSCSI Blaster or ZuluSCSI RP2040 Compact ===
* '''Switch 1:''' Turn Initiator mode on or off.
** On the RP2040 Compact, this is controlled by the jumper at <code>J310</code> on the board in the lower right.
* '''Switch 2:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the port on the device with this switch on, it will also print the debug log over the cable via the microcontroller's internal serial connection.
** On the RP2040 Compact, this is controlled by setting <code>Debug = 1</code> in the <code>zuluscsi.ini</code> file on the SD card itself.
* '''Switch 3:''' Enable or disable SCSI termination as needed.
** On the RP2040 Compact, this is controlled by the jumper at <code>J311</code> in the center of the board.

=== ZuluSCSI 1.2 ===
If you have a ZuluSCSI 1.2, the block of '''four''' DIP switches at <code>SW301</code> control various aspects of how the device responds in the system:

* '''Switch 1:''' Toggle Macintosh "Quirks" mode. On some legacy Macs, it helps if the device responds with specific things when the system calls upon it during a fresh installation. If your Mac responds erratically or doesn't behave properly with the device in the system, try turning this switch ON before anything else.
* '''Switch 2:''' Direct/Raw mode vs. standard mode. If this switch is left in its default OFF position, then the entire SD card is exposed to the system as a single block device and allows your SCSI interface card to manage it, based on the settings of <code>SW403</code> and <code>SW404</code>.
** The block of '''three''' DIP switches at <code>SW403</code> are used for setting your SCSI ID. If all three switches are off, the board's SCSI ID is 0. Turn switch 1 on to add 1 to the device ID, switch 2 to add 2, and switch 3 to add 4. If all three are on, the SCSI ID is 7.
** The rotary switch at <code>SW404</code> controls how the ZuluSCSI responds to your SCSI interface card when it queries it. Each position on the switch causes it to respond as a different device and will register differently:
*** Position 0 (straight up): Hard disk
*** Position 1: Optical drive
*** Position 2: Floppy disk
*** Position 3: Other generic removable block device
*** Position 4: Magneto-optical disk drives
*** Position 5: Seagate ST32430N Hawk HDD
*** Position 6: Sequential magnetic tape drives
*** Positions 7, 8, 9: Reserved

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not responding
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.
** If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use an SD card larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB. The card can be of any size as long as the card has an SDHC or SDXC classification badge. There is no upper limit for how large the card is (the maximum size supported by the SDXC specification is 2 TB, for example) however, you may notice slowdowns on the device if you store large numbers of individual files of any size in any single folder.

The device ''will not read'' SD cards formatted using the GPT (GUID Partition Map) method. If you try to use a card formatted with this method, the Activity LED will blink 5 times with the card inserted, indicating that the card's presence is being detected, but that it is unresponsive.

To make use of your ZuluSCSI, place disk image files in the root folder of the SD card and name them based upon the device and SCSI ID you want them to occupy on the bus. Your filename should follow the format <code>xxy.img</code>, where <code>x</code> is a two-character code representing the device to be emulated, and <code>y</code> is a number representing the SCSI ID number you intend the device to take, from 0 to 7.

If you're emulating other devices on the ZuluSCSI, use the following two-character prefixes for your images depending on the device you want it to be:

* <code>HD</code>: Hard disk
* <code>CD</code>: Optical drive
* <code>FD</code>: Floppy disk
* <code>MO</code>: Magneto-optical
* <code>RE</code>: Generic removable device
* <code>TP</code>: Sequential tape
* <code>ZP</code>: Zip-100 or Zip-250 drive

For example, if you want the ZuluSCSI to emulate a three-device system containing two hard disks at IDs 3 and 4 and a single optical drive at ID 6, copy your images over and name them <code>HD3.img</code>, <code>HD4.img</code>, and <code>CD6.iso</code> inside the root folder of the card.

[[File:Info.png|frameless|32x32px]] Images can also be stored in folders, but will not be accessible by the device unless you name the folder appropriately. This is handy when you want to cycle images on a particular device, like floppy disks or CDs.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware two different ways.

==== Using the SD card ====
The ZuluSCSI can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluSCSI is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluSCSI.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluSCSI.
# Power the system back on. The ZuluSCSI will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluSCSI and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluSCSI so it can become ready.
# When the firmware update process finishes, the ZuluSCSI will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB or USB-C port into a host computer, this is the traditional way to update RP2040 and RP2350B-based devices.

# Power down the system the ZuluSCSI is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluSCSI, attach the other end of the cable to the MicroUSB port on the ZuluSCSI. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluSCSI.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluSCSI to its host, if you removed it in step 1.

== Troubleshooting [[File:Warning.png|frameless|32x32px]] ==
Some simple things to check before you dive deeper:

* Make sure that there are no devices contending for the same ID number on the bus. Typically, the host device on a system is identified as ID 7, so avoid using ID 7 where possible.

ZuluSCSI Operations Guide

2025-04-16T02:17:18Z

Mbalmer:

ZuluSCSI Operations Guide

2025-04-16T01:51:18Z

Mbalmer:

File:Info.png

2025-04-16T01:04:53Z

Mbalmer:

info

ZuluSCSI Operations Guide

2025-04-16T00:05:43Z

Mbalmer: Updating documentation for ZSCSI Blaster

= This page is still a work in progress. Sections marked with a [[File:Warning.png|frameless|32x32px]] icon are still in the process of being written. =

== Setting Up Your ZuluSCSI ==

=== Unboxing ===
When you first receive your ZuluSCSI, depending on the options you ordered, you should receive the following:

* ZuluSCSI RP2040 Compact, ZuluSCSI Blaster, or ZuluSCSI 1.2 board
* Plastic board carrier
* 2x ¼" 4-40 screws
* microSD card or full-size SD card
* DAC board (ZuluSCSI Blaster only)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below, based on the type of board you have.
{| class="wikitable"
|+
!ZuluSCSI RP2040 Compact
!ZuluSCSI Blaster RP2350B
!ZuluSCSI 1.2
|-
|[[File:ZSCSI compact labeled.png|frameless]]
|[[File:ZSCSI Blaster labeled.png|frameless]]
|[[File:ZSCSI1.2 Labeled.png|frameless]]
|}
* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive; see below).
* '''50-pin male IDC connector:''' Plug your SCSI bus cable into this. The connector is keyed, but some SCSI cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''BOOTLDR button:''' Used in the firmware flashing process; see below.
* '''USER button:''' Reserved for future use.
* '''Termination and Initiator jumpers (Compact only):''' Populate these footprints with standard 0.1" header, solder them down, and then use a standard jumper cap to switch on the ZuluSCSI Compact's termination capabilities or enable initiator mode.
* '''DIP Switch Block (ZuluSCSI Blaster only):''' Used to enable initiator mode, termination, or debug mode.
* '''I2S Accessory Header (ZuluSCSI Blaster only):''' If you purchased the optional I2S DAC for CD audio capability, insert it here.
* '''Device type selector switch (ZuluSCSI 1.2 only):''' Use this rotary switch to select the type of device the ZuluSCSI is meant to emulate here. This switch is only active when switch 2 on the Settings DIP switch block is set to '''off.'''
* '''SCSI ID Dip Switch (ZuluSCSI 1.2 only):''' Use this set of switches to set the device's SCSI ID.
* '''Device Settings Switch block (ZuluSCSI 1.2 only):''' Use these switches to control termination, debug mode, "quirks" mode (for some Macintosh devices) and whether the entirety of the SD card is exposed as a single block device, or whether the device reads the SD card for image files and emulates multiple devices dependent on filename (as with other ZuluSCSI devices).

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==

=== ZuluSCSI Blaster or ZuluSCSI RP2040 Compact ===
* '''Switch 1:''' Turn Initiator mode on or off.
** On the RP2040 Compact, this is controlled by the jumper at <code>J310</code> on the board in the lower right.
* '''Switch 2:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the port on the device with this switch on, it will also print the debug log over the cable via the microcontroller's internal serial connection.
** On the RP2040 Compact, this is controlled by setting <code>Debug = 1</code> in the <code>zuluscsi.ini</code> file on the SD card itself.
* '''Switch 3:''' Enable or disable SCSI termination as needed.
** On the RP2040 Compact, this is controlled by the jumper at <code>J311</code> in the center of the board.

=== ZuluSCSI 1.2 ===
If you have a ZuluSCSI 1.2, the block of '''four''' DIP switches at <code>SW301</code> control various aspects of how the device responds in the system:

* '''Switch 1:''' Toggle Macintosh "Quirks" mode. On some legacy Macs, it helps if the device responds with specific things when the system calls upon it during a fresh installation. If your Mac responds erratically or doesn't behave properly with the device in the system, try turning this switch ON before anything else.
* '''Switch 2:''' Direct/Raw mode vs. standard mode. If this switch is left in its default OFF position, then the entire SD card is exposed to the system as a single block device and allows your SCSI interface card to manage it, based on the settings of <code>SW403</code> and <code>SW404</code>.
** The block of '''three''' DIP switches at <code>SW403</code> are used for setting your SCSI ID. If all three switches are off, the board's SCSI ID is 0. Turn switch 1 on to add 1 to the device ID, switch 2 to add 2, and switch 3 to add 4. If all three are on, the SCSI ID is 7.
** The rotary switch at <code>SW404</code> controls how the ZuluSCSI responds to your SCSI interface card when it queries it. Each position on the switch causes it to respond as a different device and will register differently:
*** Position 0 (straight up): Hard disk
*** Position 1: Optical drive
*** Position 2: Floppy disk
*** Position 3: Other generic removable block device (ZIP drives, Jaz drives, etc.)
*** Position 4: Magneto-optical disk drives
*** Position 5: Seagate ST32430N Hawk HDD
*** Position 6: Tape drives
*** Positions 7, 8, 9: Reserved

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not being detected
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.

If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use images larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB.

Load your images onto the card into the root folder. Images stored in folders, unless they are <code>BIN/CUE</code> images, will be ignored.

For <code>BIN/CUE</code> files, they can be placed into a folder with the same name as the image file; i.e., if you have a <code>BIN/CUE</code> pair named <code>bigdiscofstuff.bin</code> and <code>bigdiscofstuff.cue</code> you should place them in a directory named <code>bigdiscofstuff</code>. This is '''required''' if your <code>BIN/CUE</code> image has a single <code>CUE</code> file and multiple <code>BIN</code> files.

=== Drive Types ===
When configuring the ZuluSCSI, you can set it to be multiple different drive types based on the images you intend to use. Out of the box, the ZuluSCSI configures itself as an optical drive, but through the [[ZuluSCSI INI Configuration|INI file]] or by using '''filename prefixes,''' you can tell the ZuluSCSI which device you want it to behave as when you power it on.

==== Using the INI File ====
Under the <code>[IDE]</code> heading, use the <code>Device=</code> value to set the drive type:0

* <code>CDROM</code> (default) will cause the ZuluSCSI to respond as an optical drive.
* <code>Zip100</code> will cause the ZuluSCSI to respond as an ATAPI-attached 100MB Zip Drive
* <code>Zip250</code> will cause the ZuluSCSI to respond as an ATAPI-attached 250MB Zip Drive
* <code>Removable</code> will cause the ZuluSCSI to respond as a generic removable media device
* <code>HDD</code> will cause the ZuluSCSI to respond as a standard hard disk drive

If this section is absent, or the <code>zuluide.ini</code> file is not present on the SD card, the device will default to behaving as an optical drive.

==== Using a filename prefix ====
Add the following to the beginning of your filename to switch the ZuluSCSI's device mode:

* <code>cdrm</code> will cause the ZuluSCSI to load the image as an optical drive image.
* <code>zipd</code> will cause the ZuluSCSI to load the image as a 100MB or 250MB Zip disk.
* <code>remv</code> will cause the ZuluSCSI to load the image as a generic removable media device.
* <code>hddr</code> will cause the ZuluSCSI to load the image as a non-removable hard disk image.

The <code>Device=</code> option in the INI file will override this behavior. Additionally, if a filename prefix is specified, all other files that you want to use '''must have the same prefix.'''

==== Filename extensions ====
In optical drive mode, the device will only recognize images that end in <code>.iso</code> or <code>.bin/.cue</code>, while also recognizing folders for purposes of reading multipart <code>.bin/.cue</code> images.

For Zip drives or other removable media,ᚸso long as the filename doesn't contain one of the prefixes above, doesn't have an optical drive image extension (<code>.iso/.bin/.cue</code>), or one of the extensions on the ignored list below, it will load the file as a disk image and attempt to mount it.

If the ZuluSCSI starts up as an optical drive, it will use the first image it finds on the SD card as an optical disc.

==== Changing disk images ====
Without the hardware interface or web interface, changing disk images is done by pressing the eject button on the device itself or by performing a hardware eject directly through the operating system. The firmware will cycle to the next available image on the SD card in alphabetical order.

==== Ignore list ====
Files with any of the following extensions will be ignored by the ZuluSCSI and will not appear in the list of available images on the hardware or web interfaces, and will not be selected when a hardware eject is performed:

*<code>.cue</code> <code>.txt</code><code>.rtf</code><code>.md</code><code>.nfo</code><code>.pdf</code><code>.doc</code>

Compressed archive file formats:

* <code>.zip .7z .dmg .rar .tar .tgz .gz .bz2 .tbz2 .xz .zst .lzh .lha .lzo .lz4 .arj .hqx .cpt .s7z</code>

Additionally, any file that begins with <code>zulu</code> will be ignored.

==== USB Mass Storage ====
You can use the ZuluSCSI as a passthrough to access the SD card directly by putting the option <code>enable_usb_mass_storage=1</code> in the <code>[IDE]</code> section of the [[ZuluSCSI INI Configuration|INI file]]. In order to use this mode, the ZuluSCSI must not currently be operating as an attached device through the IDE port on a host computer.

==== Hotplugging ====
The ZuluSCSI supports removal and re-insertion of the SD card while the device is on and functioning. Until the device detects that a card has been inserted, you'll see the activity LED blink 5 times rapidly, pause, and then repeat until a card is reinserted. Once the card has been detected, the LED will blink once, turn off, and return to normal indication of disk access.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware two different ways.

==== Using the SD card ====
The ZuluSCSI can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluSCSI is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluSCSI.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluSCSI.
# Power the system back on. The ZuluSCSI will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluSCSI and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluSCSI so it can become ready.
# When the firmware update process finishes, the ZuluSCSI will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB port into a host computer, this is the traditional way to update RP2040-based devices like the ZuluSCSI.

# Power down the system the ZuluSCSI is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluSCSI, attach the other end of the cable to the MicroUSB port on the ZuluSCSI. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluSCSI.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluSCSI to its host, if you removed it in step 1.

== Troubleshooting ==
Some simple things to check before you dive deeper:

* Make sure there are no primary/secondary conflicts on the IDE channel that the ZuluSCSI is attached to.
* Make sure that the power connection to the device is secure and attached.
* Try toggling the Cable Select switch. Some BIOSes prefer the device to be one way or the other and there's often little rhyme or reason between even the exact same BIOS on the exact same build across two machines.

For more specific problems, keep reading.

The icon at the left of the problems listed tends to pertain to that particular operating system.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The ZuluSCSI doesn't seem to be recognized under MS-DOS. ===
If you have the ZuluSCSI attached as an optical drive in a system that doesn't natively support the ATAPI protocol, you may have to install a third-party driver to allow DOS to see the drive. This was common for all systems based on 386 processors and earlier, most 486 systems, and some Pentium-based systems.

The simplest solution is to obtain a copy of the Microsoft Windows 98 startup disk, and copy the <code>OAKCDROM.SYS</code> and <code>MSCDEX.EXE</code> files from it to the root folder of your boot drive. Then, modify your <code>CONFIG.SYS</code> and <code>AUTOEXEC.BAT</code> files like this:

==== CONFIG.SYS ====
Add this line to the top of the file:

<code>DEVICE=C:\OAKCDROM.SYS /D:MSCD000</code>

==== AUTOEXEC.BAT ====
Add this line to the end of the file:

<code>C:\MSCDEX.EXE /D:MSCD000</code>

Reboot the system, and the drive should populate.

Keep in mind that the only DOS-based CD-ROM driver that has been tested to work with the ZuluSCSI at present is the Oak Technology driver (<code>OAKCDROM.SYS</code>) and <code>VIDE-CDD.SYS</code>, the driver that is included on the Microsoft CD-ROM Extensions installation floppy disk.

Other generic drivers, such as the LG (GoldStar) or Adaptec drivers may work, but have not been fully tested.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The system recognizes the first disc image loaded, but then acts like the drive isn't ready when I change images. ===
This issue is related to firmware revisions prior to 2024.11.08. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluSCSI-firmware Github repo].

If you are unable to update the firmware, there is a workaround that you can use until you are able to do so.

After changing images, try to access the drive. The system will pause for a long moment, and then you should see a message similar to this:

<code>CDR101: Not ready reading drive E: 
(A)bort, (R)etry, (F)ail?</code>

Press F to fail the check, and then if it drops back to a command prompt, try to access the drive again and it should present the image as normal.

=== [[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (as optical drive): Performing an "eject" command in Windows Explorer doesn't actually cycle to the next image. ===
This issue is related to firmware revisions prior to 2024.12.10. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluSCSI-firmware Github repo].

The workaround for this is to have either the web interface or hardware interface connected and swap images that way. Another workaround is to manually eject the SD card from the ZuluSCSI, add a zero to the beginning of the desired disk image's name, and then reinsert the SD card. The ZuluSCSI will then look for the first image it can load alphabetically, which should be the newly-renamed image.

=== [[File:Msdos-icon.png|frameless|34x34px]](attached to sound card): The ZuluSCSI seems to be working correctly, but it's never detected. ===
This is a potential hardware configuration issue. Some sound cards, even if they have an actual IDE interface, force themselves to be configured as either the primary or secondary interface in the system and are not configurable. Most sound cards are also capable of recognizing ''only'' optical devices, so if you have the ZuluSCSI configured as something other than an optical drive, the card may not recognize the device attached to it. If you want to use the ZuluSCSI as something other than an optical drive, attach it to an IDE port attached to the motherboard or I/O card, as opposed to a sound card.

=== [[File:Msdos-icon.png|frameless|34x34px]][[File:Win31.png|32x32px]][[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (with audio DAC board): I have the device attached to my SoundBlaster's CD audio in connector, but I only hear the right channel. ===
Early SoundBlaster cards (including the Pro and Pro 2) used a different pinout on the CD audio header. Instead of R-G-G-L (right channel, ground, ground, left channel) these cards' pinout was NC-L-G-R (no connect, left, ground, right). You may need to get a different cable.

File:Warning.png

2025-04-16T00:04:23Z

Mbalmer:

warning

File:ZSCSI1.2 Labeled.png

2025-04-15T22:41:10Z

Mbalmer:

ZSCSI1.2 Labeled

File:ZSCSI Blaster labeled.png

2025-04-15T22:40:34Z

Mbalmer:

ZSCSI Blaster labeled

File:ZSCSI compact labeled.png

2025-04-15T22:39:38Z

Mbalmer:

ZSCSI compact labeled

Web Interface Instructions

2025-03-18T19:30:30Z

Mbalmer: /* Configuration and Firmware */ Added note about enclosing wifi password in quotes

The ZuluIDE's Audio and Pi Pico Shield (available as an add-on at time of purchase or separately [https://shop.rabbitholecomputing.com/products/zuluide-cd-audio-dac-upgrade-kit-for-existing-zuluide-owners here]) adds several capabilities to the ZuluIDE. In addition to Redbook CD audio playback, however, it also allows you to add a Raspberry Pi Pico W to the board to enable a control interface via HTTP, allowing you to swap disc images in and out on systems that don't natively support operating-system level eject and close operations like MacOS does.

=== Preparation and Setup ===
When you receive your ZuluIDE and the shield, it will come populated with all of the parts necessary for the '''audio-only''' side of the board needed to function. You will need to add the Pi Pico W to the board. '''Remove the shield from the ZuluIDE first, and then follow the steps below.'''

You'll need the following items:
{| class="wikitable" style="text-align: center;"
|[[File:Pico-w-noheaders.png|frameless|150x150px]]
|Raspberry Pi Pico W or Pico 2 W
'''(with or without headers)'''
|-
|[[File:Header strip.png|frameless|150x150px]]
|Male 40-pin header strip
(optional)
|-
|[[File:Female header (20-pin).jpg|frameless|150x150px]]
|2x Female 20-pin header strips
(also optional)
|}
The headers aren't strictly necessary, but if you want to be able to easily remove or replace the Pico later, you'll want them.

=== Attaching the Pico W to the Shield Board ===

===== STEP 1 =====
If you're using the headers, solder them down in the footprint provided for the Pico W. If not, skip to '''step 4.'''
[[File:Audio shield board step 1.png|center|frameless|500x500px]]

===== STEP 2 =====
Cut the headers into two 20-pin lengths, and solder them to the holes on your Pico W. If your Pico W came with headers pre-installed, you can skip this step.

===== STEP 3 =====
Insert the Pico W into the header sockets. You're done!

===== STEP 4 =====
[[File:Castellated holes.png|thumb|300x300px|Castellated (or half) holes]]
If you '''are not''' going to use headers and simply want to attach your Pico W directly to the board, you can. Place the Pico W down on the footprint provided with the USB port facing upward. To help you align the pins, you can use a cut length of header pins placed through one row of holes on the Pico W and the shield board, and solder down the opposite side. Solder directly to the castellated holes on one side (the half-holes along the edge of the board), pull your aligning header strip out of the other side of the board, and solder the other side.

=== Configuration and Firmware ===
Next, take the SD card out of your ZuluIDE. If it doesn't already have it, create a file named <code>zuluide.ini</code> in the root directory of the card with a text editor. Create a section in the file as follows:

[UI]
wifissid=YOUR_WIFI_NETWORK_NAME
wifipassword=YOUR_WIFI_PASSWORD
[[File:Firmware-update.png|thumb|300x300px|Updating the firmware on the Pi Pico]]
One more note: If your WiFi password contains special characters such as certain punctuation, extended character set characters, or the like, enclose your password in quotes, like this:

<code>wifipassword="§E©RET_∏A§§WORĐ!"</code>

You'll also need to flash the firmware on the Pi Pico to enable the HTTP host. To do this, download the latest release of the firmware from the [https://github.com/ZuluIDE/ZuluIDE-HTTP-PicoW/releases HTTP controller Github]. Press and hold the <code>BOOTSEL</code> button on the Pico W, and then, using a micro-USB cable, attach it to the computer where you downloaded the <code>.uf2</code> firmware file. The Pi Pico will appear as a drive on your system named <code>RPI-RP2</code> and you can simply drag the firmware file you downloaded directly to the drive. When the copy completes, the Pi Pico will dismount itself from the computer and reboot. You can then disconnect the Pi Pico from your computer and reinsert the Pi Pico shield into the sockets on your ZuluIDE.

===Powering Up===
When you reattach the ZuluIDE to the system and turn it on, you'll notice that the light on the Pico W will eventually light stay on. This is good -- the Pico W has connected successfully to your network! But...where is it? There's a couple of ways to find out.

==== Check the Log File ====
With the shield attached and SD card reinserted, power on the ZuluIDE, either by itself by simply attaching a USB cable directly to it or by turning on the host system. When the green light on the Pi Pico comes on and stays lit, it has successfully connected to your network. Give the ZuluIDE roughly 10-15 seconds after the light on the Pi Pico comes on, and then remove the SD card and connect it directly to your computer. Open the <code>zuluide.log</code> file and look for a line (usually at the very end of the log) that looks like this:

[10991ms] Client IP address is: 10.0.0.196

This tells you the IP address that the Pi Pico was able to fetch via DHCP, and is the address you can put into your browser to control the ZuluIDE.

==== Look At Your Router ====
If you have the ability to configure it, looking at the configuration on your WiFi router is one way of determining what the address of the Pico W is. Usually, it will try to call itself "PicoW" as its hostname. You can try using an HTTP address of something like <code>picow.local</code> but if your router doesn't handle hostname translation very well (as many home routers don't) you may have to fall back to another method of determining the interface's IP address.

==== Scan For Its Address ====
Another way to find out the address of the Pico W is to use a free utility called ''Advanced IP Scanner'' to scan your local network to try and see what IPs are attached. Advanced IP Scanner can be downloaded [https://www.majorgeeks.com/files/details/advanced_ip_scanner.html here]. This way works well if you are connected to the same WiFi network as the ZuluIDE and don't have an easy way to read the log file off the SD card itself.

To use Advanced IP Scanner, enter the range of IPs your router assigns (common candidates for home routers are <code>192.168.0.1-255</code> and <code>10.0.0.1-255</code>) into the text box at the top of the window and then press the "Scan" button. The program will go through and try to determine what devices are attached to the same network you are. In the list, look for a device named "PicoW" -- if the computer icon in the left column is blue, it's connected. Record the IP address you got, and that's the IP address you'll use to configure the ZuluIDE.

=== Using the HTTP Interface ===
[[File:HTTP control interface 1.png|thumb]]
When you bring up the web interface, you'll see only a few controls. The interface shows the image you currently have loaded on the device, a button to eject the image, a button to swap disk images, and a line showing what device the ZuluIDE has registered itself as.

Under the line is a manual refresh button that will cause the Pi Pico to manually refresh the information about the loaded disk image and device type as well as an automatic refresh option that will force a refresh any time the web interface renders a page.

The [[File:Imagebutton.png|frameless]] button will take you to another page where you can select a new disk image. It will appear blank at first, but it will populate itself. Click the desired image in the list and then hit the <code>LOAD</code> button, and it will take you back to the page shown at the right with the information changed to reflect the image you've selected.

Pressing the Eject button will simply dismount the image.

==== ISO Images Versus BIN/CUE Images ====
Most disk images will appear in the full list with their file extension shown. Entries that appear '''without''' a filename extension are directories where BIN/CUE image files reside; to use these, just select the entry in the list and all of the appropriate files will load.

Web Interface Instructions

2025-01-26T01:36:39Z

Mbalmer: New page: How to use the HTTP control interface. (+1,178 words, 3 images)

The ZuluIDE's Audio and Pi Pico Shield (available as an add-on at time of purchase or separately [https://shop.rabbitholecomputing.com/products/zuluide-cd-audio-dac-upgrade-kit-for-existing-zuluide-owners here]) adds several capabilities to the ZuluIDE. In addition to Redbook CD audio playback, however, it also allows you to add a Raspberry Pi Pico W to the board to enable a control interface via HTTP, allowing you to swap disc images in and out on systems that don't natively support operating-system level eject and close operations like MacOS does.

=== Preparation and Setup ===
When you receive your ZuluIDE and the shield, it will come populated with all of the parts necessary for the '''audio-only''' side of the board needed to function. You will need to add the Pi Pico W to the board. '''Remove the shield from the ZuluIDE first, and then follow the steps below.'''

You'll need the following items:
{| class="wikitable" style="text-align: center;"
|[[File:Pico-w-noheaders.png|frameless|150x150px]]
|Raspberry Pi Pico W or Pico 2 W
'''(with or without headers)'''
|-
|[[File:Header strip.png|frameless|150x150px]]
|Male 40-pin header strip
(optional)
|-
|[[File:Female header (20-pin).jpg|frameless|150x150px]]
|2x Female 20-pin header strips
(also optional)
|}
The headers aren't strictly necessary, but if you want to be able to easily remove or replace the Pico later, you'll want them.

=== Attaching the Pico W to the Shield Board ===

===== STEP 1 =====
If you're using the headers, solder them down in the footprint provided for the Pico W. If not, skip to '''step 4.'''
[[File:Audio shield board step 1.png|center|frameless|500x500px]]

===== STEP 2 =====
Cut the headers into two 20-pin lengths, and solder them to the holes on your Pico W. If your Pico W came with headers pre-installed, you can skip this step.

===== STEP 3 =====
Insert the Pico W into the header sockets. You're done!

===== STEP 4 =====
[[File:Castellated holes.png|thumb|300x300px|Castellated (or half) holes]]
If you '''are not''' going to use headers and simply want to attach your Pico W directly to the board, you can. Place the Pico W down on the footprint provided with the USB port facing upward. To help you align the pins, you can use a cut length of header pins placed through one row of holes on the Pico W and the shield board, and solder down the opposite side. Solder directly to the castellated holes on one side (the half-holes along the edge of the board), pull your aligning header strip out of the other side of the board, and solder the other side.

=== Configuration and Firmware ===
Next, take the SD card out of your ZuluIDE. If it doesn't already have it, create a file named <code>zuluide.ini</code> in the root directory of the card with a text editor. Create a section in the file as follows:

[UI]
wifissid=YOUR_WIFI_NETWORK_NAME
wifipassword=YOUR_WIFI_PASSWORD
[[File:Firmware-update.png|thumb|300x300px|Updating the firmware on the Pi Pico]]
You'll also need to flash the firmware on the Pi Pico to enable the HTTP host. To do this, download the latest release of the firmware from the [https://github.com/ZuluIDE/ZuluIDE-HTTP-PicoW/releases HTTP controller Github]. Press and hold the <code>BOOTSEL</code> button on the Pico W, and then, using a micro-USB cable, attach it to the computer where you downloaded the <code>.uf2</code> firmware file. The Pi Pico will appear as a drive on your system named <code>RPI-RP2</code> and you can simply drag the firmware file you downloaded directly to the drive. When the copy completes, the Pi Pico will dismount itself from the computer and reboot. You can then disconnect the Pi Pico from your computer and reinsert the Pi Pico shield into the sockets on your ZuluIDE.

===Powering Up===
When you reattach the ZuluIDE to the system and turn it on, you'll notice that the light on the Pico W will eventually light stay on. This is good -- the Pico W has connected successfully to your network! But...where is it? There's a couple of ways to find out.

==== Check the Log File ====
With the shield attached and SD card reinserted, power on the ZuluIDE, either by itself by simply attaching a USB cable directly to it or by turning on the host system. When the green light on the Pi Pico comes on and stays lit, it has successfully connected to your network. Give the ZuluIDE roughly 10-15 seconds after the light on the Pi Pico comes on, and then remove the SD card and connect it directly to your computer. Open the <code>zuluide.log</code> file and look for a line (usually at the very end of the log) that looks like this:

[10991ms] Client IP address is: 10.0.0.196

This tells you the IP address that the Pi Pico was able to fetch via DHCP, and is the address you can put into your browser to control the ZuluIDE.

==== Look At Your Router ====
If you have the ability to configure it, looking at the configuration on your WiFi router is one way of determining what the address of the Pico W is. Usually, it will try to call itself "PicoW" as its hostname. You can try using an HTTP address of something like <code>picow.local</code> but if your router doesn't handle hostname translation very well (as many home routers don't) you may have to fall back to another method of determining the interface's IP address.

==== Scan For Its Address ====
Another way to find out the address of the Pico W is to use a free utility called ''Advanced IP Scanner'' to scan your local network to try and see what IPs are attached. Advanced IP Scanner can be downloaded [https://www.majorgeeks.com/files/details/advanced_ip_scanner.html here]. This way works well if you are connected to the same WiFi network as the ZuluIDE and don't have an easy way to read the log file off the SD card itself.

To use Advanced IP Scanner, enter the range of IPs your router assigns (common candidates for home routers are <code>192.168.0.1-255</code> and <code>10.0.0.1-255</code>) into the text box at the top of the window and then press the "Scan" button. The program will go through and try to determine what devices are attached to the same network you are. In the list, look for a device named "PicoW" -- if the computer icon in the left column is blue, it's connected. Record the IP address you got, and that's the IP address you'll use to configure the ZuluIDE.

=== Using the HTTP Interface ===
[[File:HTTP control interface 1.png|thumb]]
When you bring up the web interface, you'll see only a few controls. The interface shows the image you currently have loaded on the device, a button to eject the image, a button to swap disk images, and a line showing what device the ZuluIDE has registered itself as.

Under the line is a manual refresh button that will cause the Pi Pico to manually refresh the information about the loaded disk image and device type as well as an automatic refresh option that will force a refresh any time the web interface renders a page.

The [[File:Imagebutton.png|frameless]] button will take you to another page where you can select a new disk image. It will appear blank at first, but it will populate itself. Click the desired image in the list and then hit the <code>LOAD</code> button, and it will take you back to the page shown at the right with the information changed to reflect the image you've selected.

Pressing the Eject button will simply dismount the image.

==== ISO Images Versus BIN/CUE Images ====
Most disk images will appear in the full list with their file extension shown. Entries that appear '''without''' a filename extension are directories where BIN/CUE image files reside; to use these, just select the entry in the list and all of the appropriate files will load.

File:Imagebutton.png

2025-01-26T01:20:30Z

Mbalmer:

Imagebutton

File:HTTP control interface 1.png

2025-01-26T01:15:09Z

Mbalmer:

HTTP control interface 1

File:Castellated holes.png

2025-01-25T22:43:02Z

Mbalmer:

Castellated holes

File:Audio shield board step 1.png

2025-01-25T22:28:35Z

Mbalmer:

Step 1

File:Female header (20-pin).jpg

2025-01-25T22:04:37Z

Mbalmer:

Female header (20-pin)

File:Header strip.png

2025-01-25T21:58:08Z

Mbalmer:

Header strip

File:Pico-w-noheaders.png

2025-01-25T21:52:50Z

Mbalmer:

Pi Pico W, no headers.

Main Page

2025-01-25T21:40:56Z

Mbalmer: Add link to instructions on using the web interface

== Rabbit Hole Computing Wiki ==
This is the primary documentation repository for all of [https://www.rabbitholecomputing.com Rabbit Hole Computing's] products, including the '''ZuluSCSI, ZuluIDE,''' and '''QuokkADB,''' among others.
{| class="wikitable" style="margin: auto;"
![[File:ZuluSCSI RP2040 rev 2023a.jpg|200x200px]]
![[File:ZuluIDE RP2040 Compact Rev2024a.png|200x200px]]
![[File:QuokkADB.jpg|200x200px]]
|-
!ZuluSCSI
!ZuluIDE
!QuokkADB
|-
| colspan="2" style="text-align: center;" |[[Buyer's Guide]]
|
|-
| colspan="2" style="text-align: center;" |[[Quick Start Guide]]
|
|-
| colspan="2" style="text-align: center;" |[[Basic Usage]]
|
|-
|[[ZuluSCSI v1.2]]
|[[Web Interface Instructions]]
|
|-
|[[ZuluSCSI Operations Guide]]
|[[ZuluIDE Operations Guide]]
|
|-
|[[ZuluSCSI INI Configuration]]
|[[ZuluIDE INI Configuration]]
|
|}

ZuluSCSI Operations Guide

2025-01-06T16:07:43Z

Mbalmer: /* Setting Up Your ZuluSCSI */

= This page has been copied from the ZuluIDE operations guide; it is currently being edited to match the ZuluSCSI. =

== Setting Up Your ZuluSCSI ==

--- copied from IDE page; WIP! ---

=== Unboxing ===
When you first receive your ZuluSCSI, depending on the options you ordered, you should receive the following:

* ZuluSCSI RP2040 Compact board
* 3D-printed plastic carrier
* 2x ¼" 4-40 screws
* microSD card
* Hardware interface board (optional)
* Qwiic cable (included with hardware interface board)
* DAC board with mounted Raspberry Pi Pico W (optional)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below.
[[File:ZuluSCSI RP2040 Compact (labeled).png|center|frameless|800x800px]]

* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive).
* '''40-pin male IDC connector:''' Plug your IDE bus cable into this. The connector is keyed, but some IDE cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Configuration DIP switches:''' These will set how the ZuluSCSI responds when the BIOS requests information from the device.
* '''Bootloader button:''' Used during the firmware update process.
* '''I2C Footprint:''' Addon boards can attach through this open footprint either by being soldered directly to it or by attaching standard 0.1" header to this footprint.
* '''Qwiic Port:''' Addon boards can also attach here through the use of a standard Qwiic I2C cable.
* '''MicroUSB Port:''' Used during the firmware update process. Can also be used as a serial monitor to capture debug logs in real time with a second PC.
* '''microSD Card Slot:''' Your SD card with images goes here.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''External eject and LED headers:''' If you intend to mount the device internally, but want external access to these, you can use standard 0.1" headers to run an eject button and an LED to a case panel. The red box on the image above indicates the positive pin.

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==
[[File:DIP switches (ZuluSCSI).png|center|frameless]]
Set the three DIP switches according to how the device needs to be configured in the host system.

* '''Switch 1:''' Turn IDE Cable Select on or off. ''Most'' systems will work fine with this off, but there are several systems (especially single-board industrial computers) which will use cable-select to determine primary and secondary drives and thus will need it on. If your system hangs during IDE device detection with the ZuluSCSI attached to the bus, try turning this switch ON first.
* '''Switch 2:''' Respond as Primary/Master (OFF) or Secondary/Slave (ON).
* '''Switch 3:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the MicroUSB port on the device with this switch on, it will also print the debug log over the cable via the RP2040's internal serial connection.

== Qwiic Port and External Hardware Interface ==
The external hardware interface (optional) can be connected to this port. The interface provides a Gotek-like system to navigate disc images stored on the SD card and to cycle through them.
{| class="wikitable" style="margin: auto;"
|+
![[File:Hardware interface (rev 2024a).png|frameless|379x379px]]
![[File:Qwiic cable.png|frameless|338x338px]]
|}
The rotary encoder knob on the hardware interface functions exactly like a Gotek device — spin the knob to change images or menu selections, press the knob to select. The Eject button works exactly like the eject button on the main board, although with the hardware interface attached, it will ask you to confirm the eject by pressing the rotary knob. The User button is currently reserved for future use.

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not being detected
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.

If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use images larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB.

Load your images onto the card into the root folder. Images stored in folders, unless they are <code>BIN/CUE</code> images, will be ignored.

For <code>BIN/CUE</code> files, they can be placed into a folder with the same name as the image file; i.e., if you have a <code>BIN/CUE</code> pair named <code>bigdiscofstuff.bin</code> and <code>bigdiscofstuff.cue</code> you should place them in a directory named <code>bigdiscofstuff</code>. This is '''required''' if your <code>BIN/CUE</code> image has a single <code>CUE</code> file and multiple <code>BIN</code> files.

=== Drive Types ===
When configuring the ZuluSCSI, you can set it to be multiple different drive types based on the images you intend to use. Out of the box, the ZuluSCSI configures itself as an optical drive, but through the [[ZuluSCSI INI Configuration|INI file]] or by using '''filename prefixes,''' you can tell the ZuluSCSI which device you want it to behave as when you power it on.

==== Using the INI File ====
Under the <code>[IDE]</code> heading, use the <code>Device=</code> value to set the drive type:0

* <code>CDROM</code> (default) will cause the ZuluSCSI to respond as an optical drive.
* <code>Zip100</code> will cause the ZuluSCSI to respond as an ATAPI-attached 100MB Zip Drive
* <code>Zip250</code> will cause the ZuluSCSI to respond as an ATAPI-attached 250MB Zip Drive
* <code>Removable</code> will cause the ZuluSCSI to respond as a generic removable media device
* <code>HDD</code> will cause the ZuluSCSI to respond as a standard hard disk drive

If this section is absent, or the <code>zuluide.ini</code> file is not present on the SD card, the device will default to behaving as an optical drive.

==== Using a filename prefix ====
Add the following to the beginning of your filename to switch the ZuluSCSI's device mode:

* <code>cdrm</code> will cause the ZuluSCSI to load the image as an optical drive image.
* <code>zipd</code> will cause the ZuluSCSI to load the image as a 100MB or 250MB Zip disk.
* <code>remv</code> will cause the ZuluSCSI to load the image as a generic removable media device.
* <code>hddr</code> will cause the ZuluSCSI to load the image as a non-removable hard disk image.

The <code>Device=</code> option in the INI file will override this behavior. Additionally, if a filename prefix is specified, all other files that you want to use '''must have the same prefix.'''

==== Filename extensions ====
In optical drive mode, the device will only recognize images that end in <code>.iso</code> or <code>.bin/.cue</code>, while also recognizing folders for purposes of reading multipart <code>.bin/.cue</code> images.

For Zip drives or other removable media,ᚸso long as the filename doesn't contain one of the prefixes above, doesn't have an optical drive image extension (<code>.iso/.bin/.cue</code>), or one of the extensions on the ignored list below, it will load the file as a disk image and attempt to mount it.

If the ZuluSCSI starts up as an optical drive, it will use the first image it finds on the SD card as an optical disc.

==== Changing disk images ====
Without the hardware interface or web interface, changing disk images is done by pressing the eject button on the device itself or by performing a hardware eject directly through the operating system. The firmware will cycle to the next available image on the SD card in alphabetical order.

==== Ignore list ====
Files with any of the following extensions will be ignored by the ZuluSCSI and will not appear in the list of available images on the hardware or web interfaces, and will not be selected when a hardware eject is performed:

*<code>.cue</code> <code>.txt</code><code>.rtf</code><code>.md</code><code>.nfo</code><code>.pdf</code><code>.doc</code>

Compressed archive file formats:

* <code>.zip .7z .dmg .rar .tar .tgz .gz .bz2 .tbz2 .xz .zst .lzh .lha .lzo .lz4 .arj .hqx .cpt .s7z</code>

Additionally, any file that begins with <code>zulu</code> will be ignored.

==== USB Mass Storage ====
You can use the ZuluSCSI as a passthrough to access the SD card directly by putting the option <code>enable_usb_mass_storage=1</code> in the <code>[IDE]</code> section of the [[ZuluSCSI INI Configuration|INI file]]. In order to use this mode, the ZuluSCSI must not currently be operating as an attached device through the IDE port on a host computer.

==== Hotplugging ====
The ZuluSCSI supports removal and re-insertion of the SD card while the device is on and functioning. Until the device detects that a card has been inserted, you'll see the activity LED blink 5 times rapidly, pause, and then repeat until a card is reinserted. Once the card has been detected, the LED will blink once, turn off, and return to normal indication of disk access.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware two different ways.

==== Using the SD card ====
The ZuluSCSI can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluSCSI is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluSCSI.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluSCSI.
# Power the system back on. The ZuluSCSI will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluSCSI and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluSCSI so it can become ready.
# When the firmware update process finishes, the ZuluSCSI will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB port into a host computer, this is the traditional way to update RP2040-based devices like the ZuluSCSI.

# Power down the system the ZuluSCSI is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluSCSI, attach the other end of the cable to the MicroUSB port on the ZuluSCSI. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluSCSI.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluSCSI to its host, if you removed it in step 1.

== Troubleshooting ==
Some simple things to check before you dive deeper:

* Make sure there are no primary/secondary conflicts on the IDE channel that the ZuluSCSI is attached to.
* Make sure that the power connection to the device is secure and attached.
* Try toggling the Cable Select switch. Some BIOSes prefer the device to be one way or the other and there's often little rhyme or reason between even the exact same BIOS on the exact same build across two machines.

For more specific problems, keep reading.

The icon at the left of the problems listed tends to pertain to that particular operating system.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The ZuluSCSI doesn't seem to be recognized under MS-DOS. ===
If you have the ZuluSCSI attached as an optical drive in a system that doesn't natively support the ATAPI protocol, you may have to install a third-party driver to allow DOS to see the drive. This was common for all systems based on 386 processors and earlier, most 486 systems, and some Pentium-based systems.

The simplest solution is to obtain a copy of the Microsoft Windows 98 startup disk, and copy the <code>OAKCDROM.SYS</code> and <code>MSCDEX.EXE</code> files from it to the root folder of your boot drive. Then, modify your <code>CONFIG.SYS</code> and <code>AUTOEXEC.BAT</code> files like this:

==== CONFIG.SYS ====
Add this line to the top of the file:

<code>DEVICE=C:\OAKCDROM.SYS /D:MSCD000</code>

==== AUTOEXEC.BAT ====
Add this line to the end of the file:

<code>C:\MSCDEX.EXE /D:MSCD000</code>

Reboot the system, and the drive should populate.

Keep in mind that the only DOS-based CD-ROM driver that has been tested to work with the ZuluSCSI at present is the Oak Technology driver (<code>OAKCDROM.SYS</code>) and <code>VIDE-CDD.SYS</code>, the driver that is included on the Microsoft CD-ROM Extensions installation floppy disk.

Other generic drivers, such as the LG (GoldStar) or Adaptec drivers may work, but have not been fully tested.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The system recognizes the first disc image loaded, but then acts like the drive isn't ready when I change images. ===
This issue is related to firmware revisions prior to 2024.11.08. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluSCSI-firmware Github repo].

If you are unable to update the firmware, there is a workaround that you can use until you are able to do so.

After changing images, try to access the drive. The system will pause for a long moment, and then you should see a message similar to this:

<code>CDR101: Not ready reading drive E: 
(A)bort, (R)etry, (F)ail?</code>

Press F to fail the check, and then if it drops back to a command prompt, try to access the drive again and it should present the image as normal.

=== [[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (as optical drive): Performing an "eject" command in Windows Explorer doesn't actually cycle to the next image. ===
This issue is related to firmware revisions prior to 2024.12.10. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluSCSI-firmware Github repo].

The workaround for this is to have either the web interface or hardware interface connected and swap images that way. Another workaround is to manually eject the SD card from the ZuluSCSI, add a zero to the beginning of the desired disk image's name, and then reinsert the SD card. The ZuluSCSI will then look for the first image it can load alphabetically, which should be the newly-renamed image.

=== [[File:Msdos-icon.png|frameless|34x34px]](attached to sound card): The ZuluSCSI seems to be working correctly, but it's never detected. ===
This is a potential hardware configuration issue. Some sound cards, even if they have an actual IDE interface, force themselves to be configured as either the primary or secondary interface in the system and are not configurable. Most sound cards are also capable of recognizing ''only'' optical devices, so if you have the ZuluSCSI configured as something other than an optical drive, the card may not recognize the device attached to it. If you want to use the ZuluSCSI as something other than an optical drive, attach it to an IDE port attached to the motherboard or I/O card, as opposed to a sound card.

=== [[File:Msdos-icon.png|frameless|34x34px]][[File:Win31.png|32x32px]][[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (with audio DAC board): I have the device attached to my SoundBlaster's CD audio in connector, but I only hear the right channel. ===
Early SoundBlaster cards (including the Pro and Pro 2) used a different pinout on the CD audio header. Instead of R-G-G-L (right channel, ground, ground, left channel) these cards' pinout was NC-L-G-R (no connect, left, ground, right). You may need to get a different cable.

ZuluSCSI Operations Guide

2025-01-06T16:06:42Z

Mbalmer: initial creation -- WIP

== Setting Up Your ZuluSCSI ==

--- copied from IDE page; WIP! ---

=== Unboxing ===
When you first receive your ZuluSCSI, depending on the options you ordered, you should receive the following:

* ZuluSCSI RP2040 Compact board
* 3D-printed plastic carrier
* 2x ¼" 4-40 screws
* microSD card
* Hardware interface board (optional)
* Qwiic cable (included with hardware interface board)
* DAC board with mounted Raspberry Pi Pico W (optional)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below.
[[File:ZuluSCSI RP2040 Compact (labeled).png|center|frameless|800x800px]]

* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive).
* '''40-pin male IDC connector:''' Plug your IDE bus cable into this. The connector is keyed, but some IDE cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Configuration DIP switches:''' These will set how the ZuluSCSI responds when the BIOS requests information from the device.
* '''Bootloader button:''' Used during the firmware update process.
* '''I2C Footprint:''' Addon boards can attach through this open footprint either by being soldered directly to it or by attaching standard 0.1" header to this footprint.
* '''Qwiic Port:''' Addon boards can also attach here through the use of a standard Qwiic I2C cable.
* '''MicroUSB Port:''' Used during the firmware update process. Can also be used as a serial monitor to capture debug logs in real time with a second PC.
* '''microSD Card Slot:''' Your SD card with images goes here.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''External eject and LED headers:''' If you intend to mount the device internally, but want external access to these, you can use standard 0.1" headers to run an eject button and an LED to a case panel. The red box on the image above indicates the positive pin.

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==
[[File:DIP switches (ZuluSCSI).png|center|frameless]]
Set the three DIP switches according to how the device needs to be configured in the host system.

* '''Switch 1:''' Turn IDE Cable Select on or off. ''Most'' systems will work fine with this off, but there are several systems (especially single-board industrial computers) which will use cable-select to determine primary and secondary drives and thus will need it on. If your system hangs during IDE device detection with the ZuluSCSI attached to the bus, try turning this switch ON first.
* '''Switch 2:''' Respond as Primary/Master (OFF) or Secondary/Slave (ON).
* '''Switch 3:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the MicroUSB port on the device with this switch on, it will also print the debug log over the cable via the RP2040's internal serial connection.

== Qwiic Port and External Hardware Interface ==
The external hardware interface (optional) can be connected to this port. The interface provides a Gotek-like system to navigate disc images stored on the SD card and to cycle through them.
{| class="wikitable" style="margin: auto;"
|+
![[File:Hardware interface (rev 2024a).png|frameless|379x379px]]
![[File:Qwiic cable.png|frameless|338x338px]]
|}
The rotary encoder knob on the hardware interface functions exactly like a Gotek device — spin the knob to change images or menu selections, press the knob to select. The Eject button works exactly like the eject button on the main board, although with the hardware interface attached, it will ask you to confirm the eject by pressing the rotary knob. The User button is currently reserved for future use.

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not being detected
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.

If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use images larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB.

Load your images onto the card into the root folder. Images stored in folders, unless they are <code>BIN/CUE</code> images, will be ignored.

For <code>BIN/CUE</code> files, they can be placed into a folder with the same name as the image file; i.e., if you have a <code>BIN/CUE</code> pair named <code>bigdiscofstuff.bin</code> and <code>bigdiscofstuff.cue</code> you should place them in a directory named <code>bigdiscofstuff</code>. This is '''required''' if your <code>BIN/CUE</code> image has a single <code>CUE</code> file and multiple <code>BIN</code> files.

=== Drive Types ===
When configuring the ZuluSCSI, you can set it to be multiple different drive types based on the images you intend to use. Out of the box, the ZuluSCSI configures itself as an optical drive, but through the [[ZuluSCSI INI Configuration|INI file]] or by using '''filename prefixes,''' you can tell the ZuluSCSI which device you want it to behave as when you power it on.

==== Using the INI File ====
Under the <code>[IDE]</code> heading, use the <code>Device=</code> value to set the drive type:0

* <code>CDROM</code> (default) will cause the ZuluSCSI to respond as an optical drive.
* <code>Zip100</code> will cause the ZuluSCSI to respond as an ATAPI-attached 100MB Zip Drive
* <code>Zip250</code> will cause the ZuluSCSI to respond as an ATAPI-attached 250MB Zip Drive
* <code>Removable</code> will cause the ZuluSCSI to respond as a generic removable media device
* <code>HDD</code> will cause the ZuluSCSI to respond as a standard hard disk drive

If this section is absent, or the <code>zuluide.ini</code> file is not present on the SD card, the device will default to behaving as an optical drive.

==== Using a filename prefix ====
Add the following to the beginning of your filename to switch the ZuluSCSI's device mode:

* <code>cdrm</code> will cause the ZuluSCSI to load the image as an optical drive image.
* <code>zipd</code> will cause the ZuluSCSI to load the image as a 100MB or 250MB Zip disk.
* <code>remv</code> will cause the ZuluSCSI to load the image as a generic removable media device.
* <code>hddr</code> will cause the ZuluSCSI to load the image as a non-removable hard disk image.

The <code>Device=</code> option in the INI file will override this behavior. Additionally, if a filename prefix is specified, all other files that you want to use '''must have the same prefix.'''

==== Filename extensions ====
In optical drive mode, the device will only recognize images that end in <code>.iso</code> or <code>.bin/.cue</code>, while also recognizing folders for purposes of reading multipart <code>.bin/.cue</code> images.

For Zip drives or other removable media,ᚸso long as the filename doesn't contain one of the prefixes above, doesn't have an optical drive image extension (<code>.iso/.bin/.cue</code>), or one of the extensions on the ignored list below, it will load the file as a disk image and attempt to mount it.

If the ZuluSCSI starts up as an optical drive, it will use the first image it finds on the SD card as an optical disc.

==== Changing disk images ====
Without the hardware interface or web interface, changing disk images is done by pressing the eject button on the device itself or by performing a hardware eject directly through the operating system. The firmware will cycle to the next available image on the SD card in alphabetical order.

==== Ignore list ====
Files with any of the following extensions will be ignored by the ZuluSCSI and will not appear in the list of available images on the hardware or web interfaces, and will not be selected when a hardware eject is performed:

*<code>.cue</code> <code>.txt</code><code>.rtf</code><code>.md</code><code>.nfo</code><code>.pdf</code><code>.doc</code>

Compressed archive file formats:

* <code>.zip .7z .dmg .rar .tar .tgz .gz .bz2 .tbz2 .xz .zst .lzh .lha .lzo .lz4 .arj .hqx .cpt .s7z</code>

Additionally, any file that begins with <code>zulu</code> will be ignored.

==== USB Mass Storage ====
You can use the ZuluSCSI as a passthrough to access the SD card directly by putting the option <code>enable_usb_mass_storage=1</code> in the <code>[IDE]</code> section of the [[ZuluSCSI INI Configuration|INI file]]. In order to use this mode, the ZuluSCSI must not currently be operating as an attached device through the IDE port on a host computer.

==== Hotplugging ====
The ZuluSCSI supports removal and re-insertion of the SD card while the device is on and functioning. Until the device detects that a card has been inserted, you'll see the activity LED blink 5 times rapidly, pause, and then repeat until a card is reinserted. Once the card has been detected, the LED will blink once, turn off, and return to normal indication of disk access.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware two different ways.

==== Using the SD card ====
The ZuluSCSI can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluSCSI is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluSCSI.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluSCSI.
# Power the system back on. The ZuluSCSI will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluSCSI and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluSCSI so it can become ready.
# When the firmware update process finishes, the ZuluSCSI will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB port into a host computer, this is the traditional way to update RP2040-based devices like the ZuluSCSI.

# Power down the system the ZuluSCSI is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluSCSI/ZuluSCSI-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluSCSI, attach the other end of the cable to the MicroUSB port on the ZuluSCSI. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluSCSI.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluSCSI to its host, if you removed it in step 1.

== Troubleshooting ==
Some simple things to check before you dive deeper:

* Make sure there are no primary/secondary conflicts on the IDE channel that the ZuluSCSI is attached to.
* Make sure that the power connection to the device is secure and attached.
* Try toggling the Cable Select switch. Some BIOSes prefer the device to be one way or the other and there's often little rhyme or reason between even the exact same BIOS on the exact same build across two machines.

For more specific problems, keep reading.

The icon at the left of the problems listed tends to pertain to that particular operating system.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The ZuluSCSI doesn't seem to be recognized under MS-DOS. ===
If you have the ZuluSCSI attached as an optical drive in a system that doesn't natively support the ATAPI protocol, you may have to install a third-party driver to allow DOS to see the drive. This was common for all systems based on 386 processors and earlier, most 486 systems, and some Pentium-based systems.

The simplest solution is to obtain a copy of the Microsoft Windows 98 startup disk, and copy the <code>OAKCDROM.SYS</code> and <code>MSCDEX.EXE</code> files from it to the root folder of your boot drive. Then, modify your <code>CONFIG.SYS</code> and <code>AUTOEXEC.BAT</code> files like this:

==== CONFIG.SYS ====
Add this line to the top of the file:

<code>DEVICE=C:\OAKCDROM.SYS /D:MSCD000</code>

==== AUTOEXEC.BAT ====
Add this line to the end of the file:

<code>C:\MSCDEX.EXE /D:MSCD000</code>

Reboot the system, and the drive should populate.

Keep in mind that the only DOS-based CD-ROM driver that has been tested to work with the ZuluSCSI at present is the Oak Technology driver (<code>OAKCDROM.SYS</code>) and <code>VIDE-CDD.SYS</code>, the driver that is included on the Microsoft CD-ROM Extensions installation floppy disk.

Other generic drivers, such as the LG (GoldStar) or Adaptec drivers may work, but have not been fully tested.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The system recognizes the first disc image loaded, but then acts like the drive isn't ready when I change images. ===
This issue is related to firmware revisions prior to 2024.11.08. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluSCSI-firmware Github repo].

If you are unable to update the firmware, there is a workaround that you can use until you are able to do so.

After changing images, try to access the drive. The system will pause for a long moment, and then you should see a message similar to this:

<code>CDR101: Not ready reading drive E: 
(A)bort, (R)etry, (F)ail?</code>

Press F to fail the check, and then if it drops back to a command prompt, try to access the drive again and it should present the image as normal.

=== [[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (as optical drive): Performing an "eject" command in Windows Explorer doesn't actually cycle to the next image. ===
This issue is related to firmware revisions prior to 2024.12.10. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluSCSI-firmware Github repo].

The workaround for this is to have either the web interface or hardware interface connected and swap images that way. Another workaround is to manually eject the SD card from the ZuluSCSI, add a zero to the beginning of the desired disk image's name, and then reinsert the SD card. The ZuluSCSI will then look for the first image it can load alphabetically, which should be the newly-renamed image.

=== [[File:Msdos-icon.png|frameless|34x34px]](attached to sound card): The ZuluSCSI seems to be working correctly, but it's never detected. ===
This is a potential hardware configuration issue. Some sound cards, even if they have an actual IDE interface, force themselves to be configured as either the primary or secondary interface in the system and are not configurable. Most sound cards are also capable of recognizing ''only'' optical devices, so if you have the ZuluSCSI configured as something other than an optical drive, the card may not recognize the device attached to it. If you want to use the ZuluSCSI as something other than an optical drive, attach it to an IDE port attached to the motherboard or I/O card, as opposed to a sound card.

=== [[File:Msdos-icon.png|frameless|34x34px]][[File:Win31.png|32x32px]][[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (with audio DAC board): I have the device attached to my SoundBlaster's CD audio in connector, but I only hear the right channel. ===
Early SoundBlaster cards (including the Pro and Pro 2) used a different pinout on the CD audio header. Instead of R-G-G-L (right channel, ground, ground, left channel) these cards' pinout was NC-L-G-R (no connect, left, ground, right). You may need to get a different cable.

ZuluIDE Operations Guide

2025-01-06T16:04:17Z

Mbalmer: /* Troubleshooting */ - add sound card details and CD audio pinout on early SB cards (+215 words)

== Setting Up Your ZuluIDE ==

=== Unboxing ===
When you first receive your ZuluIDE, depending on the options you ordered, you should receive the following:

* ZuluIDE RP2040 Compact board
* 3D-printed plastic carrier
* 2x ¼" 4-40 screws
* microSD card
* Hardware interface board (optional)
* Qwiic cable (included with hardware interface board)
* DAC board with mounted Raspberry Pi Pico W (optional)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below.
[[File:ZuluIDE RP2040 Compact (labeled).png|center|frameless|800x800px]]

* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive).
* '''40-pin male IDC connector:''' Plug your IDE bus cable into this. The connector is keyed, but some IDE cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Configuration DIP switches:''' These will set how the ZuluIDE responds when the BIOS requests information from the device.
* '''Bootloader button:''' Used during the firmware update process.
* '''I2C Footprint:''' Addon boards can attach through this open footprint either by being soldered directly to it or by attaching standard 0.1" header to this footprint.
* '''Qwiic Port:''' Addon boards can also attach here through the use of a standard Qwiic I2C cable.
* '''MicroUSB Port:''' Used during the firmware update process. Can also be used as a serial monitor to capture debug logs in real time with a second PC.
* '''microSD Card Slot:''' Your SD card with images goes here.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''External eject and LED headers:''' If you intend to mount the device internally, but want external access to these, you can use standard 0.1" headers to run an eject button and an LED to a case panel. The red box on the image above indicates the positive pin.

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==
[[File:DIP switches (ZuluIDE).png|center|frameless]]
Set the three DIP switches according to how the device needs to be configured in the host system.

* '''Switch 1:''' Turn IDE Cable Select on or off. ''Most'' systems will work fine with this off, but there are several systems (especially single-board industrial computers) which will use cable-select to determine primary and secondary drives and thus will need it on. If your system hangs during IDE device detection with the ZuluIDE attached to the bus, try turning this switch ON first.
* '''Switch 2:''' Respond as Primary/Master (OFF) or Secondary/Slave (ON).
* '''Switch 3:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the MicroUSB port on the device with this switch on, it will also print the debug log over the cable via the RP2040's internal serial connection.

== Qwiic Port and External Hardware Interface ==
The external hardware interface (optional) can be connected to this port. The interface provides a Gotek-like system to navigate disc images stored on the SD card and to cycle through them.
{| class="wikitable" style="margin: auto;"
|+
![[File:Hardware interface (rev 2024a).png|frameless|379x379px]]
![[File:Qwiic cable.png|frameless|338x338px]]
|}
The rotary encoder knob on the hardware interface functions exactly like a Gotek device — spin the knob to change images or menu selections, press the knob to select. The Eject button works exactly like the eject button on the main board, although with the hardware interface attached, it will ask you to confirm the eject by pressing the rotary knob. The User button is currently reserved for future use.

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not being detected
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.

If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use images larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB.

Load your images onto the card into the root folder. Images stored in folders, unless they are <code>BIN/CUE</code> images, will be ignored.

For <code>BIN/CUE</code> files, they can be placed into a folder with the same name as the image file; i.e., if you have a <code>BIN/CUE</code> pair named <code>bigdiscofstuff.bin</code> and <code>bigdiscofstuff.cue</code> you should place them in a directory named <code>bigdiscofstuff</code>. This is '''required''' if your <code>BIN/CUE</code> image has a single <code>CUE</code> file and multiple <code>BIN</code> files.

=== Drive Types ===
When configuring the ZuluIDE, you can set it to be multiple different drive types based on the images you intend to use. Out of the box, the ZuluIDE configures itself as an optical drive, but through the [[ZuluIDE INI Configuration|INI file]] or by using '''filename prefixes,''' you can tell the ZuluIDE which device you want it to behave as when you power it on.

==== Using the INI File ====
Under the <code>[IDE]</code> heading, use the <code>Device=</code> value to set the drive type:0

* <code>CDROM</code> (default) will cause the ZuluIDE to respond as an optical drive.
* <code>Zip100</code> will cause the ZuluIDE to respond as an ATAPI-attached 100MB Zip Drive
* <code>Zip250</code> will cause the ZuluIDE to respond as an ATAPI-attached 250MB Zip Drive
* <code>Removable</code> will cause the ZuluIDE to respond as a generic removable media device
* <code>HDD</code> will cause the ZuluIDE to respond as a standard hard disk drive

If this section is absent, or the <code>zuluide.ini</code> file is not present on the SD card, the device will default to behaving as an optical drive.

==== Using a filename prefix ====
Add the following to the beginning of your filename to switch the ZuluIDE's device mode:

* <code>cdrm</code> will cause the ZuluIDE to load the image as an optical drive image.
* <code>zipd</code> will cause the ZuluIDE to load the image as a 100MB or 250MB Zip disk.
* <code>remv</code> will cause the ZuluIDE to load the image as a generic removable media device.
* <code>hddr</code> will cause the ZuluIDE to load the image as a non-removable hard disk image.

The <code>Device=</code> option in the INI file will override this behavior. Additionally, if a filename prefix is specified, all other files that you want to use '''must have the same prefix.'''

==== Filename extensions ====
In optical drive mode, the device will only recognize images that end in <code>.iso</code> or <code>.bin/.cue</code>, while also recognizing folders for purposes of reading multipart <code>.bin/.cue</code> images.

For Zip drives or other removable media,ᚸso long as the filename doesn't contain one of the prefixes above, doesn't have an optical drive image extension (<code>.iso/.bin/.cue</code>), or one of the extensions on the ignored list below, it will load the file as a disk image and attempt to mount it.

If the ZuluIDE starts up as an optical drive, it will use the first image it finds on the SD card as an optical disc.

==== Changing disk images ====
Without the hardware interface or web interface, changing disk images is done by pressing the eject button on the device itself or by performing a hardware eject directly through the operating system. The firmware will cycle to the next available image on the SD card in alphabetical order.

==== Ignore list ====
Files with any of the following extensions will be ignored by the ZuluIDE and will not appear in the list of available images on the hardware or web interfaces, and will not be selected when a hardware eject is performed:

*<code>.cue</code> <code>.txt</code><code>.rtf</code><code>.md</code><code>.nfo</code><code>.pdf</code><code>.doc</code>

Compressed archive file formats:

* <code>.zip .7z .dmg .rar .tar .tgz .gz .bz2 .tbz2 .xz .zst .lzh .lha .lzo .lz4 .arj .hqx .cpt .s7z</code>

Additionally, any file that begins with <code>zulu</code> will be ignored.

==== USB Mass Storage ====
You can use the ZuluIDE as a passthrough to access the SD card directly by putting the option <code>enable_usb_mass_storage=1</code> in the <code>[IDE]</code> section of the [[ZuluIDE INI Configuration|INI file]]. In order to use this mode, the ZuluIDE must not currently be operating as an attached device through the IDE port on a host computer.

==== Hotplugging ====
The ZuluIDE supports removal and re-insertion of the SD card while the device is on and functioning. Until the device detects that a card has been inserted, you'll see the activity LED blink 5 times rapidly, pause, and then repeat until a card is reinserted. Once the card has been detected, the LED will blink once, turn off, and return to normal indication of disk access.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware two different ways.

==== Using the SD card ====
The ZuluIDE can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluIDE is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluIDE.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluIDE.
# Power the system back on. The ZuluIDE will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluIDE and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluIDE so it can become ready.
# When the firmware update process finishes, the ZuluIDE will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB port into a host computer, this is the traditional way to update RP2040-based devices like the ZuluIDE.

# Power down the system the ZuluIDE is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluIDE, attach the other end of the cable to the MicroUSB port on the ZuluIDE. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluIDE.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluIDE to its host, if you removed it in step 1.

== Troubleshooting ==
Some simple things to check before you dive deeper:

* Make sure there are no primary/secondary conflicts on the IDE channel that the ZuluIDE is attached to.
* Make sure that the power connection to the device is secure and attached.
* Try toggling the Cable Select switch. Some BIOSes prefer the device to be one way or the other and there's often little rhyme or reason between even the exact same BIOS on the exact same build across two machines.

For more specific problems, keep reading.

The icon at the left of the problems listed tends to pertain to that particular operating system.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The ZuluIDE doesn't seem to be recognized under MS-DOS. ===
If you have the ZuluIDE attached as an optical drive in a system that doesn't natively support the ATAPI protocol, you may have to install a third-party driver to allow DOS to see the drive. This was common for all systems based on 386 processors and earlier, most 486 systems, and some Pentium-based systems.

The simplest solution is to obtain a copy of the Microsoft Windows 98 startup disk, and copy the <code>OAKCDROM.SYS</code> and <code>MSCDEX.EXE</code> files from it to the root folder of your boot drive. Then, modify your <code>CONFIG.SYS</code> and <code>AUTOEXEC.BAT</code> files like this:

==== CONFIG.SYS ====
Add this line to the top of the file:

<code>DEVICE=C:\OAKCDROM.SYS /D:MSCD000</code>

==== AUTOEXEC.BAT ====
Add this line to the end of the file:

<code>C:\MSCDEX.EXE /D:MSCD000</code>

Reboot the system, and the drive should populate.

Keep in mind that the only DOS-based CD-ROM driver that has been tested to work with the ZuluIDE at present is the Oak Technology driver (<code>OAKCDROM.SYS</code>) and <code>VIDE-CDD.SYS</code>, the driver that is included on the Microsoft CD-ROM Extensions installation floppy disk.

Other generic drivers, such as the LG (GoldStar) or Adaptec drivers may work, but have not been fully tested.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The system recognizes the first disc image loaded, but then acts like the drive isn't ready when I change images. ===
This issue is related to firmware revisions prior to 2024.11.08. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluIDE-firmware Github repo].

If you are unable to update the firmware, there is a workaround that you can use until you are able to do so.

After changing images, try to access the drive. The system will pause for a long moment, and then you should see a message similar to this:

<code>CDR101: Not ready reading drive E: 
(A)bort, (R)etry, (F)ail?</code>

Press F to fail the check, and then if it drops back to a command prompt, try to access the drive again and it should present the image as normal.

=== [[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (as optical drive): Performing an "eject" command in Windows Explorer doesn't actually cycle to the next image. ===
This issue is related to firmware revisions prior to 2024.12.10. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluIDE-firmware Github repo].

The workaround for this is to have either the web interface or hardware interface connected and swap images that way. Another workaround is to manually eject the SD card from the ZuluIDE, add a zero to the beginning of the desired disk image's name, and then reinsert the SD card. The ZuluIDE will then look for the first image it can load alphabetically, which should be the newly-renamed image.

=== [[File:Msdos-icon.png|frameless|34x34px]](attached to sound card): The ZuluIDE seems to be working correctly, but it's never detected. ===
This is a potential hardware configuration issue. Some sound cards, even if they have an actual IDE interface, force themselves to be configured as either the primary or secondary interface in the system and are not configurable. Most sound cards are also capable of recognizing ''only'' optical devices, so if you have the ZuluIDE configured as something other than an optical drive, the card may not recognize the device attached to it. If you want to use the ZuluIDE as something other than an optical drive, attach it to an IDE port attached to the motherboard or I/O card, as opposed to a sound card.

=== [[File:Msdos-icon.png|frameless|34x34px]][[File:Win31.png|32x32px]][[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (with audio DAC board): I have the device attached to my SoundBlaster's CD audio in connector, but I only hear the right channel. ===
Early SoundBlaster cards (including the Pro and Pro 2) used a different pinout on the CD audio header. Instead of R-G-G-L (right channel, ground, ground, left channel) these cards' pinout was NC-L-G-R (no connect, left, ground, right). You may need to get a different cable.

ZuluIDE Operations Guide

2024-11-12T01:55:14Z

Mbalmer: Change "not ready" troubleshooting step

== Setting Up Your ZuluIDE ==

=== Unboxing ===
When you first receive your ZuluIDE, depending on the options you ordered, you should receive the following:

* ZuluIDE RP2040 Compact board
* 3D-printed plastic carrier
* 2x ¼" 4-40 screws
* microSD card
* Hardware interface board (optional)
* Qwiic cable (included with hardware interface board)
* DAC board with mounted Raspberry Pi Pico W (optional)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below.
[[File:ZuluIDE RP2040 Compact (labeled).png|center|frameless|800x800px]]

* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive).
* '''40-pin male IDC connector:''' Plug your IDE bus cable into this. The connector is keyed, but some IDE cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Configuration DIP switches:''' These will set how the ZuluIDE responds when the BIOS requests information from the device.
* '''Bootloader button:''' Used during the firmware update process.
* '''I2C Footprint:''' Addon boards can attach through this open footprint either by being soldered directly to it or by attaching standard 0.1" header to this footprint.
* '''Qwiic Port:''' Addon boards can also attach here through the use of a standard Qwiic I2C cable.
* '''MicroUSB Port:''' Used during the firmware update process. Can also be used as a serial monitor to capture debug logs in real time with a second PC.
* '''microSD Card Slot:''' Your SD card with images goes here.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''External eject and LED headers:''' If you intend to mount the device internally, but want external access to these, you can use standard 0.1" headers to run an eject button and an LED to a case panel. The red box on the image above indicates the positive pin.

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==
[[File:DIP switches (ZuluIDE).png|center|frameless]]
Set the three DIP switches according to how the device needs to be configured in the host system.

* '''Switch 1:''' Turn IDE Cable Select on or off. ''Most'' systems will work fine with this off, but there are several systems (especially single-board industrial computers) which will use cable-select to determine primary and secondary drives and thus will need it on. If your system hangs during IDE device detection with the ZuluIDE attached to the bus, try turning this switch ON first.
* '''Switch 2:''' Respond as Primary/Master (OFF) or Secondary/Slave (ON).
* '''Switch 3:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the MicroUSB port on the device with this switch on, it will also print the debug log over the cable via the RP2040's internal serial connection.

== Qwiic Port and External Hardware Interface ==
The external hardware interface (optional) can be connected to this port. The interface provides a Gotek-like system to navigate disc images stored on the SD card and to cycle through them.
{| class="wikitable" style="margin: auto;"
|+
![[File:Hardware interface (rev 2024a).png|frameless|379x379px]]
![[File:Qwiic cable.png|frameless|338x338px]]
|}
The rotary encoder knob on the hardware interface functions exactly like a Gotek device — spin the knob to change images or menu selections, press the knob to select. The Eject button works exactly like the eject button on the main board, although with the hardware interface attached, it will ask you to confirm the eject by pressing the rotary knob. The User button is currently reserved for future use.

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not being detected
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.

If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use images larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB.

Load your images onto the card into the root folder. Images stored in folders, unless they are <code>BIN/CUE</code> images, will be ignored.

For <code>BIN/CUE</code> files, they can be placed into a folder with the same name as the image file; i.e., if you have a <code>BIN/CUE</code> pair named <code>bigdiscofstuff.bin</code> and <code>bigdiscofstuff.cue</code> you should place them in a directory named <code>bigdiscofstuff</code>. This is '''required''' if your <code>BIN/CUE</code> image has a single <code>CUE</code> file and multiple <code>BIN</code> files.

=== Drive Types ===
When configuring the ZuluIDE, you can set it to be multiple different drive types based on the images you intend to use. Out of the box, the ZuluIDE configures itself as an optical drive, but through the [[ZuluIDE INI Configuration|INI file]] or by using '''filename prefixes,''' you can tell the ZuluIDE which device you want it to behave as when you power it on.

==== Using the INI File ====
Under the <code>[IDE]</code> heading, use the <code>Device=</code> value to set the drive type:0

* <code>CDROM</code> (default) will cause the ZuluIDE to respond as an optical drive.
* <code>Zip100</code> will cause the ZuluIDE to respond as an ATAPI-attached 100MB Zip Drive
* <code>Zip250</code> will cause the ZuluIDE to respond as an ATAPI-attached 250MB Zip Drive
* <code>Removable</code> will cause the ZuluIDE to respond as a generic removable media device
* <code>HDD</code> will cause the ZuluIDE to respond as a standard hard disk drive

If this section is absent, or the <code>zuluide.ini</code> file is not present on the SD card, the device will default to behaving as an optical drive.

==== Using a filename prefix ====
Add the following to the beginning of your filename to switch the ZuluIDE's device mode:

* <code>cdrm</code> will cause the ZuluIDE to load the image as an optical drive image.
* <code>zipd</code> will cause the ZuluIDE to load the image as a 100MB or 250MB Zip disk.
* <code>remv</code> will cause the ZuluIDE to load the image as a generic removable media device.
* <code>hddr</code> will cause the ZuluIDE to load the image as a non-removable hard disk image.

The <code>Device=</code> option in the INI file will override this behavior. Additionally, if a filename prefix is specified, all other files that you want to use '''must have the same prefix.'''

==== Filename extensions ====
In optical drive mode, the device will only recognize images that end in <code>.iso</code> or <code>.bin/.cue</code>, while also recognizing folders for purposes of reading multipart <code>.bin/.cue</code> images.

For Zip drives or other removable media,ᚸso long as the filename doesn't contain one of the prefixes above, doesn't have an optical drive image extension (<code>.iso/.bin/.cue</code>), or one of the extensions on the ignored list below, it will load the file as a disk image and attempt to mount it.

If the ZuluIDE starts up as an optical drive, it will use the first image it finds on the SD card as an optical disc.

==== Changing disk images ====
Without the hardware interface or web interface, changing disk images is done by pressing the eject button on the device itself or by performing a hardware eject directly through the operating system. The firmware will cycle to the next available image on the SD card in alphabetical order.

==== Ignore list ====
Files with any of the following extensions will be ignored by the ZuluIDE and will not appear in the list of available images on the hardware or web interfaces, and will not be selected when a hardware eject is performed:

*<code>.cue</code> <code>.txt</code><code>.rtf</code><code>.md</code><code>.nfo</code><code>.pdf</code><code>.doc</code>

Compressed archive file formats:

* <code>.zip .7z .dmg .rar .tar .tgz .gz .bz2 .tbz2 .xz .zst .lzh .lha .lzo .lz4 .arj .hqx .cpt .s7z</code>

Additionally, any file that begins with <code>zulu</code> will be ignored.

==== USB Mass Storage ====
You can use the ZuluIDE as a passthrough to access the SD card directly by putting the option <code>enable_usb_mass_storage=1</code> in the <code>[IDE]</code> section of the [[ZuluIDE INI Configuration|INI file]]. In order to use this mode, the ZuluIDE must not currently be operating as an attached device through the IDE port on a host computer.

==== Hotplugging ====
The ZuluIDE supports removal and re-insertion of the SD card while the device is on and functioning. Until the device detects that a card has been inserted, you'll see the activity LED blink 5 times rapidly, pause, and then repeat until a card is reinserted. Once the card has been detected, the LED will blink once, turn off, and return to normal indication of disk access.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware two different ways.

==== Using the SD card ====
The ZuluIDE can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluIDE is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluIDE.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluIDE.
# Power the system back on. The ZuluIDE will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluIDE and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluIDE so it can become ready.
# When the firmware update process finishes, the ZuluIDE will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB port into a host computer, this is the traditional way to update RP2040-based devices like the ZuluIDE.

# Power down the system the ZuluIDE is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluIDE, attach the other end of the cable to the MicroUSB port on the ZuluIDE. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluIDE.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluIDE to its host, if you removed it in step 1.

== Troubleshooting ==
Some simple things to check before you dive deeper:

* Make sure there are no primary/secondary conflicts on the IDE channel that the ZuluIDE is attached to.
* Make sure that the power connection to the device is secure and attached.
* Try toggling the Cable Select switch. Some BIOSes prefer the device to be one way or the other and there's often little rhyme or reason between even the exact same BIOS on the exact same build across two machines.

For more specific problems, keep reading.

The icon at the left of the problems listed tends to pertain to that particular operating system.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The ZuluIDE doesn't seem to be recognized under MS-DOS. ===
If you have the ZuluIDE attached as an optical drive in a system that doesn't natively support the ATAPI protocol, you may have to install a third-party driver to allow DOS to see the drive. This was common for all systems based on 386 processors and earlier, most 486 systems, and some Pentium-based systems.

The simplest solution is to obtain a copy of the Microsoft Windows 98 startup disk, and copy the <code>OAKCDROM.SYS</code> and <code>MSCDEX.EXE</code> files from it to the root folder of your boot drive. Then, modify your <code>CONFIG.SYS</code> and <code>AUTOEXEC.BAT</code> files like this:

==== CONFIG.SYS ====
Add this line to the top of the file:

<code>DEVICE=C:\OAKCDROM.SYS /D:MSCD000</code>

==== AUTOEXEC.BAT ====
Add this line to the end of the file:

<code>C:\MSCDEX.EXE /D:MSCD000</code>

Reboot the system, and the drive should populate.

Keep in mind that the only DOS-based CD-ROM driver that has been tested to work with the ZuluIDE at present is the Oak Technology driver (<code>OAKCDROM.SYS</code>). Other generic drivers, such as the LG (GoldStar) or Adaptec drivers may work, but also may not.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The system recognizes the first disc image loaded, but then acts like the drive isn't ready when I change images. ===
This issue is related to firmware revisions prior to 2024.11.08. Update your device firmware on the [https://github.com/rabbitholecomputing/ZuluIDE-firmware Github repo].

If you are unable to update the firmware, there is a workaround that you can use until you are able to do so.

After changing images, try to access the drive. The system will pause for a long moment, and then you should see a message similar to this:

<code>CDR101: Not ready reading drive E: 
(A)bort, (R)etry, (F)ail?</code>

Press F to fail the check, and then if it drops back to a command prompt, try to access the drive again and it should present the image as normal.

=== [[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (as optical drive): Performing an "eject" command in Windows Explorer doesn't actually cycle to the next image. ===
This is currently a known issue. The workaround for this is to have either the web interface or hardware interface connected and swap images that way. Another workaround is to manually eject the SD card from the ZuluIDE, add a zero to the beginning of the desired disk image's name, and then reinsert the SD card. The ZuluIDE will then look for the first image it can load alphabetically, which should be the newly-renamed image.

ZuluIDE Operations Guide

2024-11-04T17:39:58Z

Mbalmer: Finish main initial content (+1,207 words, 2 images. OS icons don't count)

== Setting Up Your ZuluIDE ==

=== Unboxing ===
When you first receive your ZuluIDE, depending on the options you ordered, you should receive the following:

* ZuluIDE RP2040 Compact board
* 3D-printed plastic carrier
* 2x ¼" 4-40 screws
* microSD card
* Hardware interface board (optional)
* Qwiic cable (included with hardware interface board)
* DAC board with mounted Raspberry Pi Pico W (optional)

== Board Overview ==
Take a moment to identify the various parts of the board as shown below.
[[File:ZuluIDE RP2040 Compact (labeled).png|center|frameless|800x800px]]

* '''4-pin Molex floppy power connector:''' Run a standard Molex 4-pin power cable to this port. If your system power supply has only the larger style, get an adapter cable to switch it to the smaller size (the same size as that found on a 3½" floppy disk drive).
* '''40-pin male IDC connector:''' Plug your IDE bus cable into this. The connector is keyed, but some IDE cables lack the key, so make sure that the red stripe on the cable lines up with the little arrow embossed into the connector itself.
* '''Configuration DIP switches:''' These will set how the ZuluIDE responds when the BIOS requests information from the device.
* '''Bootloader button:''' Used during the firmware update process.
* '''I2C Footprint:''' Addon boards can attach through this open footprint either by being soldered directly to it or by attaching standard 0.1" header to this footprint.
* '''Qwiic Port:''' Addon boards can also attach here through the use of a standard Qwiic I2C cable.
* '''MicroUSB Port:''' Used during the firmware update process. Can also be used as a serial monitor to capture debug logs in real time with a second PC.
* '''microSD Card Slot:''' Your SD card with images goes here.
* '''Activity LED:''' Flashes in sync with drive access, also used to indicate status conditions as described later
* '''Eject button:''' Performs a hardware eject for optical drives. Some operating systems will need this after dismounting an image from the system to register that the drive door is closed.
* '''External eject and LED headers:''' If you intend to mount the device internally, but want external access to these, you can use standard 0.1" headers to run an eject button and an LED to a case panel. The red box on the image above indicates the positive pin.

== Molex power connector ==
Make sure that your power connection uses a '''3½" floppy power connector,''' not the larger drive connector used on full-size optical drives, hard drives, and the like.
{| class="wikitable" style="margin: auto;"
![[File:Molex 3.5" power connector.png|frameless|135x135px]]
![[File:Molex 3.5" power connector (top).png|frameless|100x100px]]
![[File:Molex 5.25" power connector.png|frameless|117x117px]]
![[File:Molex 5.25" power connector (top).png|frameless|100x100px]]
|-
| colspan="2" |✅ 3½" connector
| colspan="2" |❌ 5¼" connector
|}
If your host system only has the 5¼" connectors, you'll need to either purchase or make an adapter cable. Making an adapter cable requires the following parts:

* '''4× 5¼ male pins:''' TE Connectivity P/N 60620-1
* '''1× 5¼ male housing:''' TE Connectivity P/N 1-480426-0
* '''4× 3½ female sockets:''' TE Connectivity P/N 170262-1
* '''1× 3½ female housing:''' TE Connectivity P/N 171822-4

When making the cables, use 20-gauge wire. If you're crimping a splitter cable, it's also possible to use 18-gauge wire on the 5¼ side going to the female plug, and then crimp the larger wire going into the male splitter side together with 22 or 24-gauge wire going to the 3½ side. Crimping the cables can be done with standard tools found on Amazon, such as the IWISS SN-025.

== DIP Switch Configuration ==
[[File:DIP switches (ZuluIDE).png|center|frameless]]
Set the three DIP switches according to how the device needs to be configured in the host system.

* '''Switch 1:''' Turn IDE Cable Select on or off. ''Most'' systems will work fine with this off, but there are several systems (especially single-board industrial computers) which will use cable-select to determine primary and secondary drives and thus will need it on. If your system hangs during IDE device detection with the ZuluIDE attached to the bus, try turning this switch ON first.
* '''Switch 2:''' Respond as Primary/Master (OFF) or Secondary/Slave (ON).
* '''Switch 3:''' Debug log disable/enable. If this switch is ON, the device will automatically write out a detailed debug log to <code>zululog.txt</code> on the SD card as long as the device is powered on. Additionally, if you have a USB cable plugged into the MicroUSB port on the device with this switch on, it will also print the debug log over the cable via the RP2040's internal serial connection.

== Qwiic Port and External Hardware Interface ==
The external hardware interface (optional) can be connected to this port. The interface provides a Gotek-like system to navigate disc images stored on the SD card and to cycle through them.
{| class="wikitable" style="margin: auto;"
|+
![[File:Hardware interface (rev 2024a).png|frameless|379x379px]]
![[File:Qwiic cable.png|frameless|338x338px]]
|}
The rotary encoder knob on the hardware interface functions exactly like a Gotek device — spin the knob to change images or menu selections, press the knob to select. The Eject button works exactly like the eject button on the main board, although with the hardware interface attached, it will ask you to confirm the eject by pressing the rotary knob. The User button is currently reserved for future use.

== Activity LED ==
The Activity LED will flash normally during disk access, however, in certain specific failure modes or status changes, you will see it flashing with a pattern.

* '''1 fast blink, at boot time:''' Image file loaded successfully
* '''3 fast blinks:''' No valid images found on SD card
* '''5 fast blinks:''' SD card is present, but is not being detected
* '''Morse code pattern:''' Firmware crash. The particular pattern will indicate where the crash occurred.

If a firmware crash occurs, it will also try to save information to the file <code>zuluerr.txt</code> on the SD card.

== SD Card Preparation and Use ==
Format your SD card with either the FAT32 or exFAT filesystems. If you intend to use images larger than 4 GB in size, you ''must'' format the card using exFAT as the FAT32 filesystem cannot support individual files larger than 4 GB.

Load your images onto the card into the root folder. Images stored in folders, unless they are <code>BIN/CUE</code> images, will be ignored.

For <code>BIN/CUE</code> files, they can be placed into a folder with the same name as the image file; i.e., if you have a <code>BIN/CUE</code> pair named <code>bigdiscofstuff.bin</code> and <code>bigdiscofstuff.cue</code> you should place them in a directory named <code>bigdiscofstuff</code>. This is '''required''' if your <code>BIN/CUE</code> image has a single <code>CUE</code> file and multiple <code>BIN</code> files.

=== Drive Types ===
When configuring the ZuluIDE, you can set it to be multiple different drive types based on the images you intend to use. Out of the box, the ZuluIDE configures itself as an optical drive, but through the [[ZuluIDE INI Configuration|INI file]] or by using '''filename prefixes,''' you can tell the ZuluIDE which device you want it to behave as when you power it on.

==== Using the INI File ====
Under the <code>[IDE]</code> heading, use the <code>Device=</code> value to set the drive type:0

* <code>CDROM</code> (default) will cause the ZuluIDE to respond as an optical drive.
* <code>Zip100</code> will cause the ZuluIDE to respond as an ATAPI-attached 100MB Zip Drive
* <code>Zip250</code> will cause the ZuluIDE to respond as an ATAPI-attached 250MB Zip Drive
* <code>Removable</code> will cause the ZuluIDE to respond as a generic removable media device
* <code>HDD</code> will cause the ZuluIDE to respond as a standard hard disk drive

If this section is absent, or the <code>zuluide.ini</code> file is not present on the SD card, the device will default to behaving as an optical drive.

==== Using a filename prefix ====
Add the following to the beginning of your filename to switch the ZuluIDE's device mode:

* <code>cdrm</code> will cause the ZuluIDE to load the image as an optical drive image.
* <code>zipd</code> will cause the ZuluIDE to load the image as a 100MB or 250MB Zip disk.
* <code>remv</code> will cause the ZuluIDE to load the image as a generic removable media device.
* <code>hddr</code> will cause the ZuluIDE to load the image as a non-removable hard disk image.

The <code>Device=</code> option in the INI file will override this behavior. Additionally, if a filename prefix is specified, all other files that you want to use '''must have the same prefix.'''

==== Filename extensions ====
In optical drive mode, the device will only recognize images that end in <code>.iso</code> or <code>.bin/.cue</code>, while also recognizing folders for purposes of reading multipart <code>.bin/.cue</code> images.

For Zip drives or other removable media,ᚸso long as the filename doesn't contain one of the prefixes above, doesn't have an optical drive image extension (<code>.iso/.bin/.cue</code>), or one of the extensions on the ignored list below, it will load the file as a disk image and attempt to mount it.

If the ZuluIDE starts up as an optical drive, it will use the first image it finds on the SD card as an optical disc.

==== Changing disk images ====
Without the hardware interface or web interface, changing disk images is done by pressing the eject button on the device itself or by performing a hardware eject directly through the operating system. The firmware will cycle to the next available image on the SD card in alphabetical order.

==== Ignore list ====
Files with any of the following extensions will be ignored by the ZuluIDE and will not appear in the list of available images on the hardware or web interfaces, and will not be selected when a hardware eject is performed:

* <code>.zip</code>
* <code>.7z</code>
* <code>.rar</code>
* <code>.tar</code>
* <code>.tgz</code>
* <code>.gz</code>
* <code>.bz2</code>
* <code>.tbz2</code>
* <code>.xz</code>
* <code>.zst</code>
* <code>.z</code>
* <code>.lzh</code>
* <code>.lha</code>
* <code>.lzo</code>
* <code>.lz4</code>
* <code>.arj</code>
* <code>.dmg</code>
* <code>.hqx</code>
* <code>.cpt</code>
* <code>.s7z</code>
* <code>.cue</code>
* <code>.txt</code>
* <code>.rtf</code>
* <code>.md</code>
* <code>.nfo</code>
* <code>.pdf</code>
* <code>.doc</code>

Additionally, any file that begins with <code>zulu</code> will be ignored.

==== USB Mass Storage ====
You can use the ZuluIDE as a passthrough to access the SD card directly by putting the option <code>enable_usb_mass_storage=1</code> in the <code>[IDE]</code> section of the [[ZuluIDE INI Configuration|INI file]]. In order to use this mode, the ZuluIDE must not currently be operating as an attached device through the IDE port on a host computer.

==== Hotplugging ====
The ZuluIDE supports removal and re-insertion of the SD card while the device is on and functioning. Until the device detects that a card has been inserted, you'll see the activity LED blink 5 times rapidly, pause, and then repeat until a card is reinserted. Once the card has been detected, the LED will blink once, turn off, and return to normal indication of disk access.

== Updating the Firmware ==
New firmware releases can be obtained by visiting the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page] for the project. The most recent firmware will be listed at the top with a green "Latest" badge. You can update the firmware two different ways.

==== Using the SD card ====
The ZuluIDE can update itself when it's initially powered on. You'll need to have access to the device so you can remove its SD card.

# Power down the system that the ZuluIDE is attached to and remove its SD card.
# Attach the SD card to the computer where you'll download the update.
# From the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page], download the latest firmware file with a '''.BIN''' extension.
# Copy the downloaded '''.BIN''' file to the root folder of the SD card and rename it as <code>ZuluIDE.bin</code>.
# Dismount the SD card from the computer, and reinsert the SD card into the ZuluIDE.
# Power the system back on. The ZuluIDE will automatically begin the firmware update process, which takes about one second. If the system has to boot to the ZuluIDE and its startup is particularly quick, you may need to reset the computer once to allow the firmware update process to complete on the ZuluIDE so it can become ready.
# When the firmware update process finishes, the ZuluIDE will delete the update file and continue on to normal operation.

==== Using the BOOTLDR button ====
[[File:Bootloader button.png|thumb|140x140px|BOOTLDR button]]
If you have physical access to the device and a way to plug the MicroUSB port into a host computer, this is the traditional way to update RP2040-based devices like the ZuluIDE.

# Power down the system the ZuluIDE is attached to, and if necessary, unplug it from its cabling.
# From the [https://github.com/ZuluIDE/ZuluIDE-firmware/releases Github page], download the latest firmware file with a '''.UF2''' extension.
# Attach a MicroUSB cable to the device you'll be uploading the firmware from.
# While holding down the BOOTLDR button on the ZuluIDE, attach the other end of the cable to the MicroUSB port on the ZuluIDE. [[File:Firmware-update.png|thumb|Copy the UF2 file to the device.]]
# A Windows Explorer window may appear with a drive called <code>RPi-RP2</code>. If it doesn't, open a Windows Explorer window and look for a drive with this name.
# Copy the '''.UF2''' file you downloaded to the root folder of the drive that appeared when you plugged in the ZuluIDE.
# The <code>RPi-RP2</code> window should close on its own once the copy completes. When the device disconnects on its own, the firmware update process is complete.
# Disconnect the USB cables and reattach the ZuluIDE to its host, if you removed it in step 1.

== Troubleshooting ==
Some simple things to check before you dive deeper:

* Make sure there are no primary/secondary conflicts on the IDE channel that the ZuluIDE is attached to.
* Make sure that the power connection to the device is secure and attached.
* Try toggling the Cable Select switch. Some BIOSes prefer the device to be one way or the other and there's often little rhyme or reason between even the exact same BIOS on the exact same build across two machines.

For more specific problems, keep reading.

The icon at the left of the problems listed tends to pertain to that particular operating system.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The ZuluIDE doesn't seem to be recognized under MS-DOS. ===
If you have the ZuluIDE attached as an optical drive in a system that doesn't natively support the ATAPI protocol, you may have to install a third-party driver to allow DOS to see the drive. This was common for all systems based on 386 processors and earlier, most 486 systems, and some Pentium-based systems.

The simplest solution is to obtain a copy of the Microsoft Windows 98 startup disk, and copy the <code>OAKCDROM.SYS</code> and <code>MSCDEX.EXE</code> files from it to the root folder of your boot drive. Then, modify your <code>CONFIG.SYS</code> and <code>AUTOEXEC.BAT</code> files like this:

==== CONFIG.SYS ====
Add this line to the top of the file:

<code>DEVICE=C:\OAKCDROM.SYS /D:MSCD000</code>

==== AUTOEXEC.BAT ====
Add this line to the end of the file:

<code>C:\MSCDEX.EXE /D:MSCD000</code>

Reboot the system, and the drive should populate.

Keep in mind that the only DOS-based CD-ROM driver that has been tested to work with the ZuluIDE at present is the Oak Technology driver (<code>OAKCDROM.SYS</code>). Other generic drivers, such as the LG (GoldStar) or Adaptec drivers may work, but also may not.

=== [[File:Msdos-icon.png|32x32px]][[File:Win31.png|32x32px]](as optical drive): The system recognizes the first disc image loaded, but then acts like the drive isn't ready when I change images. ===
This is currently a known issue. There is a temporary workaround, however.

After changing images, try to access the drive. The system will pause for a long moment, and then you should see a message similar to this:

<code>CDR101: Not ready reading drive E: 
(A)bort, (R)etry, (F)ail?</code>

Press F to fail the check, and then if it drops back to a command prompt, try to access the drive again and it should present the image as normal.

=== [[File:Win9598.png|37x37px]][[File:Winxp.png|36x36px]] (as optical drive): Performing an "eject" command in Windows Explorer doesn't actually cycle to the next image. ===
This is currently a known issue. The workaround for this is to have either the web interface or hardware interface connected and swap images that way. Another workaround is to manually eject the SD card from the ZuluIDE, add a zero to the beginning of the desired disk image's name, and then reinsert the SD card. The ZuluIDE will then look for the first image it can load alphabetically, which should be the newly-renamed image.

File:Debian.png

2024-11-04T16:37:58Z

Mbalmer: Linux - Debian distro

== Summary ==
Linux - Debian distro

File:Ubuntu.png

2024-11-04T16:37:41Z

Mbalmer: Linux - Ubuntu distro

== Summary ==
Linux - Ubuntu distro

File:MacosX.png

2024-11-04T16:37:09Z

Mbalmer: Early Mac OS X (10.0-Rhapsody through roughly 10.8-Mountain Lion)

== Summary ==
Early Mac OS X (10.0-Rhapsody through roughly 10.8-Mountain Lion)

File:Macos9.png

2024-11-04T16:34:31Z

Mbalmer: Mbalmer uploaded a new version of File:Macos9.png

== Summary ==
MacOS 8 and 9

File:Macos9.png

2024-11-04T16:33:06Z

Mbalmer: MacOS 8 and 9

== Summary ==
MacOS 8 and 9

File:Linux-generic.png

2024-11-04T16:32:18Z

Mbalmer: Generic Linux distros

== Summary ==
Generic Linux distros

File:Macse.png

2024-11-04T16:31:30Z

Mbalmer: Macintosh (System 6 and earlier)

== Summary ==
Macintosh (System 6 and earlier)

File:Winxp.png

2024-11-04T15:58:01Z

Mbalmer: Windows XP icon

== Summary ==
Windows XP icon

File:Win9598.png

2024-11-04T15:57:42Z

Mbalmer: Windows 95/98 icon

== Summary ==
Windows 95/98 icon

File:Win31.png

2024-11-04T15:56:46Z

Mbalmer: Windows 3.1 icon

== Summary ==
Windows 3.1 icon

File:Msdos-icon.png

2024-11-04T15:33:07Z

Mbalmer:

MS-DOS icon

File:Firmware-update.png

2024-11-04T15:05:04Z

Mbalmer:

Firmware update instructions

File:Bootloader button.png

2024-11-04T15:03:02Z

Mbalmer:

Bootloader button

ZuluIDE Operations Guide

2024-11-03T04:31:39Z

Mbalmer: Initial save (incomplete; 1,381 words, 8 images)

ZuluIDE Operations Guide

2024-11-02T21:38:24Z

Mbalmer:

File:Qwiic cable.png

2024-11-02T21:14:02Z

Mbalmer:

A Qwiic cable.

File:Hardware interface (rev 2024a).png

2024-11-02T21:13:05Z

Mbalmer:

Hardware interface, revision 2024a

ZuluIDE Operations Guide

2024-11-02T20:10:59Z

Mbalmer:

File:DIP switches (ZuluIDE).png

2024-11-02T19:48:59Z

Mbalmer:

DIP switch block (ZuluIDE)

File:Molex 5.25" power connector (top).png

2024-11-02T19:39:59Z

Mbalmer:

Molex 5.25" power connector (top)

File:Molex 5.25" power connector.png

2024-11-02T19:39:33Z

Mbalmer:

Molex 5.25" power connector