sukkopera / psxnewlib

Playstation controller interface library for Arduino

PsxNewLib - PlayStation Controller Interface Library for Arduino

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.

Since v0.4, it also allows driving the vibration motors available on DualShock and later controllers.

It is compatible with a large number of different controller models, including the GunCon/G-Con light gun by Namco. Please see below for a list of which have been tested so far.

Using the Library

First of all, please note that this library depends on greiman's DigitalIO library, which you need to install as well. Unfortunately, the version that is available in the Library Manager has a bug that might cause an error during compilation. Because of this, I recommend not to install it through the Library Manager, but rather to get the master version and install it manually. You can also do that with my fork, which supports a few more platforms.

Moving on to the code, you need to 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

As the following picture from the amazing CuriousInventor PS2 Interface Guide shows, PlayStation controllers use 9 pins:

Pin #	Signal	Direction	Notes
1	Data	Controller -> PlayStation	Open Collector
2	Command	PlayStation -> Controller
3	Motor Power		7.5V
4	Ground
5	Power		3.6V
6	Attention	PlayStation -> Controller
7	Clock	PlayStation -> Controller
8	(Unknown)
9	Acknowledge	Controller -> PlayStation	Open Collector

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.

TL;DR

Just follow the PsxControllerShield schematics but with 1k pull-ups:

• Power the controller at 3.3V.
• Don't bother with Motor Power unless you wanna rumble.
• Connect all signals with proper level shifting and 1k pull-ups.

Power

When plugged in a real PlayStation console, controllers are powered with 3.6V on pin 5. There are (too) many tutorials and videos out there that suggest that powering the controller at 5V is just fine, but the truth is that it is not: PlayStation controllers are not made to work at that voltage and they WILL break sooner or later. You have been warned.

Now, I know 3.6V regulators aren't exactly common. An LM317 could be used but it requires extra resistors to set the output voltage and as such it is prone to errors. 3.3V seems close enough though, there are plenty of regulators for that voltage and my experience seems to suggest that all PSX controllers work just perfectly with this slight undervoltage, which is definitely safer than powering everything at 5V. Most conveniently, almost all classic Arduinos have an onboard 3.3V regulator. It is generally rated for only "little" current (say 50 mA?), but that will be enough.

Motor Power is not essential if you do not mean to use the rumble feature. If you do, you can derive 7.5V from 9V through an LM317 regulator, unfortunately there are no shortcuts this time... Unless you use one of those wireless controllers that are battery-powered: in this case, don't worry at all about the Motor Power pin. 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.

Data

If you power the controller at 3.3V, all the I/O lines must also work at that voltage. Most Arduinos work at 5V, thus some level adjustement MUST be done. There are a few ways to achieve this, the easiest of which is probably using those bidirectional 4-channel level shifters you can get cheaply from China. You don't need bidirectionality, strictly speaking, still they are (almost) ideal for this application since they also provide pull-ups for the open-collector outputs and come in sets of 4.

The only issue is that these adapters generally come with 10k pull-up resistors, which are too weak and will create compatibility issues with some controllers. Therefore, you MUST replace them with 1k ones or put 1k in parallel to each.

Of course, if you use an Arduino board that works at 3.3V, you won't need any level shifting but you will still need the pull-up resistors, as the built-in ones are too weak.

