Date: 2021-06-20
Contact: Björn Kalkbrenner terminar@cyberphoria.org
Discord: https://discord.gg/NFdCmjcp4e
Please keep in mind, that this is the second alpha version. It will be instable and slow as hell!
Rebellion is an ongoing project which lets you use Native Instruments devices (such as a Maschine MK3 or the Komplete Kontrol MK2 keyboards) outside the Komplete Kontrol or Maschine software. Of course it is currently possible without Rebellion to access some of the functions via MIDI without any additional software but that's limited.
Rebellion tries to break these limitations by adopting a proprietary IPC protocol which is used by Native Instruments itself when passing data between the Maschine and Komplete Kontrol software to NIHA/NIHIA (the Native Instruments Hardware Agent/Native Instruments Host Integration Agent "services").
Other existing solutions are using the MIDI API or stop NIHA/NIHIA to access the devices directly via USB - but when NIHA/NIHIA are stopped, the Native Instruments software ecosystem can't be used anymore.
Rebellion tries to masquerades itself as Maschine2 or Komplete Kontrol software instance by connecting to NIHA/NIHIA and takes over the supported device(s).
- Rebellion (alpha1) controlling the Native Instruments Komplete Kontrol S61 MK2 - switching instances
- Rebellion (alpha1) controlling the Native Instruments Maschine MK3
LGPLv3 with some closed-source scripts but for a more detailed info see FAQ.md.
- available for Windows and MacOS (via platform abstraction layer)
- core library developed with C++ (src/librebellion)
- core contains Lua 5.4 as cross platform scripting engine for user defined functions and tests/prototyping
- Go based daemon as higher level gateway (src/rebelliond) (OSC, MIDI?)
- C++ based program (src/host) which can be used to display the events and play around a bit the the current user defined test functions (load image, toggle LEDs, ...)
- access to low level functions via library
- high level support via OSC connection
- maybe: high level support via MIDI messages
- integrated graphics API for devices with displays
- integrated state machine for handling specific use cases (e.g. pressing keys in order to have command layers, e.g. [SHIFT/GROUP_A], [LOCK] which is automatically remembered)
Rebellion creates two logfiles in the application directory.
- print.log contains redirected "print" lines
- printdump.log contains noncaptured/unknown protocol events
Stdout will display everything (and even more) debug information. For a test please start the application with redirected stdout into a file like
./rebellion_host(.exe) >> stdout.log
or (available on macOS)
./rebellion_host |tee -a stdout.log
No sensible data is captured from the computer, it's just about the communication to and from the Native Instruments devices. The logs may contain the serial number of the devices because the communication is bound to the serial numbers as some sort of unique identifiers.
The logfiles are human readable, in case of interest what the entries mean, just ask.
Two device types (MASCHINE_MK3, KOMPLETE_KONTROL_MK2) are currently automatically searched by the core when it is started/used - they are also tested and working (and completely mapped). That can be overwritten/extended via the config.lua.
Due to the fact that i don't own other devices I need external testers for devices. They are integrated into the core but not mapped yet (button names and such stuff will not work in the event messages).
It should be possible to use Rebellion with the following devices when a release version is done:
- Maschine MK3 => "MASCHINE_MK3"
- Maschine MK2 => "MASCHINE_MK2"
- Maschine MK1 => "MASCHINE_MK1"
- Maschine Plus => "MASCHINE_PLUS"
- Maschine Studio => "MASCHINE_STUDIO"
- Maschine Mikro MK3 => "MASCHINE_MIKRO_MK3"
- Maschine Mikro MK2 => "MASCHINE_MIKRO_MK2"
- Maschine Mikro MK1 => "MASCHINE_MIKRO_MK1"
- Maschine Jam => "MASCHINE_JAM"
- Komplete Kontrol MK1 => "KOMPLETE_KONTROL_MK1"
- Komplete Kontrol MK2 => "KOMPLETE_KONTROL_MK2"
- Komplete Kontrol A => "KOMPLETE_KONTROL_A"
- Komplete Kontrol M => "KOMPLETE_KONTROL_M"
Add something like
devices = {
"MASCHINE_MK3",
"KOMPLETE_KONTROL_MK2",
"MASCHINE_MIKRO_MK3"
}
to a file named config.lua in the Rebellion root folder - of course
adding your specific device to the file.
There are several other (or older) Native Instruments devices which may also work:
- Traktor Kontrol D2
- Traktor Kontrol F1
- Traktor Kontrol S2 MK1
- Traktor Kontrol S2 MK2
- Traktor Kontrol S2 MK3
- Traktor Kontrol S3
- Traktor Kontrol S4 MK1
- Traktor Kontrol S4 MK2
- Traktor Kontrol S4 MK3
- Traktor Kontrol S5
- Traktor Kontrol X1 MK1
- Traktor Kontrol X1 MK2
- Traktor Kontrol Z1
- Traktor Kontrol Z2
Due to missing hardware that can't be tested yet. If anybody owns such devices please let me now, i'll try to create a special debug version of Rebellion.
Testers for other devices appreciated!
I am currently searching for users who can use Rebellion with their (currently unmapped) devices, test some things and send me the logs.
Reach me via email (terminar@cyberphoria.org) or the official Discord channel (https://discord.gg/NFdCmjcp4e).
I talked to a handful of people about the (a better) integration of the NI devices into
- Reaper
- Ableton
If you are a developer and interested in this topic, please contact me!
Regarding developers:
Take a look at
- src/host/main.cpp
- src/rebelliond/rebelliond.go
to get some first examples or contact me. API documentation will follow within the next releases if there is something like a stable version.
Testers - please contact me or visit the discord.
Regarding the KKMK2 - Currently the "led count" is fixed to the length of the S61. When using the KNOB1 e.g. on the S49 it will not stop at the end (last key) of the piano light stripe and just fade away - just rotate counter-clockwise to get back the led. On the S88 it should stop somewhere (12 keys?) before the end of the piano light stripe.
Sending data to the display may result in a non functional (hanging) main loop or may take a while to proceed. This may happen in the rebelliond testState 6. Maybe restarting NIHA/NIHIA is helpful.
- DBTN[number] Buttons above the displays
- KNOB[number] Knobs below the displays
| Control | Description |
|---|---|
| DBTN1 | Load skull image into the left display (takes around 6+ seconds the first time) |
| DBTN2 | Select left display to draw on |
| DBTN4 | Clear left display |
| DBTN5 | Load skull image into the right display (takes around 6+ seconds the first time), additionally draw a small black line onto the image |
| DBTN6 | Select right display to draw on |
| DBTN8 | Clear right display |
| FIXED_VEL | Toggle all leds (white) |
| STOP | Exit the application |
| KNOB1 | Move around the led left/right (backwards/forwards) around the device |
| KNOB2 | Select color for led, (15 colors available on Maschine MK3) |
| KNOB3 | Select brightness for led (4 steps available on the Maschine MK3) |
| KNOB4 | Select color (RED: 0-255) for sketch point |
| KNOB5 | Select color (GREEN: 0-255) for sketch point |
| KNOB6 | Select color (BLUE: 0-255) for sketch point |
| KNOB7 | Sketch point/line on the selected display (X-Axis). clockwise = right, counter-clockwise = left |
| KNOB8 | Sketch point/line on the selected display (Y-Axis). clockwise = down, counter-clockwise = up |
On Windows, TDM-GCC (https://jmeubank.github.io/tdm-gcc/) is needed for the golang based rebelliond (uses cgo to link librebellion). Select "GCC 10.3.0 x86_64-w64-mingw32" in Visual Studio Code.
Currently you shouldn't try to build this if you don't really need to.
He did an awesome research and project at Github - (NIProtocol), wrote an article at Medium - (Rage Against the Maschine) and was a big inspiration for this project. Some small assumptions like the initial bootstrap connection process were wrong which forced me to reverse engineer the whole stuff again on my own but his work was wonderful kickstart.
- James Teh / jcsteh - original reaKontrol version Github
- Nikolas Bergerhoff / brumbear - reaKontrol fork Github
Rebellion began as a discussion at the official reaKontrol thread.
Of course he is doing great stuff at The Site Of Jürgen Moßgraber (DrivenByMoss 4 Reaper/Bitwig) but regarding Rebellion, his comments in the reaKontrol thread about his experience with the NI devices were another part of the puzzle.
The documented work at Github - Drachenkaetzchen/cabl / Native Instruments Maschine MK3 Display Protocol was a great help to understand the display format of the Maschine MK3. Also it was a bridge to realize that some data which is sent via USB to the device is just the same sent via IPC.
He also did some research at Github / biappi / Macchina in 2012 trying to access the Maschine (MK1). It was nice to see that the basic protocol didn't change much since 2012.