1 <html devsite> 2 <head> 3 <title>MIDI Test Procedure</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>These tests may be used to validate the MIDI feature on Android devices. 27 Successful execution of these tests is a prerequisite to 28 <a href="midi.html#claim-feature">claim the MIDI feature</a>. 29 </p> 30 31 <h2 id="preparation">Preparation</h2> 32 33 34 <h3 id="hardware">Hardware</h3> 35 36 <p> 37 The following hardware is needed for the tests. 38 </p> 39 40 <ul> 41 <li> MIDI keyboard with USB connector, e.g. the <a href="http://www.akaipro.com/product/lpk25">Akai LPK25</a></li> 42 <li> MIDI keyboard with Bluetooth Low Energy (BLE) support, e.g. the <a href="http://miselu.com/">Miselu C.24</a></li> 43 <li> USB cables</li> 44 <li> USB On-The-Go (OTG) adapter to convert a female USB-A to male micro-USB or USB-C</li> 45 <li> Android device running Android 6.0 Marshmallow or later release</li> 46 <li> Optional: desktop computer</li> 47 </ul> 48 49 <h3 id="apps">Apps</h3> 50 51 <p> 52 Several apps are used by this test procedure. 53 The apps are available in source code on GitHub project 54 <a href="https://github.com/philburk/android-midisuite">android-midisuite</a>, 55 and via <em>Google Play</em>™ at links in the following table. 56 </p> 57 58 <table> 59 <tr> 60 <th>Source code</th> 61 <th>Google Play™</th> 62 <th>Description</th> 63 </tr> 64 <tr> 65 <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiScope">MidiScope</a> or 66 <a href="https://github.com/googlesamples/android-MidiScope">MidiScope</a></td> 67 <td><a href="https://play.google.com/store/apps/details?id=com.mobileer.example.midiscope">MIDI Scope</a></td> 68 <td>displays MIDI messages on-screen</td> 69 </tr> 70 <tr> 71 <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiKeyboard">MidiKeyboard</a></td> 72 <td><a href="https://play.google.com/store/apps/details?id=com.mobileer.midikeyboard">MIDI Keyboard</a></td> 73 <td>sends MIDI messages by pressing an on-screen music keyboard</td> 74 </tr> 75 <tr> 76 <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiSynthExample">MidiSynthExample</a> or 77 <br /><a href="https://github.com/googlesamples/android-MidiSynth">MidiSynth</a></td> 78 <td><a href="https://play.google.com/store/apps/details?id=com.mobileer.midisynthexample">MIDI Synth Ex</a></td> 79 <td>simple MIDI synthesizer that uses sawtooth oscillators</td> 80 </tr> 81 <tr> 82 <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiBtlePairing">MidiBtlePairing</a></td> 83 <td><a href="https://play.google.com/store/apps/details?id=com.mobileer.example.midibtlepairing">MIDI BLE Connect</a></td> 84 <td>pairs an Android device with a BLE peripheral</td> 85 </tr> 86 <tr> 87 <td><a href="https://github.com/philburk/android-midisuite/tree/master/MidiTools">MidiTools</a></td> 88 <td></td> 89 <td>library dependency of the above apps</td> 90 </tr> 91 </table> 92 93 <p> 94 If you choose to work from source code rather than install via <em>Google Play</em>™, 95 first build the app using the supplied <em>Android.mk</em>. 96 Then install the app using 97 <a href="http://developer.android.com/tools/help/adb.html">Android Debug Bridge</a> (ADB). 98 For example, to install the <em>MidiScope</em> app:</p> 99 100 <ol> 101 <li> Use a workstation with ADB installed.</li> 102 <li> Connect a USB cable from the workstation to the Android device.</li> 103 <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> 104 <li> On the workstation, enter:</li> 105 </ol> 106 107 <pre class="devsite-click-to-copy"> 108 <code class="devsite-terminal">cd <var>THIS_FOLDER</var></code> 109 <code class="devsite-terminal">adb install -r MidiScope.apk</code> 110 </pre> 111 112 113 <h2 id="virtual_synth_tests">Virtual synth tests</h2> 114 115 116 <p>Note that a MIDI input port can have only one connection. So if another app is 117 already using an input port, that port will not be available. If you cannot connect to 118 an input port then try closing other apps.</p> 119 120 <p>Hardware needed: Android device under test</p> 121 122 <h3 id="simple_connection">Simple connection</h3> 123 124 125 <p>Apps needed: <em>MidiKeyboard</em>, <em>MidiSynthExample</em></p> 126 127 <p>This tests device enumeration, virtual devices, port connections, and message 128 sending.</p> 129 130 <ol> 131 <li> Adjust volume on Android device to about halfway.</li> 132 <li> Orient phone in landscape mode.</li> 133 <li> Launch <em>MidiKeyboard</em> app.</li> 134 <li> Select <strong>SynthExample</strong> from the spinner menu.</li> 135 <li> Play keys. You should hear notes being played in the <em>SynthExample</em> app.</li> 136 <li> Exit the application by pressing the <strong>Back</strong> button so that the port will be 137 closed.</li> 138 </ol> 139 140 <h2 id="host_mode">USB test: host mode</h2> 141 142 143 <p>Hardware needed: USB MIDI keyboard, USB cable, OTG adapter</p> 144 145 <p>Repeat these tests several times. We have seen the USB stack crash hard on some 146 prototype devices if devices were plugged in and unplugged a few times.</p> 147 148 <h3 id="keyboard_already_plugged_in">Keyboard already plugged in</h3> 149 150 151 <p>Apps needed: <em>MidiSynthExample</em> or <em>MidiScope</em></p> 152 153 <p>This tests USB MIDI in host mode.</p> 154 155 <ol> 156 <li> Adjust volume on Android device to about halfway.</li> 157 <li> Plug in USB keyboard using the OTG adapter.</li> 158 <li> Launch <em>SynthExample</em> app or the <em>MidiScope</em> app.</li> 159 <li> From the menu select the USB keyboard. It will display the brand.</li> 160 <li> Play notes on the keyboard. If you ran <em>SynthExample</em> then you should hear notes 161 being played on the phone. If you ran <em>MidiScope</em> then you should see <em>NoteOn</em> and 162 <em>NoteOff</em> messages on-screen.</li> 163 <li> Unplug the keyboard. The <em>Sender for Synth</em> menu should display <em>- - - - -</em>.</li> 164 <li> Exit the application by pressing the <strong>Back</strong> button.</li> 165 </ol> 166 167 <h3 id="hot_plug_usb_keyboard">Hot-plug USB keyboard</h3> 168 169 170 <p>Apps needed: <em>MidiSynthExample</em> or <em>MidiScope</em></p> 171 172 <p>This tests USB MIDI in host mode.</p> 173 174 <ol> 175 <li> Adjust volume on Android device to about halfway.</li> 176 <li> Make sure there is not a USB MIDI keyboard plugged in.</li> 177 <li> Launch <em>SynthExample</em> app.</li> 178 <li> At middle, next to <em>Sender for Synth</em>, look in menu. You should not see the USB 179 keyboard listed.</li> 180 <li> Plug in USB keyboard using the OTG adapter.</li> 181 <li> At middle, next to <em>Sender for Synth</em>, select the USB keyboard. It will display 182 the brand.</li> 183 <li> Play notes on the keyboard. You should hear notes being played on the phone.</li> 184 <li> At middle, next to <em>Sender for Synth</em>, select <strong>- - - - -</strong>.</li> 185 <li> Play notes on the keyboard. You should hear nothing.</li> 186 <li> At middle, next to <em>Sender for Synth</em>, select the USB keyboard. It will display 187 the brand.</li> 188 <li> Play notes on the keyboard. You should hear notes being played on the phone.</li> 189 <li> Unplug the synthesizer. The <em>Sender for Synth</em> menu should display <em>- - - - -</em>.</li> 190 <li> Exit the application by pressing the <strong>Back</strong> button.</li> 191 </ol> 192 193 <h2 id="peripheral_mode">USB test: peripheral mode</h2> 194 195 196 <p>Hardware needed: USB cable, OTG adapter</p> 197 198 <h3 id="android_to_android">Android-to-Android</h3> 199 200 201 <p>Apps needed: <em>MidiKeyboard</em> on Android device under test, <em>MidiScope</em> on another 202 Android device.</p> 203 204 <p>Use Android devices as a peripheral controller for another Android device. To help test 205 this mode, use another Android device running in host mode. Note that 206 you could modify the test to work with a desktop computer running Digital Audio Workstation (DAW) 207 software such as 208 GarageBand.</p> 209 210 <ol> 211 <li> Connect the USB cable to the Android device under test (Android device <strong>A</strong>).</li> 212 <li> Use an OTG adapter to connect the other end of the cable to a second Android 213 device <strong>B</strong> that operates in host mode.</li> 214 <li> On Android device A: 215 <ol> 216 <li> Drag finger down from top of screen.</li> 217 <li> Select <strong>USB for Charging</strong> icon.</li> 218 <li> Select <strong>MIDI</strong>.</li> 219 <li> Launch <em>MidiKeyboard</em> app.</li> 220 <li> Select <strong>Android USB Peripheral Port</strong> from <em>Receiver for Keys</em> menu at top.</li> 221 </ol> 222 </li> 223 <li> On Android device B: 224 <ol> 225 <li> Launch <em>MidiScope</em> app.</li> 226 <li> Select the other Android device as the source.</li> 227 </ol> 228 </li> 229 <li> On Android device A: 230 <ol> 231 <li> Play notes on the keyboard and look for <em>NoteOn</em> and <em>NoteOff</em> on Android device B.</li> 232 </ol> 233 </li> 234 </ol> 235 236 <h2 id="bluetooth_le_test">BLE test</h2> 237 238 239 <p>Hardware needed: MIDI keyboard supporting BLE</p> 240 241 <h3 id="basic_pairing_and_playing">Basic pairing and playing</h3> 242 243 244 <p>Apps needed: <em>MidiBtlePairing</em>, <em>MidiSynthExample</em></p> 245 246 <p>Test a keyboard connected to Android over BLE.</p> 247 248 <ol> 249 <li> Reboot the Android device.</li> 250 <li> Power on the BLE keyboard.<br /> 251 (The Miselu C.24 keyboard is powered on by pushing the button near the back so 252 that it pops open. The power button on the C.24 pulses blue when in pairing 253 mode.)</li> 254 <li> Launch the <em>MidiBtlePairing</em> app. It has a <em>MIDI+BTLE</em> icon.</li> 255 <li> Press the <strong>Bluetooth Scan</strong> button.</li> 256 <li> Select desired BLE peripheral.</li> 257 <li> The app should return to the main page, and you should see the peripheral listed. If 258 you are using a C.24, then you will notice that the light should turn green on 259 the C.24 to indicate paired mode.</li> 260 <li> Exit the app by pressing the <strong>Home</strong> button, not the <strong>Back</strong> button.</li> 261 <li> Launch the SynthExample app.</li> 262 <li> Select the BLE keyboard as the sender from the menu.</li> 263 <li> You should be able to press keys on the BLE keyboard and hear notes on 264 Android.</li> 265 </ol> 266 267 </body> 268 </html> 269
