ESP32 Aquarius Controller Adapter
This is an adapter for an Aquarius game pad, running on an ESP32
development board (apparently a DOIT ESP32 DEVKIT V1). Originally, it
was meant to be a Tang Nano FPGA development board, but I was unable
to get USB serial working on that. The ESP32 is cheaper, anyway, and
can do much more. Apparently the board I'm using as a DOIT ESP32
DEVKIT V1 or a clone thereof.
The ESP32 side can be compiled using ESP IDF. I used the latest
stable at the time of writing, 5.0. It probably doesn't work on any
other version, since the IDF is not very stable in general, like most
modern free software projects (in fact, this project was started with
4.4.2 and 4.4.3, which were compatible with each other, but 5.0 made
many gratuitous API, build system, and even compiler behavior
changes). To build and flash (not necessary to do separately, since
the flash command depends on successful build internally, but I do
it so that it doesn't try to access the serial port until building is
complete):
idf.py build && idf.py flash
The IDF's esp_hid component crashed for me, which was solved by
increasing the event task stack sizes. I copied components/esp_hid
from the main IDF here and applied esp_hid.patch. I suggest
re-copying and re-patching for newer IDF versions rather than keeping
this copy.
Originally this was meant to be a serial-over-USB device that used a
user-space driver. The source for this is aqdrv.c; compile with:
gcc -O2 -o aqdrv{,.c}
Run aqdrv as someone who can access /dev/uinput (or change the
permissions on /dev/uinput, which is just asking for much bigger
security issues than running an open source, simple driver as root).
It takes two optional parameters, in any order: the mapping type and
the serial device name. Naturally, it needs to run with privilege to
access the serial device, as well.
If no mapping type is specified, it uses the default (just straight
mapping: XY ABCXYZ). Otherwise it can specify the Aq emulator's port
A (XY XYRtABRt2) or B (ZRz HlHuLtHdHrLt2) using that letter
(case-insensitive).
IF no serial device is given, it uses /dev/ttyACM0. If the serial
device can't be opened, it will first try prepending /dev/ and
/dev/tty. It also supports - for standard input/output, although
I do not recommend this (even though my first version only supported
that, it's more trouble than it's worth). If the device stll can't be
opened, aqdrv will retry indefinitely every 5 seconds.
Since it's an ESP32, I also support wireless access. I tried to
support BLE, BT Classic, and WiFi.
By default, it starts up HID on BLE and BT Classic. On my system, it
requires manual connection via bluetoothctl when starting cold, but
it re-attaches after that, usually. This is unlike my other bluetooth
devices, which auto-attach on powerup without intervention other than
the initial pairing. I have no idea why; this is supposed to just
work, so there is no help I could find on the Internet.
It also, by default, starts up a standard (RFCOMM) serial port (SPP)
over BT Classic. There is no standard for BLE serial ports, so I did
not do this. There is a "driver" for several BLE vendor protocols,
but I won't support it (among other things, I am heavily opposed to
using Python for device drivers, or anything else, for that matter).
Operation is idential to the default USB serial port, except of course
using /dev/rfcomm0. For some reason, though, even though the
permissions are identical, not being part of the dialup group on my
system gives a permission denied error for running screen on
rfcomm0, but not for ttyUSB0 or ttyACM0. The main other
difference is that system logging is only done on the built-in serial
port. Connecting to SPP is done using the rfcomm command, or via
your bluetooth GUI's serial access funtion, presumably (I haven't
tested this). For example, to bind (connect on first access;
disconnect when device closed) rfcomm0 to SPP device 1, and then
start the driver:
sudo rfcomm bind 0 94:B9:7E:C3:49:12 1
sudo ./aqdrv a rfcomm0
For WiFi, there is also a service that acts like the serial port
running on port 28010 (mnemonic for Z80A) by default (but
configurable). If all of the attempts at opening a device fail,
aqdrv will try interpretning the device sas host or
host:port before giving up and waiting 5 seconds.
sudo ./aqdrv a 192.168.1.220
In addition, I have in the past used network-gamepads for remote
input devices on Linux, so I have added a client implementation,
adapted from its input-client.c. You need to configure a target IP
address/host name, port, and optional (clear text) password for a
machine running input-server. The main advantage this has over
aqdrv is that it doesn't require a Linux-side driver written by me.
However, it is not standard on most distributions, so it does still
require effort. Note that if you kill input-server or otherwise
lose connection, reconnection will not happen until a change occurs on
the controller. The socket status is only chacked when the change
event is sent. You will likely also have to set the listen address to
0.0.0.0 instead of the default :::, since I do not use/suppport
IPv6 on the ESP32 side.
sudo input-server -b 0.0.0.0 &
License
As mentioned in the files, all code and documentation was created and
granted to the Public Domain by Thomas J. Moore in 2022-2023, except
as noted. In paritcular, components/esp_hid and
main/esp_hid_gap.[ch] are almost exactly extracted from the
Espressif ESP IDF. Also, 'main/ngp_protocol*is mostly from network-gamepads, andinput-event-codes.h` comes from the exported
Linux kernel headers on my current system. See those files for
copyright information.
Hardware
The hardware consists of the dev board with a DB25 cable (maybe an old
printer cable?) attached (it's what I had available), which is then
attached to a DB25-to-DB9 serial adapter. The end result 9 GPIO pins
attached to the 9 DB9 pins, one of which is permanently output as low,
and the other 8 of which are essentially the Aquarius game port. In
short:
Aq DB9 DB25 ESP32
GND 1 8 GPIO23
0 2 3 GPIO22
1 3 2 GPIO17
2 4 20 GPIO13
3 5 7 GPIO21
4 9 22 GPIO33
5 8 5 GPIO32
6 7 4 GPIO18
7 6 6 GPIO19
Serial Commands
Commands are entered as single characters on any "serial" interface:
System
- Esc-Esc-Esc: Reboot (any time, even in middle of other input).
Naturally, this only works if the ESP32 is responding to serial
input at all; if not, the
EN/reset button must be used.
- v/V(erbose): toggle main serial port log level (warning/info/debug)
Note that this may not work, since I will probably remove most tracing.
Basic Gamepad Protocol
- a/A(q) - print "\r\nAquarius\r\n" (to verify it's me)
- r/R(aw) - print "\r=XX" where XX is the Aquarius gameport value, in hex
- c/C(ooked) - print "\rxyb<123456>"; n = axis value, 1-6=1-6 or space
Bluetooth configuration
- b/B(t) - set BT mode:
- l/L) Toggle BLE HID (FIXME: maybe mutually exc. w/ classic HID)
- c/C) Toggle classic BT HID
- s/S) Toggle classic BT Serial (SPP)
- w/W) Save config & reboot if boot mode changed
- j/J(oymap) - set HID mapping:
-
- Aq joystick 1: ax=XY b=XYRt ABRt2
-
- Aq joystick 2: ax=RxRy b=HlHuLt HdHrLt2
-
- Simple joystick: ax=XY b=ABCXYZ
- b/B) Toggle boot mode (single/all)
- w/W) Save config & reboot if boot mode changed
WiFi
- w/W(iFi) - interactive WiFi connect config
Each SSID has its own config, and the strongest configured
interface is connected. Each config has password and IP address/port
config, as well as network-gamepads config (below).
- n/N(g) - interactive network-gamepads config
IP=0: disable
Port=0/blank: 9292
password (blank=no passwd)
Note that the Bluetooth HID mode affects the ngp client behavior.
Known Bugs
- For me at least, BT doesn't auto-connect on cold boot, ever. It's
supposed to "just work", so I have no idea what's wrong.
- For me at least, if both BLE and BT Classic are enabled, BLE is
ignored. So, to use BLE, both BT Classic HID and SPP must be
disabled, probably.
- Sometimes (actualy, most of the time on cold boot) it fails to
connect WiFi. A reboot is often necessary. Instead, it should
probably retry every few seconds as long as there are configured
SSIDs.
- As of now, static IP config has not been tested, and is therefore
likely broken. In particular, dhcpc startup and shutdown is handled
by the default handlers, and also by my code, and I'll have to
rearchitect to make my own event handlers to make it work properly.
TODO
- Binary protocol, or at least no use of printf
- Feature: "smartconfig" for wifi (requires Android device)
- Better handling of key rollover
- Maybe support PIN in BT config
- IPv6 over WiFi
- Serial continuous output mode (only on change)
- Dynamic enable/disable of BT, WiFi