A note on the Acknowledge pin: the original library did not use it and this is one of the reasons why it is not compatible with some controllers: it waits for a fixed interval between consecutive bytes instead of checking for the ACK pulse. Since some controllers are slower than others (typically older ones), they might not yet be ready for the next byte if the delay is not well calibrated (and it isn't).

The current version of PsxNewLib does the same, in that it does not use the ACK pin at all, but the delay was calibrated better. However this means that all controllers are polled much slower than they could be. Since this could be easily avoided by polling the ACK pin, future versions of the library will require it (the devel branch already does), so you are advised to wire it even if it is not necessary for the time being. If you don't want to waste a 4-channel module for a single signal, just connect it directly to an Arduino pin of choice and then connect a 1k resistor between it and 3.3V.

Arduino Shield

In order to make things as safe and straightforward as possible, I have 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:

Manufacturer	Model	Supported	Notes
Sony	PlayStation Controller (SCPH-1010)		Not tested yet
Sony	Revised PlayStation Controller (SCPH-1080)
Sony	Analog Joystick (SCPH-1110)		Informally known as the Flightstick
Sony	Dual Analog Controller (Japan, SCPH-1150)		Not tested yet
Sony	Dual Analog Controller (USA, SCPH-1180)		Not tested yet but likely to work, as SCPH-1180e does
Sony	Dual Analog Controller (Europe, SCPH-1180e)		Controller actually only has SCPH-1180 on it, but I'm assuming it's the European version since it was bought in Italy
Sony	DualShock Analog Controller (SCPH-1200)
Sony	DualShock 2 Analog Controller (SCPH-10010)
Sony	DualShock Controller for PSOne (SCPH-110)
Asciiware	Arcade Stick (SCEH-0002)
Logitech	Cordless Action (G-X2D11)
Namco	Arcade Stick (NPC-102 (SLEH-0004))
Namco	neGcon (NPC-101)		Since v0.3
Namco	JogCon (NPC-105)		Since v0.3
Namco	G-Con/GunCon		Since v0.4, see the GunconAbsMouse example for details - Tested by @sonik-br
Taito	Densha de Go! Two-Handle Controller (SLPH-00051)		Tested by @tylau0
Taito	Densha de Go! One-Handle Controller (TCPP-20001)		Since v0.4 - Tested by @tylau0
EastVita	Wireless Controller		Chinese knock-off, cheap but with surprising quality, pretty similar to the Lynxmotion controller, probably goes under other names, too

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.
• Matheus Fraguas (@sonik-br) for helping getting the G-Con/GunCon supported.
• Eddie Lau (@tylau0) for helping with the Densha de Go! controllers.
• Kate (@katemonster33) for contributing Rumble support.
• All the other guys who helped understand how the PSX controller protocol works.

psxnewlib's Issues

Dual Controller Support?

Hey SukkoPera, thanks for making this great library! I was wondering if or how it is possible to implement two controllers through PsxNewLib... Does the library currently support this function? I suppose it would only be possible to BitBang the second controller due to the lack of more SPI ports on most Arduinos - but never the less it would be very useful, as most converters out there have 2 controller ports.

Joystick_ does note name a type; did you mean 'Joystick'?

I am having an issue uploading the PSX2USB sketch to a Sparkfun Arduino Pro Micro because when attempting to upload the sketch I get the following error.
error: 'Joystick_' does not name a type; did you mean 'Joystick'?

I have not modified the sketch in any way. What am I doing wrong and how can I fix this?

Hardware SPI on Leonardo

Hi!
I'm trying to use the hardware ICSP pins on the Leonardo with the PsxControllerHwSpi lib.
No success ...
I'm doing:
PSX > Leonardo ICSP pin
DAT > 1 (MISO)
CLK > 3 (SCK)
CMD > 4 (MOSI)
ATT > 9 (digital pin, not on ICSP)
Also GND and 3.3V...

It's supposed to work on the Leonardo or just on the Uno?

Trying for most part of 2 days to get this working

I spent a few hours trying to get the original PS2x working - I noticed no one mentions the 3.3v logic and runs 5v..
I've used a 1K and 2K resistor on all lines - I couldn't get my official controllers analogue mode LED to light on 3.3v so I'm using an LDO 3.3v regulator on the 5v line. That seems to let the analogue button turn the LED on at least.
I have 10k pull up on pin one (data) , I have another USB port on a 9v step cable on an input jack split off to power Pin 3 for rumble. The unused Pin 9 is on a pullup resistor (because I've tried everything).

I mean at least I was able to figure out it was the DATA line causing your version of the library to print in the serial monitor that i'm pushing every button at once... otherwise it doesn't detect a controller.

Using Arduino UNO R3 - successfully hacked up an SD card breakout board earlier and was able to read / write to FAT32 card by using the same resistors to convert necessary lines etc without a guide - definitely sure the arduino isn't the issue.

Any pointers here? Tried genuine controllers / aftermarket controllers... PS1 / PS2

Rumble support

Am interested in having rumble support. I see that you have the static bytes disabled for rumble. Any reason why, or is it too much of a hassle to make it support the motors?

Multitap buttonPressed

I have tried your devel branch to test multitap and it works as expected over the serial port.
I want to make a joystick like in your master branch but then found that buttonPressed is not part of the devel branch, is this something you plan to add in the future?

Multitap (devel branch)

Hi!

I'm doing some tests with the multitap feature of the devel branch.
Using HardwareSpi.
Code works fine until I disable/enable interrupts for reading controller.
Like this

noInterrupts();
const bool success = psx.read (0, controller);
interrupts();

Code just hangs.

Any idea why?

PS1 Densha de Go controller one-handle version TCPP-20001 support

I confirm that the PS1 original two-handle version SLPH-00051 works with the current PsxNewLib code. However the same code doesn't work with the one-handle version TCPP-20001. May I know what one could do to help sort out what root cause? Thanks.
(FYI, the PsxLibrary at https://playground.arduino.cc/Main/PSXLibrary/ does work with both controller versions.)

Support for more boards

Hi!

This is not really an issue.
I want to port the library to other boards. Mainly STM32 and RP2040 based boards.
Those boards are cheaper (currently) and natively works at 3.3v.

The DigitalIO lib is too much "black magic" to me :)
Any tip on how to add a new board to it?

Seeking compatibility with Steering Wheel Madcatz Dual Force

Context

I have build some OpenPSX2AmigaPadAdapter. It's working well with several official PS1 and PS2 joypads. Tx for the great work.

My point is to make work a Steering Wheel Madcatz Dual Force with my Amiga.

I looked OpenPSX2AmigaPadAdapter firmware, the pull request to make is obsviously in PsxNewLib.

Status

On psx.begin() we get a 0 / No Controller found.

I've noticed that on the plug :

• pin/wire 5 / red / power 3.3v is missing (not broken, was never here).
• pin/wire 8 / white is missing (not broken, was never here).

I'll dig into several documentations in the next days (the one you linked at the end of README.md).

I would be delighted of you can share some hints to be able to accomplish this.

Adding support for the Jogcon's motor

Hi!

Recently I've got an Jogcon and I've been messing with it's motors.

There's some documentation of it's commands here

After some experiments I've got it working on PsxNewLib. Please take a look at my fork

Basically it needs to be in analog mode with rumble enabled. Then when pooling, we don't set the two motors bytes. Instead it's one byte with the Mode and Power. Mode can be like rotate left, rotate right, return to center...

There's also an working sketch example to trigger the effects with button presses.

Analog Dualshock controller (SCPH-1200) gives type "Guitar Hero".

With DumpButtonsBitBang and DumpButtonsHwSpi examples my SCPH-1200 controller gives controller type "Guitar Hero" to Serial Monitor. Other than that, controller works fully with PsxNewLib, so this doesn't matter much.
(I got library from Arduino IDE library manager. It is version 0.4.0)

A0 and A1 as OUTPUT for button press????????

Why the analog Pins A0 and A1 are outputs if nothing is conected????

In the 2 examples are setup as outputs.

I have a N1W320 wireless joystick and doesn't work T.T

Can you iluminate me about the clocks problems???

thnx 4 all.

Wireless Controller keeps disconneting

Hi,
thank you for this library. I am using it for a car controller in my bachelor thesis.
I have used Dualshock 2 wired controller but I would like to switch to wireless controller.
I have bought a chinese clone from Aliexpress but sadly I can't get it working neither via bitbang nor HW SPI.
Bitbang doesn't work at all.
HW SPI works, but the controller keeps disconnecting every 3-5 seconds.
Do you please have any clue what might be wrong?

Thank you very much
Best Regards

SCPH-1150 rumble

Hi!

The japanese SCPH-1150 dual analog controller features a primitive type of rumble.
It uses single motor with only on/off state and does not support any kind of configuration command. So no need to "enable rumble".

I don't have access to this model of controller but the DualShock is backward compatible with this old rumble mode.
I've added support for this type of rumble and it's working with a DualShock. I can submit a PR with the code change.

BTW I've also added support for the jogcon's motors long ago. Been using it for years now. Should I submit a PR for it too?
I would ask you to take a look if you see a better way to implement it and to fit the lib's coding style.

Generic controller not working

I have 2 different kind generic controllers (made in china), one of them work perfect, but the other kind don't work with PSXNwelib.
I try withe library PS2X_lib and the control work, switch to PsxNewLib and stop to work, the leds on the receiver blink and looks like no binding with the controller

DUMP_COMMS:
<-- 01 42 00
--> FF FF FF
<-- 01 42 00
--> FF FF FF
<-- 01 42 00
--> FF FF FF
<-- 01 42 00
--> FF FF FF
<-- 01 42 00
--> FF FF FF
<-- 01 42 00
--> FF FF FF

could you help with this issue?

Namco Volume Controller SLPH-00015 and 3.3V Arduinos support

is it supported?

white Jap version
green Eur version (i have one of these)

Reportedly it is using the Negcon analog protocol.

side question: will this sketch also work with an 3.3V Pro Micro board (instead of using a level shifter)?

Agetec Bass Landing Fishing Controller SLUH-00063

Hi!
Looks like we have another device protocol to handle :)

I don't have direct (physical) access to this device but I'm working with a friend, remotely, and trying to understand the protocol used.

The Agetec Bass Landing Fishing Controller (SLUH-00063) is not documented at all online.

Device starts in DIGITAL mode. There's no way for the user to change mode.
But after we send "enter config" and "exit config" commands, it starts to reply in a new mode. This mode is not implemented yet, and not documented anywhere.

Device sends cumulative value since last poll for the "rotating crank handle".
Also sends 3 motion values. Looks to be a gyro.
Device have two rumble motors. Reports them in the same way as a dualshock.
But the reply to 0x45 command is not identical to a DualShock. DS reports as having two modes. The fishing controller reports as having just a single mode.
Reply to 0x4C is also very unique for this device.

I'm still trying to understand it better, and will send a PR when ready.

Library cannot compile for RP2040 devices

The arduino library for these boards already utilizes the variable name 'poll' internally. Changing the name within PsxNewLib.h seemed to fix it for me.

enableAnalogSticks not working

Hi, I'm running this example

https://github.com/SukkoPera/PsxNewLib/blob/9b88bdda232b83a1b736be81c6973c0629072ede/examples/PSX2USB/PSX2USB.ino

and enableAnalogSticks fails for me on an official ps2 controller. Any idea of what could be going on?

• Running on a pro micro
• Using 3.3v 500ma as power for the controller as I read online that feeding it the full 5v 1a could hurt my controllers

Controller features detection

Opening this more as a way to talk about it. :)

