USBJoystick 0.24
Posted: Fri Oct 02, 2026
USBJoystick is a USB joystick driver for RISC OS 5. It supports USB HID-compliant joystick (or gamepad, or steering wheel etc.), including the XBOX 360 wired and wireless controllers. It provides the legacy Acorn, RTFM and SerialPort SWI interfaces, so existing games can be used with modern controllers.
What’s new?
Download
Version 0.24 is attached to this post (source and binary)
Full driver source is here: https://gitlab.riscosopen.org/rwalker/usbjoystick
Full configuration plug-in source is here: https://gitlab.riscosopen.org/rwalker/joysetup
Requirements
You need a RISC OS 5 machine with USB hardware. I have only tried a Pi model B+. In theory, any USB HID-compliant joystick will work, but again, I have only tried what I have:
SparkFS (or similar) will be needed to open the attached zip file. Then read the 'ReadMe' file.
Starting
The bare-minimum would be to double-click the module inside the !System distribution in the archive, but that is not optimal.
The correct approach is explained in the ReadMe file in the archive (merge the driver and the plugin into !Boot/!System and get USBJoystick loaded when your OS boots).
Documentation and Examples
Within the USBJoystick source code, there is a 'doc' directory which explains how USBJoystick works and the SWIs on offer.
USBJoystick offers some *commands, and you can explore these with '*Help USBJoystick'.
There is also a 'utils' directory, containing some BASIC test applications:
Enumeration
Joysticks will be discovered when the module starts. If you connect a joystick later on, it should be automatically detected (without restarting the module). Similarly, if you disconnect a joystick, the module will stop talking to it.
Mapping
The classic Acorn and Serial Port Joystick APIs refer to joysticks by a joystick number (0 or 1, for player 1 and 2 respectively). Note that the RTFM and Serial Port APIs only support one or two joysticks, but the Acorn API can support many more.
Each joystick number can offer two directional axes, typically up/down (Y) and left/right (X). A modern USB joystick will have multiple analogue axes (X, Y, Z, RX, RY, RZ) and separate digital inputs (DPAD or HAT switches). The desired USB axes need to be 'mapped' to the legacy number, X axis and Y axis.
You can map up to 16 buttons, but these will only work independently with the Acorn Joystick APIs. Games using the Serial Port or RTFM API will see a 'fire' when any of the buttons are pressed.
You can see the mapping with *USBJoystick_Mappings or use the configuration plug-in. If the automatic mapping is not suitable, you can customise it - again, with the *commands or the plug-in.
Acorn I/O Podule Analogue to Digital converter
USBJoystick can emulate the ADC converter found on the I/O podule. It hooks into OSByte 128, so software using this SWI (including BASIC’s ADVAL function) will work. You can map an axis, or part of an axis, to an ADC channel, and a pair of buttons for fire. Please investigate the *command help: there is some mapping required.
The partial mapping is useful for configurations like a single Y axis (0 for middle, +32768 for top, and -32767 for bottom), where you want to map ADC Channel 0 to ‘up’ (so 0 to 32768 will be translated to 0 to 65520) and Channel 1 to ‘down’ (so 0 to -32767 will be translated to 0 to 65520).
Note that the configuration plug-in does not fully expose the range mapping yet. That will come in a future version.
Using the Joystick
Once you have mapped, you can use any software which supports the Acorn (SWI Joystick_Read) or Serial Port (SWI Joystick_Status). The USB Joystick driver module will transform the USB data into a format for those SWIs, and respond to their requests. With the help of ADFFS, games which use the RTFM API should also function.
I have tried some of the games from this web site: James Pond and SWIV work over the Serial Port SWI, and Zool works over the Acorn SWI.
Testing
Obviously, this thing is far from finished. It clearly needs more testing: one machine, two USB joysticks, and three games doesn’t really cut it!
All feedback is welcome.
Technical matters
If you have any problems with the module, it would be helpful if you could run Reporter before you run the module. If Reporter is active, some debugging guff will appear in Reporter’s log. This may help me! Reporter is available here: http://www.avisoft.f9.co.uk/Reporter.htm
The *command *USBJoystick_Debug 0 (replacing 0 for your joystick id, or removing it entirely to see all) may also provide useful information for me.
The output from Colin Granville's USBDescriptors may be useful.
Acknowledgements
Jon’s efforts with JASPP itself was my inspiration for developing this (obviously, this is tiny effort in comparison!). There are further acknowledgements in the release archive.
What’s new?
- Mapping/binding interface re-vamped: UI, *commands and SWI interface
- The full source code is included in the archive
- ReadMe file explaining how to install
- Boot and System merge sets for installation
- A script to make USBJoystick load during the OS boot-up
Download
Version 0.24 is attached to this post (source and binary)
Full driver source is here: https://gitlab.riscosopen.org/rwalker/usbjoystick
Full configuration plug-in source is here: https://gitlab.riscosopen.org/rwalker/joysetup
Requirements
You need a RISC OS 5 machine with USB hardware. I have only tried a Pi model B+. In theory, any USB HID-compliant joystick will work, but again, I have only tried what I have:
- a USB-Atari interface, with an old Atari joystick, and a Chinese knock-off MegaDrive pad
- a wireless XBOX360-style controller (a Chinese clone, not a real Microsoft one!)
SparkFS (or similar) will be needed to open the attached zip file. Then read the 'ReadMe' file.
Starting
The bare-minimum would be to double-click the module inside the !System distribution in the archive, but that is not optimal.
The correct approach is explained in the ReadMe file in the archive (merge the driver and the plugin into !Boot/!System and get USBJoystick loaded when your OS boots).
Documentation and Examples
Within the USBJoystick source code, there is a 'doc' directory which explains how USBJoystick works and the SWIs on offer.
USBJoystick offers some *commands, and you can explore these with '*Help USBJoystick'.
There is also a 'utils' directory, containing some BASIC test applications:
- ADCTest: tests the I/O module ADC OSByte interface)
- AcornTest: tests the Acorn 8-bit and 16-bit Joystick_Read SWI
- Acorn2Test: tests the new prototype device read SWIs
- RTFMTest: tests the RTFM interface - this is not currently usable
- SerPortTest: tests the Serial Port (Vertical Twist) Joystick_Status SWI
Enumeration
Joysticks will be discovered when the module starts. If you connect a joystick later on, it should be automatically detected (without restarting the module). Similarly, if you disconnect a joystick, the module will stop talking to it.
Mapping
The classic Acorn and Serial Port Joystick APIs refer to joysticks by a joystick number (0 or 1, for player 1 and 2 respectively). Note that the RTFM and Serial Port APIs only support one or two joysticks, but the Acorn API can support many more.
Each joystick number can offer two directional axes, typically up/down (Y) and left/right (X). A modern USB joystick will have multiple analogue axes (X, Y, Z, RX, RY, RZ) and separate digital inputs (DPAD or HAT switches). The desired USB axes need to be 'mapped' to the legacy number, X axis and Y axis.
You can map up to 16 buttons, but these will only work independently with the Acorn Joystick APIs. Games using the Serial Port or RTFM API will see a 'fire' when any of the buttons are pressed.
You can see the mapping with *USBJoystick_Mappings or use the configuration plug-in. If the automatic mapping is not suitable, you can customise it - again, with the *commands or the plug-in.
Acorn I/O Podule Analogue to Digital converter
USBJoystick can emulate the ADC converter found on the I/O podule. It hooks into OSByte 128, so software using this SWI (including BASIC’s ADVAL function) will work. You can map an axis, or part of an axis, to an ADC channel, and a pair of buttons for fire. Please investigate the *command help: there is some mapping required.
The partial mapping is useful for configurations like a single Y axis (0 for middle, +32768 for top, and -32767 for bottom), where you want to map ADC Channel 0 to ‘up’ (so 0 to 32768 will be translated to 0 to 65520) and Channel 1 to ‘down’ (so 0 to -32767 will be translated to 0 to 65520).
Note that the configuration plug-in does not fully expose the range mapping yet. That will come in a future version.
Using the Joystick
Once you have mapped, you can use any software which supports the Acorn (SWI Joystick_Read) or Serial Port (SWI Joystick_Status). The USB Joystick driver module will transform the USB data into a format for those SWIs, and respond to their requests. With the help of ADFFS, games which use the RTFM API should also function.
I have tried some of the games from this web site: James Pond and SWIV work over the Serial Port SWI, and Zool works over the Acorn SWI.
Testing
Obviously, this thing is far from finished. It clearly needs more testing: one machine, two USB joysticks, and three games doesn’t really cut it!
All feedback is welcome.
Technical matters
If you have any problems with the module, it would be helpful if you could run Reporter before you run the module. If Reporter is active, some debugging guff will appear in Reporter’s log. This may help me! Reporter is available here: http://www.avisoft.f9.co.uk/Reporter.htm
The *command *USBJoystick_Debug 0 (replacing 0 for your joystick id, or removing it entirely to see all) may also provide useful information for me.
The output from Colin Granville's USBDescriptors may be useful.
Acknowledgements
Jon’s efforts with JASPP itself was my inspiration for developing this (obviously, this is tiny effort in comparison!). There are further acknowledgements in the release archive.