Troubleshooting

If you run into an issue or your BlueSCSI is not working as expected please review the topics on this page.

Most problems can often be resolved by trying another SCSI cable, verifying termination settings, checking the jumpers or configuration of your BlueSCSI, using another power source (Berg or USB cable), or trying another SD card (see SD Cards for known good and known bad cards).

Resolving common issues:

Review the suggestions and answers below to try and narrow down or resolve your problem.

What to try first:

• Format your SD card with SD Memory Card Formatter tool with the “Overwrite format” option selected.
• Try a different SD card that is of another brand. Make sure it is Class 10 or better. See SD Cards for recommended brands and cards to avoid.
• Check for any known settings or issues for your vintage machine on the Compatibility page.
• Update to the latest version of the BlueSCSI firmware.
• Try powering the BlueSCSI via the USB port on the Raspberry Pi Pico board (1Amp at least).
• Use only one image on the SD card and ensure the file name follows the required naming requirements.
  Try one of the premade hard drive images from the Bluescsi Images page.
• Remove all other SCSI devices from the chain. Confirm your SCSI cables and terminators are working and connected properly.
• Disable the ROM drive if present. In some cases it may be necessary to erase the ROM drive and reflash BlueSCSI firmware.
• Review your board jumpers and configuration. If your model has a PWR_ON jumper, check if it is connected.
• Check if termination is turned on. If your model has a TRM_ON jumper, check if it is enabled. If BlueSCSI is the last or the only device on the SCSI cable, termination should be set to on. However, you can try toggling it on or off.

The BlueSCSI isn’t being recognized by my computer or device:

• Review the above steps in the General Troubleshooting Tips section.
• Check for any known issues or gotchas on the Compatibility page. Some computers require a special .ini file for their configuration.
• If you have a Desktop 2023.09a or Desktop 2023.10a version verify the setting of the Initiator / Target jumper block. For general use, the jumper should be on the Target side. Only place the jumper on the Initiator side when using Initiator Mode.
• Some computers do not provide any, or not enough, termination power for the BlueSCSI to properly function, even if the LED appears to be on. Try using an external power source, such as a Berg power or USB charger (1Amp) to power the device. The log.txt file on the BlueSCSI’s SD card will record the voltage detected on the Pico board to help you troubleshoot any low power problems.
• Check the log.txt file to verify the BlueSCSI sees the disk images you placed on the SD card and note any errors. If log.txt is missing, empty, or the board does not enumerate as USB serial, follow the No log.txt section below.

The BlueSCSI isn’t seeing my SD card (the LED flashes 5 times in a pattern)

• Format with SD Memory Card Formatter tool with the “Overwrite format” option selected. Remember to always backup your data before you erase your SD card.
• Try another brand or type of SD card. If possible, verify the SD card works in another system. See SD Cards.
• Re-seat the SD card in the slot. On socketed boards, gently push the card fully home; on kit-assembled boards, inspect the SD slot solder joints.

The BlueSCSI doesn’t mount or show any of my disk images (the LED flashes 3 times in a pattern)

• Verify you are using the correct naming mechanism for disk images. See the Usage page for file name requirements.
• Check that your disk image is valid or formatted correctly. For example, some Macintosh emulators can create disk images that are not initially compatible with the BlueSCSI unless modified.
• If you assembled a kit that required you to solder the SD card socket, carefully check your soldering work on the SD card slot.
• If the SD Card is being used in RAW mode it is normal for the LED to flash 3 times.

No log.txt, empty log.txt, or no USB serial enumeration

These three symptoms have the same family of causes. The SD card is the most common culprit; power and the USB cable are next. Work through the checks in order.

1. Confirm the BlueSCSI is powered

• The PWR LED must be lit. If it is not, the board is not getting power.
• If you are relying on SCSI termination power, switch to USB or Berg power instead. Some hosts (Mac Plus, Portable, some PowerBooks via HDI-30) do not supply termination power at all. See the Compatibility page for host-specific notes.
• Measure the PWR_ON header voltage; below 4V means the host is not providing enough termination power.

2. Check the Pico LED pattern (does the firmware see the SD card?)

3. The SD card is detected but log.txt is missing, empty, or truncated

This almost always means the SD card itself is unreliable, even if it tests fine in a card reader. Cycling through brand-new cards from the same vendor often does not help, since they share the same controller quirks.

• Reformat the card with SD Memory Card Formatter using Overwrite format (not Quick).
• If a fresh recommended card still produces an empty or truncated log, suspect the SD slot wiring. On a kit-assembled board, inspect the SD socket solder joints with magnification.

4. The board does not appear as USB serial when plugged into a computer

Whether the board enumerates as serial is independent of whether log.txt is written, but the two symptoms often appear together because both depend on firmware reaching its main loop, which in turn depends on the SD card initializing.

