MIDI basics

This article shows how a Blue Gecko can be used as a MIDI controller over Bluetooth Low Energy. At first we give some basic info about the MIDI standard then on the Apple Bluetooth Low Energy MIDI Specification. Finally, we highlight and explain the most important code snippets from the attached sample application which implements a very basic MIDI controller.

The protocol

MIDI is an industry standard music technology protocol that connects products from many different companies including digital musical instruments, computers, tablets and smartphones. MIDI is used everyday around the world by musicians, DJs, producers, educators, artists and hobbyists to create, perform, learn and share music and artistic works. Nearly every hit album, film score, TV show and theatrical production uses MIDI to connect and create. MIDI information is transmitted in "MIDI messages", which can be thought of as instructions which tell a music synthesizer how to play a piece of music. The synthesizer receiving the MIDI data must generate the actual sounds.

Physical layer

The MIDI specification for the electrical interface is based on a fully isolated current loop. The MIDI OUT port nominally sources a +5 volt source through a 220 ohm resistor out through pin 4 on the MIDI OUT DIN connector, in on pin 4 of the receiving device's MIDI IN DIN connector, through a 220 ohm protection resistor and the LED of an optoisolator. The current then returns via pin 5 on the MIDI IN port to the originating device's MIDI OUT port pin 5, again with a 220 ohm resistor in the path, giving a nominal current of about 5 milliamperes. Despite the cable's appearance, there is no conductive path between the two MIDI devices, only an optically isolated one. The data rate on this system is a relatively slow (by today standards) 31,250 bits per second, logic 0 being current ON. The MIDI data stream is a unidirectional asynchronous bit stream with 10 bits transmitted per byte (a start bit, 8 data bits, and one stop bit). The MIDI data stream is usually originated by a MIDI controller, such as a musical instrument keyboard.

MIDI controller and sound module

A MIDI controller is a device which is played as an instrument, and it translates the performance into a MIDI data stream in real time (as it is played). The MIDI data output from a MIDI controller is transmitted via the devices' MIDI OUT connector. The recipient of this MIDI data stream is commonly a MIDI sound generator or sound module, which will receive MIDI messages at its MIDI IN connector, and respond to these messages by playing sounds.

MIDI messages

There are a number of different types of MIDI messages. See the https://www.midi.org for details.

In the example code attached we implemented only Note On and Note Off messages. The Note On message is used for turning on MIDI notes. This is typically sent when a key pressed on keyboard. The Note Off message is used for turning off MIDI notes. This is typically sent when a key released on keyboard.

MIDI over BLE

There are number of solutions where the standard DIN connector and physical layer changed to a more modern medium like USB or Ethernet. Apple defined a custom BLE service for MIDI support. This is now part of the MIDI standard.

This specification can be found here:

https://www.midi.org/specifications/item/bluetooth-le-midi

To support MIDI over BLE the accessory has to fulfill a set requirements collected below.

Connection interval

The accessory shall request a connection interval of 15 ms or less. Apple recommends starting with a request for a connection interval of 11.25 ms and going to 15 ms if the connection request is rejected by the Apple product. Intervals higher than 15 ms are unsuitable for live playback situations.

MTU negotiation

The accessory shall support MTU negotiation. See the MTU Size section in the Bluetooth Low Energy chapter of the Bluetooth Accessory Design Guidelines for Apple Products for implementation details.

Multiple packet transmissions

The accessory shall support sending and receiving the maximum number of Bluetooth Low Energy packets that can fit into the connection interval. MIDI minimum bandwidth requirements may not be met otherwise.

Custom MIDI Service and Characteristic

The GATT should contain the following service and characteristic

The MIDI I/O characteristics

Header and Timestamp fields

Additional Header and Timestamp fields has to be added before the standard MIDI message format

• Header bit 7 is start bit and set to 1
• Header bit 6 is reserved and set to 0
• Header bits 0-5 are upper 6 bits of 13 bit timestamp
• Timestamp bit 7 is start bit and set to 1

Note that the actual timestamp value is splitted between the Header and Timestamp fields.

The 13-bit timestamp for a MIDI event in any given Bluetooth Low Energy packet is formed from the bottom 6 bits of the Header field and the bottom 7 bits of the Timestamp filed. Timestamps are in expressed in milliseconds, implying that the maximum timestamp range is 8192 ms. Timestamps shall be sent in monotonically increasing order.

Example application

The attached application act as a very basic MIDI controller. It can send MIDI note on and MIDI note off messages when a button pressed or released on the WSTK. Pressing PB0 button repeatedly will play the Imperial March from Star Wars. Pressing PB1 is resetting the sequence so the melody can start from the beginning.

