Add MIDI test procedure
Bug: 24664900
Change-Id: I7ef05763e6d407b1e18efb49f8204ae9bafb33e9
diff --git a/src/devices/audio/midi_test.jd b/src/devices/audio/midi_test.jd
new file mode 100644
index 0000000..fa80670
--- /dev/null
+++ b/src/devices/audio/midi_test.jd
@@ -0,0 +1,259 @@
+page.title=MIDI Test Procedure
+@jd:body
+
+<!--
+ Copyright 2015 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>These tests may be used to validate the MIDI feature on Android devices.
+Successful execution of these tests is a prerequisite to
+<a href="midi.html#claim-feature">claim the MIDI feature</a>.
+</p>
+
+<h2 id="preparation">Preparation</h2>
+
+
+<h3 id="hardware">Hardware</h3>
+
+<p>
+The following hardware is needed for the tests.
+</p>
+
+<ul>
+ <li> MIDI keyboard with USB connector, e.g. the <a href="http://www.akaipro.com/product/lpk25">Akai LPK25</a></li>
+ <li> MIDI keyboard with Bluetooth Low Energy (BLE) support, e.g. the <a href="http://miselu.com/">Miselu C.24</a></li>
+ <li> USB cables</li>
+ <li> USB On-The-Go (OTG) adapter to convert a female USB-A to male micro-USB or USB-C</li>
+ <li> Android device running Android 6.0 Marshmallow or later release</li>
+ <li> Optional: desktop computer</li>
+</ul>
+
+<h3 id="apps">Apps</h3>
+
+
+<p>Several apps are used by this test procedure:</p>
+
+<table>
+<tr>
+ <th>App</th>
+ <th>Description</th>
+</tr>
+<tr>
+ <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiScope">MidiScope</a> or
+ <a href="https://github.com/googlesamples/android-MidiScope">MidiScope</a></td>
+ <td>displays MIDI messages on-screen</td>
+</tr>
+<tr>
+ <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiKeyboard">MidiKeyboard</a></td>
+ <td>sends MIDI messages by pressing an on-screen music keyboard</td>
+</tr>
+<tr>
+ <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiSynthExample">MidiSynthExample</a> or
+ <br /><a href="https://github.com/googlesamples/android-MidiSynth">MidiSynth</a></td>
+ <td>simple MIDI synthesizer that uses sawtooth oscillators</td>
+</tr>
+<tr>
+ <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiBtlePairing">MidiBtlePairing</a></td>
+ <td>pairs an Android device with a BLE peripheral</td>
+</tr>
+<tr>
+ <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiTools">MidiTools</a></td>
+ <td>library dependency of the above apps</td>
+</tr>
+</table>
+
+<p>
+Most of these apps are part of the GitHub project
+<a href="https://github.com/philburk/android-midisuite">android-midisuite</a>.
+</p>
+
+<p>Each test has a list of apps that are used. After building each app, you can install the app using
+<a href="http://developer.android.com/tools/help/adb.html">Android Debug Bridge</a> (ADB).
+For example, to install the <em>MidiScope</em> app:</p>
+
+<ol>
+ <li> Use a workstation with ADB installed.</li>
+ <li> Connect a USB cable from the workstation to the Android device.</li>
+ <li> You may need to allow the USB connection on the Android device; see <a href="midi.html#usb-peripheral">USB peripheral mode</a></li>
+ <li> On the workstation, enter:</li>
+</ol>
+
+<pre>
+cd <em><this-folder></em>
+adb install -r MidiScope.apk
+</pre>
+
+
+<h2 id="virtual_synth_tests">Virtual synth tests</h2>
+
+
+<p>Note that a MIDI input port can have only one connection. So if another app is
+already using an input port, that port will not be available. If you cannot connect to
+an input port then try closing other apps.</p>
+
+<p>Hardware needed: Android device under test</p>
+
+<h3 id="simple_connection">Simple connection</h3>
+
+
+<p>Apps needed: <em>MidiKeyboard</em>, <em>MidiSynthExample</em></p>
+
+<p>This tests device enumeration, virtual devices, port connections, and message
+sending.</p>
+
+<ol>
+ <li> Adjust volume on Android device to about halfway.</li>
+ <li> Orient phone in landscape mode.</li>
+ <li> Launch <em>MidiKeyboard</em> app.</li>
+ <li> Select <strong>SynthExample</strong> from the spinner menu.</li>
+ <li> Play keys. You should hear notes being played in the <em>SynthExample</em> app.</li>
+ <li> Exit the application by pressing the <strong>Back</strong> button so that the port will be
+closed.</li>
+</ol>
+
+<h2 id="host_mode">USB test: host mode</h2>
+
+
+<p>Hardware needed: USB MIDI keyboard, USB cable, OTG adapter</p>
+
+<p>Repeat these tests several times. We have seen the USB stack crash hard on some
+prototype devices if devices were plugged in and unplugged a few times.</p>
+
+<h3 id="keyboard_already_plugged_in">Keyboard already plugged in</h3>
+
+
+<p>Apps needed: <em>MidiSynthExample</em> or <em>MidiScope</em></p>
+
+<p>This tests USB MIDI in host mode.</p>
+
+<ol>
+ <li> Adjust volume on Android device to about halfway.</li>
+ <li> Plug in USB keyboard using the OTG adapter.</li>
+ <li> Launch <em>SynthExample</em> app or the <em>MidiScope</em> app.</li>
+ <li> From the menu select the USB keyboard. It will display the brand.</li>
+ <li> Play notes on the keyboard. If you ran <em>SynthExample</em> then you should hear notes
+being played on the phone. If you ran <em>MidiScope</em> then you should see <em>NoteOn</em> and
+<em>NoteOff</em> messages on-screen.</li>
+ <li> Unplug the keyboard. The <em>Sender for Synth</em> menu should display <em>- - - - -</em>.</li>
+ <li> Exit the application by pressing the <strong>Back</strong> button.</li>
+</ol>
+
+<h3 id="hot_plug_usb_keyboard">Hot-plug USB keyboard</h3>
+
+
+<p>Apps needed: <em>MidiSynthExample</em> or <em>MidiScope</em></p>
+
+<p>This tests USB MIDI in host mode.</p>
+
+<ol>
+ <li> Adjust volume on Android device to about halfway.</li>
+ <li> Make sure there is not a USB MIDI keyboard plugged in.</li>
+ <li> Launch <em>SynthExample</em> app.</li>
+ <li> At middle, next to <em>Sender for Synth</em>, look in menu. You should not see the USB
+keyboard listed.</li>
+ <li> Plug in USB keyboard using the OTG adapter.</li>
+ <li> At middle, next to <em>Sender for Synth</em>, select the USB keyboard. It will display
+the brand.</li>
+ <li> Play notes on the keyboard. You should hear notes being played on the phone.</li>
+ <li> At middle, next to <em>Sender for Synth</em>, select <strong>- - - - -</strong>.</li>
+ <li> Play notes on the keyboard. You should hear nothing.</li>
+ <li> At middle, next to <em>Sender for Synth</em>, select the USB keyboard. It will display
+the brand.</li>
+ <li> Play notes on the keyboard. You should hear notes being played on the phone.</li>
+ <li> Unplug the synthesizer. The <em>Sender for Synth</em> menu should display <em>- - - - -</em>.</li>
+ <li> Exit the application by pressing the <strong>Back</strong> button.</li>
+</ol>
+
+<h2 id="peripheral_mode">USB test: peripheral mode</h2>
+
+
+<p>Hardware needed: USB cable, OTG adapter</p>
+
+<h3 id="android_to_android">Android-to-Android</h3>
+
+
+<p>Apps needed: <em>MidiKeyboard</em> on Android device under test, <em>MidiScope</em> on another
+Android device.</p>
+
+<p>Use Android devices as a peripheral controller for another Android device. To help test
+this mode, use another Android device running in host mode. Note that
+you could modify the test to work with a desktop computer running Digital Audio Workstation (DAW)
+software such as
+GarageBand.</p>
+
+<ol>
+ <li> Connect the USB cable to the Android device under test (Android device <strong>A</strong>).</li>
+ <li> Use an OTG adapter to connect the other end of the cable to a second Android
+device <strong>B</strong> that operates in host mode.</li>
+ <li> On Android device A:
+ <ol>
+ <li> Drag finger down from top of screen.</li>
+ <li> Select <strong>USB for Charging</strong> icon.</li>
+ <li> Select <strong>MIDI</strong>.</li>
+ <li> Launch <em>MidiKeyboard</em> app.</li>
+ <li> Select <strong>Android USB Peripheral Port</strong> from <em>Receiver for Keys</em> menu at top.</li>
+ </ol>
+ </li>
+ <li> On Android device B:
+ <ol>
+ <li> Launch <em>MidiScope</em> app.</li>
+ <li> Select the other Android device as the source.</li>
+ </ol>
+ </li>
+ <li> On Android device A:
+ <ol>
+ <li> Play notes on the keyboard and look for <em>NoteOn</em> and <em>NoteOff</em> on Android device B.</li>
+ </ol>
+ </li>
+ </ol>
+
+<h2 id="bluetooth_le_test">BLE test</h2>
+
+
+<p>Hardware needed: MIDI keyboard supporting BLE</p>
+
+<h3 id="basic_pairing_and_playing">Basic pairing and playing</h3>
+
+
+<p>Apps needed: <em>MidiBtlePairing</em>, <em>MidiSynthExample</em></p>
+
+<p>Test a keyboard connected to Android over BLE.</p>
+
+<ol>
+ <li> Reboot the Android device.</li>
+ <li> Power on the BLE keyboard.<br />
+ (The Miselu C.24 keyboard is powered on by pushing the button near the back so
+that it pops open. The power button on the C.24 pulses blue when in pairing
+mode.)</li>
+ <li> Launch the <em>MidiBtlePairing</em> app. It has a <em>MIDI+BTLE</em> icon.</li>
+ <li> Press the <strong>Bluetooth Scan</strong> button.</li>
+ <li> Select desired BLE peripheral.</li>
+ <li> The app should return to the main page, and you should see the peripheral listed. If
+you are using a C.24, then you will notice that the light should turn green on
+the C.24 to indicate paired mode.</li>
+ <li> Exit the app by pressing the <strong>Home</strong> button, not the <strong>Back</strong> button.</li>
+ <li> Launch the SynthExample app.</li>
+ <li> Select the BLE keyboard as the sender from the menu.</li>
+ <li> You should be able to press keys on the BLE keyboard and hear notes on
+Android.</li>
+</ol>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index c1149ec..018930d 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -52,7 +52,15 @@
<li><a href="<?cs var:toroot ?>devices/audio/avoiding_pi.html">Priority Inversion</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/src.html">Sample Rate Conversion</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/debugging.html">Debugging</a></li>
- <li><a href="<?cs var:toroot ?>devices/audio/midi.html">MIDI</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/audio/midi.html">
+ <span class="em">MIDI</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/audio/midi_test.html">MIDI Test Procedure</a></li>
+ </ul>
<li><a href="<?cs var:toroot ?>devices/audio/usb.html">USB Digital Audio</a></li>
<li><a href="<?cs var:toroot ?>devices/audio/tv.html">TV Audio</a></li>
</ul>