• Verify the micro USB cable is a data cable, not charge-only. Many short cables shipped with phones or accessories are charge-only. Use a cable you have previously used to flash a microcontroller.
• Plug directly into the computer, not through a USB hub.
• Try a different USB port.
• If the board still does not enumerate, work through steps 1-3 above. A firmware that cannot mount the SD card may bail out before bringing up the USB serial interface.

5. Still no log

• Try the USB Serial Debug procedure on the Developers (Advanced) page to capture any boot output that may never reach the SD card.
• Reflash the latest firmware from the BlueSCSI releases page. See Updating Firmware (and note step 4 above if the board will not appear as RPI-RP2).
• If you have a second BlueSCSI, swap the SD card into it to isolate whether the card or the board is at fault.

Resolving specific issues

The external activity LED does not light up. When the computer accesses an emulated disk drive the activity LED remains dark.

• Confirm the polarity of the LED to ensure it is installed correctly
• The computer may not be providing enough termination power on the SCSI bus. Measure the voltage on the PWR_ON header with a multimeter. If this measures below 4 volts try supplying external power through the Berg connector on the BlueSCSI.

On a Macintosh system the Pico board LED flashes and a flashing question mark with a floppy disk or a folder is shown on the screen.

• The flashing question mark icon indicates that the Mac cannot find a suitable version of the Mac OS to boot from on your disk image
• Verify that a compatible version of the Mac OS is installed on your disk image.
• If you are using a disk image created by or for a Mac emulator this will likely not work on the BlueSCSI because it is missing a SCSI driver. In some cases the Disk Jockey program can install an appropriate SCSI driver onto an existing disk image.
• Use a premade disk image with an OS already installed or a premade blank disk image and install an OS using physical or virtual installation media. These disk images can be found on the Bluescsi Images page.
• Use Disk Jockey to create a new BlueSCSI compatible disk image and install an OS using physical or virtual installation media.
• Ensure that your disk image size does not exceed any size limits for your Mac OS version or system hardware.

I’m using a known good SD card and disk image but my system won’t boot from the BlueSCSI.

• Disable the ROM drive if present. In some cases it may be necessary to erase the ROM drive and reflash BlueSCSI firmware.
• Check for any known issues or gotchas on the Compatibility page. Some computers require a special .ini for their configuration.
• Remove all other SCSI devices from the chain. Confirm your SCSI cables and terminators are working and connected properly.
• Check if termination power is turned on. In most cases termination power should be set to on. However, you can try toggling it on or off.
• Check the log.txt file to verify the BlueSCSI is identifying the disk images.
• If your Mac has the internal HD connected, it will be device 0, so make sure you name your disk image as 1 or higher(up to 6).

The log file shows scsiHostWrite: sent N bytes, expected M (Initiator Mode)

This message means the target device dropped out of the DATA_OUT phase before BlueSCSI finished sending its bytes. In practice this is almost always a cable problem, not a firmware or drive bug.

• Replace the SCSI cable with a known-good, short (under 1 meter) cable. Old ribbon and IDC cables degrade with age and corrosion and are the most common cause of this error.
• Re-seat both connectors and verify pin 1 / keying orientation.
• Verify termination on both ends of the bus is correct.
• Only after a fresh cable still fails should you suspect the target drive or BlueSCSI firmware. See Initiator Mode for more imaging-specific guidance.

The log file shows a “scsi_accel_rp2040_finishRead timeout” error.

• This indicates that your SD card may be too old or slow to keep up with the SCSI bus of your system. Try a newer or faster speed SD card.
• You may also try and format your SD card with the SD Memory Card Formatter tool with the “Overwrite format” option selected.

A Macintosh PowerBook will hang during boot when a BlueSCSI is externally connected via an HDI-30 SCSI port to DB-25 adapter

• Some PowerBooks do not provide termination power and cannot supply power to the BlueSCSI. Connect a USB power adapter (1A) to the port on the Raspberry Pi Pico board to properly power the BlueSCSI.

My external BlueSCSI is not working with my Macintosh Plus computer.

• The Macintosh Plus uses an early implementation of the SCSI standard and requires some special configuration to get it working. See the Compatibility page and download the .ini file for the Macintosh Plus.
• In addition, the Macintosh Plus does not provide termination power. You’ll need to power the BlueSCSI via a USB power adapter (1A) or perform a diode modification on the logic board.
• FYI - the Macintosh Portable requires the same .ini file as the Macintosh Plus and also requires you to power the BlueSCSI via a USB power adapter (1A) as it does not provide termination power.

I am seeing log messages stating “SDIO card reports write CRC error”

• Update to the latest firmware release, the SDIO interface has been improved to decrease the likelihood of seeing these errors
• If these errors persist after updating to the latest firmware, then in all releases since v2024-10-21 (nightly), you can try adding the following INI file configuration option:

