1Hercules DJ Controller Driver for Linux
2=============================
3
4This is a Linux userspace driver for some Hercules DJ controllers.
5
6Originally this was a part of Mixxx,
7but in order to issue more timely updates
8(not bound to the Mixxx release schedule),
9it is now a standalone project.
10That means you can use it with any version of Mixxx,
11without needing to recompile anything other than this driver.
12
13Since it runs in userspace,
14you don't need to keep modifying your kernel to keep it working.
15And if the driver crashes,
16the rest of your system keeps running.
17But please tell me if it crashes!
18
19
20Supported Controllers
21---------------------
22
23The driver currently supports:
24
25* Hercules DJ Control MP3 e2
26* Hercules DJ Control Steel
27* Hercules DJ Console 4-Mx
28* Hercules Console Mk4
29* Hercules DJ 4Set (thanks watchingJu!)
30
31Things that are reported to work but I can't test:
32
33* Hercules DJ Control MP3 LE / Glow
34* Hercules Console Mk2 (See comment in the next section)
35
36Things I won't support:
37
38* Hercules Console Mk2 (already works with HID code in Mixxx)
39* Hercules RMX (already works with HID code in Mixxx)
40
41
42If you have a Hercules device that doesn't "just work" with Mixxx,
43send me an email, there's a chance I can support it with this driver.
44
45
46How To Get
47----------
48
49Check the [Github Project](https://github.com/nealey/hdjd) for the canonical source repo.
50
51
52How To Run
53----------
54
55Currently, the driver must be started after you plug in a device.
56
57If you haven't done so, build it by typing `make` under the source dir.
58Then, just run it by typing `./hdjd` and it will tell you what it found.
59
60Also make sure your user can read and write to raw USB devices.
61See [this Mixxx wiki page](https://mixxx.org/wiki/doku.php/troubleshooting#hid_and_usb_bulk_controllers_on_gnu_linux) for how to do this with udev-based systems (almost every Linux distribution).
62
63
64If you are trying to add support for another controller and try to debug the messages sent and received, you can build
65it in debug mode
66by providing `make` the `DEBUG=1` option:
67
68 $ make clean all DEBUG=1
69
70
71Current Issues
72--------------
73
74Recent versions of Mixxx may not be setting up the USB system correctly,
75resulting in your disk running out of space because
76`syslog` and the kernel log have millions of messages.
77If this happens, make sure to disable the "USB Device" for your controller in Mixxx.
78
79
80If you find a problem, please, please, pretty-please,
81email me <neale@woozle.org>.
82Posting on the Mixxx Community Forums is fine too,
83maybe someone there can help you,
84but I don't check the forums very often.
85Sorry.
86
87
88License
89-------
90
91[MIT](LICENSE.md)
92
93
94Thanks
95------
96
97Thanks to Guillemot (makers of the Hercules controllers) for sending me
98a whole bunch of controllers so I could make a better driver.
99
100Thanks to the Mixxx project for connecting me with Guillemot,
101and for providing something interesting to use this driver ;-)
102
103Thanks to JosepMaJAZ for many stability improvements,
104code cleanup,
105better error checking,
106and testing against the 4-Mx.
107
108
109Contact Me
110----------
111
112Neale Pickett <neale@woozle.org>