backend: add a raw, controllable backend for embedded use-cases

Author: jcelerier

cmake/libremidi.examples.cmake

@@ -30,6 +30,7 @@ add_example(sysextest)
 add_example(minimal)
 add_example(midi2_echo)
 add_example(rawmidiin)
+add_example(rawio)
 
 if(LIBREMIDI_HAS_STD_FLAT_SET AND LIBREMIDI_HAS_STD_PRINTLN)
   add_example(midi_to_pattern)

cmake/libremidi.tests.cmake

@@ -52,6 +52,9 @@ target_link_libraries(midi_stream_decoder_test PRIVATE libremidi Catch2::Catch2W
 add_executable(midi_timing_test tests/unit/midi_timing.cpp)
 target_link_libraries(midi_timing_test PRIVATE libremidi Catch2::Catch2WithMain)
 
+add_executable(rawio_test tests/unit/rawio.cpp)
+target_link_libraries(rawio_test PRIVATE libremidi Catch2::Catch2WithMain)
+
 include(CTest)
 add_test(NAME conversion_test COMMAND conversion_test)
 add_test(NAME error_test COMMAND error_test)
@@ -63,3 +66,4 @@ add_test(NAME midifile_write_tracks_test COMMAND midifile_write_tracks_test)
 add_test(NAME protocols_test COMMAND protocols_test)
 add_test(NAME midi_stream_decoder_test COMMAND midi_stream_decoder_test)
 add_test(NAME midi_timing_test COMMAND midi_timing_test)
+add_test(NAME rawio_test COMMAND rawio_test)

examples/rawio.cpp

@@ -0,0 +1,87 @@
+#include "utils.hpp"
+
+#include <libremidi/configurations.hpp>
+#include <libremidi/libremidi.hpp>
+
+#include <cstdlib>
+#include <iostream>
+
+/// This example demonstrates the raw I/O backend, which allows
+/// the user to plug in their own byte-level transport functions.
+/// This is useful for Arduino, Teensy, ESP32, serial ports, SPI, USB HID, etc.
+///
+/// In this example we simulate a loopback: bytes written by the output
+/// are fed directly into the input, as if connected by a serial wire.
+int main()
+{
+  // MIDI 1.0 raw I/O example
+  {
+    std::cout << "=== MIDI 1 Raw I/O ===" << std::endl;
+
+    // The receive callback will be stored here by the library
+    libremidi::rawio_input_configuration::receive_callback feed_input;
+
+    // Create a MIDI input that prints received messages
+    libremidi::midi_in midiin{
+        libremidi::input_configuration{
+            .on_message
+            = [](const libremidi::message& m) {
+      std::cout << "Received MIDI 1: " << m << std::endl;
+    }},
+        libremidi::rawio_input_configuration{
+            .set_receive_callback = [&](auto cb) { feed_input = std::move(cb); },
+            .stop_receive = [&] { feed_input = nullptr; }}};
+
+    // Create a MIDI output whose write function loops back to the input
+    libremidi::midi_out midiout{
+        libremidi::output_configuration{},
+        libremidi::rawio_output_configuration{
+            .write_bytes = [&](std::span<const uint8_t> bytes) -> stdx::error {
+      // Simulate a serial loopback: bytes go directly to the input
+      if (feed_input)
+        feed_input(bytes, 0);
+      return {};
+    }}};
+
+    midiin.open_virtual_port("rawio_in");
+    midiout.open_virtual_port("rawio_out");
+
+    // Send some MIDI messages
+    midiout.send_message(0x90, 60, 100); // Note On: C4, velocity 100
+    midiout.send_message(0x80, 60, 0);   // Note Off: C4
+    midiout.send_message(0xB0, 7, 80);   // CC: Volume = 80
+  }
+
+  // MIDI 2.0 (UMP) raw I/O example
+  {
+    std::cout << "\n=== MIDI 2 Raw I/O (UMP) ===" << std::endl;
+
+    libremidi::rawio_ump_input_configuration::receive_callback feed_input;
+
+    libremidi::midi_in midiin{
+        libremidi::ump_input_configuration{.on_message = [](const libremidi::ump& m) {
+          std::cout << "Received UMP: " << m << std::endl;
+        }},
+        libremidi::rawio_ump_input_configuration{
+            .set_receive_callback = [&](auto cb) { feed_input = std::move(cb); },
+            .stop_receive = [&] { feed_input = nullptr; }}};
+
+    libremidi::midi_out midiout{
+        libremidi::output_configuration{},
+        libremidi::rawio_ump_output_configuration{
+            .write_ump = [&](std::span<const uint32_t> words) -> stdx::error {
+      if (feed_input)
+        feed_input(words, 0);
+      return {};
+    }}};
+
+    midiin.open_virtual_port("rawio_ump_in");
+    midiout.open_virtual_port("rawio_ump_out");
+
+    // Send a MIDI 2.0 Note On UMP (type 4, group 0, channel 0, note 60)
+    uint32_t ump[2] = {0x40900000 | 60, 0xC0000000};
+    midiout.send_ump(ump, 2);
+  }
+
+  return 0;
+}

examples/rawio_esp32_serial/libremidi

@@ -0,0 +1 @@
+../../include/libremidi

examples/rawio_esp32_serial/rawio_esp32_serial.ino

@@ -0,0 +1,149 @@
+/// ESP32 Serial MIDI example using libremidi's raw I/O backend.
+///
+/// Wiring: MIDI IN on Serial2 RX (GPIO 16), MIDI OUT on Serial2 TX (GPIO 17)
+/// Standard MIDI baud rate is 31250.
+///
+/// This sketch receives MIDI on Serial2, parses it through libremidi
+/// (giving you structured messages with sysex filtering, etc.),
+/// sends MIDI back out on the same serial port,
+/// and broadcasts every received message as an OSC /midi UDP packet
+/// to the local network (192.168.1.255:5678).
+
+#include <WiFi.h>
+#include <WiFiUdp.h>
+
+// Note: you need to have the "include/libremidi" folder copied or 
+// symlinked into the sketch folder for this to work, or change the 
+// Arduino platform configuration files to add the proper include path.
+#define LIBREMIDI_HEADER_ONLY 1
+#include <libremidi/configurations.hpp>
+#include <libremidi/libremidi.hpp>
+
+// --- Configuration ---
+static constexpr int MIDI_BAUD = 31250;
+static constexpr int MIDI_RX_PIN = 16;
+static constexpr int MIDI_TX_PIN = 17;
+
+static const char* WIFI_SSID = "your-ssid";
+static const char* WIFI_PASS = "your-password";
+
+static const IPAddress UDP_BROADCAST{192, 168, 1, 255};
+static constexpr uint16_t UDP_PORT = 49444;
+static const char* OSC_PATH = "/midi"; // must be 5 chars (+ padding) for the packet layout below
+
+// --- Globals ---
+
+// The callback that libremidi gives us to feed incoming bytes
+static libremidi::rawio_input_configuration::receive_callback g_feed_input;
+
+// The libremidi objects need to survive across loop() calls
+static std::optional<libremidi::midi_in> g_midi_in;
+static std::optional<libremidi::midi_out> g_midi_out;
+
+static WiFiUDP g_udp;
+
+/// Build and send an OSC message containing a single 3-byte MIDI event.
+///
+/// OSC /midi packet layout (all 4-byte aligned):
+///   "/midi\0\0\0"   (8 bytes: pattern + null + padding)
+///   ",m\0\0"         (4 bytes: typetag string)
+///   [port, b0, b1, b2] (4 bytes: OSC MIDI atom)
+void osc_broadcast_midi(uint8_t status, uint8_t d1, uint8_t d2)
+{
+  // Pre-built packet: only the last 3 bytes change
+  uint8_t pkt[16] = {
+      // OSC address pattern "/midi" + null + 2 padding zeros
+      '/', 'm', 'i', 'd', 'i', 0, 0, 0,
+      // OSC type tag ",m" + null + 1 padding zero
+      ',', 'm', 0, 0,
+      // OSC MIDI data: port (0), status, data1, data2
+      0, status, d1, d2};
+
+  g_udp.beginPacket(UDP_BROADCAST, UDP_PORT);
+  g_udp.write(pkt, sizeof(pkt));
+  g_udp.endPacket();
+}
+
+// Called by libremidi whenever a complete MIDI message is received and parsed
+void on_midi_message(const libremidi::message& msg)
+{
+  // Print to USB serial for debugging
+  Serial.printf("MIDI [%02X", msg.bytes[0]);
+  for (size_t i = 1; i < msg.bytes.size(); i++)
+    Serial.printf(" %02X", msg.bytes[i]);
+  Serial.println("]");
+
+  // Broadcast as OSC over UDP (channel messages are always 3 bytes)
+  if (msg.bytes.size() == 3)
+    osc_broadcast_midi(msg.bytes[0], msg.bytes[1], msg.bytes[2]);
+
+  // Echo note-on messages back on serial with velocity halved
+  if (msg.get_message_type() == libremidi::message_type::NOTE_ON && g_midi_out)
+  {
+    uint8_t velocity = msg.bytes[2] / 2;
+    g_midi_out->send_message(msg.bytes[0], msg.bytes[1], velocity);
+  }
+}
+
+void setup()
+{
+  // USB serial for debug output
+  Serial.begin(115200);
+
+  // Connect to WiFi
+  WiFi.begin(WIFI_SSID, WIFI_PASS);
+  Serial.print("Connecting to WiFi");
+  while (WiFi.status() != WL_CONNECTED)
+  {
+    delay(500);
+    Serial.print(".");
+  }
+  Serial.printf("\nConnected, IP: %s\n", WiFi.localIP().toString().c_str());
+
+  // Start UDP for OSC broadcast
+  g_udp.begin(UDP_PORT);
+
+  // MIDI serial port
+  Serial2.begin(MIDI_BAUD, SERIAL_8N1, MIDI_RX_PIN, MIDI_TX_PIN);
+
+  // Create MIDI input
+  g_midi_in.emplace(
+      libremidi::input_configuration{
+          .on_message = on_midi_message,
+          .ignore_sysex = true,
+          .ignore_timing = true,
+          .ignore_sensing = true,
+      },
+      libremidi::rawio_input_configuration{
+          .set_receive_callback = [](auto cb) { g_feed_input = std::move(cb); },
+          .stop_receive = [] { g_feed_input = nullptr; },
+      });
+
+  // Create MIDI output (serial)
+  g_midi_out.emplace(
+      libremidi::output_configuration{},
+      libremidi::rawio_output_configuration{
+          .write_bytes = [](std::span<const uint8_t> bytes) -> stdx::error {
+    Serial2.write(bytes.data(), bytes.size());
+    return {};
+  }});
+
+  // Open ports to activate the callbacks
+  g_midi_in->open_virtual_port("esp32_in");
+  g_midi_out->open_virtual_port("esp32_out");
+
+  Serial.println("MIDI ready, broadcasting OSC to " + UDP_BROADCAST.toString() + ":" + UDP_PORT);
+}
+
+void loop()
+{
+  // Read all available bytes from the MIDI serial port
+  // and feed them into libremidi for parsing
+  int avail = Serial2.available();
+  if (avail > 0 && g_feed_input)
+  {
+    uint8_t buf[64];
+    int n = Serial2.readBytes(buf, min(avail, (int)sizeof(buf)));
+    g_feed_input({buf, static_cast<size_t>(n)}, 0);
+  }
+}

include/libremidi/api-c.h

@@ -26,6 +26,7 @@ enum libremidi_api
   NETWORK,        /*!< MIDI over IP */
   ANDROID_AMIDI,  /*!< Android AMidi API */
   KDMAPI,         /*!< OmniMIDI KDMAPI (Windows) */
+  RAW_IO,         /*!< User-provided raw byte I/O (serial, SPI, USB, etc.) */
 
   // MIDI 2.0 APIs
   ALSA_RAW_UMP = 0x1000, /*!< Raw ALSA API for MIDI 2.0 */
@@ -36,6 +37,7 @@ enum libremidi_api
   NETWORK_UMP,           /*!< MIDI2 over IP */
   JACK_UMP,              /*!< MIDI2 over JACK, type "32 bit raw UMP". Requires PipeWire v1.4+. */
   PIPEWIRE_UMP,          /*!< MIDI2 over PipeWire. Requires v1.4+. */
+  RAW_IO_UMP,            /*!< User-provided raw UMP I/O (serial, SPI, USB, etc.) */
 
   DUMMY = 0xFFFF /*!< A compilable but non-functional API. */
 };

