BLE MIDI Server Example

Anonymous · ‎Jan 07, 2018

Overview

In this example, the CYW20719 device is configured as a MIDI Server that sends MIDI data over BLE. The CYW920719Q40EVB_01 Eval board is connected to a PC and keypress from the keyboard is sent as input to the PUART terminal of the CYW20719 device via Serial COM terminal interface of the Eval board. The CYW20719 maps the ASCII inputs from the PUART to MIDI notes and sends them as BLE notification to a MIDI Central in accordance with the BLE MIDI Specification.

Requirements

Tool: WICED Studio 6.1 and above, Any MIDI Central Client (Example: Garageband App for iOS), Serial Terminal (Example: TeraTerm, CoolTerm). This blog

Programming Language: C

Associated Parts: CYW20719

Related Hardware: CYW920719Q40EVB_01 Board

Block Diagram

MIDI Protocol

The MIDI (Musical Instrument Digital Interface) protocol is a standard that defines the way various devices transfer music related audio data. The BLE Protocol can be used to implement the MIDI standards, enabling a connection between BLE enabled musical instruments and other devices such as Phones, computers, speakers etc., A BLE MIDI Controller should meet the following standards:

Scan Response Packet

Either the advertisement packet or scan response packet should contain the UUID of the MIDI Service in the Service UUID field. MIDI Service UUID: 03B80E5A-EDE8-4B33-A751-6CE34EC4C700
Below is an example for a typical scan response packet that contains the service UUID alone:

0x11 0x07 0x00 0xC7 0xC4 0x4E 0xE3 0x6C 0x51 0xA7 0x33 0x4B 0xE8 0xED 0x5A 0x0E 0xB8 0x03 (Totally 18 Bytes)

First Byte 0x11 is the length (17 Bytes, excluding the length byte)
The second byte 0x07 indicates 128 Bit Service UUID is present.
The last 16 bytes are the 128 Bit UUIDs for the MIDI Service. (UUID: 03B80E5A-EDE8-4B33-A751-6CE34EC4C700)

GATT Database

The GATT Database should have a MIDI Service with UUID same as the UUID in the scan response packet (UUID: 03B80E5A-EDE8-4B33-A751-6CE34EC4C700)
Inside the MIDI Service, there should be a characteristic (MIDI IO Characteristic) with UUID: (7772E5DB-3868-4112-A1A9-F2669D106BF3)
It's properties are Read, Write without response and Notify
The permissions should be set to "Encryption Required"
The MIDI IO Characteristic should have a CCCD (Client characteristic configuration descriptor)
Upon pairing the MIDI Client will read the MIDI Characteristic, for which the MIDI Controller should respond with an empty packet.

Other Requirements

Connection interval < 15 mS (to avoid Jitter)
MTU Negotiation should be supported

MIDI Data Format:

The MIDI events i.e. messages are sent as notifications. The first 2 bytes of the notifications contain the time stamps in millisecond resolution.

The Byte [0] is the MIDI header. The MSB (7th Bit) is always 1 and the 6th bit is always 0. The rest of the bits contain the Most Significant 6 bits of the time stamp.

The Byte [1] is the MIDI Timestamp byte. The 7th Bit is always 1 and the rest of the 7 bits contain the lest significant 7 bits of the timestamp.

Thus the Byte [0] and the Byte[1], together contain a 13 bit time stamp in milliseconds.

The Byte [2] contain the MIDI Status (NOTE ON, NOTE OFF, Control Change, Program Change etc.,)

The next bytes contain the MIDI messages (Status followed by MIDI Data. Refer the MIDI Specification for more details)

Simple Piano Example:

This is a simple example in case of a piano. For the sake of simplicity and testing we can set the time stamps to be 0.

When the key is pressed, it is called NOTE ON message. When you release the key it is called NOTE OFF message. NOTE ON and NOTE OFF are send as notifications. The status field of the notifications indicate whether a message is NOTE ON of NOTE OFF.