[SDIO]
AddClockDelay=1

• This setting should make BlueSCSI more able to tolerate electrically noisy environments
• If adding some clock delay resolves the write CRC errors then consider adding EMI shielding around BlueSCSI to decrease electrical noise propagation from other components in your system

BlueSCSI doesn’t recognize my files but they look correct on the SD card (Windows hidden file extensions)

Windows hides known file extensions by default. This means a file you saved as bluescsi.ini may actually be bluescsi.ini.txt, or a disk image like NE4.hda may actually be NE4.hda.txt. Because the real extension is hidden, the files will appear correct in File Explorer but BlueSCSI will not recognize them.

• Check the log file first. The firmware will warn you if it detects this problem. Look for messages like:

WARNING: Config file with incorrect file extension found: bluescsi.ini.txt

• To fix this, make file extensions visible in Windows:
  1. Open File Explorer
  2. Click View in the toolbar
  3. Check File name extensions (on Windows 11, go to View → Show → File name extensions)
  4. Rename any files that now show double extensions (e.g. rename bluescsi.ini.txt to bluescsi.ini)
• Tip: When creating new files on Windows, such as bluescsi.ini, use Notepad and choose Save As with the “All Files (*.*)” file type selected instead of “Text Documents (.txt)”. This prevents Windows from silently adding a .txt extension.

BlueSCSI does not appear as a USB drive when updating firmware

During a firmware update the Pico board should enumerate on your computer as a USB drive named RPI-RP2. If it does not appear:
* Verify the micro USB cable is a data cable, not charge-only. Many short cables shipped with phones, headphones, or other accessories are wired for charging only. Try a different cable known to carry data, such as one you’ve used to flash other microcontrollers, or one that came with a SATA/USB enclosure.
* Plug the BlueSCSI directly into the PC, not through a USB hub.
* Try a different USB port.

About the LED patterns on the BlueSCSI

The BlueSCSI has two LED lights for power and activity (labeled PWR and ACT), in addition the Raspberry Pi Pico board has a single LED. When power is applied to the BlueSCSI the pattern of these LEDs can help you troubleshoot common issues. Below is a summary of what the LEDs indicate and what patterns to look out for.

• The PWR LED on the BlueSCSI is illuminated. This power light indicates the board is receiving power.

• The ACT LED on the BlueSCSI is blinks. This activity light indicates the BlueSCSI is being read or written to by your computer or device.

• The LED on the Pico board flashes 5 times, this indicates that the BlueSCSI does not detect a valid SD card. Try another brand or type of SD card and ensure it is making a secure connection. You should also try formatting the SD card using the SD Memory Card Formatter tool with the “Overwrite format” option selected.

• The LED on the Pico board flashes 3 times, this indicates that the BlueSCSI cannot find any valid disk images. If this happens, verify you are using the correct disk image file naming convention detailed on the Usage page.

Log file functionality

The BlueSCSI automatically creates a helpful log file on your SD card when it’s powered on. This can be very helpful in troubleshooting common issues or simply confirming information, such as the amount of voltage your Raspberry Pi Pico board is getting, or if your hard drive images are being detected properly.

Every time your BlueSCSI gets power a log.txt file is written to the root directory of your SD card. Please note, the log file is overwritten every time the BlueSCSI is turned on, so be sure to copy your log file to your PC if you need to save it.

If you do not see a log file, see the No log.txt section for a step-by-step decision tree. The most common cause is an unreliable SD card, see SD Cards for recommended brands.

Enabling Debug mode for advanced logs:

You can optionally enable a debug mode to log additional information to the log file. This may help you narrow down a specific issue. To do this create a new text file named bluescsi.ini and place it in the root directory of your SD card. Edit this .ini file with the following text:

[SCSI]
Debug=1

Save the file and ensure the file extension is .ini and not .txt or txt.ini or anything else. The next time the BlueSCSI is powered on a more detailed log file will be generated.

Reporting an issue

If you need to report an issue it’s important to provide as much information as possible so others can better assist you. Take the following steps when reporting an issue or requesting support from others:

• Be calm, patient, and kind. This project is supported by a community of enthusiasts, not a paid staff or support team.
• Specify your BlueSCSI hardware model (e.g. Desktop) and version (e.g. 2023.03a)
• Detail the computer system or device you are using it with
• Note the brand and size of the SD card and if it is new or used
• Include the full log.txt file and if present the err.txt file
• Consider enabling debug mode via the bluescsi.ini file, this toggles more technical data and details to appear in the log.txt file and may help identify your issue.

Additional support

If you are still experiencing an issue you can use these community powered support options to ask for help. Remember to be calm, patient, and understanding when asking for help from others.

• Open Retro SCSI Discord
• TinkerDifferent Forum
• GitHub Discussions