PsxNewLib - Playstation controller interface library for Arduino
Created by SukkoPera. I am just trying to add rumble support.
PsxNewLib is an Arduino library that allows interfacing controllers designed for the Sony PlayStation and PlayStation 2 with Arduino boards.
When I started developing my PlayStation to Commodore adapter, I originally used the famous library by Bill Porter to interface with the controller. This seemed to work well initially, but then a number of issues surfaced:
- It does not support non-DualShock controllers, which basically rules out all the excellent arcade sticks made for the PlayStation.
- It only supports bit-banging the protocol. This means that it can work on any pins, but since the protocol is essentially SPI, we could let the hardware take care of it, making communication more reliable.
- It just didn't work with some controllers, due to timing issues.
- It looks more like a quick hack at the code level, rather than a polished and maintainable library.
In order to take of these issues, I started working on a new library, and so PsxNewLib was born.
Features
Currently, PsxNewLib provides access to the status of all digital buttons, analog sticks (on DualShock and later controllers) and analog buttons (on DualShock 2 and later controllers). It also provides functions to enable and disable the analog sticks and buttons.
It does NOT allow driving the vibration motors available on DualShock and later controllers. I'm not interested in this feature, but if you are, please open an Issue saying so. If many people ask, I will look into it.
Using the Library
First of all you must decide whether you want to use the hardware SPI pins or not. According to this, you either have to instantiate a PsxControllerHwSpi or PsxControllerBitBang object. Then you can just refer to the example sketches to learn how to use this library, as the interface should be quite straightforward.
The API has a few rough edges and is not guaranteed to be stable, but any changes will be to make it easier to use.
Among the examples, there is one which will turn any PlayStation controller into a USB one simply by using an Arduino Leonardo or Micro. It is an excellent way to make a cheap adapter and to test the controller and library.
Wiring the Controller
Follow the pinout in the following picture from the amazing CuriousInventor PS2 Interface Guide:
You are advised not to rely on wire colors, but rather on pin positions. The wires in the image come from an official Sony controller, I expect their colors to be fairly consistent among all Sony controllers, but you shouldn't really trust them.
I recommend using 3.3V power and signal levels. While everything will appear to work fine at 5V, PlayStation controllers are not made to work at that voltage and they will break sooner or later. Many of the tutorials out there ignore this fact, but they really shouldn't. You have been warned.
In order to make things as safe and straightforward as possible, I have also designed an Arduino shield that will work perfectly with this library. Please check it out and use it as your reference for all connections.
Compatibility List
PsxNewLib aims to be compatible with all devices. I expect this to be the case with all the official controllers produced by Sony. Third-party devices should also work anyway. If you find one that doesn't work, please open an issue and I'll do my best to add support for it.
The following table contains the results of my tests, all done at 3.3V voltage level through my OpenPSX2AmigaPadAdapter:
Debugging
If you have problems, uncomment the DUMP_COMMS
#define in PsxNewLib.h and watch your serial monitor.
Releases
If you want to use this library, you are recommended to get the latest release rather than the current git version, as the latter might be under development and is not guaranteed to be working.
Every release is accompanied by any relevant notes about it, which you are recommended to read carefully.
License
PsxNewLib is released under the GNU General Public License (GPL) v3. If you make any modifications to the library, you must contribute them back.
PsxNewLib is provided to you ‘as is’ and without any express or implied warranties whatsoever with respect to its functionality, operability or use, including, without limitation, any implied warranties of merchantability, fitness for a particular purpose or infringement. We expressly disclaim any liability whatsoever for any direct, indirect, consequential, incidental or special damages, including, without limitation, lost revenues, lost profits, losses resulting from business interruption or loss of data, regardless of the form of action or legal theory under which the liability may be asserted, even if advised of the possibility or likelihood of such damages.
Thanks
- Bill Porter for the original library.
- CuriousInventor for their excellent interfacing guide.
- All the other guys who helped understand how the PSX controller protocol works.