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

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

This Knowledge Base Article (KBA) aims to act as a “master” KBA which keeps a curated index of all the Bluetooth related KBAs divided into logical categories for an easier and more convenient look-up. It may also include non-KBA content which is relevant for designing your Bluetooth application (e.g. app notes or web pages).

If you are just getting started with Silicon Labs Bluetooth solutions then your starting point should be QSG139: Getting Started with Bluetooth® Software Development. At the end of that document you are presented with the flowchart below which shows what documents should be read and in which order. Additionally you can check out our Bluetooth Training page for more training material.

Knowledge Base Articles List

The content listed below is grouped together into categories to make it easier for you to find what you are looking for. Want to know more about security, or looking for a peripheral example, then head down to the right section and see what KBAs or other relevant content has been created under those topics.

Each category has an associated index number and each individual KBA has its own index number within the category. The KBA's are prefixed with KBA_BT_AABB where AA is the category index and BB is the KBA index within that category. The category index numbers are as follows:

• [01] Bluetooth - General
• [02] Bluetooth - Advertising
• [03] Bluetooth - Stack features
• [04] Bluetooth - Performance
• [05] Bluetooth - Bluetooth Mesh
• [06] Bootloading - General
• [07] Bootloading - UART DFU
• [08] Bootloading - OTA DFU
• [09] Application Examples
• [10] Peripheral Examples
• [11] Security
• [12] Tools
• [13] Hardware
• [14] Migration
• [15] Mobile
• [16] NCP

The KBAs with attached example code are marked with this icon .

Note: Do you want to get automatic notifications when new content is added to the list? Just click the Follow button in upper right corner to subscribe to email notifications. We will make comments when new content is created to trigger those notifications.

[01] Bluetooth General

• KBA_BT_0101: Selecting Your Blue Gecko SoC/Module
• KBA_BT_0102: BLE Basics (master/slave, GATT client/server, data RX/TX)
• KBA_BT_0103: Understanding the Bluetooth Connection Process
• KBA_BT_0104: Acknowledged vs Unacknowledged GATT operations 
• KBA_BT_0105: Bluetooth 5 Features 
• KBA_BT_0106: Bluetooth SIG Resources 
• KBA_BT_0107: Bluetooth Stack Operations Flowcharts

[02] Bluetooth - Advertising

• KBA_BT_0201: Bluetooth advertising data basics 
• KBA_BT_0202: Bluetooth advertising using manufacturer specific data 
• KBA_BT_0203: Providing Extra Data by Scan Response 
• KBA_BT_0204: Using scan request reporting
• KBA_BT_0205: Advertisement Constructor 
• KBA_BT_0206: Extended Advertising Example 
• KBA_BT_0207: Periodic Advertising

[03] Bluetooth - Stack features

• KBA_BT_0301: LE Coded PHY on EFR32xG13
• KBA_BT_0302: Advertising and Scanning with LE Coded PHY 
• KBA_BT_0303: Enabling Coexistence Feature in Bluetooth SDK projects
• KBA_BT_0304: Different characteristic value types 
• KBA_BT_0305: Handling GPIO Interrupts using External Signals 
• KBA_BT_0306: Using the lazy soft timer
• KBA_BT_0307: Enabling TX/RX activity indicator pins in BLE SDK 2.4.0 and later 
• KBA_BT_0308: Polymorphic GATT 
• KBA_BT_0309: How to save float values (or any arbitrary data) in PS keys
• KBA_BT_0310: Changes to the le_gap class of API functions
• KBA_BT_0311: Whitelisting
• KBA_BT_0312: Service Change Indications 
• KBA_BT_0313: GATT Caching

[04] Bluetooth - Performance

• KBA_BT_0401: Optimizing Current Consumption in Bluetooth Low Energy Devices 
• KBA_BT_0402: EM3 and EM4S for non-connectable advertising 
• KBA_BT_0403: Using Energy Modes with Bluetooth Stack 
• KBA_BT_0404: Throughput with Bluetooth Low Energy technology
• KBA_BT_0405: Bluetooth Tx power settings
• KBA_BT_0406: Adaptive Frequency Hopping
• KBA_BT_0407: Bluetooth Radio Task Priorities
• KBA_BT_0408: Current consumption during advertising with different Tx power setting
• KBA_BT_0409: Using the PLFRCO as low-frequency clock source
• KBA_BT_0410: TX power limitations for regulatory compliance (ETSI, FCC)

