Draft new device names section for DerekCook#21

README.md

@@ -262,3 +262,70 @@ the native library, and build the standalone jar file which embeds
 everything needed at runtime, using the standard Maven location and
 naming convention of `target/coremidi4j-{version}.jar` (it also builds
 the source and javadoc jars needed for deployment to Maven Central).
+
+## Device Names
+
+In release 1.1 we changed the way device names are reported to Java in
+order to accommodate situations where people have several of the same
+device attached to their system (see the [Issue 21
+discussion](https://github.com/DerekCook/CoreMidi4J/issues/21) for
+details.
+
+Previously, we would simply return the CoreMIDI "Endpoint" name as the
+device name. The problem with this is that the endpoint name for all
+identical devices would be the same, and there is no way for the user
+to edit them to distinguish between their devices.
+
+Now, we instead return the CoreMIDI "Device" name associated with the
+endpoint as the Java MIDI device name. This device name can be edited
+by the user as described [below](#editing-device-names) to distinguish
+between their devices of the same type. And for devices that have
+multiple endpoints associated with them, for example a controller with
+different kinds of ports, we combine both the editable Device name
+followed by the non-editable Endpoint name.
+
+To make this concrete, my Ableton Push 2 controller has two output
+ports, `Live Port` and `User Port`. Under previous releases of
+CoreMidi4J, these would show up in Java named simply `Live Port` and
+`User Port`, and there was no way to change them. In release 1.0 and
+later they show up as `Ableton Push 2 Live Port` and `Ableton Push 2
+User Port` and the "Ableton Push 2" name can be changed to whatever I
+want using Audio Midi Setup as described
+[below](#editing-device-names).
+
+> :wrench: This means that if you update your application which embeds
+> CoreMidi4J to use a current release and you were previously using
+> release 1.0 or earlier, you may need to warn your users that their
+> device names have likely changed, so they need to check and update
+> their saved configuration settings appropriately.
+
+If you need even more details about the device, the
+[`CoreMidiDeviceInfo` class](https://github.com/DerekCook/CoreMidi4J/blob/master/CoreMIDI4J/src/uk/co/xfactorylibrarians/coremidi4j/CoreMidiDeviceInfo.java)
+returned by CoreMidi4J to describe its devices has additional
+properties which provide access to CoreMIDI-specific device
+attributes. When you know you are dealing with a
+[`MidiDevice.Info`](https://docs.oracle.com/javase/8/docs/api/javax/sound/midi/MidiDevice.Info.html)
+object returned by CoreMidi4J, you can cast it into a
+`CoreMidiDeviceInfo` object and access this additional information.
+
+### Editing Device Names
+
+Users can change the device names associated with their MIDI devices
+using Apple's **Audio Midi Setup** utility (found in the **Utilities**
+subfolder within your main **Applications** folder, unless you have
+moved it). Once the utility is launched, switch to the **MIDI Studio**
+window (using the **Window** menu to open it if needed):
+
+<image src="doc/assets/AudioMidiSetup.png" alt="Audio MIDI Setup" width="930">
+
+To rename the very-generic "USB MIDI Device" shown at the bottom right
+of my MIDI Studio window, I can either double-click on it, or click
+once to select it and then click the Information button in the
+toolbar. That opens a Properties window where the device name can be edited:
+
+<image src="doc/assets/EditDeviceName.png" alt="Editing Device Name" width="536">
+
+When editing a device name like this, as soon as you click the
+**Apply** button in the Properties window, CoreMIDI4J will report a
+MIDI environment change event, and will use the newly assigned device
+name when reporting the connected MIDI devices.