ble_midi.hpp

Go to the documentation of this file.

#pragma once
 
// BLE MIDI — Bluetooth Low Energy MIDI 1.0 transport (Apple BLE-MIDI 1.0 spec,
// also adopted by the MIDI Association in 2015). This header declares the
// cross-platform discovery / connection / I/O surface that backends implement.
//
// Backends:
//   macOS / iOS:  CoreBluetooth (CBCentralManager + CBPeripheral) bridged
//                 into CoreMIDI via the well-known BLE-MIDI service UUID
//                 03B80E5A-EDE8-4B33-A751-6CE34EC4C700. On Apple the
//                 CoreMIDI driver also exposes paired BLE peripherals as
//                 regular MIDI endpoints; this surface adds explicit
//                 scan-and-pair control for unpaired peripherals.
//   Linux:        BlueZ D-Bus (org.bluez.GattCharacteristic1 notifications) +
//                 ALSA virtual port for output.
//   Windows:      WinRT BluetoothLEAdvertisementWatcher scan +
//                 GATT FromBluetoothAddressAsync connect +
//                 GattCharacteristic.ValueChanged notify, bridged into the
//                 MidiSystem via the BleMidiPortRegistry.
//   Android:      BluetoothLeScanner + BluetoothGatt notification
//                 via the existing JNI bridge. Scaffold only.
//
// Spec reference (BLE-MIDI 1.0):
//   Service UUID:        03B80E5A-EDE8-4B33-A751-6CE34EC4C700
//   Characteristic UUID: 7772E5DB-3868-4112-A1A9-F2669D106BF3 (read/write/notify)
//
// Packet format (per 20-byte MTU minimum):
//   header  = 0x80 | (timestamp_high & 0x3F)            (top 6 bits of 13-bit ms)
//   tstmp   = 0x80 | (timestamp_low  & 0x7F)            (bottom 7 bits)
//   [status, data1, data2, ...]
//   Running status, multi-message-per-packet, and split-sysex follow the
//   Apple spec — backends MUST reassemble before delivering to callbacks.
//
// Baseline behavior: discover BLE MIDI peripherals, connect to one, and
// receive MIDI events (notes) via the standard MidiInputCallback path.
// Pairing UI is delegated to the platform — the scanner surfaces peripherals
// and the host app drives the pairing dialog (iOS CABTMIDICentralViewController,
// macOS equivalent, or a custom widget).
 
#include <pulp/midi/device.hpp>
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <vector>
 
namespace pulp::midi {

struct BleMidiPeripheral {
    std::string id;
    std::string name;
    int rssi = 0;
    std::chrono::steady_clock::time_point last_seen{};
    bool is_paired = false;
};

enum class BleMidiConnectionState {
    Idle,
    Scanning,
    Connecting,
    Connected,
    Disconnected,
    Failed,
};

enum class BleMidiError {
    None,
    PermissionDenied,    
    BluetoothOff,        
    Unsupported,         
    PeripheralNotFound,  
    ConnectFailed,       
    ServiceNotFound,     
    Timeout,             
};

using BleMidiScanCallback = std::function<void(const BleMidiPeripheral&)>;

using BleMidiStateCallback =
    std::function<void(const std::string& peripheral_id,
                       BleMidiConnectionState state,
                       BleMidiError error)>;

class BleMidiCentral {
public:
    virtual ~BleMidiCentral() = default;

    virtual bool is_available() const = 0;

    virtual bool start_scan(BleMidiScanCallback callback) = 0;
    virtual void stop_scan() = 0;
    virtual bool is_scanning() const = 0;

    virtual std::vector<BleMidiPeripheral> known_peripherals() const = 0;

    virtual bool connect(const std::string& peripheral_id) = 0;
    virtual void disconnect(const std::string& peripheral_id) = 0;
 
    virtual void set_state_callback(BleMidiStateCallback callback) = 0;

    virtual std::string midi_input_port_for(const std::string& peripheral_id) const = 0;
    virtual std::string midi_output_port_for(const std::string& peripheral_id) const = 0;
};

std::unique_ptr<BleMidiCentral> create_ble_midi_central();
 
// ── BLE-MIDI 1.0 packet codec ──────────────────────────────────────────────
//
// The codec is cross-platform and Skia-free — every backend reuses it.
// Reassembles 13-bit timestamps, running status, and multi-message
// packets per the BLE-MIDI 1.0 spec. Exposed for tests + for the BlueZ
// / WinRT backends which receive raw GATT bytes and must produce
// MidiEvents.

struct BleMidiUuids {
    static constexpr const char* kService =
        "03B80E5A-EDE8-4B33-A751-6CE34EC4C700";
    static constexpr const char* kCharacteristic =
        "7772E5DB-3868-4112-A1A9-F2669D106BF3";
};

class BleMidiPacketDecoder {
public:
    using MessageCallback =
        std::function<void(const std::vector<uint8_t>& bytes,
                           uint32_t timestamp_ms)>;
 
    void set_message_callback(MessageCallback cb) { cb_ = std::move(cb); }

    bool decode(const uint8_t* data, std::size_t size);

    void reset();
 
private:
    MessageCallback cb_;
    uint8_t last_status_ = 0;
    std::vector<uint8_t> sysex_buffer_;
    uint8_t last_header_ts_ = 0;
};

std::vector<uint8_t> encode_ble_midi_packet(const uint8_t* msg,
                                            std::size_t size,
                                            uint32_t timestamp_ms);
 
}  // namespace pulp::midi