Skip to content

Commit

Permalink
Merge pull request #7 from phasewalker18/Bugfix
Browse files Browse the repository at this point in the history 
Bugfix
  • Loading branch information
@phunkyg
phunkyg authored Sep 25, 2018
2 parents ed82bc9 + 4992862 commit 8586b30
Showing 1 changed file with 58 additions and 25 deletions.
83 changes: 58 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,29 @@
# ReaControl24

Control24 digital control surface protocol middleware.
Control24 digital control surface protocol middleware for Reaper.

This middleware will allow you to establish communication between the Control24 hardware and Reaper.OSC or any other similar DAW with OSC capability.
It will bring the Control24 online and provide 2 way binary communiation with it (daemon process).
It will translate between the binary protocol of the desk and OSC messages to exchange with the DAW (client process).
This middleware allows you to use the Digidesign Control24 hardware with Reaper.
It will allow you to establish communication between the Control24 hardware and Reaper.OSC or any other similar DAW with OSC capability.
It will bring the Control24 online and provide 2 way communiation with it, so you can control the DAW by using the Control24 buttons, faders and pots, and the DAW can update the Control24 fader positions, LEDs and displays.

Some basic stateful mode handling is provided to receive text from the DAW and display it on the scribble strips, and deal with issues like fader command echos.

You will need super user (or elevated Administrator in Windows) privileges to use this software, as it uses libpcap packet capture library to establish network connectivity with the Control24 ethernet interface. All other TCP and UDP traffic is ignored/filtered out, so you should not have any privacy concerns if the source has not been tampered with.
# How it Works

The Ethernet packets are captured using a Packet Capture utility, sometimes know as a 'network sniffer'.
Only packets for the Control24 are captured, all normal network traffice is ignored.
ReaControl's 'daemon' process then deals with this network traffic, and passes it to its 'client' process.
The 'client' process translates the Control24's binary language to OSC and vice-versa, passing binary messages back to the 'daemon' process which then sends them back as network packets to the Control24.
Finally, the OSC messages are sent as normal TCP/IP packets to the Reaper.OSC extension, which drives the DAW, according to the mappings found in the control file, OR in the Actions list. Return OSC messages are sent back to the 'client' process for the return trip, again as normal TCP/IP packets.

Each component can be on a separate computer, or all on the same one.

Some basic stateful mode handling is provided by the 'client' process to receive text from the DAW and display it on the scribble strips, handle controls which can toggle, and deal with issues like fader command echos.

