midi_ci.hpp

Go to the documentation of this file.

#pragma once
 
// MIDI-CI (Capability Inquiry) — MIDI 2.0 device discovery, profiles, property exchange.
// Operates over UMP (Universal MIDI Packets) for CI message encoding/decoding.
 
#include <string>
#include <string_view>
#include <vector>
#include <map>
#include <memory>
#include <functional>
#include <cstdint>
#include <optional>
 
namespace pulp::midi {
 
class PeSubscriptionManager;  // defined in midi_ci_pe.hpp
struct PeSubscription;

enum class CiMessageType : uint8_t {
    DiscoveryInquiry     = 0x70,
    DiscoveryReply       = 0x71,
    InvalidateMUID       = 0x7E,
    ProfileSetOn         = 0x22,  
    ProfileSetOff        = 0x23,  
    ProfileInquiry       = 0x24,
    ProfileReply         = 0x25,
    ProfileEnable        = 0x26,  
    ProfileDisable       = 0x27,  
    ProfileDetailsInquiry = 0x28, 
    ProfileDetailsReply   = 0x29, 
    ProfileSpecificData   = 0x2F, 
    PropertyGetInquiry   = 0x34,
    PropertyGetReply     = 0x35,
    PropertySetInquiry   = 0x36,
    PropertySetReply     = 0x37,
    PropertySubscribeInquiry = 0x38,
    PropertySubscribeReply   = 0x39,
    PropertyNotify           = 0x3F,
    ProcessInquiry       = 0x40,
    ProcessReply         = 0x41
};

struct MUID {
    uint32_t value = 0;
 
    static MUID generate();
    static MUID broadcast() { return {0x0FFFFFFF}; }
    bool is_broadcast() const { return value == 0x0FFFFFFF; }
    bool operator==(const MUID& o) const { return value == o.value; }
};

using PeNotifyCallback = std::function<void(MUID subscriber_muid,
                                            std::string_view resource,
                                            std::string_view header_json,
                                            const std::vector<uint8_t>& payload)>;

struct CiDeviceInfo {
    MUID muid;
    uint32_t manufacturer_id = 0;  // 3-byte SysEx ID
    uint16_t family_id = 0;
    uint16_t model_id = 0;
    uint32_t software_version = 0;
    uint8_t ci_version = 2;        // CI version supported
    uint8_t max_sysex_size = 128;
};

struct ProfileId {
    uint8_t bank = 0;
    uint8_t number = 0;
    uint8_t version = 0;
    uint8_t level = 0;
    uint8_t reserved = 0;
 
    bool operator==(const ProfileId& o) const {
        return bank == o.bank && number == o.number && version == o.version && level == o.level;
    }
};

struct ProfileState {
    ProfileId id;
    bool enabled = false;
    uint16_t channel_count = 0;  // 0 = group-wide
};

struct FunctionBlockId {
    uint8_t value = 0x7F;  
 
    static FunctionBlockId broadcast() { return {0x7F}; }
    bool is_broadcast() const { return value == 0x7F; }
    bool operator==(const FunctionBlockId& o) const { return value == o.value; }
};

struct FunctionBlockInfo {
    FunctionBlockId id;
    std::string name;          
    uint8_t first_group = 0;   
    uint8_t group_count = 1;   
    bool active = true;        
    bool is_midi1 = false;     
    bool ui_hint_receiver = true;
    bool ui_hint_sender = true;
};

struct ProfileDetails {
    ProfileId id;
    uint8_t target = 0;            
    std::vector<uint8_t> data;     
};

class CiDiscovery {
public:
    CiDiscovery();
    ~CiDiscovery();

    void set_device_info(const CiDeviceInfo& info) { local_info_ = info; }
    const CiDeviceInfo& device_info() const { return local_info_; }

    MUID local_muid() const { return local_info_.muid; }

    std::vector<uint8_t> process_message(const uint8_t* data, size_t size);

    std::vector<uint8_t> create_discovery_inquiry() const;

    std::vector<uint8_t> create_profile_inquiry(MUID destination) const;

    const std::vector<CiDeviceInfo>& discovered_devices() const { return discovered_; }

    void add_profile(const ProfileState& profile) { profiles_.push_back(profile); }
    const std::vector<ProfileState>& profiles() const { return profiles_; }

    bool enable_profile(const ProfileId& id);
    bool disable_profile(const ProfileId& id);

    void set_property(std::string_view resource, std::string_view value);
    std::optional<std::string> get_property(std::string_view resource) const;
 
    // ── Function Block support (CI 1.2 §3.2) ──────────────────────────
    //
    // Function Blocks are MIDI 2.0's logical grouping for UMP endpoints.
    // CI uses them to scope profile + property state per-block so a single
    // endpoint can publish (for example) a piano profile on block 0 and a
    // drum-pad profile on block 1 without the two state machines
    // colliding. Pulp's Function Block surface is responder-side metadata
    // today; the consumer/inquirer side ships as part of UMP endpoint
    // discovery in `pulp::midi::UmpSession`.