[05] Bluetooth - Bluetooth Mesh

• KBA_BT_0501: BT Mesh embedded provisioner example 
• KBA_BT_0502: Bluetooth Mesh Vendor Specific Model Example 
• KBA_BT_0503: Advertising Sets Used by the Bluetooth Mesh Stack
• KBA_BT_0504: Adding custom advertising to the Bluetooth mesh examples
• KBA_BT_0505: Bluetooth Mesh Training resources
• KBA_BT_0506: Minimalistic OnOff client for testing Bluetooth Mesh on custom board
• KBA_BT_0507: Bluetooth Mesh Host Switch Example

[06] Bootloading - General

• KBA_BT_0601: Why Doesn't My Sample Application Run?
• KBA_BT_0602: Bootloader changes in BLE SDK
• KBA_BT_0603: Adding Gecko Bootloader to Bluetooth projects
• KBA_BT_0604: Switching between firmware images using Internal Storage Bootloader
• KBA_BT_0605: Upgrading Gecko Bootloader
• KBA_BT_0606: Upgrading Gecko Bootloader with Slot address change
• KBA_BT_0607: Adding metadata to GBL files 
• KBA_BT_0608: Factory programmed firmware of Bluetooth devices

[07] Bootloading - UART DFU

• KBA_BT_0701: Upgrading from factory firmware (v2.0.0) and from Bluetooth SDK v2.1.x with UART DFU type legacy bootloader
• KBA_BT_0702: UART DFU - Upgrading BGM111 by EFM32PG example 

[08] Bootloading - OTA DFU

• KBA_BT_0801: Using Blue Gecko app OTA
• KBA_BT_0802: Uploading images to internal/external flash using OTA DFU 
• KBA_BT_0803: Bluetooth OTA updates using customized advertising data
• KBA_BT_0804: Secure OTA DFU
• KBA_BT_0805: Setting Bluetooth Address as device name in OTA 
• KBA_BT_0806: Using BLED112 to do Over-the-Air update of BGMxxx 
• KBA_BT_0807: Implementing OTA firmware update in the user application 

[09] Application Examples

• KBA_BT_0901: Bluetooth SoC-Empty example
• KBA_BT_0902: How to use Voice over Bluetooth Low Energy example for Thunderboard Sense
• KBA_BT_0903: SPP-over-BLE example 
• KBA_BT_0904: Creating an Eddystone-URL Beacon 
• KBA_BT_0905: SPP client example using BLED112 dongle 
• KBA_BT_0906: Multi-Slave Multi-Master Dual-Topology example 
• KBA_BT_0907: Parallel handling of multiple slaves with Bluetooth stack 
• KBA_BT_0908: Using RTCC as Timer or Calendar while running BLE stack 
• KBA_BT_0909: Scheduling application tasks while running BLE stack
• KBA_BT_0910: Using the UD flash in the Bluetooth C SDK 
• KBA_BT_0911: Midi over BLE 
• KBA_BT_0912: Control LEDs on a Bluetooth WSTK with a Mobile App 
• KBA_BT_0913: BLE Central and GATT client example - working with an Android app 
• KBA_BT_0914: ANCS 
• KBA_BT_0915: Throughput Tester Example 
• KBA_BT_0916: Working with Long Characteristic Values 
• KBA_BT_0917: Implementing wireless direct test mode (DTM) 
• KBA_BT_0919: Using EM3 or EM4 energy mode in a Bluetooth beacon app 
• KBA_BT_0920: Bluetooth Device Tracking with Tile 

[10] Peripheral Examples

