From 0c333567f599206cb0be6b74f02e59820536e0b2 Mon Sep 17 00:00:00 2001
From: cbdev <cb@cbcdn.com>
Date: Sun, 31 Mar 2019 09:00:12 +0200
Subject: Move backend documentation out of main README

---
 backends/evdev.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 backends/evdev.md

(limited to 'backends/evdev.md')

diff --git a/backends/evdev.md b/backends/evdev.md
new file mode 100644
index 0000000..dfe5ec9
--- /dev/null
+++ b/backends/evdev.md
@@ -0,0 +1,72 @@
+### The `evdev` backend
+
+This backend allows using Linux `evdev` devices such as mouses, keyboards, gamepads and joysticks
+as input and output devices. All buttons and axes available to the Linux system are mappable.
+Output is provided by the `uinput` kernel module, which allows creation of virtual input devices.
+This functionality may require elevated privileges (such as special group membership or root access).
+
+#### Global configuration
+
+This backend does not take any global configuration.
+
+#### Instance configuration
+
+| Option	| Example value		| Default value | Description						|
+|---------------|-----------------------|---------------|-------------------------------------------------------|
+| `device`	| `/dev/input/event1`	| none		| `evdev` device to use as input device			|
+| `input`	| `Xbox Wireless`	| none		| Presentation name of evdev device to use as input (prefix-matched) |
+| `output`	| `My Input Device`	| none		| Output device presentation name. Setting this option enables the instance for output	|
+| `exclusive`	| `1`			| `0`		| Prevent other processes from using the device		|
+| `id`		| `0x1 0x2 0x3`		| none		| Set output device bus identification (Vendor, Product and Version), optional |
+| `axis.AXISNAME`| `34300 0 65536 255 4095` | none	| Specify absolute axis details (see below) for output. This is required for any absolute axis to be output.
+
+The absolute axis details configuration (e.g. `axis.ABS_X`) is required for any absolute axis on output-enabled
+instances. The configuration value contains, space-separated, the following values:
+
+* `value`: The value to assume for the axis until an event is received
+* `minimum`: The axis minimum value
+* `maximum`: The axis maximum value
+* `fuzz`: A value used for filtering the input stream
+* `flat`: An offset, below which all deviations will be ignored
+* `resolution`: Axis resolution in units per millimeter (or units per radian for rotational axes)
+
+For real devices, all of these parameters for every axis can be found by running `evtest` on the device.
+
+#### Channel specification
+
+A channel is specified by its event type and event code, separated by `.`. For a complete list of event types and codes
+see the [kernel documentation](https://www.kernel.org/doc/html/v4.12/input/event-codes.html). The most interesting event types are
+
+* `EV_KEY` for keys and buttons
+* `EV_ABS` for absolute axes (such as Joysticks)
+* `EV_REL` for relative axes (such as Mouses)
+
+The `evtest` tool is useful to gather information on devices active on the local system, including names, types, codes
+and configuration supported by these devices.
+
+Example mapping:
+```
+ev1.EV_KEY.KEY_A > ev1.EV_ABS.ABS_X
+```
+
+Note that to map an absolute axis on an output-enabled instance, additional information such as the axis minimum
+and maximum are required. These must be specified in the instance configuration. When only mapping the instance
+as a channel input, this is not required.
+
+#### Known bugs / problems
+
+Creating an `evdev` output device requires elevated privileges, namely, write access to the system's
+`/dev/uinput`. Usually, this is granted for users in the `input` group and the `root` user.
+
+Input devices may synchronize logically connected event types (for example, X and Y axes) via `EV_SYN`-type
+events. The MIDIMonster also generates these events after processing channel events, but may not keep the original
+event grouping.
+
+Relative axes (`EV_REL`-type events), such as generated by mouses, are currently handled in a very basic fashion,
+generating only the normalized channel values of `0`, `0.5` and `1` for any input less than, equal to and greater
+than `0`, respectively. As for output, only the values `-1`, `0` and `1` are generated for the same interval.
+
+`EV_KEY` key-down events are sent for normalized channel values over `0.9`.
+
+Extended event type values such as `EV_LED`, `EV_SND`, etc are recognized in the MIDIMonster configuration file
+but may or may not work with the internal channel mapping and normalization code.
\ No newline at end of file
-- 
cgit v1.2.3


From c75721e77ecada3c88f4b493c1e3036c151bfe88 Mon Sep 17 00:00:00 2001
From: cbdev <cb@cbcdn.com>
Date: Wed, 24 Jul 2019 21:33:23 +0200
Subject: Clarify backend documentation

---
 backends/evdev.md | 4 +++-
 backends/lua.c    | 4 ++--
 backends/lua.md   | 2 +-
 3 files changed, 6 insertions(+), 4 deletions(-)

(limited to 'backends/evdev.md')

diff --git a/backends/evdev.md b/backends/evdev.md
index dfe5ec9..d750f1e 100644
--- a/backends/evdev.md
+++ b/backends/evdev.md
@@ -30,6 +30,8 @@ instances. The configuration value contains, space-separated, the following valu
 * `flat`: An offset, below which all deviations will be ignored
 * `resolution`: Axis resolution in units per millimeter (or units per radian for rotational axes)
 
+If an axis is not used for output, this configuration can be omitted.
+
 For real devices, all of these parameters for every axis can be found by running `evtest` on the device.
 
 #### Channel specification
@@ -69,4 +71,4 @@ than `0`, respectively. As for output, only the values `-1`, `0` and `1` are gen
 `EV_KEY` key-down events are sent for normalized channel values over `0.9`.
 
 Extended event type values such as `EV_LED`, `EV_SND`, etc are recognized in the MIDIMonster configuration file
-but may or may not work with the internal channel mapping and normalization code.
\ No newline at end of file
+but may or may not work with the internal channel mapping and normalization code.
diff --git a/backends/lua.c b/backends/lua.c
index 4d946cd..61e4e08 100644
--- a/backends/lua.c
+++ b/backends/lua.c
@@ -277,7 +277,7 @@ static int lua_configure_instance(instance* inst, char* option, char* value){
 	lua_instance_data* data = (lua_instance_data*) inst->impl;
 
 	//load a lua file into the interpreter
-	if(!strcmp(option, "script")){
+	if(!strcmp(option, "script") || !strcmp(option, "source")){
 		if(luaL_dofile(data->interpreter, value)){
 			fprintf(stderr, "Failed to load lua source file %s for instance %s: %s\n", value, inst->name, lua_tostring(data->interpreter, -1));
 			return 1;
@@ -285,7 +285,7 @@ static int lua_configure_instance(instance* inst, char* option, char* value){
 		return 0;
 	}
 
-	fprintf(stderr, "Unknown configuration parameter %s for lua backend\n", option);
+	fprintf(stderr, "Unknown configuration parameter %s for lua instance %s\n", option, inst->name);
 	return 1;
 }
 
diff --git a/backends/lua.md b/backends/lua.md
index e273b28..1c67477 100644
--- a/backends/lua.md
+++ b/backends/lua.md
@@ -43,7 +43,7 @@ The backend does not take any global configuration.
 
 | Option	| Example value		| Default value 	| Description		|
 |---------------|-----------------------|-----------------------|-----------------------|
-| `source`	| `script.lua`		| none			| Lua source file	|
+| `script`	| `script.lua`		| none			| Lua source file	|
 
 A single instance may have multiple `source` options specified, which will all be read cumulatively.
 
-- 
cgit v1.2.3


From 4e604b493e0dc855b6ea6978e5cf8e2de5d2b8d5 Mon Sep 17 00:00:00 2001
From: cbdev <cb@cbcdn.com>
Date: Sun, 28 Jul 2019 23:40:40 +0200
Subject: Fix evdev relative axes, add detect option

---
 TODO              |  1 -
 backends/evdev.c  | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 backends/evdev.h  |  8 ++++++++
 backends/evdev.md | 18 ++++++++++++------
 monster.cfg       |  4 +++-
 5 files changed, 75 insertions(+), 13 deletions(-)

(limited to 'backends/evdev.md')

diff --git a/TODO b/TODO
index 2a97c30..5f4ce91 100644
--- a/TODO
+++ b/TODO
@@ -3,5 +3,4 @@ Note source in channel value struct
 Optimize core channel search (store backend offset)
 Printing backend / Verbose mode
 
-evdev relative axis size
 mm_managed_fd.impl is not freed currently
diff --git a/backends/evdev.c b/backends/evdev.c
index ca8469a..565eb17 100644
--- a/backends/evdev.c
+++ b/backends/evdev.c
@@ -27,6 +27,12 @@ typedef union {
 	uint64_t label;
 } evdev_channel_ident;
 
+static struct {
+	uint8_t detect;
+} evdev_config = {
+	.detect = 0
+};
+
 int init(){
 	backend evdev = {
 		.name = BACKEND_NAME,
@@ -49,7 +55,15 @@ int init(){
 }
 
 static int evdev_configure(char* option, char* value) {
-	fprintf(stderr, "The evdev backend does not take any global configuration\n");
+	if(!strcmp(option, "detect")){
+		evdev_config.detect = 1;
+		if(!strcmp(value, "off")){
+			evdev_config.detect = 0;
+		}
+		return 0;
+	}
+
+	fprintf(stderr, "Unknown configuration option %s for evdev backend\n", option);
 	return 1;
 }
 
@@ -185,6 +199,22 @@ static int evdev_configure_instance(instance* inst, char* option, char* value) {
 		data->exclusive = 1;
 		return 0;
 	}
+	else if(!strncmp(option, "relaxis.", 8)){
+		data->relative_axis = realloc(data->relative_axis, (data->relative_axes + 1) * sizeof(evdev_relaxis_config));
+		if(!data->relative_axis){
+			fprintf(stderr, "Failed to allocate memory\n");
+			return 1;
+		}
+		data->relative_axis[data->relative_axes].code = libevdev_event_code_from_name(EV_REL, option + 8);
+		data->relative_axis[data->relative_axes].max = strtoul(value, &next_token, 0);
+		data->relative_axis[data->relative_axes].current = strtoul(next_token, NULL, 0);
+		if(data->relative_axis[data->relative_axes].code < 0){
+			fprintf(stderr, "Failed to configure relative axis extents for %s.%s\n", inst->name, option + 8);
+			return 1;
+		}
+		data->relative_axes++;
+		return 0;
+	}
 #ifndef EVDEV_NO_UINPUT
 	else if(!strcmp(option, "output")){
 		data->output_enabled = 1;
@@ -214,7 +244,7 @@ static int evdev_configure_instance(instance* inst, char* option, char* value) {
 		return 0;
 	}
 #endif
-	fprintf(stderr, "Unknown configuration parameter %s for evdev backend\n", option);
+	fprintf(stderr, "Unknown instance configuration parameter %s for evdev instance %s\n", option, inst->name);
 	return 1;
 }
 
@@ -275,21 +305,32 @@ static int evdev_push_event(instance* inst, evdev_instance_data* data, struct in
 		.fields.code = event.code
 	};
 	channel* chan = mm_channel(inst, ident.label, 0);
+	size_t axis;
 
 	if(chan){
 		val.raw.u64 = event.value;
 		switch(event.type){
 			case EV_REL:
-				val.normalised = 0.5 + ((event.value < 0) ? 0.5 : -0.5);
+				for(axis = 0; axis < data->relative_axes; axis++){
+					if(data->relative_axis[axis].code == event.code){
+						data->relative_axis[axis].current = clamp(data->relative_axis[axis].current + event.value, data->relative_axis[axis].max, 0);
+						val.normalised = (double) data->relative_axis[axis].current / (double) data->relative_axis[axis].max;
+						break;
+					}
+				}
+				if(axis == data->relative_axes){
+					val.normalised = 0.5 + ((event.value < 0) ? 0.5 : -0.5);
+					break;
+				}
 				break;
 			case EV_ABS:
 				range = libevdev_get_abs_maximum(data->input_ev, event.code) - libevdev_get_abs_minimum(data->input_ev, event.code);
-				val.normalised = (event.value - libevdev_get_abs_minimum(data->input_ev, event.code)) / (double) range;
+				val.normalised = clamp((event.value - libevdev_get_abs_minimum(data->input_ev, event.code)) / (double) range, 1.0, 0.0);
 				break;
 			case EV_KEY:
 			case EV_SW:
 			default:
-				val.normalised = 1.0 * event.value;
+				val.normalised = clamp(1.0 * event.value, 1.0, 0.0);
 				break;
 		}
 
@@ -299,6 +340,10 @@ static int evdev_push_event(instance* inst, evdev_instance_data* data, struct in
 		}
 	}
 
+	if(evdev_config.detect){
+		fprintf(stderr, "Incoming evdev data for channel %s.%s.%s\n", inst->name, libevdev_event_type_get_name(event.type), libevdev_event_code_get_name(event.type, event.code));
+	}
+
 	return 0;
 }
 
@@ -470,6 +515,8 @@ static int evdev_shutdown(){
 
 		libevdev_free(data->output_proto);
 #endif
+		data->relative_axes = 0;
+		free(data->relative_axis);
 		free(data);
 	}
 
diff --git a/backends/evdev.h b/backends/evdev.h
index c6e3a25..d719631 100644
--- a/backends/evdev.h
+++ b/backends/evdev.h
@@ -24,10 +24,18 @@ static int evdev_shutdown();
 	#define UINPUT_MAX_NAME_SIZE 512
 #endif
 
+typedef struct /*_evdev_relative_axis_config*/ {
+	int code;
+	int64_t max;
+	int64_t current;
+} evdev_relaxis_config;
+
 typedef struct /*_evdev_instance_model*/ {
 	int input_fd;
 	struct libevdev* input_ev;
 	int exclusive;
+	size_t relative_axes;
+	evdev_relaxis_config* relative_axis;
 
 	int output_enabled;
 #ifndef EVDEV_NO_UINPUT
diff --git a/backends/evdev.md b/backends/evdev.md
index d750f1e..995b44c 100644
--- a/backends/evdev.md
+++ b/backends/evdev.md
@@ -7,7 +7,9 @@ This functionality may require elevated privileges (such as special group member
 
 #### Global configuration
 
-This backend does not take any global configuration.
+| Option        | Example value         | Default value         | Description           |
+|---------------|-----------------------|-----------------------|-----------------------|
+| `detect`      | `on`                  | `off`                 | Output the channel specification for all events coming in on configured instances to help with configuration. |
 
 #### Instance configuration
 
@@ -18,7 +20,8 @@ This backend does not take any global configuration.
 | `output`	| `My Input Device`	| none		| Output device presentation name. Setting this option enables the instance for output	|
 | `exclusive`	| `1`			| `0`		| Prevent other processes from using the device		|
 | `id`		| `0x1 0x2 0x3`		| none		| Set output device bus identification (Vendor, Product and Version), optional |
-| `axis.AXISNAME`| `34300 0 65536 255 4095` | none	| Specify absolute axis details (see below) for output. This is required for any absolute axis to be output.
+| `axis.AXISNAME`| `34300 0 65536 255 4095` | none	| Specify absolute axis details (see below) for output. This is required for any absolute axis to be output. | 
+| `relaxis.AXISNAME`| `65534 32767` | none	| Specify relative axis details (extent and optional initial value) for output and input (see below). |
 
 The absolute axis details configuration (e.g. `axis.ABS_X`) is required for any absolute axis on output-enabled
 instances. The configuration value contains, space-separated, the following values:
@@ -34,6 +37,13 @@ If an axis is not used for output, this configuration can be omitted.
 
 For real devices, all of these parameters for every axis can be found by running `evtest` on the device.
 
+To use the input from relative axes in absolute-value based protocols, the backend needs a reference frame to
+convert the relative movements to absolute values.
+
+If relative axes are used without specifying their extents, the channel will generate normalized values
+of `0`, `0.5` and `1` for any input less than, equal to and greater than `0`, respectively. As for output, only
+the values `-1`, `0` and `1` are generated for the same interval.
+
 #### Channel specification
 
 A channel is specified by its event type and event code, separated by `.`. For a complete list of event types and codes
@@ -64,10 +74,6 @@ Input devices may synchronize logically connected event types (for example, X an
 events. The MIDIMonster also generates these events after processing channel events, but may not keep the original
 event grouping.
 
-Relative axes (`EV_REL`-type events), such as generated by mouses, are currently handled in a very basic fashion,
-generating only the normalized channel values of `0`, `0.5` and `1` for any input less than, equal to and greater
-than `0`, respectively. As for output, only the values `-1`, `0` and `1` are generated for the same interval.
-
 `EV_KEY` key-down events are sent for normalized channel values over `0.9`.
 
 Extended event type values such as `EV_LED`, `EV_SND`, etc are recognized in the MIDIMonster configuration file
diff --git a/monster.cfg b/monster.cfg
index 7db3ec3..2e6f76f 100644
--- a/monster.cfg
+++ b/monster.cfg
@@ -1,6 +1,8 @@
 [backend artnet]
 bind = 0.0.0.0
 
+[backend evdev]
+
 [artnet art]
 universe = 0
 dest = 255.255.255.255
@@ -11,6 +13,6 @@ input = TPPS
 [loopback loop]
 
 [map]
+mouse.EV_REL.REL_X > loop.chan0
 art.{3..4}{4..3} > loop.chan{4..3}{3..4}
 art.{1..10} > loop.data{1..10}
-art.{500..599} > loop.test{500..599}
-- 
cgit v1.2.3


From a23ce7718ab61e73586d2738329d6bbace0b764b Mon Sep 17 00:00:00 2001
From: cbdev <cb@cbcdn.com>
Date: Thu, 1 Aug 2019 20:54:17 +0200
Subject: Implement evdev relative axis inversion

---
 backends/evdev.c  | 15 ++++++++++++++-
 backends/evdev.h  |  1 +
 backends/evdev.md |  8 +++++++-
 3 files changed, 22 insertions(+), 2 deletions(-)

(limited to 'backends/evdev.md')

diff --git a/backends/evdev.c b/backends/evdev.c
index 565eb17..7a7913d 100644
--- a/backends/evdev.c
+++ b/backends/evdev.c
@@ -205,8 +205,13 @@ static int evdev_configure_instance(instance* inst, char* option, char* value) {
 			fprintf(stderr, "Failed to allocate memory\n");
 			return 1;
 		}
+		data->relative_axis[data->relative_axes].inverted = 0;
 		data->relative_axis[data->relative_axes].code = libevdev_event_code_from_name(EV_REL, option + 8);
-		data->relative_axis[data->relative_axes].max = strtoul(value, &next_token, 0);
+		data->relative_axis[data->relative_axes].max = strtoll(value, &next_token, 0);
+		if(data->relative_axis[data->relative_axes].max < 0){
+			data->relative_axis[data->relative_axes].max *= -1;
+			data->relative_axis[data->relative_axes].inverted = 1;
+		}
 		data->relative_axis[data->relative_axes].current = strtoul(next_token, NULL, 0);
 		if(data->relative_axis[data->relative_axes].code < 0){
 			fprintf(stderr, "Failed to configure relative axis extents for %s.%s\n", inst->name, option + 8);
@@ -313,6 +318,9 @@ static int evdev_push_event(instance* inst, evdev_instance_data* data, struct in
 			case EV_REL:
 				for(axis = 0; axis < data->relative_axes; axis++){
 					if(data->relative_axis[axis].code == event.code){
+						if(data->relative_axis[axis].inverted){
+							event.value *= -1;
+						}
 						data->relative_axis[axis].current = clamp(data->relative_axis[axis].current + event.value, data->relative_axis[axis].max, 0);
 						val.normalised = (double) data->relative_axis[axis].current / (double) data->relative_axis[axis].max;
 						break;
@@ -374,6 +382,11 @@ static int evdev_handle(size_t num, managed_fd* fds){
 				read_flags = LIBEVDEV_READ_FLAG_SYNC;
 			}
 
+			//exclude synchronization events
+			if(ev.type == EV_SYN){
+				continue;
+			}
+
 			//handle event
 			if(evdev_push_event(inst, data, ev)){
 				return 1;
diff --git a/backends/evdev.h b/backends/evdev.h
index d719631..f89e362 100644
--- a/backends/evdev.h
+++ b/backends/evdev.h
@@ -25,6 +25,7 @@ static int evdev_shutdown();
 #endif
 
 typedef struct /*_evdev_relative_axis_config*/ {
+	uint8_t inverted;
 	int code;
 	int64_t max;
 	int64_t current;
diff --git a/backends/evdev.md b/backends/evdev.md
index 995b44c..88dfc85 100644
--- a/backends/evdev.md
+++ b/backends/evdev.md
@@ -38,12 +38,18 @@ If an axis is not used for output, this configuration can be omitted.
 For real devices, all of these parameters for every axis can be found by running `evtest` on the device.
 
 To use the input from relative axes in absolute-value based protocols, the backend needs a reference frame to
-convert the relative movements to absolute values.
+convert the relative movements to absolute values. To invert the mapping of the relative axis, specify the `max` value
+as a negative number, for example:
+
+```
+relaxis.REL_X = -1024 512
+```
 
 If relative axes are used without specifying their extents, the channel will generate normalized values
 of `0`, `0.5` and `1` for any input less than, equal to and greater than `0`, respectively. As for output, only
 the values `-1`, `0` and `1` are generated for the same interval.
 
+
 #### Channel specification
 
 A channel is specified by its event type and event code, separated by `.`. For a complete list of event types and codes
-- 
cgit v1.2.3


From bbeade8898200a8024169ece30c620016fd5eaf1 Mon Sep 17 00:00:00 2001
From: cbdev <cb@cbcdn.com>
Date: Thu, 1 Aug 2019 20:58:21 +0200
Subject: Implement midi backend detect option

---
 README.md         |  2 +-
 backends/evdev.md |  2 +-
 backends/midi.c   | 41 +++++++++++++++++++++++++++++++++++------
 backends/midi.md  |  1 +
 4 files changed, 38 insertions(+), 8 deletions(-)

(limited to 'backends/evdev.md')

diff --git a/README.md b/README.md
index d64190f..8a0d7f9 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ on any other (or the same) supported protocol, for example to:
 * Dynamically route and modify events using the Lua programming language ([Example configuration](configs/lua.cfg) and [Script](configs/demo.lua)) to create your own lighting controller or run effects on TouchOSC (Flying faders demo [configuration](configs/flying-faders.cfg) and [script](configs/flying-faders.lua))
 * Use an OSC app as a simple lighting controller via ArtNet or sACN
 * Visualize ArtNet data using OSC tools
-* Control lighting fixtures or DAWs using gamepad controllers ([Example configuration](configs/evdev.conf))
+* Control lighting fixtures or DAWs using gamepad controllers, trackballs, etc ([Example configuration](configs/evdev.conf))
 * Play games or type using MIDI controllers
 
 [![Build Status](https://travis-ci.com/cbdevnet/midimonster.svg?branch=master)](https://travis-ci.com/cbdevnet/midimonster) [![Coverity Scan Build Status](https://scan.coverity.com/projects/15168/badge.svg)](https://scan.coverity.com/projects/15168)
diff --git a/backends/evdev.md b/backends/evdev.md
index 88dfc85..d57201d 100644
--- a/backends/evdev.md
+++ b/backends/evdev.md
@@ -9,7 +9,7 @@ This functionality may require elevated privileges (such as special group member
 
 | Option        | Example value         | Default value         | Description           |
 |---------------|-----------------------|-----------------------|-----------------------|
-| `detect`      | `on`                  | `off`                 | Output the channel specification for all events coming in on configured instances to help with configuration. |
+| `detect`      | `on`                  | `off`                 | Output channel specifications for any events coming in on configured instances to help with configuration. |
 
 #### Instance configuration
 
diff --git a/backends/midi.c b/backends/midi.c
index 2999e6b..c1480c0 100644
--- a/backends/midi.c
+++ b/backends/midi.c
@@ -31,6 +31,12 @@ enum /*_midi_channel_type*/ {
 	sysmsg
 };
 
+static struct {
+	uint8_t detect;
+} midi_config = {
+	.detect = 0
+};
+
 int init(){
 	backend midi = {
 		.name = BACKEND_NAME,
@@ -55,8 +61,8 @@ int init(){
 		return 1;
 	}
 
-	snd_seq_nonblock(sequencer, 1);		
-		
+	snd_seq_nonblock(sequencer, 1);
+
 	fprintf(stderr, "MIDI client ID is %d\n", snd_seq_client_id(sequencer));
 	return 0;
 }
@@ -70,6 +76,14 @@ static int midi_configure(char* option, char* value){
 		return 0;
 	}
 
+	if(!strcmp(option, "detect")){
+		midi_config.detect = 1;
+		if(!strcmp(value, "off")){
+			midi_config.detect = 0;
+		}
+		return 0;
+	}
+
 	fprintf(stderr, "Unknown MIDI backend option %s\n", option);
 	return 1;
 }
@@ -214,7 +228,7 @@ static int midi_set(instance* inst, size_t num, channel** c, channel_value* v){
 		snd_seq_ev_set_source(&ev, data->port);
 		snd_seq_ev_set_subs(&ev);
 		snd_seq_ev_set_direct(&ev);
-		
+
 		switch(ident.fields.type){
 			case note:
 				snd_seq_ev_set_noteon(&ev, ident.fields.channel, ident.fields.control, v[u].normalised * 127.0);
@@ -224,7 +238,6 @@ static int midi_set(instance* inst, size_t num, channel** c, channel_value* v){
 				break;
 			case pressure:
 				snd_seq_ev_set_keypress(&ev, ident.fields.channel, ident.fields.control, v[u].normalised * 127.0);
-
 				break;
 			case pitchbend:
 				snd_seq_ev_set_pitchbend(&ev, ident.fields.channel, (v[u].normalised * 16383.0) - 8192);
@@ -249,6 +262,7 @@ static int midi_handle(size_t num, managed_fd* fds){
 	instance* inst = NULL;
 	channel* changed = NULL;
 	channel_value val;
+	char* event_type = NULL;
 	midi_channel_ident ident = {
 		.label = 0
 	};
@@ -258,6 +272,7 @@ static int midi_handle(size_t num, managed_fd* fds){
 	}
 
 	while(snd_seq_event_input(sequencer, &ev) > 0){
+		event_type = NULL;
 		ident.label = 0;
 		switch(ev->type){
 			case SND_SEQ_EVENT_NOTEON:
@@ -267,22 +282,26 @@ static int midi_handle(size_t num, managed_fd* fds){
 				ident.fields.channel = ev->data.note.channel;
 				ident.fields.control = ev->data.note.note;
 				val.normalised = (double)ev->data.note.velocity / 127.0;
+				event_type = "note";
 				break;
 			case SND_SEQ_EVENT_KEYPRESS:
 				ident.fields.type = pressure;
 				ident.fields.channel = ev->data.note.channel;
 				ident.fields.control = ev->data.note.note;
 				val.normalised = (double)ev->data.note.velocity / 127.0;
+				event_type = "pressure";
 				break;
 			case SND_SEQ_EVENT_CHANPRESS:
 				ident.fields.type = aftertouch;
 				ident.fields.channel = ev->data.control.channel;
 				val.normalised = (double)ev->data.control.value / 127.0;
+				event_type = "aftertouch";
 				break;
 			case SND_SEQ_EVENT_PITCHBEND:
 				ident.fields.type = pitchbend;
 				ident.fields.channel = ev->data.control.channel;
 				val.normalised = ((double)ev->data.control.value + 8192) / 16383.0;
+				event_type = "pitch";
 				break;
 			case SND_SEQ_EVENT_CONTROLLER:
 				ident.fields.type = cc;
@@ -290,6 +309,7 @@ static int midi_handle(size_t num, managed_fd* fds){
 				ident.fields.control = ev->data.control.param;
 				val.raw.u64 = ev->data.control.value;
 				val.normalised = (double)ev->data.control.value / 127.0;
+				event_type = "cc";
 				break;
 			case SND_SEQ_EVENT_CONTROL14:
 			case SND_SEQ_EVENT_NONREGPARAM:
@@ -318,6 +338,15 @@ static int midi_handle(size_t num, managed_fd* fds){
 				return 1;
 			}
 		}
+
+		if(midi_config.detect && event_type){
+			if(ident.fields.type == pitchbend || ident.fields.type == aftertouch){
+				fprintf(stderr, "Incoming MIDI data on channel %s.ch%d.%s\n", inst->name, ident.fields.channel, event_type);
+			}
+			else{
+				fprintf(stderr, "Incoming MIDI data on channel %s.ch%d.%s%d\n", inst->name, ident.fields.channel, event_type, ident.fields.control);
+			}
+		}
 	}
 	free(ev);
 	return 0;
@@ -375,13 +404,13 @@ static int midi_start(){
 	}
 
 	//register all fds to core
-	nfds = snd_seq_poll_descriptors_count(sequencer, POLLIN | POLLOUT);	
+	nfds = snd_seq_poll_descriptors_count(sequencer, POLLIN | POLLOUT);
 	pfds = calloc(nfds, sizeof(struct pollfd));
 	if(!pfds){
 		fprintf(stderr, "Failed to allocate memory\n");
 		goto bail;
 	}
-	nfds = snd_seq_poll_descriptors(sequencer, pfds, nfds, POLLIN | POLLOUT);	
+	nfds = snd_seq_poll_descriptors(sequencer, pfds, nfds, POLLIN | POLLOUT);
 
 	fprintf(stderr, "MIDI backend registering %d descriptors to core\n", nfds);
 	for(p = 0; p < nfds; p++){
diff --git a/backends/midi.md b/backends/midi.md
index 9733cc2..5e295ee 100644
--- a/backends/midi.md
+++ b/backends/midi.md
@@ -7,6 +7,7 @@ The MIDI backend provides read-write access to the MIDI protocol via virtual por
 | Option	| Example value		| Default value 	| Description		|
 |---------------|-----------------------|-----------------------|-----------------------|
 | `name`	| `MIDIMonster`		| none			| MIDI client name	|
+| `detect`      | `on`                  | `off`                 | Output channel specifications for any events coming in on configured instances to help with configuration. |
 
 #### Instance configuration
 
-- 
cgit v1.2.3