I've been testing and debugging a lot of psx controllers lately.
And comparing my findings with what's documented online. There's a lot of wrong or missing information.

So the big news: There are controllers with multiple switchable modes (not just digital/analog).
And rumble can be supported on all modes, not just on the dualshock device.

Command 0x45 returns the constants:
amount of modes
amount of actuators
And the variable:
current mode (led state too)

Then command 0x46 can get info for each actuator with the constants:
Actuator function (rumble, jog rotation,...)
Sub function (low speed, high speed,...)
Parameter length (if it's just on/off or more complex arguments)
Max current drain

And command 0x44C can get info for each controller mode with some data that I don't understand yet, but can be used to identify the protocol (negcon, digital, analog,...)

I've seen a controller with a physical switch for digital, analog, negcon. All with rumble and two motors.
This device reports as single mode, too signal that the software can't change it's mode. user must move the switch.

And I've seen a controller with a mode button and 4 possible modes (digital, analog, flightstick, negcon).
It reports correctly and all 4 modes can be set from software. (via command 0x44)

So it looks like that rumble is not tied to specific controller types. And most important, games can use those features!
There's some games that only have analog input with a negcon controller. And the same game can have rumble enabled with a negcon compatible controller.

Some of my debug data in the next message...

Remove dependency on DigitalIO

It seems to be used only in examples, so it can probably be removed.

Guncon support

Hi threre!
This lib supports a ps1 guncon lightgun?