• KBA_BT_1001: Using the LEUART 
• KBA_BT_1002: Using Low Energy Timers 
• KBA_BT_1003: Using accelerometer found in the WSTK expansion board 
• KBA_BT_1004: Hardware Timers with EFR32xG1x 
• KBA_BT_1005: Reporting Battery Voltage over BLE 
• KBA_BT_1006: Thermometer example with EFR32 internal temperature sensor 
• KBA_BT_1007: Enable LCD screen on WSTK 
• KBA_BT_1008: Watchdog on BGM111 (and other Blue Gecko modules / boards) 
• KBA_BT_1009: Waking from Deep Sleep Using RF Sense 
• KBA_BT_1010: Push buttons and interrupts in a Bluetooth project 
• KBA_BT_1011: How can I extend the Bluetooth examples with UART functionality? 
• KBA_BT_1012: Adding Watchdog in NCP Mode

Additional Resources

• MCU Peripheral Examples on GitHub (also includes EFR32)

[11] Security

• KBA_BT_1101: Using Bluetooth security features in Silicon Labs Bluetooth SDK
• KBA_BT_1102: Pairing Processes
• KBA_BT_1103: Application Layer Security 
• KBA_BT_1104: The New Bond Replacement Algorithm
• KBA_BT_1105: How to handle missing bonding keys 
• KBA_BT_1106: OOB introduction and example 
• KBA_BT_1107: Secure connection with serial communication between two BGM modules 
• KBA_BT_1108: Authenticating Bluetooth Devices with no User Interface 

[12] Tools

• KBA_BT_1201: Condensed Bluetooth SDK revision history (2.0.0 and later)
• KBA_BT_1202: Building C++ BLE projects
• KBA_BT_1203: Creating projects for EFR32BG on a custom board
• KBA_BT_1204: How to flash BGM11x or EFR32BG from command line?
• KBA_BT_1205: Programming an external BGM111 using the WSTK
• KBA_BT_1206: Log System
• KBA_BT_1207: Event and Error Checking 
• KBA_BT_1208: Using virtual COM port (VCOM)
• KBA_BT_1209: Debugging BGTool not being able to communicate with NCP target.
• KBA_BT_1210: Connect Custom board to Simplicity Studio using JTAG/SWD.

Additional Resources

• Simplicity Studio now Treats Bluetooth Modules as Parts

[13] Hardware

• KBA_BT_1301: How to find schematics and other documentation for radio boards?
• KBA_BT_1302: Supplying EFR32 PAVDD from 3.3V
• KBA_BT_1303: Enabling LNA on MGM12P for Bluetooth usage
• KBA_BT_1304: Antenna tuning for BGM12x (coin-cell usage example)
• KBA_BT_1305: Quartz Crystals, MEMS Oscillators, and Phase Noise for BLE Applications
• KBA_BT_1306: TX Power Levels 
• KBA_BT_1307: What is a STEP file and how to obtain a STEP file for Silicon Labs IOT products?
• KBA_BT_1308: Saving CTUNE value as manufacturing token
• KBA_BT_1309: Design and Assembly guidelines when using xGM parts based System in Package (SiP)

Additional Resources

• Debugging and Programming Interfaces for Custom Designs
• Production Programming Options for Silicon Labs Devices
• RF Range Calculator
• Driving FEMs (and PAs and LNAs) on EFR32

[14] Migration

• KBA_BT_1401: Updating NCP projects to SDK 2.4.x
• KBA_BT_1402: Bluetooth Smart SDK Migration Guide From V2.0.1 to V2.1.x
• KBA_BT_1403: Migrating Simplicity Studio projects from Bluetooth SDK 2.1.1 to 2.3.1
• KBA_BT_1404: Migrating Simplicity Studio projects from Bluetooth SDK 2.3.x to 2.4.x
• KBA_BT_1405: Migration guide to Bluetooth SDK 2.7.x

[15] Mobile

• KBA_BT_1501: BLE devices on iOS Bluetooth Settings page
• KBA_BT_1502: Evaluating SPP-over-BLE example using BLE1xx cable replacement app 
• KBA_BT_1503: iOS 9.1 with respect to Bluetooth LE
• KBA_BT_1504: Mobile Devices used for Interoperability Testing
• KBA_BT_1505: Selecting suitable connection parameters for iOS 
• KBA_BT_1506: How to find the Bluetooth 5 feature status of a listed device such as a smartphone

