Skip to content

Toolbox Developer Docs

Jump to bottom Edit New page
Eric Helgeson edited this page Sep 22, 2024 · 5 revisions

About

BlueSCSI Toolbox is a set of apps for vintage computers that uses SCSI Vendor commands to interact with the BlueSCSI. It allows the Host machine to do things like Change CD's, get or send files, and connect to Wi-Fi.

BlueSCSI Toolbox is currently on 5 platforms: Classic Macintosh, Amiga, NeXT, BeOS, and DOS/Win.

For BlueSCSI Toolbox usage, see Toolbox. The documentation below is for Toolbox Application Developers.

Identifying a valid BlueSCSI

A BlueSCSI Toolbox app must correctly identify that is talking to a BlueSCSI.

  • Scan the SCSI bus by sending an Inquiry 0x12 command.
  • Check the Inquiry vendor response. It will contain a text representation of the BlueSCSI Firmware version, eg: BlueSCSIv2024.05.22
    • Note: Some drive types can not support this additional vendor data such as Networking or ZIP drives.
  • Check the BlueSCSI Toolbox API Version (uint8) to ensure your app supports the API version. (See Versions below)
  • Once a BlueSCSI drive is found, send a MODE SENSE 0x1A command for page 0x31. Validate it against the BlueSCSIVendorPage (see: lib/SCSI2SD/src/firmware/mode.c)
  • To find all other devices this BlueSCSI is emulating (including Networking or ZIP) send the BLUESCSI_TOOLBOX_LIST_DEVICES command.
    • Note: there maybe be more than one BlueSCSI on the bus, so scan the rest of the ID's that are not handled by this BlueSCSI.

Versions

The current BlueSCSI Toolbox API Version is 0. If the version is not available or unset it is safe to assume it is 0.

Toolbox Apps must check the version to understand the compatibility of the APIs they are using. They also must give the user actionable error messages about updating the firmware or Toolbox app. This will be enforced when version 1 onward.

Version 1 is in active development. All breaking changes will be documented in GitHub Issues and Pull Requests with the Toolbox tag.

Main Features

Below is a high level overview of the main features available with BlueSCSI Toolbox. See the Commands section for detailed information on each command.

Receiving Files

The Host machine can read files directly off the SD card and write them to the Host.

To receive files

  • Count and list the files with BLUESCSI_TOOLBOX_COUNT_FILES 0xD2 and BLUESCSI_TOOLBOX_LIST_FILES 0xD0.
  • Use the file index and byte offset to transfer the desired file with BLUESCSI_TOOLBOX_GET_FILE 0xD1.

Sending Files

Sending files from the Host to the SD card is a three-step process:

  • BLUESCSI_TOOLBOX_SEND_FILE_PREP 0xD3 to prepare a file on the SD card for receiving.
  • BLUESCSI_TOOLBOX_SEND_FILE_10 0xD4 to send the actual data of the file.
  • BLUESCSI_TOOLBOX_SEND_FILE_END 0xD5 to close the file.

CD Changer

CD Changer allows you to list CD's of the currently selected target when using a CD Dir (eg: CD3 on the root of the SD card).

Apps must handle multiple CD drives on one (or many) BlueSCSI's on the same SCSI chain.

  • Count and list the current CD's BLUESCSI_TOOLBOX_COUNT_CDS 0xDA BLUESCSI_TOOLBOX_LIST_CDS 0xD7.
  • Set the Next CD by calling BLUESCSI_TOOLBOX_SET_NEXT_CD 0xD8
  • Instruct the Host operating system that the CD has changed.

WiFi

If your BlueSCSI has a Pico-W you can use it as a network adapter (on compatible hosts). The WiFi Toolbox commands allow you to scan for and join WiFi access points.

Commands

NOTE: All Toolbox commands CDB(Command Descriptor Block) length is 10.

BLUESCSI_TOOLBOX_COUNT_FILES 0xD2