The application is built upon the Simplicity Studio Bluetooth SDK ver. 2.11 and tested with the BGM13S Starter Kit (SLWSTK4305A) but it should work with other EFR32 based Bluetooth enabled targets with minimal changes.

We going to highlight the most important steps which are needed for building a MIDI over BLE compatible device.

GATT definition

The GATT.xml file has to contain the MIDI service definition as it is showed below.

  <!--MIDI Service-->
  <service advertise="true" name="MIDI Service" requirement="mandatory" sourceId="custom.type" type="primary" uuid="03B80E5A-EDE8-4B33-A751-6CE34EC4C700">
    <informativeText>Custom service</informativeText>
    <!--MIDI I/O Characteristic-->
    <characteristic id="xgatt_midi" name="MIDI I/O Characteristic" sourceId="custom.type" uuid="7772E5DB-3868-4112-A1A9-F2669D106BF3">
      <informativeText>Custom characteristic</informativeText>
      <value length="20" type="hex" variable_length="true">0x20</value>
      <properties encrypted_read="true" encrypted_read_requirement="optional" encrypted_write="true" encrypted_write_requirement="optional" notify="true" notify_requirement="optional" read="true" read_requirement="optional" write_no_response="true" write_no_response_requirement="optional"/>
    </characteristic>
  </service>

Enable the bonding before connection

void midi_init_ble_connection(void)
{
    gecko_cmd_sm_set_bondable_mode(1);
}

Set the connection interval to the required 15 ms.

void midi_ble_connected(uint8_t connection)
{
    /* store the connection ID */
    connectionId = connection;
    /* connection parameter constrains for ble MIDI */
    gecko_cmd_le_connection_set_timing_parameters(connection, 0x12, 0x12, 0, 0x64, 0, 0xFFFF);
}

Setup CRYOTIMER for creating 1ms timer for the timestamp

This timestamp has to be included to the MIDI message.

void midi_init_timer(void)
{
    CRYOTIMER_Init_TypeDef cryoInit = CRYOTIMER_INIT_DEFAULT;

    /* General settings */
    cryoInit.enable    = 1;
    cryoInit.debugRun  = 0;
    cryoInit.em4Wakeup = 0;

    /* Clocking settings */
    /* With a frequency of 1000Hz on ULFRCO, this will result in a 1.00 ms timeout */
    cryoInit.osc    = cryotimerOscULFRCO;
    cryoInit.presc  = cryotimerPresc_1;
    cryoInit.period = cryotimerPeriod_1;
    CRYOTIMER_Init(&cryoInit);
}

Setup GPIO interrupt for button press

Here is the PBB0_pressed function registered as a GPIO interrupt service routine and will be triggered for both rising and falling edges. The function is reading the GPIO state and sends a note on or note off message accordingly. The code snippet below shows the recommended way for registering the ISR.