[16] NCP

• KBA_BT_1601: Custom communication over NCP 
• KBA_BT_1602: NCP Host Implementation and Example 
• KBA_BT_1603: Local Event Handling on Bluetooth NCP 

MIDI over BLE with Wireless Gecko Soc-s and Modules

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

MIDI over BLE with Wireless Gecko Soc-s and Modules

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 specification can be found here:

https://developer.apple.com/bluetooth/Apple-Bluetooth-Low-Energy-MIDI-Specification.pdf

With the release of iOS 8 and OS X Yosemite, sending and receiving MIDI data is supported using Bluetooth Low Energy connections on any iOS device or Mac that has native Bluetooth Low Energy support.

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

We are currently exploring the potential of using the WGM110 module in a WiFi direct project. One scenario is there maybe multiple WGM110 devices.

We assume the user  has already connected to all of the devices and set everything up (for example one touch security).

Based on their mac address etc... we could give each Direct WiFi Device  a unique names.

An android application could simply cycle through the list of WiFi direct devices detected and connect to them one by one in order query their functionality (Perhaps json, or a web page might be provided by the WiFi Direct device).

Does this approach seem sensible?

Using Bluetooth security features in Silicon Labs Bluetooth SDK

This article introduces the Bluetooth security features and terms then summarizes the practical usage of GATT permissions and pairing processes using the Silicon Labs Bluetooth SDK.

Bluetooth Security Basics

The most common threats in wireless communications are:

• Passive eavesdropping
• Active eavesdropping = Man in the Middle (MITM)
• Privacy (tracking)

Bluetooth defines 5 distinct security features against these threats:

• Pairing — creating trusted relationships between devices (Key Generation, Key Exchange, Identity Information Exchange)
• Bonding — Storing the keys created during pairing for later connections
• Device authentication — verification that devices have the same keys (Protected from MITM)
• Encryption — data confidentiality (FIPS or NIST approved AES128-CCM algorithm used)
• Data signing (Message integrity) — protection against data alteration

These features implemented in different layers of the Bluetooth stack. Let's have a quick look on these.

Pairing

• Is the process of creating trusted relationships between devices
• Used to generate and exchange security keys
• Used to exchange identity information

Bluetooth uses Secure Simple Pairing (SSP) pairing model. The actual pairing process depends on the device I/O capabilities and the security requirements defined by the application.

• Just works — For devices without UI. No user interaction required. No MITM protection. In case of Just works pairing there is no possibility to confirm the identity of the connecting devices. Devices will pair with encryption but without authentication.
• Passkey entry — User needs to enter a passkey the remote party displays. Provides MITM protection
• Numeric comparison — User needs to confirm passkeys both devices display. Provides MITM protection
• Out-of-band — Encryption keys exchanged for example with NFC

More details can be found here in the Pairing Processes KBA.

Bonding

• Storing security keys for future use
• ex. authentication of connections or verifying devices identity

Authentication

• Authentication is defined as a way to prove that the device with which you are connecting is actually the device it claims to be and not a third-party attacker
• Authentication in the GATT Profile is applied to each characteristic independently. The GATT Profile procedures are used to access information that may require the client to be authenticated

A characteristic may be allowed to be read by any device, but only written by an authenticated device. Similarly, if a characteristic can be written, it does not mean the characteristic can also be read. Each individual characteristic could have different security properties.

Encryption

• Encryption protects the data confidentiality and integrity
• Paired or bonded devices can encrypt/decrypt data sent within a connection
• Bluetooth uses AES-128 as the encryption algorithm

Notice: No encryption of broadcast data

Attribute permissions

• Attributes have a set of permissions that controls whether they can be read or written, or whether the attribute value shall be sent over an encrypted link
• Attribute permissions are used by the server to determine whether read or write access is permitted for a given attribute
• Attribute permissions are established by the GATT Profile so different permissions can be granted for the characteristics and descriptors

Security Levels

Security level is a property of a connection. Using different security features can lead to different security levels per connection. The different levels summarized below.

Privacy

• Bluetooth provides privacy protection
• Devices can either use public or private (random) addresses