Each NOTE ON and NOTE OFF may be 5 bytes : Byte[0], Byte[1], Byte[2, Byte[3], Byte[4]

Byte[0] : MIDI Header. In this example, it is always 0x80, as the timestamp is set as 0.

Byte[1] : Timestamp. This too will remain 0x80

Byte[2] :

For a NOTE ON message Byte[2] = 0x90 | Channel number

For a NOTE OFF message Byte[2] = 0x80 | Channel number

Channel Number:

When different musical instruments need to be played, each one is assigned one channel number. For example, if you are using piano and drum, piano is assigned channel number 0 and drum is assigned channel number 1.

In our example, only one instrument is used. So channel number is 0.

So BYTE[2] for NOTE ON message is 0x90, Byte[2] for NOTE OFF message is 0x80

Byte[3]: This contains the hex code of the actual note we play.

In keyboard we have basic 12 notes. The notes and their corresponding hex codes used in this example are given in the table below:

Note	Hex Code
C	0x3C
C#	0x3D
D	0x3E
D#	0x3F
E	0x40
F	0x41
F#	0x42
G	0x43
G#	0x44
A	0x45
A#	0x46
B	0x47
C1	0x48

Byte [4]: This is the velocity. This denotes how fast we press the key. It ranges from 0 to 0x7F.

If velocity is 0, it also means NOTE OFF message, even though Byte [2] is 0x90. So, for NOTE ON messages, the velocity (Byte [4]) should be a non-zero value. We usually select the middle value between 0 and 127 i.e. 63 (0x3f)

Assume the following case.

1) User first presses C

2) Releases C

3) Presses D#

4) releases D#

Assuming the velocity to be 0x3F, This can be sent as 4 notifications:

Notification 1: 0x80 0x80 0x90 0x3c 0x3f

Notification 2: 0x80 0x80 0x80 0x3c 0x0

Notification 3: 0x80 0x80 0x90 0x3F 0x3f

Notification 4: 0x80 0x80 0x80 0x3F 0x0

Programming and Testing

Install the WICED Studio 6.1 (or above) in your PC. Plug in two CYW920719Q40EVB_01 Boards and let the drivers bind
to the devices. Make sure the jumpers are in place. Open WICED Studio and set the platform as 20719-B1_Bluetooth. For more details, please refer CYW920719Q40EVB_01-Kit-Guide.pdf present in Doc folder in the project explorer.
Copy the midi_server project folder. In the WICED Studio, right-click the Apps folder in the Project Explorer pane and click Paste. You can see these folders under the Apps folder.
Open two windows of Serial Terminal (Example: Teraterm or Coolterm), and bind each of those windows to the PUART COM Ports of each devices. Each device has two COM Ports with consecutive numbers. The COM Port with the bigger number corresponds to the PUART that displays Debug Messages. The one with the smaller number corresponds to the HCI UART. The BaudRate is set to 115200 in the firmware. Make sure the BaudRate in serial terminals is also set to 115200.
Create a Make Target for the project by selecting Project -> Make Target -> Create. Paste the following as the entry in the Target Name field:

midi_server-CYW920719Q40EVB_01 UART=COMxx download

Make sure that the Same as the Target Name checkbox is checked. Click OK.

(Note: In the above target, XX is the HCI COM Port numbers of the device.)

6. Double click the Target you just created, shown in the Make Target Pane on the right. You can see the midi_server program being built and downloaded into the board. (For more details or troubleshooting, please refer the WICED-20706-BT-Quick-Start-Guide). Once downloaded, the PUART debug logs can be seen in Teraterm.

7. Have any MIDI Client and Central for connecting to the server device. The example shown here is the Garageband App for iOS. Open Garageband and go to Settings -> Bluetooth MIDI Device. The advertising MIDI Server will be shown on the device with the name “MIDI”

8.Tap on the device to initiate connection and pairing. Once the pairing is completed, the instrument (Keyboard or Guitar) can be selected in the Garageband App. Now, the user can make send MIDI notes to the phone by pressing keys on the computer’s keyboard via the Serial Terminal. The below picture shows the mapping of notes with the keys in the keyboard.

9. As the keys are being pressed, corresponding sound heard from the phone.

10. If MIDI Timestamps need to be used, enable #define USE_TIMESTAMPS macro in midi_server.h

11. In order to initiate disconnection from the device side, press the user button on the Eval board.

Document	Title	Comment
002-22816	CYW920719Q40EVB-01 Evaluation Board User Guide	The User Guide can be accessed in the WICED Studio from Project Explorer -> 20719-B1_Bluetooth -> Doc
002-19103	Developing Custom Applications with BT Designer - Document	This document can be accessed from Project Explorer -> 20719-B1_Bluetooth -> Doc

BLE MIDI Server Example