Counts the number of files in the ToolBoxSharedDir (default /shared). The purpose is to allow the host program to know how much data will be sent back by the List files function.

This can be sent to any valid BlueSCSI target.

Example CDB:

D2:00:00:00:00:00:00:00:00:00

Example Response

00000000  08                                               '.'

BLUESCSI_TOOLBOX_LIST_FILES 0xD0

Returns a list of files in the ToolBoxSharedDir (Default /shared) in the following 40 byte struct:

typedef struct {
    unsigned char index;   /* byte 00: file index in directory */
    unsigned char type;    /* byte 01: type 0 = file, 1 = directory */
    char name[33];         /* byte 02-34: filename (32 byte max) + space for NUL terminator */
    unsigned char size[5]; /* byte 35-39: file size (40 bit big endian unsigned) */
} ToolboxFileEntry;

NOTE: File names are truncated to 32 chars - but can still be transferred. NOTE: You may need to convert characters that are valid file names on FAT32/ExFat to support the hosts native character encoding and file name limitations. NOTE: Currently the response is limited to 100 entries, Will return

Example CDB:

D0:00:00:00:00:00:00:00:00:00

Example Response:

00000000  00:01:6c:69:73:74:2e:74:78:74:00:00:00:00:00:00  '..list.txt......'
00000010  00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00  '................'
00000020  00:00:00:00:00:00:5f:9b:01:01:61:6d:65:6e:64:2d  '......_...amend-'
00000030  33:36:62:2e:73:69:74:00:00:00:00:00:00:00:00:00  '36b.sit.........'
00000040  00:00:00:00:00:00:00:00:00:00:00:00:00:00:b1:87  '................'
... snip ...

BLUESCSI_TOOLBOX_GET_FILE 0xD1

Transfers a file from the ToolBoxSharedDir (Default /shared) to the Host computer.

CDB[1] contains the index of the file to transfer.

CDB[2..5] contains the offset of the file in 4096 byte blocks.

Example CDB:

D1:07:00:00:00:00:00:00:00:00

Example response (This is some text in a test file):

00000000  74:65:73:74:66:69:6c:65:0a                       'testfile.'

NOTE: When offset is 0 the file is opened. When the last block is read it is closed.

BLUESCSI_TOOLBOX_TOGGLE_DEBUG 0xD6

Enable or disable Debug logs. Also allows you to get the current status.

If CDB[1] is set to 0 it is the subcommand Set Debug. The value of CDB[2] is used as the boolean value for the debug flag.

If CDB[1] is set to 1 it is the subcommand Get Debug. The boolean value is sent as a 1 byte value.

NOTE: Debug logs significantly decrease performance while enabled. When your app enables debug you MUST notify them of the decreased performance.

Example CDB (disable debug):

D6:00:01:00:00:00:00:00:00:00

Example CDB (debug status):

D6:01:0:00:00:00:00:00:00:00

Example response (debug on):

00000000  01                                               '.       '

BLUESCSI_TOOLBOX_SEND_FILE_PREP 0xD3

Prepares a file on the SD card in the ToolBoxSharedDir (Default /shared) for receiving.

The file name is 33 char name sent in the SCSI data, null terminated. The name should only contain valid characters for file names on FAT32/ExFAT.

If the file is not able to be created a CHECK_CONDITION ILLEGAL_REQUEST is set as the sense.

Example CDB (disable debug):

D3:00:00:00:00:00:00:00:00:00
newfile.txt\0 # File name In SCSI Data.

BLUESCSI_TOOLBOX_SEND_FILE_10 0xD4

Receive data from the host in blocks of 512 bytes.

CDB[1..2] - Number of bytes sent in this request.

CDB[3..5] - Offset in the file for these bytes.

If the file has a write error sense will be set as CHECK_CONDITION ILLEGAL_REQUEST. You may try to resend the block or fail and call BLUESCSI_TOOLBOX_SEND_FILE_END

BLUESCSI_TOOLBOX_SEND_FILE_END 0xD5