    void add_function_block(const FunctionBlockInfo& block) {
        function_blocks_.push_back(block);
    }

    const std::vector<FunctionBlockInfo>& function_blocks() const {
        return function_blocks_;
    }

    const FunctionBlockInfo* find_function_block(FunctionBlockId id) const {
        for (auto& fb : function_blocks_) {
            if (fb.id == id) return &fb;
        }
        return nullptr;
    }
 
    // ── Profile Inquiry / Add / Remove (CI 1.2 §7) ────────────────────
    //
    // CI 1.2 distinguishes Inquiry (request the full list), Reply
    // (responder publishes the list), Added Report (responder pushes
    // "I now expose this profile"), and Removed Report (responder
    // pushes "this profile is gone"). Pulp owned Inquiry + Reply
    // already (`add_profile` / `profiles()` / `handle_profile_inquiry`);
    // the explicit Add / Remove helpers below complete the wire surface.

    std::vector<uint8_t> create_profile_added_report(MUID destination,
                                                     const ProfileId& id);

    std::vector<uint8_t> create_profile_removed_report(MUID destination,
                                                       const ProfileId& id);
 
    // ── Profile Details (CI 1.2 §7.6) ─────────────────────────────────
    //
    // Profile Details Inquiry asks "give me more info about profile X
    // (target byte Y)"; Reply carries an opaque payload defined by the
    // profile spec. Pulp publishes details via `set_profile_details()`
    // and answers inquiries from the local store. Inquirers consume
    // replies via `discovered_profile_details()`.

    void set_profile_details(const ProfileId& id, uint8_t target,
                             const std::vector<uint8_t>& data);

    std::vector<ProfileDetails> profile_details_for(const ProfileId& id) const;

    std::vector<uint8_t> create_profile_details_inquiry(MUID destination,
                                                        const ProfileId& id,
                                                        uint8_t target) const;

    const std::vector<ProfileDetails>& discovered_profile_details() const {
        return discovered_details_;
    }
 
    // ── Profile-Specific Data (CI 1.2 §7.7) ───────────────────────────
    //
    // Profile-Specific Data is the catch-all for profile-defined runtime
    // messaging. The wire envelope is fixed — F0 7E ... 0x2F src dst
    // profile_id(5) length(2) data ... F7 — and the payload semantics
    // are defined by the profile spec, not by CI.

    std::vector<uint8_t> create_profile_specific_data(MUID destination,
                                                      const ProfileId& id,
                                                      const uint8_t* data,
                                                      std::size_t size) const;
 
    inline std::vector<uint8_t> create_profile_specific_data(
        MUID destination, const ProfileId& id,
        const std::vector<uint8_t>& data) const {
        return create_profile_specific_data(destination, id, data.data(), data.size());
    }

    std::function<void(MUID source, const ProfileId& id,
                       const std::vector<uint8_t>& data)>
        on_profile_specific_data;

    std::function<void(const CiDeviceInfo&)> on_device_discovered;
    std::function<void(const ProfileId&, bool enabled)> on_profile_changed;
    std::function<void(MUID source, const ProfileId&)> on_profile_added;
    std::function<void(MUID source, const ProfileId&)> on_profile_removed;
    std::function<void(MUID source, const ProfileDetails&)> on_profile_details;

    PeNotifyCallback on_pe_notify;

    PeSubscriptionManager& subscription_manager();
    const PeSubscriptionManager& subscription_manager() const;

    std::size_t notify(std::string_view resource,
                       std::string_view header_json,
                       const std::vector<uint8_t>& payload);
 
private:
    CiDeviceInfo local_info_;
    std::vector<CiDeviceInfo> discovered_;
    std::vector<ProfileState> profiles_;
    std::vector<FunctionBlockInfo> function_blocks_;
    // Local profile-details store, keyed by (bank, number, version, level, target)
    // to allow multiple target bytes per profile id.
    std::vector<ProfileDetails> local_details_;
    std::vector<ProfileDetails> discovered_details_;
    std::map<std::string, std::string, std::less<>> properties_;
    mutable std::unique_ptr<PeSubscriptionManager> sub_mgr_;
 
    std::vector<uint8_t> handle_discovery(const uint8_t* data, size_t size);
    std::vector<uint8_t> handle_profile_inquiry(const uint8_t* data, size_t size);
    std::vector<uint8_t> handle_profile_added(const uint8_t* data, size_t size);
    std::vector<uint8_t> handle_profile_removed(const uint8_t* data, size_t size);
    std::vector<uint8_t> handle_profile_details_inquiry(const uint8_t* data, size_t size);
    void handle_profile_details_reply(const uint8_t* data, size_t size);
    void handle_profile_specific_data(const uint8_t* data, size_t size);
    std::vector<uint8_t> handle_subscribe(const uint8_t* data, size_t size);
    void handle_notify(const uint8_t* data, size_t size);
};
 
}  // namespace pulp::midi