midi.hpp

Go to the documentation of this file.

#ifndef SBL_USB_MIDI_HPP_
#define SBL_USB_MIDI_HPP_
 
/**
 * @file midi.hpp
 * @brief USB MIDI device interface
 *
 * Provides bidirectional USB MIDI 1.0 via TinyUSB's MIDI device class.
 * Operates on cable 0 (single virtual cable).
 *
 * RX path: tud_midi_stream_read() → raw MIDI bytes → feed to sbl::midi::Parser
 * TX path: MidiEvent → raw MIDI bytes → tud_midi_stream_write()
 *
 * Output ports. A USB device has one cable, so hardware targets have one
 * output port and `port` is always 0. A target that offers more says so
 * through out_port_count(): the workbench gives an app several, which is what
 * a multi-voice sequencer sends into (FDP-078).
 *
 * Requires CFG_TUD_MIDI=1 in tusb_config.h and the composite CDC+MIDI
 * descriptor in usb_descriptors.c.
 *
 * Usage:
 *   // RX: poll in main loop (or use sbl::midi::poll_usb())
 *   uint8_t buf[64];
 *   uint32_t n = sbl::usb::MidiPort::read(buf, sizeof(buf));
 *   parser.push(buf, n);
 *
 *   // TX: send events
 *   sbl::usb::MidiPort::send(event);
 */
 
#include <cstdint>
#include <sbl/protocol/midi/types.hpp>
 
namespace sbl::usb {
 
/**
 * @brief USB MIDI device port (static class)
 *
 * All methods are safe to call from main loop context.
 * Not ISR-safe — TinyUSB device stack is not reentrant.
 */
class MidiPort {
public:
    /**
     * @brief Check if USB MIDI interface is mounted by host
     * @return true if host has enumerated and configured the MIDI interface
     */
    static bool connected();
 
    /**
     * @brief Read decoded MIDI bytes from USB (RX)
     *
     * TinyUSB unpacks 4-byte USB MIDI Event Packets into standard MIDI
     * byte stream. Feed the output directly to sbl::midi::Parser::push().
     *
     * @param buf Buffer to receive MIDI bytes
     * @param max_len Maximum bytes to read
     * @return Number of bytes read (0 if nothing available)
     */
    static uint32_t read(uint8_t* buf, uint32_t max_len);
 
    /**
     * @brief Send a MidiEvent over USB MIDI (TX)
     *
     * Converts the event to standard MIDI bytes and writes them via
     * tud_midi_stream_write(), which handles USB packet framing.
     *
     * @param event The MIDI event to send
     * @param port Output port, 0 to out_port_count() - 1
     * @return true if all bytes were written, false if the buffer is full or
     *         the port does not exist
     */
    static bool send(const sbl::midi::MidiEvent& event, uint8_t port = 0);
 
    /**
     * @brief Write raw MIDI bytes to USB MIDI (TX)
     *
     * TinyUSB packs bytes into 4-byte USB MIDI Event Packets.
     *
     * @param data Raw MIDI bytes to send
     * @param len Number of bytes
     * @param port Output port, 0 to out_port_count() - 1
     * @return Number of bytes written (0 if the port does not exist)
     */
    static uint32_t write(const uint8_t* data, uint32_t len, uint8_t port = 0);
 
    /**
     * @brief How many output ports this target has
     *
     * One on a USB device. A port existing does not mean anything is
     * listening to it.
     */
    static uint8_t out_port_count();
};
 
} // namespace sbl::usb
 
#endif // SBL_USB_MIDI_HPP_