BBC USB Tools and Programs ========================== J.G.Harston 20-Dec-2018 USB support tools and utilities for DataCentre style BBC USB interfaces, see retroclinic.com/acorn/datacentre/datacentre.htm. Files ===== USBROM/src, USBROM - USB Support ROM, keyboard, printer, mouse drivers USBKBD/src, USBKBD - transient USB keyboard driver USBPRN/src, USBPRN - transient USB printer driver USBKeyMap - keymap and keyboard layouts HIDcodes - list of HID keycodes HIDcodes/gif - keyboard diagram labelled with HID keycodes USBFiler - navigate and transfer files to/from USB drives USBtoDisk, DiskToUSB - copy whole disk images to/from USB drives USBLib - low-level USB control library. USBSTATUS - display status table of USB devices MSEDEMO, KBDDEMO, PRNDEMO - demo programs USBDUMP, USBTEST - test programs USB Support ROM =============== Sideways ROM of USB support tools and device drivers. The ROM image has a relocation table so it can be included as a Sideways Module. Supported commands are: *USBDEVICES - lists all USB devices currently plugged in. *USBKBD |OFF - enables or disables USB keyboard *CONFIGURE USBKBD |OFF - configure USB keyboard *USBMOUSE ON|OFF - select a USB mouse *CONFIGURE USBMOUSE ON|OFF - configure USB mouse *USBPRINT ON|OFF - select a USB printer *CONFIGURE USBPRINT ON|OFF - configure USB printer *RESET () - cause a reset as though Break pressed *USBDEVICES ----------- Lists all the USB devices currently plugged in in the following format. Num Adr Prt Type 00 01 02 HUB 09 00 Hub 01 02 01 BMD 08 50 Disk 02 03 01 HID 03 01 Keyboard 03 03 01 OTH 0B 00 Card 04 04 01 HID 03 02 Mouse 05 05 01 PRN 07 02 Printer The device types are: HUB hub HID Human Interface Device (eg keyboard) OTH other PRN Printer BMD Block Media Device (eg disk) RES Reserved CDC Communication Device SER Serial interface *USBKBD |OFF - select a USB keyboard *CONFIGURE USBKBD |OFF - configure USB keyboard ---------------------------------------------------- Selects or disables a USB keyboard. It hooks into the BBC's KEYV and EVENTV to do background keyboard processing in parallel to the BBC's own keyboard. The layout is specified with the country . Normally the Break key causes a system reset, if bit 3 of is set then the Break key generates top-bit character &8A. The keyboard numbers recognised are: causes a reset is function key &8A 1 UK 32 Japan (same as BBC/ECMA) 9 UK 40 Japan 2 BBC/ECMA 48 USA 10 BBC/ECMA 56 USA Any other keyboard number will give inconsistent results. *USBKBD with no parameter displays the current setting. If any other USB device is selected, *USBKBD takes priority and disables them. Note: the Print key is f0, End is COPY, Shift-0 gives underline, BS and DEL both generate CHR$127, PageUp and PageDown generate Shift-Up and Shift-Down. Alt modifies top-bit-set keys (eg function and editing keys) in the same way as pressing both Shift and Ctrl. The driver currently does not set the USB keyboard LEDs, just the main keyboard LEDs. The configuration setting is stored in the 'Country' setting in CMOS byte 19. *STATUS will display the current configuration. *USBPRINT ON|OFF - select a USB printer *CONFIGURE USBPRINT ON|OFF - configure USB printer -------------------------------------------------- Selects or disables a USB printer. *USBPRINT ON enables the USB printer, claims the User Printer Vector, and selects it with *FX5,13. *USBPRINT OFF disables the USB printer and releases the User Printer Vector, but does not change the *FX5 setting. *USBPRINT with no parameter displays the current setting. If another USB device is already selected, attempting to select the USB printer will generate a 'USB already in use' error. *USBMOUSE ON|OFF - select a USB mouse *CONFIGURE USBMOUSE ON|OFF - configure USB mouse ------------------------------------------------ Selects or disables a USB mouse. *USBMOUSE with no parameter displays the current setting. If another USB device is already selected, attempting to select the USB mouse will generate a 'USB already in use' error. When a mouse is enabled: ADVAL(7) returns the X coordinate ADVAL(8) returns the Y coordinate ADVAL(9) returns the mouse buttons %xxxxxRML, set if button is pressed INKEY-10 returns the Left button state INKEY-11 returns the Middle button state INKEY-12 returns the Right button state Also, OSWORD 64 returns: XY+0,1 mouse X coordinate XY+2,3 mouse Y coordinate XY+4 text X position XY+5 text Y position XY+6 buttons %RMLxxxxx, clear if button is pressed *RESET (), OSBYTE 163,253 - cause a Reset ---------------------------------------------- If configured, pressing Break on the USB keyboard will cause a reset as though Break on the system keyboard was pressed. This functionality is exposed via OSBYTE 163,253,num and *RESET . The parameter is the reset type as returned by OSBYTE 253: 0=Soft reset (Break) 1=PowerOn reset (Power On) 2=Hard reset (Ctrl-Break) Transient USB keyboard driver ============================= USBKBD/src is the source for *USBKBD a transient USB keyboard driver. It functions the same as the ROM-based *USBKBD, but without the Break key functionality. It has no way to select the keyboard identity, so change the kbd%= line to change the keymapping. Transient USB printer driver ============================ USBPRN/src is the source for *USBPRN a transient USB printer driver. It functions the same as the ROM-based *USBPRINT. USBFiler, USBtoDisk, DiskToUSB, etc. ==================================== Programs to read and write files and disk images to and from USB storage devices. USBLib ====== Low-level USB control library. Test and demo programs ====================== USBSTATUS --------- BASIC program that displays USB host status and table of information of all devices plugged in reported by QD command. MSEDEMO ------- RetroClinic USB mouse demo, showing how to read messages from a mouse. KBDDEMO ------- USB keyboard demo, showing how to read messages from a keyboard. PRNDEMO ------- USB printer demo, showing how to send text to a printer by sending a text file to a USB printer. The file can have LF, CR, LFCR or CRLF line endings, and TABs are expanded. USBDUMP, USBTEST ---------------- Some USB test programs. Problems, issues and technical information ========================================== The version 1 DataCentre uses the Vinculum VNC1L USB host. It fails when communicating with devices plugged in via a hub. They can be enumerated, but after selecting the with the SC command trying to read data from them with the DRD command consistantly returns Command failed. USBSTATUS shows that it doesn't allocate a large enough input channel from hub-connected devices. The version 2 DataCentre uses the Vinculum VNC2 USB host. It allows a device on a hub to be selected. However, selecting a Human Interface Device (a keyboard or mouse) either as the sole device or plugged in via a hub slows the computer to an unusable speed, and then stalls it. This seems to be consistant with reports that using a HID device with the VNC2 results in the VNC2 receiving runaway unwanted interupts, slowing the VNC2 more than 300-fold. See: http://joshp.no-ip.com:8080/vnc2/#issue1 The QD command will only return binary data if the Short Command Set is used as well as binary responses selected with the IPH command. I haven't been able to work out how to request a HID Descriptor from a keyboard. I haven't been able to work out how to send a LED command packet. The configuration setting is stored in the 'Country' CMOS byte 19 as: b7: USBPRINT ON b6: USBMOUSE ON b5-b0: USBKBD , 0=OFF, b3=BREAK returns ASCII keypress When the USB keyboard driver is active the keytable OSBYTEs are used as workspace: OSBYTE &AC: last keypress OSBYTE &AD: &80+keyboard number %11xxxxxx indicates only MOS keyboard active %10xxxxxx indicates keyboard extension active (USB keyboard) %0xxxxxxx indicates International Keyboard active Other memory locations used are: &0096: key modifier workspace (Ctrl/Shift/Alt) &0800/1: old EVNTV when USBKBD active &0802/3: old KEYV when USBKBD active &0802/3: old UPTV when USBPRINT active &0D9B/C: old BYTEV when USBMOUSE active &0D92-7: Mouse coordinates &0D98: Mouse buttons The following errors can be generated: 149,"Vectors claimed" - EVNTV, KEYV, UPTV or BYTEV already point to a sideways ROM 194,"USB already in use" - USB device already being used 210,"USB not present" - no USB hardware found 214,"No keyboard" - no USB keyboard present 252,"Bad number" - a 0-255 was expected 254,"Bad command" - *CONFIGURE with a missing parameter