include/libremidi/backends.hpp

@@ -77,6 +77,9 @@
   #include <libremidi/backends/network_ump.hpp>
 #endif
 
+#include <libremidi/backends/rawio.hpp>
+#include <libremidi/backends/rawio_ump.hpp>
+
 #if defined(LIBREMIDI_ANDROID)
   #include <libremidi/backends/android/android.hpp>
 #endif
@@ -144,6 +147,7 @@ LIBREMIDI_STATIC constexpr auto available_backends = make_tl(
     android::backend{}
 #endif
     ,
+    rawio::backend{},
     dummy_backend{});
 
 // There should always be at least one back-end.
@@ -194,6 +198,7 @@ LIBREMIDI_STATIC constexpr auto available_backends = make_tl(
     pipewire_ump::backend{}
 #endif
     ,
+    rawio_ump::backend{},
     dummy_backend{});
 
 // There should always be at least one back-end.

include/libremidi/backends/rawio.hpp

@@ -0,0 +1,25 @@
+#pragma once
+#include <libremidi/backends/rawio/config.hpp>
+#include <libremidi/backends/rawio/midi_in.hpp>
+#include <libremidi/backends/rawio/midi_out.hpp>
+#include <libremidi/backends/rawio/observer.hpp>
+
+#include <string_view>
+
+NAMESPACE_LIBREMIDI::rawio
+{
+struct backend
+{
+  using midi_in = rawio::midi_in;
+  using midi_out = rawio::midi_out;
+  using midi_observer = rawio::observer;
+  using midi_in_configuration = rawio_input_configuration;
+  using midi_out_configuration = rawio_output_configuration;
+  using midi_observer_configuration = rawio_observer_configuration;
+  static const constexpr auto API = libremidi::API::RAW_IO;
+  static const constexpr std::string_view name = "raw_io";
+  static const constexpr std::string_view display_name = "Raw I/O";
+
+  static inline bool available() noexcept { return true; }
+};
+}