Public address is fixed and unique to a device Random address can change over time and hides the public address from unwanted devices Bonded devices can resolve the public address

Bluetooth 4.2 Security Features

• New LE Secure connections feature using Elliptic Curve Diffie-Hellman (ECDH) public-private key pairs for numeric comparison paring method

• New numeric comparison paring method. In this pairing method both devices will display a 6-digit passkey. The user must confirm, that the two devices display the same passkey by pressing a button.

• Passkey entry and OOB has updated LE Secure Connection variant. But there is no change from application perspective.

• LE privacy 1.2 — Identity resolving moved from host to controller for faster and lower power operation

Using security features in Silicon Labs Bluetooth SDK

To use the security features you need to do the following steps:

1. Set up attribute permissions in GATT
2. Set up security manager
3. Set up bonding (enabled/disable/delete)
4. Increase security level (optional)
5. Handle security manager stack events by the application

Set up attribute permissions in GATT

The characteristics access and security properties are defined in the gatt.xml file by the XML attribute properties and its parameters, which must be used inside the characteristic XML attribute tags. Alternatively, Visual GATT Editor can be also used for defining the GATT elements and their permissions. The table below describes the parameters that can be used for defining attribute permissions.

GATT Examples

Here we have 3 example for setting up attribute permissions for a characteristic.

Example 1 — No restrictions

In this case properties ensure that reading and writing the characteristic is without any restriction. It does not require authentication or encrypted link. Any GATT client can read or write it.

Example 2 — Encrypted write

Now let's set up the characteristic differently

In this case reading the characteristic is without any restriction. But writing the characteristic requires encrypted link. Characteristics which requires encryption cannot be accessed without pairing. So writing this characteristic in the first time will trigger the pairing process. The pairing can be just works so it is allowed to not have MITM protection.

Example 3 — Authenticated write

Now let's modify the characteristic properties again.

In this case reading the reading the characteristic is without any restriction. But writing requires authentication. It means the remote device must be bonded with man in the middle (MITM) protection enabled. So the characteristic cannot be accessed in case of just works pairing used. Writing this characteristic in the first time will trigger the pairing process.

Setting up the security manager

The application shall use the gecko_cmd_sm_configure(flags, io_capabilities) API to set up the security configuration. The io_capabilities and flagsparameters affect the security level with which the devices will use in connection and leads to different pairing mechanisms.

The io_capabilities parameter informs the stack about the possible user input and output method that is available on the device. See the available options here below:

The flags parameter controls different application specific security requirements. This parameter gives flexibility to the application to decide how strictly use or not use at all the Bluetooth security features. The table below shows the different options:

If the flags parameter is 0, so no application specific requirement set, the pairing method depends only on the IO capabilities of the initiator and the responder device (shown as I and R on the table below).

If a device has application specific security requirements (flags parameter is not 0) then the used pairing method and security level of the connection will be different.

MITM - bit 0

Setting the bit 0 forces the MITM protection. In practice it means that our devices will not bond with devices which don't have the io capabilities at least for legacy pairing.

Encryption - bit 1

Setting the bit 1 forces link encryption. In practice it means that our devices will always use encrypted link with bonded devices. Note if the bonding table is full therefore the device can't save the new bond.

LE Secure connections support - bit 2

If both devices support LE Secure Connections, then the value of then bit 2 doesn’t matter. If either one of the devices doesn’t support secure connections i.e. it supports legacy pairing only, then bit 2 comes into play.

If bit 2 set to 1, secure connection is enforced, and the pairing attempt will fail with error code 0x303 (pairing_fail_authentication_requirements error). This is essentially saying that we don’t want to pair with legacy devices. If bit 2 set to 0, the pairing will fall back to legacy pairing methods.

Application level confirmation of bonding request - bit 3

If bit 3 is set then bonding requests need to be confirmed by the application too. This feature gives additional control over incoming bond requests. So the application can reject devices which otherwise could bond. The application notified about the received bonding request by the sm_confirm_bondingstack event.

The application shall accept or reject the bonding request with the cmd_sm_bonding_confirm command.

Set up bonding (enabled/disable/delete)