You will need super user (or elevated Administrator in Windows) privileges to use this software (specifically the daemon process'), as it uses packet capture libraries (libpcap / npcap) to establish network connectivity with the Control24 ethernet interface. All other TCP and UDP traffic is ignored/filtered out, so you should not have any privacy concerns if the source has not been tampered with.

### Installing - OSX, macos, Linux

Ensure the current or default python environment has a 2.x interpreter in the current path, and install the pre-requisites into user environment using pip or similar
Ensure the current or default python environment has a 2.x interpreter in the current path (enter 'python' at the command line), and install the pre-requisites into user environment using pip or similar

Example pip install

Expand All @@ -23,21 +33,26 @@ pip install -r requirements.txt --user

By default all log outputs will be created into a subdirectory below wherever you install the files, so choose somewhere that this can happen without issues

Some older python installations in OSX do cause issues as they pre-date upgrades in the python security/encryption, so please ensure you are at the highest OS level you can be, and if that is not enough, you can find guides online on how to make the changes you need to python, or to install a second python environment just for ReaControl.

### Installing - Windows 10

The installation process for Windows is quite a bit more involved, as the OS does not come supplied with several requirements:
The pre-requisite installation process for Windows is quite a bit more involved, as the OS does not come supplied with python or packet capture libraries. We have provided an instruction video for this process at: http://TODO

* Download and install Python 2.7.x - https://www.python.org/downloads
* Download and install latest 64 bit Python 2.7.x - https://www.python.org/downloads
* Download and install Npcap ensuring to tick the WinPcap API-compatible mode which is off by default - https://nmap.org/npcap/
* Current version of Main Installer: https://nmap.org/npcap/dist/npcap-0.99-r7.exe
* Download the Npcap SDK
* Current version of SDK Download: https://nmap.org/npcap/dist/npcap-sdk-0.1.zip
* Download and install the c++ compiler for python - https://www.microsoft.com/en-us/download/details.aspx?id=44266
* Download the sources from github for: pypcap - https://github.com/pynetwork/pypcap/releases - currently 1.2.0
* Download the sources from github for: pypcap - https://github.com/pynetwork/pypcap/releases - currently 1.2.1

(Following is a re-statement of the procedure for 'installation from sources' of pypcap found at - https://github.com/pynetwork/pypcap/blob/master/docs/index.rst)

Choose a folder to work in: The 'install' subfolder of ReaControl24 is a reasonable choice.

* Unzip the pypcap download into the chosen install folder.
* Check if the zip made 2 folders called 'pypcap-1.2.0' or similar, one within the other. If so, move the inner one down a level so it sits under 'install'
* Check if the zip made 2 folders called 'pypcap-1.2.0' or similar, one within the other. If so, move the inner one down a level so it sits under 'install'
* Unzip the npcap sdk download. Again see if this results in an inner folder and if so, move it down.
* Rename the folder for this: "wpdpack"
* Start a windows command prompt from the start menu or run "cmd"
Expand All @@ -60,7 +75,7 @@ pip install -r requirements.txt -U
```

When complete, to run the daemon, rather than using 'sudo', use an 'Administrator command prompt' and omit the sudo
When supplying a network name, either the name or the GUID will work
When supplying a network name, either the name or the GUID will work. If you are struggling to find the right value, use the --help command line switch and the program will list them for you.


## Getting Started
Expand All @@ -85,6 +100,10 @@ Start the osc client process with:
python control24osc.py
```

### Advanced options

Use the --help command line switch for each process and the possibilities will be shown. Addresses and ports can be set for TCP/IP links, and the network interface can be set to state where the Control24 can be found.

### Prerequisites

```
Expand All @@ -96,29 +115,33 @@ pypcap (build from source)
OSC capable DAW such as Reaper 5.x
```

Also, the winpcapy library (re-distributed here for now, until a repostiory is found):
For Windows:

```
winpcapy.py, Authored by (c) Massimo Ciani 2009
Npcap
Npcap SDK
Microsoft C++ compiler for Python
```

### Compatibility

Although ReaControl24 is written in python, it depends on certain libraries like pypcap, that are usually wrappers around C libraries. These can vary from platform to platform. Testing of various platforms is ongoing, status at this time is:
Although ReaControl24 is written in python, it depends on certain libraries like pypcap, that can vary from platform to platform. Testing of various platforms is ongoing, status at this time is:


|Platform|control24d|control24osc|
|---|---|---|
|macos 10.13.x|Full|Full|
|macos < 10.13|OK in theory|OK in theory|
|Rasbpian ?|Full|Full|
|Windows 10|Full|Full|
|macos < 10.13|May require python upgrade/2nd environment|ditto|
|Rasbpian June 2018|Full|Full|
|Rasbpian prior|OK in theory|OK in theory|
|Other Linux|OK in theory|OK in theory|
|Windows 10|In Progress (DEV_Compatibility branch)|Full|

Please let us know if you try another, we will update our list or help with any issues.

## Usage

By default, the daemon will attempt to use the first active Ethernet adapter found in the system. It will also set up its listener on the IP address of that adapter.
By default, the daemon will attempt to use the first active Ethernet adapter found in the system. It will also set up its listener on the first IP address of that adapter.
The OSC client will do much the same, but it will only use the IP address as it doesn't require the network adapter name.
Log files will be created in a 'logs' subdirectory relative to where the processes are ran from.

Expand All @@ -136,17 +159,21 @@ In Windows, close the Command Prompt window where you launched the program.
By way of an apology, may this bring levity to your day
"Son where we're going, we don't need no tests"

Seriously though, without a dedicated piece of test hardware, this isn't easy. Some effort may be made to emulate traffic in the future!

### Coding standards

50% NOOB, 49% IDIOT, 1% Beer driven lunacy. Any contributors should feel free to laugh and point, as long as the criticism can be usefully applied.
Some improvements have been made since the early days, we strive to be more 'pythonic' and keep things clean!

## Deployment

The daemon process MUST be on a host with an interface in the same LAN segment as the Control24. It will present an IP socket that uses python multiprocessing library. The control24osc process and DAW may reside anywhere that you can route the traffic to.
If you use a dedicated SBC like a Raspberry pi, you may wish to add the startup of the scripts to your system startup commands, so the communication is available right after boot, and you can effectively run the SBC 'headless'.

## Customisation

A starting Reaper.OSC file is provided with some basic mappings to the OSC address schema. Feel free to add to this as required by your preferences or any new good mappings. Please share (by commit to this repo) anything that proves useful.
A starting Reaper.OSC file is provided with some basic mappings to the OSC address schema. Feel free to add to this as required by your preferences or any new good mappings. Please share (by commit to this repo, or just let us know) anything that proves useful.

To make a new mapping, check out the help text in the Default Reaper.OSC file provided by Cockos
Add lines with the token at the start, then followed by the OSC address pattern.
Expand All @@ -167,8 +194,10 @@ Other attributes determine how the tree is 'walked' according to the binary rece

## Contributing

Get a github account, and join in. That simple.

This is freeware, non warranty, non commercial code to benefit the hungry children and hungrier DAW users of the world. If you pull and don't contribute, you should feel bad. Real bad.
Please develop here in this repo for the benefit of all. All pull and merge requests will be accepted and best efforts made to make sense of it all when merging.
Please develop here in this repo for the benefit of all. All pull/merge requests will be accepted and best efforts made to make sense of it all when merging. If a fork serves you better, then please feel free, but try to let us pull any good stuff you might come up with.

Welcome to the latest contributors and collaborators! Your help is very much appreciated.

Expand All @@ -178,12 +207,17 @@ We will attempt to use [SemVer](http://semver.org/) for versioning. For the vers

## Authors

* **PhaseWalker18** - *Beer Consumption, code defecation*
* **PhaseWalker18** - *Beer Consumption, code defecation* (sadly no longer with us)
* **DisruptorMon** - *Slave Driving, cheap beer supply, testing*

If you are feeling especially thankful for this entering your life, please feel free to send donations to this BTC address: 1BPQvQjcAGuMjBnG25wuoD64i7KmWZRrpnN
If you are feeling especially thankful for this entering your life, please feel free to send donations to this BTC address: 1BPQvQjcAGuMjBnG25wuoD64i7KmWZRrpN

### Contributors

See also the list of contributors via github.
* **phunkyg** - Current Maintainer
* **lasloos** - Pro Control tester

See also the list of contributors via github for the latest picture.

## License

Expand All @@ -194,4 +228,3 @@ All other intellectual property rights remain with the original owners.

* **2mmi** - *Initial Idea, inspiration and saviour of us all


0 comments on commit 8586b30

Please sign in to comment.