Troubleshooting - BlueSCSI/BlueSCSI-v2 GitHub Wiki

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.

Resolving common issues:

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

[!Note] Advanced features, such as the ROM Drive, Initiator Mode, and WiFi DaynaPORT have their own pages with dedicated troubleshooting information.

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
  • 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 power is turned on. If your model has a TRM_ON jumper, check if it is enabled. In most cases termination power 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 you can't see a log.txt file:
      • Check the section About the LED patterns to see if your SD card has been detected.
      • Advanced users could also try using USB Serial Debug, which is covered on the Developers-(Advanced) page, to see if there is any log information.

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.

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.

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 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

About the LED patterns on the BlueSCSI

BlueSCSI_Ext_Blink

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, then check the section above About the LED patterns to see if your SD card has been detected. Advanced users can also try using USB Serial Debug, which is covered on the Developers-(Advanced) page, to see if there is any log information.

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.