parser.hpp

Go to the documentation of this file.

// sbl/midi/parser.hpp — MIDI byte stream parser
//
// State machine that parses raw UART bytes into MidiEvent structs.
// Supports running status, System Real-Time passthrough mid-message,
// and Note On velocity 0 → Note Off conversion.
//
// SysEx is acknowledged (resets running status) but not buffered (V1).
//
// Inspired by MI stmlib/midi/midi.h (MIT license).
//
// Usage:
//   sbl::midi::Parser parser;
//   parser.set_callback(on_midi_event);
//   parser.set_channel(0);  // Channel 1 (0-indexed), or 0xFF for omni
//
//   // In main loop or UART RX ISR:
//   while (uart_available()) {
//       parser.push(uart_read_byte());
//   }
 
#pragma once
 
#include <cstdint>
 
#include <sbl/midi/types.hpp>
 
namespace sbl::midi {
 
/**
 * @brief MIDI byte stream parser — state machine with running status
 *
 * @note All public methods are ISR-safe — O(1) state machine with no
 *       hardware I/O. Callback is invoked synchronously from push().
 */
class Parser {
public:
    /**
     * @brief Set the callback for parsed MIDI events
     * @note ISR-safe — stores a function pointer, no I/O.
     */
    void set_callback(MidiCallback cb) { callback_ = cb; }
 
    /**
     * @brief Set channel filter
     * @param ch Channel 0-15, or 0xFF for omni (receive all channels)
     * @note ISR-safe — stores a byte, no I/O.
     */
    void set_channel(uint8_t ch) { channel_filter_ = ch; }
 
    /**
     * @brief Feed one byte from UART RX
     *
     * State machine processes the byte and dispatches complete messages
     * via the callback. System Real-Time messages are dispatched
     * immediately, even mid-message.
     *
     * @note ISR-safe — O(1) state machine, no blocking or I/O.
     */
    void push(uint8_t byte) {
        // System Real-Time: dispatch immediately, don't disturb parser state
        if (byte >= 0xF8) {
            dispatch_realtime(byte);
            return;
        }
 
        // Status byte?
        if (byte & 0x80) {
            // SysEx start — enter sysex mode, reset running status
            if (byte == 0xF0) {
                in_sysex_ = true;
                running_status_ = 0;
                data_count_ = 0;
                return;
            }
 
            // SysEx end — exit sysex mode
            if (byte == 0xF7) {
                in_sysex_ = false;
                return;
            }
 
            // Any other status byte ends SysEx
            in_sysex_ = false;
 
            // System Common (0xF1-0xF6) — clear running status
            if (byte >= 0xF0) {
                running_status_ = 0;
                // System common messages: handle based on byte count
                switch (byte) {
                    case 0xF1:  // Time Code: 1 data byte
                    case 0xF3:  // Song Select: 1 data byte
                        running_status_ = 0;
                        status_ = byte;
                        expected_ = 1;
                        data_count_ = 0;
                        return;
                    case 0xF2:  // Song Position: 2 data bytes
                        running_status_ = 0;
                        status_ = byte;
                        expected_ = 2;
                        data_count_ = 0;
                        return;
                    case 0xF6:  // Tune Request: no data
                        // Dispatch immediately
                        if (callback_) {
                            MidiEvent ev;
                            ev.type = MessageType::TuneRequest;
                            callback_(ev);
                        }
                        return;
                    default:
                        return;
                }
            }
 
            // Channel message status byte
            running_status_ = byte;
            status_ = byte;
            expected_ = expected_data_bytes(byte);
            data_count_ = 0;
            return;
        }
 
        // Data byte (0x00-0x7F)
        if (in_sysex_) return;  // Ignore SysEx data bytes
 
        // No status context? Apply running status
        if (data_count_ == 0 && running_status_ == 0) {
            return;  // Orphan data byte — discard
        }
 
        // If we're starting fresh data and have running status
        if (data_count_ == 0 && status_ == 0) {
            status_ = running_status_;
            expected_ = expected_data_bytes(running_status_);
        }
 
        // Store data byte
        if (data_count_ == 0) {
            data1_ = byte;
        } else {
            data2_ = byte;
        }
        ++data_count_;
 
        // Complete message?
        if (data_count_ >= expected_) {
            dispatch_channel_message();
            data_count_ = 0;
            status_ = 0;  // Reset for running status
        }
    }
 
    /**
     * @brief Feed multiple bytes
     * @note ISR-safe — O(n) loop over push(), no blocking or I/O.
     */
    void push(const uint8_t* data, uint16_t len) {
        for (uint16_t i = 0; i < len; ++i) {
            push(data[i]);
        }
    }
 
private:
    MidiCallback callback_ = nullptr;
    uint8_t channel_filter_ = 0xFF;  // Omni by default
 
    // Parser state
    uint8_t running_status_ = 0;
    uint8_t status_ = 0;
    uint8_t expected_ = 0;
    uint8_t data_count_ = 0;
    uint8_t data1_ = 0;
    uint8_t data2_ = 0;
    bool in_sysex_ = false;
 
    void dispatch_realtime(uint8_t byte) {
        if (!callback_) return;
 
        MidiEvent ev;
        switch (byte) {
            case 0xF8: ev.type = MessageType::Clock; break;
            case 0xFA: ev.type = MessageType::Start; break;
            case 0xFB: ev.type = MessageType::Continue; break;
            case 0xFC: ev.type = MessageType::Stop; break;
            case 0xFE: ev.type = MessageType::ActiveSensing; break;
            case 0xFF: ev.type = MessageType::SystemReset; break;
            default: return;
        }
        callback_(ev);
    }
 
    void dispatch_channel_message() {
        if (!callback_) return;
 
        uint8_t msg_channel = status_ & 0x0F;
 
        // Channel filter
        if (channel_filter_ != 0xFF && msg_channel != channel_filter_) {
            return;
        }
 
        MidiEvent ev;
        ev.channel = msg_channel;
        ev.data1 = data1_;
        ev.data2 = data2_;
 
        uint8_t msg_type = status_ & 0xF0;
        switch (msg_type) {
            case 0x80:
                ev.type = MessageType::NoteOff;
                break;
            case 0x90:
                // Note On with velocity 0 = Note Off
                if (data2_ == 0) {
                    ev.type = MessageType::NoteOff;
                } else {
                    ev.type = MessageType::NoteOn;
                }
                break;
            case 0xA0: ev.type = MessageType::PolyPressure; break;
            case 0xB0: ev.type = MessageType::ControlChange; break;
            case 0xC0: ev.type = MessageType::ProgramChange; break;
            case 0xD0: ev.type = MessageType::ChannelPressure; break;
            case 0xE0: ev.type = MessageType::PitchBend; break;
            default: return;
        }
 
        callback_(ev);
    }
};
 
} // namespace sbl::midi