Once the file is completely sent this command will close the file.

Example CDB (disable debug):

D5:00:00:00:00:00:00:00:00:00

BLUESCSI_TOOLBOX_LIST_CDS 0xD7

Lists all the files for the current directory for the selected SCSI ID target. Eg: When selecting SCSI ID 3 it will look for a CD3 folder and list files from there. The structure is ToolboxFileEntry.

NOTE: Since there is no universal name for a CD image there is no filtering done on the lists of files.

BLUESCSI_TOOLBOX_COUNT_CDS 0xDA

Counts all the files for the current directory for the selected SCSI ID target. Eg: When selecting SCSI ID 3 it will look for a CD3 folder and count files from there.

Same response as BLUESCSI_TOOLBOX_COUNT_FILES.

BLUESCSI_TOOLBOX_SET_NEXT_CD 0xD8

Sets the next CD to the index of the file in the current directory for the selected SCSI ID target. Eg: When selecting SCSI ID 3 it will look for a CD3 folder and set the CD to the index of the file in that directory.

CDB[1] - File index.

Example CDB (Set Next CD to file at index 7):

D8:07:00:00:00:00:00:00:00:00

NOTE: You may need to instruct the Host system that the CD has been switched.

SCSI_NETWORK_WIFI_CMD 0x1C

All Toolbox Wi-Fi commands use sub-commands under 0x1C. Subcommands are under CDB[2]

SCSI_NETWORK_WIFI_CMD_SCAN 0x01

Starts a Wi-Fi scan for access points. A 1 byte boolean value is returned if the scan was successfully started or not.

NOTE: This operation is async.

SCSI_NETWORK_WIFI_CMD_COMPLETE 0x02

Check if the SCSI_NETWORK_WIFI_CMD_SCAN is finished. A 1 byte boolean value is returned.

SCSI_NETWORK_WIFI_CMD_SCAN_RESULTS 0x03

Requires SCSI_NETWORK_WIFI_CMD_COMPLETE to be complete. If not it will send a CHECK_CONDITION sense code.

Contains a list of up to 10 wifi_network_entry:

struct __attribute__((packed)) wifi_network_entry {
	char ssid[64];
	char bssid[6];
	int8_t rssi;
	uint8_t channel;
	uint8_t flags; // WIFI_NETWORK_FLAG_AUTH 0x1
	uint8_t _padding;
};

SCSI_NETWORK_WIFI_CMD_INFO 0x04

Returns the current wifi_network_entry struct.

SCSI_NETWORK_WIFI_CMD_JOIN 0x05

Instruct the Pico-W to join the Access Point information stored in wifi_join_request:

struct __attribute__((packed)) wifi_join_request {
	char ssid[64];
	char key[64];
	uint8_t channel;
	uint8_t _padding;
};

NOTE: This operation is async.

Unstable APIs

These APIs are not currently considered part of the major version of the API and may change before being added in.

BLUESCSI_TOOLBOX_LIST_DEVICES 0xD9

Responds with 8 bytes, Each bytes index corresponds to an image or device type this BlueSCSI is currently emulating.

NOTE: Currently, an unstable API and should not be relied on, will change in future versions.

Example CDB:

D9:00:00:00:00:00:00:00:00:00

Example Response:

00000000  ff:00:ff:02:06:07:00:ff                          '........'

Source

If there are any errors in the docs please refer to the source. Any clarifications or updates on the wiki is appreciated.

Using the BlueSCSI name or logo

If you would like permission to use the BlueSCSI logo or BlueSCSI name in your Toolbox application please reach out via our normal support channels.

Note: You may use verbiage in lines with "Compatible with BlueSCSI" if you don't wish to explicitly use the name or logo in your app.

BlueSCSI v1

Note BlueSCSI Toolbox API v0. Only Get and Send files is supported on BlueSCSI v1.

Add a custom footer

BlueSCSI Logo

Clone this wiki locally