void midi_init_buttons(void)
{
    /* Init GPIO ISR dispatcher */
    CMU_ClockEnable(cmuClock_GPIO, true);
    GPIOINT_Init();

    /* Setup PB0 */
    /* GPIO init for button pins */
    GPIO_PinModeSet(BSP_BUTTON0_PORT, BSP_BUTTON0_PIN, gpioModeInput, 0);

    /* Register GPIO ISR */
    GPIOINT_CallbackRegister(BSP_BUTTON0_PIN, PB0_pressed);

    /* Trigger for both edge */
    GPIO_IntConfig(BSP_BUTTON0_PORT, BSP_BUTTON0_PIN, true, true, true);
...

Function to send a note on message

The midi_note_on() function prepare and send a note on message. First the function gets the timestamp from the CRYOTIMER. The CRYTIMER provides a 32 bit counter but according to the specification we need only the lower 13 bit, so the rest of the bits are masked. Then the function fills the header and timestamp fields. The header byte is 0b10xxxxxx where xxxxxxx is top 6 bits of timestamp. The timestamp byte is 0b1xxxxxxx where xxxxxxx is lower 7 bits of timestamp.

The status byte is 0x90 is 0b1sssnnnn where sss is message type and nnnn is the MIDI channel.

The last two bytes contains the 2 byte long event field in this case it is the note and velocity.

Finally the function sends the message with the gecko_cmd_GATT_server_send_characteristic_notification API function.

void midi_note_on(uint8 note, uint8 velocity)
{
  static midi_data_t note_on;

  /* Get the timestamp from the CRYOTIMER */
  uint32 temp = CRYOTIMER_CounterGet();
  /* Mask it - only the lower 13 bit needed */
  temp = temp & 0x00001fff;
  /* Header byte = 0b10xxxxxx where xxxxxxx is top 6 bits of timestamp */
  note_on.midi_event.header = 0x80 | (temp >> 7);
  /* Timestamp byte = 0b1xxxxxxx where xxxxxxx is lower 7 bits of timestamp */
  note_on.midi_event.timestamp = 0x80 | (temp & 0x003f);
  /* Status byte = 0b1sssnnnn where sss is message type and nnnn is channel */
  note_on.midi_event.status = 0x90;
  /* setting the note parameter */
  note_on.midi_event.note = note;
  /* setting the velocity parameter */
  note_on.midi_event.velocity = velocity;
  /* sending the assembled MIDI message */
  gecko_cmd_GATT_server_send_characteristic_notification(connectionId, GATTdb_xGATT_MIDI, 5, (uint8 const *) &note_on);
}

Testing

Once the application flashed to kit it starts advertise itself. After connection it pairs and bonds with just work method. The application tested with the following IOS apps:

• Korg Module
• Korg Gadget
• Apple GarageBand

References

[1] https://www.midi.org

[2] https://www.midi.org/specifications/item/bluetooth-le-midi

[3] https://en.wikipedia.org/wiki/MIDI

Introduction

The EFR32xG13 devices (revision D or newer) include an internal oscillator, the PLFRCO, or Precision Low Frequency RC Oscillator, which is a self-calibrating RC oscillator that eliminates the need for a 32.768kHz crystal.

The PLFRCO can be used by the Bluetooth stack as the low frequency clock source (instead of the LFXO) that is used by the system to wake-up the device on each connection interval when sleep is enabled in the stack.

The PLFRCO has a frequency accuracy of +/-500 ppm which is within the Bluetooth specification requirements.

It is best suited for some BLE use cases such as applications with very constrained cost targets or board layout space, devices that maintain short connection intervals or have infrequent BLE connections as well as devices that advertise most of the time (such as iBeacon or Google Eddystone devices).

Selecting the PLFRCO

Using the PLFRCO requires only a few changes in init_mcu.c and one change in the Bluetooth stack configuration structure.

In the Bluetooth stack configuration structure the sleep clock accuracy needs to be changed to 500 ppm.

static gecko_configuration_t config = {
    ...
    ...
    .bluetooth.sleep_clock_accuracy = 500, // ppm
    ...
    ...
};

In init_mcu.c it is required to initialize the PLFRCO and select it as a clock source for the low frequency clock branches. There’s essentially 2 steps to take:

• Remove the LFXO related initialization code
• Uncomment PLFRCO related code to change clock sources LFA, LFB, LFE and init oscillator

// UNCOMMENT THIS >>

//To use PLFRCO please remove commenting of these lines
//and comment out or delete the LFXO lines if they are present
//If using PLFRCO update gecko_configuration_t config's
//.bluetooth.sleep_clock_accuracy to 500 (ppm)
//  #if defined(PLFRCO_PRESENT)
//    /* Ensure LE modules are accessible */
//    CMU_ClockEnable(cmuClock_CORELE, true);
//    /* Enable PLFRCO as LFECLK in CMU (will also enable oscillator if not enabled) */
//    CMU_ClockSelectSet(cmuClock_LFA, cmuSelect_PLFRCO);
//    CMU_ClockSelectSet(cmuClock_LFB, cmuSelect_PLFRCO);
//    CMU_ClockSelectSet(cmuClock_LFE, cmuSelect_PLFRCO);
//  #endif

// DELETE OR UNCOMMENT THIS >>

// Initialize LFXO
CMU_LFXOInit_TypeDef lfxoInit = BSP_CLK_LFXO_INIT;
lfxoInit.ctune = BSP_CLK_LFXO_CTUNE;
CMU_LFXOInit(&lfxoInit);
// Set system LFXO frequency
SystemLFXOClockSet(BSP_CLK_LFXO_FREQ);

// Set LFXO if selected as LFCLK
CMU_ClockSelectSet(cmuClock_LFA, cmuSelect_LFXO);
CMU_ClockSelectSet(cmuClock_LFB, cmuSelect_LFXO);
CMU_ClockSelectSet(cmuClock_LFE, cmuSelect_LFXO);

Tradeoffs

The most obvious benefit of using the PLFRCO instead of the LFXO is the cost savings from not using the low frequency crystal. The drawback is that the PLFRCO increases the sleep current by up to 500 nA and extends the RX receive window on the slave side at the beginning of each connection interval.

Sleep Current

Below are sleep current measurements on the same device with LFXO and PLFRCO where the sleep current difference is about 280 nA.

Figure 1. EFR32xG13 sleep current with LFXO

Figure 2. EFR32xG13 sleep current with PLFRCO

RX Period Extension

At the beginning of each connection interval the master device is the first to send out a packet. This makes it a hard requirement that the slave must be listening (in RX) in order not to lose that initial packet from the master device. The combined clock accuracy from master and slave (sum of both accuracy values in ppm) is used to calculate when the slave should wake-up to listen for the incoming packet.

When the accuracy is lower, the slave must wake-up earlier, so there will be a longer RX receive window when using a PLFRCO compared to the LFXO due to the lower accuracy. The images below show an empty packet taken from the slave side with 1 second connection interval and 0 dBm output power. When using PLFRCO the RX receive window is extended by ~250 µs. The longer the connection intervals the more pronounced will be the RX window extension when compared to LFXO usage.

Figure 3. Empty packet using LFXO

Figure 4. Empty packet using PLFRCO

One final note, when the slave misses connection intervals (e.g. device was temporarily out of range or due to interference) then the RX receive window will be widened by the combined accuracy until the slave is able to catch the initial packet from the master. Let's consider a combined accuracy of +/-600 ppm. If the connection interval is 1 s and the slave misses a connection interval, the next interval's RX receive window will be widened by 600 µs = 600 parts of 1 million micro-seconds.

Hardware & SDK Requirements

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.4.0 GA or newer, the latest version is always recommended.
• NCP target – At least 1 Bluetooth Mesh compatible boards - EFR32xG12, EFR32xG13 or EFR32xG21 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• NCP host - POSIX compatible machine to run the host application. Running the application on Windows needs some porting afford, this has only been tested with Linux and Cygwin.

How to Use It

The NCP mode requires both the host and target to work.

Supported Commands

A simple console is implemented to receive commands from user. Users can add any customized command by adding an new item to CMDs array in app.c.

Generate NCP target

1. Create "NCP - Mesh Empty Target" project based on the attached board and the latest Bluetooth Mesh SDK.
2. Open the ${projectname}.isc file, add "Light Lightness Client", "Generic Power OnOff Client" and "Light CTL Client" models to the Bluetooth SIG Models section. It's recommended to delete "Configuration Client" and "Generic OnOff Server" models from it. Modify the _Features Bitmask to 0x000b, then click "Generate" button.
3. If the NCP target needs to sleep, you need to make step 4-5 changes to the project. The provided example DOESN'T enable the sleep mode.
4. Add below code right before while(1) in main.c:

#if defined(_SILICON_LABS_32B_SERIES_1_CONFIG_3)
  /* xG13 devices have two RTCCs, one for the stack and another for the application.
     * The clock for RTCC needs to be enabled in application code. In xG12 RTCC init
     * is handled by the stack */
  CMU_ClockEnable(cmuClock_RTCC, true);
#endif

1. Open the hal-config.h file and define the symbol NCP_DEEP_SLEEP_ENABLED. After that, you need to specify the wake up pin location to the symbols NCP_WAKEUP_PORT, NCP_WAKEUP_PIN and NCP_WAKEUP_POLARITY. The same rule applies to the symbol NCP_HOST_WAKEUP_ENABLED if you want the NCP target could wakeup the host.
2. Erase the attached board, then build and program to it.

Run the example

• Download the attachment and extract it.
• cd to the foler and run "make SDK_DIR=xxx", where xxx is the real directory of your BT Mesh SDK. Assuming it builds without errors.
• The executable takes 2 parameters - serial port and baud rate. Run it as "sudo ./exe/switch /dev/ttyACM2 115200"
• If the shell starts normally, type "h" to get usage example
• Find a provisioner and light node to test it.

Introduction

This program offers a way to do some simple mesh testing on custom hardware with no access to prints, LCD, or external inputs like buttons. This is a lightweight version of the soc-btmesh-switch sample application where files and instruction for serial printing, LCD printing and GPIO functionalities are taken out. Can be used for testing bt-mesh functionality without hardware dependencies.

The program offers the switch functionality issuing commands to turn the light On and Off every 2 seconds.

Implementation

• In Simplicity Studio, select your radio board, select the latest Bluetooth Mesh SDK and create soc-btmesh-empty example project for your device.

• Copy and replace the attached files (main.c and soc-bt-mesh-empty.isc) into your project.

• Open the recently copied soc-bt-mesh-empty.isc file and generate. Compile and flash to your radio board.

Testing

• Select another radio board with a WSTK as shown in the figure below. This device will act as the light node. Flash the soc-btmesh-light sample application from Simplicity Studio.

• Provision both devices and create a network.

• Make sure that the light nodes in the network subscribe to the address that the switch publishes to.

• You will observe the light node get commands to turn On and Off every 2 seconds.