To enable secure connection (Security Level 2 and above) the application need to allow bonding. The stack provides the gecko_cmd_sm_set_bondable_mode API function to enable or disable the bonding.

Please note if gecko_cmd_sm_configure(flags, io_capabilities) called with flags parameter where bit 1 is set then the bonding enabled automatically.

During application development sometimes it is useful to delete all the bondings to trigger and test the pairing processes. It can be done by the cmd_sm_delete_bondings API.

There are use cases when the application has to manage the bonding table directly. This is out of scope of this article. You can read more about this in a separate KBA.

Increase security level

If the GATT attribute permissions are set correctly the application don't have to increase the security level manually. The security level of the connection will be increased once there is access demand for GATT elements which requires higher security level. If the 2 devices not bonded yet the pairing process also triggered.

However there can be use cases where the application handles the security level of the connections. In those cases it makes sense to call the cmd_sm_increase_security API function in the evt_le_connection_opened event handler.

Handle security manager stack events by the application

During the pairing process there are few stack events that the application has to handle otherwise the pairing and bonding will fail. These events are the following.

evt_sm_passkey_display
The evt_sm_passkey_display event indicates a request by stack to display the passkey to the user during the pairing process. The application shall write the passkey to a display given by the event as passkey parameter. This event only can happen if the device has a display. It is defined in its io capabilities. See [the Setting up the security manager](### Setting up the security manager) chapter above.

evt_sm_passkey_request
The evt_sm_passkey_request event indicates a request for the user to enter the passkey displayed on the remote device. The application has to read the passkey then push it to stack by the sm_enter_passkey command.

If the passkey was valid and the bonding completed the stack raise a evt_sm_bonded event. If the passkey was invalid or the bonding failed because of any other reason the stack will raise a evt_sm_bonding_failed event.

evt_sm_confirm_passkey
This event can happen when the stack is using numeric comparison pairing method. Its indicates a request to display the passkey to the user then asks to confirm that displayed passkey is the same what is displayed on the remote device. The cmd_sm_passkey_confirm has to be called by the application to accept or reject the displayed passkey depending on the users answer.

evt_sm_bonded
This event is triggered after the pairing or bonding procedure has been successfully completed.

evt_sm_confirm_bonding
This event indicates that new bonding request has been received. The application has to call sm_bonding_confirm to accept or reject the incoming bonding request. This feature can be activated by calling the gecko_cmd_sm_configure(flags, io_capabilities) where the bit 2 of the flag parameter is set to 1.

evt_sm_bonding_failed
This event is triggered when the pairing or bonding procedure failed. The possible reasons and errorcodes are documented here.

References

API Documentation

Bluetooth Core Specification

Pairing Processes

Application Layer Security

Bond Replacing Algorithm

OOB Introduction

Secure Connection Example

Authenticating Devices with No User Interface

/* Gecko configuration parameters (see gecko_configuration.h) */
static const gecko_configuration_t config = {
  .config_flags = 0,
  .sleep.flags = 0, // <- DISABLE THE SLEEP HERE
..
}

Step 4 – On Silicon Labs kits you can use the UART over the J-Link CDC. For that you need to route the UART signals from the MCU to the board controller of the kit.

This can be done by setting VCOM enable pin high. Most of the kits it can be done by setting a GPIO by software. But on some kits a 0 Ohm resistor must soldered additionally.

Here is how you can enable VCOM by software.

GPIO_PinOutSet(BSP_BCC_ENABLE_PORT, BSP_BCC_ENABLE_PIN);

Example

The attached  uart_echo.c and uart_echo.h implements terminal echo. It can be used in any Bluetooth SDK project once the steps described above are completed.

Calling the UART_EchoInit(uint8_t vcom) sets the VCOM enable pin, configures the uartdrv then start to receive.

Once a byte received the UART_rx_callback called by the uartdrv. The callback immediately transmits the received byte back and start to receive the next byte.

Hi,

The project in the zip file is using the old SDK. 

But you can use the attached .c and .h files in newer SDKs. 

-Balázs 

Meanwhile here is my host project attached. It works for me.

-Balázs