ruble 0.0.3.alpha

data/ext/ruble/bindings/Peripheral.hpp

@@ -0,0 +1,108 @@
+#pragma once
+
+#include "containers/Callback.hpp"
+#include "containers/NamedBitSet.hpp"
+#include "containers/NamedBitSet.ipp"
+#include "utils/hash.hpp"
+
+namespace RuBLE {
+//    enum class PeripheralStatus : std::size_t {
+//        INITIALIZED = 0, CONNECTED, CONNECTABLE, PAIRED
+//    };
+    class Peripheral {
+    public:
+        static constexpr const std::string_view StatusFlagNames[] = {
+                "initialized", "connected", "connectable", "paired"
+        };
+        using StatusFlagSet = NamedBitSet<StatusFlagNames>;
+//        using Status = RuBLE::PeripheralStatus;
+
+        using DataObject [[maybe_unused]] = Data_Object<Peripheral>;
+        using Owner = Adapter;
+        using ServiceMap = std::map<BluetoothUUID, std::shared_ptr<Service>>;
+        using PartialResourceIdentifier = std::string_view;
+        static bool unpair_all_on_exit;
+    protected:
+        Owner *_owner;
+        std::shared_ptr<SimpleBLE::Peripheral> _peripheral;
+        SimpleBLE::BluetoothAddress _addr;
+        SimpleBLE::BluetoothAddressType _addr_type;
+        std::shared_ptr<Callback> _on_connected;
+        std::shared_ptr<Callback> _on_disconnected;
+        std::shared_ptr<ServiceRegistry> _service_registry;
+        StatusFlagSet _service_cache_tag;
+        VALUE _self = Qnil;
+        std::optional<PartialResourceIdentifier> _resource_identifier;
+
+    public:
+//        static std::shared_ptr<Peripheral> create(const SimpleBLE::Peripheral &peripheral);
+
+        [[nodiscard]] Object self() const;
+        Peripheral() = delete;
+        Peripheral(const SimpleBLE::Peripheral&, Owner*);
+        ~Peripheral() = default;
+
+//    Peripheral(const Peripheral&) = delete;
+//    Peripheral(Peripheral&&) = delete;
+        [[nodiscard]] bool initialized() const;
+
+        [[nodiscard]] const Owner *owner() const;
+        Owner *owner();
+
+        SimpleBLE::Peripheral &get();
+        [[nodiscard]] const SimpleBLE::Peripheral &get() const;
+
+        [[nodiscard]] std::string identifier() const;
+        [[nodiscard]] constexpr const BluetoothAddress &address() const;
+        [[nodiscard]] constexpr const BluetoothAddressType &address_type() const;
+
+//        constexpr std::string this_resource_identifier() const;
+//        constexpr ResourceUniqueIdentifier<Peripheral> full_resource_identifier() const;
+
+        [[nodiscard]] std::map<uint16_t, ByteArray> manufacturer_data() const;
+        [[nodiscard]] int16_t rssi() const;
+        [[nodiscard]] int16_t tx_power() const;
+        [[nodiscard]] uint16_t mtu() const;
+        [[nodiscard]] bool is_connected() const;
+        [[nodiscard]] bool is_connectable() const;
+        [[nodiscard]] bool is_paired() const;
+        [[nodiscard]] StatusFlagSet status_flags() const;
+        [[nodiscard]] std::vector<std::string_view> statuses() const;
+        void connect();
+        void disconnect();
+        void unpair();
+
+        [[nodiscard]] const std::map<BluetoothUUID, std::shared_ptr<Service>> &services() const;
+        std::shared_ptr<Service> operator[](const BluetoothUUID &svcUuid) const;
+
+        [[nodiscard]] ByteArray read(BluetoothUUID const &service, BluetoothUUID const &characteristic);
+        [[nodiscard]] ByteArray read(BluetoothUUID const &service, BluetoothUUID const &characteristic,
+                                     BluetoothUUID const &descriptor);
+        void write(BluetoothUUID const &service, BluetoothUUID const &characteristic,
+                   BluetoothUUID const &descriptor, const ByteArray &data);
+        void write_request(BluetoothUUID const &service, BluetoothUUID const &characteristic,
+                           const ByteArray &data);
+        void write_command(BluetoothUUID const &service, BluetoothUUID const &characteristic,
+                           const ByteArray &data);
+        void notify(BluetoothUUID const &service, BluetoothUUID const &characteristic,
+                    std::function<void(ByteArray payload)> callback);
+        void indicate(BluetoothUUID const &service, BluetoothUUID const &characteristic,
+                      std::function<void(ByteArray payload)> callback);
+        void unsubscribe(BluetoothUUID const &service, BluetoothUUID const &characteristic);
+
+        [[nodiscard]] std::string to_s() const;
+        // bool operator==(const Peripheral &ap) const;
+
+        void on_connect(Object on_connect);
+        void on_disconnect(Object on_disconnect);
+        void ruby_mark() const;
+
+        template<typename, class, class> friend class Registry;
+        friend void Init_Registries();
+    };
+
+    constexpr const BluetoothAddress &Peripheral::address() const { return _addr; /*_peripheral->address();*/ }
+    constexpr const BluetoothAddressType &Peripheral::address_type() const {
+        return _addr_type;
+    }
+}

data/ext/ruble/bindings/RuBLE.cpp

@@ -0,0 +1,115 @@
+#include "types/declarations.hpp"
+#include "utils/exception_handling.hpp"
+
+using namespace std::chrono_literals;
+
+namespace RuBLE {
+    static_assert(!AdapterRegistry::is_owned);
+    static_assert(PeripheralRegistry::is_owned);
+    static_assert(ServiceRegistry::is_owned);
+    static_assert(CharacteristicRegistry::is_owned);
+
+    [[maybe_unused]] InRuby::Guard main_thread_in_ruby;
+
+
+    void Init_BluetoothAddressType() {
+        rb_cBluetoothAddressType = Utils::define_described_enum<BluetoothAddressType>("BluetoothAddressType", rb_mRuBLE);
+    }
+
+    void Init_DeInit() {
+        rb_mRuBLE
+            .define_singleton_function("shutdown", &DeInit); // to make it easier to break in gdb from ruby
+        rb_set_end_proc(DeInit, Qnil);
+    }
+
+    void DeInit(VALUE = Qnil) {
+        static std::atomic_flag called = false;
+        // if called is already true, this is a no-op
+        if (called.test_and_set()) return;
+
+
+        // todo: confirm this only applies to peripherals we ourselves have paired
+        if (adapterRegistry && Peripheral::unpair_all_on_exit) {
+            adapterRegistry->for_each([](std::shared_ptr<Adapter> &adapter) {
+                if (adapter->scan_is_active()) adapter->scan_stop();
+                adapter->_peripheral_registry->for_each([](auto &peripheral) {
+                    if (peripheral->is_paired()) peripheral->unpair();
+                    if (peripheral->is_connected()) {
+                        std::cout << "Peripheral " << peripheral << " is connected. Disconnecting on shutdown." << std::endl;
+                        peripheral->disconnect();
+                    }
+                });
+            });
+        }
+
+        // Wait to ensure rubyQueue has stopped (if it hasn't yet)
+        RubyQueue::stop_on_exit(Qnil);
+//        rubyQueue->wait_for_stop();
+
+        // TODO(?): clear factories so ruby objects deallocate in this instance
+        //  (we might not be segfaulting anymore, making this unneeded)
+    }
+
+    [[maybe_unused]] void c_debug() {
+#ifdef RUBLE_DEBUG
+        std::cerr << "Insert gbb breakpoint here" << std::endl;
+#endif
+    }
+
+    void Init_ExceptionHandling() {
+        ExceptionHandling::wrap_termination_handler();
+//        register_handler<Rice::Exception>(RuBLE::handle_exception<Rice::Exception>);
+    }
+
+    void Init_Utils() {
+        rb_mUtils = Rice::define_module_under(rb_mRuBLE, "Utils");
+
+        if constexpr (!DEBUG) return;
+        rb_mUtils.define_module_function("throw_cxx_exception", ExceptionHandling::throw_exception);
+    }
+
+    //static_assert(Identifiers::PartiallyIdentifiableResource<Adapter>);
+    //static_assert(std::same_as<RuBLE::Identifiers::IDTypes::Full<RuBLE::Adapter, true>::tuple, std::tuple<std::string>>);
+
+    // See https://jasonroelofs.com/rice/4.x
+    void Init_RuBLE() {
+        RuBLE::main_thread_in_ruby = RuBLE::in_ruby.assert_in_ruby_guard();
+        assert(RuBLE::main_thread_in_ruby);
+        Init_ExceptionHandling();
+
+    #ifdef HAVE_VALGRIND
+        VALGRIND_PRINTF_BACKTRACE("Enabling leak checking now.\n");
+        VALGRIND_CLO_CHANGE("--leak-check=full");
+    #endif
+        Rice::detail::Registries::instance.instances.isEnabled = true;
+        rb_mRuBLE = Rice::define_module("RuBLE");
+        rubyQueue = RubyQueue::instance();
+
+    #ifdef RUBLE_DEBUG
+        std::cout << "RubyQueue: " << Utils::to_hex_addr(rubyQueue.get()) << std::endl;
+        rb_mRuBLE.define_singleton_function("c_debug", &c_debug); // to make it easier to break in gdb from ruby
+    #endif
+        rb_mRuBLEUnderlying = Rice::define_module_under(rb_mRuBLE, "Underlying");
+        Init_Utils();
+        Init_BluetoothAddressType();
+        Init_ByteArray();
+        Init_Descriptor();
+        Init_Characteristic();
+        Init_Service();
+        Init_Peripheral();
+        Init_Adapter();
+        Init_Registries();
+        Init_DeInit();
+
+        rubyQueue->start();
+        rubyQueue->ensure_started();
+    }
+}
+
+extern "C" [[maybe_unused]] void Init_RuBLE() {
+    RuBLE::Init_RuBLE();
+}
+
+extern "C" [[maybe_unused]] void Init_ruBLE() {
+    RuBLE::Init_RuBLE();
+}

data/ext/ruble/bindings/Service.cpp

@@ -0,0 +1,112 @@
+#include "bindings/Service.hpp"
+
+#include <utility>
+#include "bindings/Characteristic.hpp"
+#include "management/Registry.hpp"
+#include "management/RegistryFactory.hpp"
+#include "bindings/Peripheral.hpp"
+#include "types/declarations.hpp"
+
+namespace RuBLE {
+    Service::Service(const SimpleBLE::Service &service, Owner *owner) :
+            _owner(owner),
+            _service(std::make_shared<SimpleBLE::Service>(service)),
+            _uuid(_service->uuid()),
+            _characteristic_registry(characteristicRegistryFactory->registry(this)),
+            _self(DataObject(*this)) {}
+
+    Object Service::self() const {
+        return _self;
+    }
+
+    SimpleBLE::Service &Service::get() { return *_service; }
+
+    const SimpleBLE::Service &Service::get() const { return *_service; }
+
+    ByteArray Service::data() const { return _service->data(); }
+
+    const std::map<BluetoothUUID, std::shared_ptr<Characteristic>> &Service::characteristics() const {
+        if (!rb_during_gc()) {
+            // we can't create new characteristics during GC
+            for (const auto &c : _service->characteristics()) _characteristic_registry->fetch(c);
+        }
+        return _characteristic_registry->data();
+//        std::vector<SimpleBLE::Characteristic> unwrappedCharacteristics = _service->characteristics();
+//        auto objects = _characteristic_registry->map_to_objects(unwrappedCharacteristics);
+//
+//        std::function<BluetoothUUID(const Characteristic&)> mapFn = &Characteristic::uuid;
+//        auto result = map_by<BluetoothUUID, std::shared_ptr<Characteristic>>(objects, mapFn);
+//        return std::move(result);
+    }
+
+    std::shared_ptr<Characteristic> Service::operator[](const BluetoothUUID &charUuid) const {
+        // only check SimpleBLE backend for characteristic if not already instantiated
+        if (!_characteristic_registry->contains(charUuid)) const auto _result = characteristics();
+        return _characteristic_registry->at(charUuid);
+    }
+
+
+    ByteArray Service::read(const BluetoothUUID &characteristic) {
+        return peripheral()->read(uuid(), characteristic);
+    }
+
+    ByteArray
+    Service::read(const BluetoothUUID &characteristic, const BluetoothUUID &descriptor) {
+        return peripheral()->read(uuid(), characteristic, descriptor);
+    }
+
+    void
+    Service::write(const BluetoothUUID &characteristic, const BluetoothUUID &descriptor,
+                   const ByteArray &data) {
+        peripheral()->write(uuid(), characteristic, descriptor, data);
+    }
+
+    void
+    Service::write_request(const BluetoothUUID &characteristic, const ByteArray &data) {
+        peripheral()->write_request(uuid(), characteristic, data);
+    }
+
+    void
+    Service::write_command(const BluetoothUUID &characteristic, const ByteArray &data) {
+        peripheral()->write_command(uuid(), characteristic, data);
+    }
+
+    void Service::notify(const BluetoothUUID &characteristic,
+                         std::function<void(ByteArray)> callback) {
+        peripheral()->notify(uuid(), characteristic, std::move(callback));
+    }
+
+    void Service::indicate(const BluetoothUUID &characteristic,
+                           std::function<void(ByteArray)> callback) {
+        peripheral()->indicate(uuid(), characteristic, std::move(callback));
+    }
+
+    void Service::unsubscribe(const BluetoothUUID &characteristic) {
+        peripheral()->unsubscribe(uuid(), characteristic);
+    }
+
+    std::string Service::to_s() const {
+        std::ostringstream oss;
+        oss << Utils::basic_object_inspect_start(*this) << " ";
+        oss << "@uuid=\"" << uuid() << "\" ";
+        oss << "@data=\"" << data() << "\" ";
+//        oss << "#characteristics=" << characteristics().size();
+        oss << ">";
+        return oss.str();
+    }
+
+    void Service::ruby_mark() const {
+        rb_gc_mark(self());
+        for (const auto &[uuid, characteristic]: characteristics())
+            Rice::ruby_mark(characteristic.get());
+    }
+
+    void Init_Service() {
+        rb_cService = define_class_under<Service>(rb_mRuBLE, "Service")
+                .define_method("uuid", &Service::uuid) // returns BluetoothUUID
+                .define_method("data", &Service::data) // returns SimpleBLE::ByteArray
+                .define_method("characteristics", &Service::characteristics) // returns std::vector<Characteristic>
+                .define_method("inspect", &Service::to_s);
+        define_class_under<std::shared_ptr<RuBLE::Service>>(rb_mRuBLE, "ServicePtr");
+    }
+}

data/ext/ruble/bindings/Service.hpp

@@ -0,0 +1,61 @@
+#pragma once
+
+#include "types/declarations.hpp"
+#include "types/ruby.hpp"
+#include "utils/hash.hpp"
+
+namespace RuBLE {
+    class Peripheral;
+//    template<Identifiers::OwnerTypedResource T>
+//    class ResourceUniqueIdentifier;
+
+    class Service {
+    public:
+        using Owner = Peripheral;
+        using DataObject = Data_Object<Service>;
+    protected:
+        Owner *_owner;
+        std::shared_ptr<SimpleBLE::Service> _service;
+        std::shared_ptr<CharacteristicRegistry> _characteristic_registry;
+        BluetoothUUID _uuid;
+        VALUE _self = Qnil;
+
+    public:
+        [[nodiscard]] Object self() const;
+        Service() = delete;
+        Service(const SimpleBLE::Service&, Owner*);
+        SimpleBLE::Service &get();
+        [[nodiscard]] const SimpleBLE::Service &get() const;
+        [[nodiscard]] constexpr const Owner *owner() const { return _owner; }
+        constexpr Owner *owner() { return _owner; }
+        [[nodiscard]] constexpr const Peripheral *peripheral() const { return owner(); }
+        constexpr Peripheral *peripheral() { return owner(); }
+
+        [[nodiscard]] constexpr const BluetoothUUID &uuid() const { return _uuid; }
+//        [[nodiscard]] constexpr ResourceUniqueIdentifier<Service> full_resource_identifier() const;
+//        [[nodiscard]] constexpr BluetoothUUID this_resource_identifier() const { return uuid(); }
+
+
+        [[nodiscard]] ByteArray data() const;
+        [[nodiscard]] const std::map<BluetoothUUID, std::shared_ptr<Characteristic>> &characteristics() const;
+        [[nodiscard]] std::shared_ptr<Characteristic> operator[](const BluetoothUUID &charUuid) const;
+
+        [[nodiscard]] ByteArray read(const BluetoothUUID &characteristic);
+        [[nodiscard]] ByteArray read(const BluetoothUUID &characteristic, const BluetoothUUID &descriptor);
+        void write(const BluetoothUUID &characteristic, const BluetoothUUID &descriptor, const ByteArray &data);
+        void write_request(const BluetoothUUID &characteristic, const ByteArray &data);
+        void write_command(const BluetoothUUID &characteristic, const ByteArray &data);
+        void notify(const BluetoothUUID &characteristic, std::function<void(ByteArray payload)> callback);
+        void indicate(const BluetoothUUID &characteristic, std::function<void(ByteArray payload)> callback);
+        void unsubscribe(const BluetoothUUID &characteristic);
+        void ruby_mark() const;
+
+        [[nodiscard]] std::string to_s() const;
+        // bool operator==(const Service &ap) const;
+        // bool operator==(const Service &ap) const;
+
+        friend void Init_Service();
+        friend void Init_Registries();
+        template<typename, class, class> friend class Registry;
+    };
+}

data/ext/ruble/bindings/common.hpp

@@ -0,0 +1,48 @@
+#pragma once
+
+#include "types/ruby.hpp"
+#include "types/declarations.hpp"
+
+namespace RuBLE {
+    extern std::shared_ptr<RubyQueue> rubyQueue;
+
+    extern Rice::Module rb_mRuBLE;
+    extern Rice::Module rb_mRuBLEUnderlying;
+    extern Rice::Module rb_mUtils;
+    [[maybe_unused]] extern BluetoothAddressType_DT rb_cBluetoothAddressType;
+    extern Characteristic_DT rb_cCharacteristic;
+    [[maybe_unused]] extern CharacteristicCapabilityType_DT rb_cCharacteristicCapabilityType;
+    [[maybe_unused]] extern Descriptor_DT rb_cDescriptor;
+    extern Service_DT rb_cService;
+    [[maybe_unused]] extern ServiceRegistry_DT rb_cServiceRegistry;
+    extern AdapterRegistry_DT rb_cAdapterRegistry;
+    [[maybe_unused]] extern PeripheralRegistry_DT rb_cPeripheralRegistry;
+    [[maybe_unused]] extern CharacteristicRegistry_DT rb_cCharacteristicRegistry;
+    extern ByteArray_DT rb_cByteArray;
+    extern Peripheral_DT rb_cPeripheral;
+    extern Adapter_DT rb_cAdapter;
+
+
+    extern std::shared_ptr<AdapterRegistryFactory> adapterRegistryFactory;
+    extern std::shared_ptr<AdapterRegistry> adapterRegistry;
+    extern std::shared_ptr<PeripheralRegistryFactory> peripheralRegistryFactory;
+    extern std::shared_ptr<ServiceRegistryFactory> serviceRegistryFactory;
+    extern std::shared_ptr<CharacteristicRegistryFactory> characteristicRegistryFactory;
+
+    extern void Init_RuBLE();
+    extern void Init_Adapter();
+    extern void Init_BluetoothAddressType();
+    extern void Init_Characteristic();
+    extern void Init_ByteArray();
+    extern void Init_Descriptor();
+    extern void Init_Peripheral();
+    extern void Init_Registries();
+    extern void Init_Service();
+    extern void Init_Utils();
+    extern void Init_DeInit();
+    extern void DeInit(VALUE);
+    extern void c_debug();
+}
+
+extern "C" [[maybe_unused]] void Init_RuBLE();
+extern "C" [[maybe_unused]] void Init_ruBLE();

data/ext/ruble/bindings/globals.cpp

@@ -0,0 +1,43 @@
+#include "types/declarations.hpp"
+#include "types/ruby.hpp"
+#include "types/SimpleBLE.hpp"
+#include "common.hpp"
+#include "utils/ruby_context.hpp"
+#include "utils/hash.hpp"
+#include "utils/garbage_collection.hpp"
+#include "utils/exception_handling.hpp"
+#include "bindings/Characteristic.hpp"
+#include "management/Registry.hpp"
+#include "bindings/Peripheral.hpp"
+#include "bindings/Adapter.hpp"
+#include "bindings/Characteristic.hpp"
+#include <memory>
+
+namespace RuBLE {
+    thread_local InRuby in_ruby {};
+
+    std::shared_ptr<RubyQueue> rubyQueue;
+    Rice::Module rb_mRuBLE;
+    Rice::Module rb_mRuBLEUnderlying;
+    Rice::Module rb_mUtils;
+    [[maybe_unused]] BluetoothAddressType_DT rb_cBluetoothAddressType;
+    Characteristic_DT rb_cCharacteristic;
+    [[maybe_unused]] CharacteristicCapabilityType_DT rb_cCharacteristicCapabilityType;
+    [[maybe_unused]] Descriptor_DT rb_cDescriptor;
+    Service_DT rb_cService;
+    [[maybe_unused]] ServiceRegistry_DT rb_cServiceRegistry;
+    AdapterRegistry_DT rb_cAdapterRegistry;
+    [[maybe_unused]] PeripheralRegistry_DT rb_cPeripheralRegistry;
+    [[maybe_unused]] CharacteristicRegistry_DT rb_cCharacteristicRegistry;
+    ByteArray_DT rb_cByteArray;
+    Peripheral_DT rb_cPeripheral;
+    Adapter_DT rb_cAdapter;
+
+    std::shared_ptr<AdapterRegistryFactory> adapterRegistryFactory;
+    std::shared_ptr<AdapterRegistry> adapterRegistry;
+    std::shared_ptr<PeripheralRegistryFactory> peripheralRegistryFactory;
+    std::shared_ptr<ServiceRegistryFactory> serviceRegistryFactory;
+    std::shared_ptr<CharacteristicRegistryFactory> characteristicRegistryFactory;
+
+    bool Peripheral::unpair_all_on_exit = true;
+}

data/ext/ruble/cmake.mk

@@ -0,0 +1,62 @@
+# Included from ./Makefile
+
+
+# TODO: add compile rules for `all` and `install` to
+#   create build dir and invoke cmake with appropriate arguments
+
+
+# install: install-so install-rb
+# install-so: Makefile
+# install-rb: pre-install-rb do-install-rb install-rb-default
+# install-rb-default: pre-install-rb-default do-install-rb-default
+# all:    Makefile
+# static: $(STATIC_LIB)
+# .PHONY: all install static install-so install-rb
+# .PHONY: clean clean-so clean-static clean-rb
+
+pre-build: # TODO: add deps
+  echo mkdir -p $(build_dir)
+  echo cd $(build_dir)
+  echo cmake $(ext_dir) -A $(plattorm) -G 'Unix Makefile' -C build-config.cmake --install-prefix ...
+
+
+$(DLLIB): pre-build
+  # should install to $(TARGET_SO_DIR)
+  echo make -C $(build_dir) $@
+  
+
+# TODO add static target in cmake
+$(STATIC_LIB): pre-build
+  echo make -C $(build_dir) $@
+  echo "ERROR: Static builds not supported"
+  exit 2
+
+so: $(DLLIB) # todo: is this already defined?
+
+all: so static
+
+install-static: static
+  # todo: why don't we not use cmake at all for the install?
+  echo make -C $(build_dir) $@
+
+install-so-local: so
+  # copy so into lib/ruBLE/ruBLE.so
+
+install-so: so
+  # todo: why don't we not use cmake at all for the install?
+  echo make -C $(build_dir) $@
+
+clean-static:
+  echo make -C $(build_dir) clean
+
+clean-so:
+  echo make -C $(build_dir) clean
+
+distclean-so:
+  rm -Rf $(build_dir)
+
+distclean-static:
+  rm -Rf $(build_dir)
+
+
+

data/ext/ruble/concerns/CharacteristicValueTracker.cpp

@@ -0,0 +1,18 @@
+#include "CharacteristicValueTracker.hpp"
+
+namespace RuBLE {
+    bool CharacteristicValueTracker::record_new_value(ByteArray new_data) const {
+        if (!value_tracking()) return true; // always assume value changed if no tracking
+        std::shared_ptr<ByteArray> old_value =
+                std::exchange(_value, std::make_shared<ByteArray>(std::move(new_data)));
+
+        // if no previous value, returns whether or not new value is empty
+        if (!old_value) return _value->length() > 0;
+        // otherwise, return true if old and new values differ
+        return *old_value != *_value;
+    }
+
+    void CharacteristicValueTracker::ruby_mark() const {
+        if (_value) _value->ruby_mark();
+    }
+}

data/ext/ruble/concerns/CharacteristicValueTracker.hpp

@@ -0,0 +1,40 @@
+#pragma once
+#include "types/declarations.hpp"
+#include <optional>
+
+namespace RuBLE {
+    // just felt cleaner to abstract out this logic. open to being persuaded otherwise
+    class CharacteristicValueTracker {
+    protected:
+        std::optional<bool> _track_values;
+        mutable std::shared_ptr<ByteArray> _value;
+
+        constexpr CharacteristicValueTracker(std::optional<bool> enabled = std::nullopt) :
+            _track_values(enabled) {}
+
+        // returns true if value changed
+        bool record_new_value(ByteArray new_data) const;
+
+    public:
+        virtual bool can_notify() const = 0;
+        constexpr void set_value_tracking(bool new_value) {
+            if (new_value && !can_notify()) {
+                throw std::runtime_error("Characteristic does not have 'notify' capability.");
+            } else if (!new_value) {
+                _value = nullptr;
+            }
+            _track_values = new_value;
+        }
+
+        constexpr bool value_tracking() const {
+            return _track_values.value_or(can_notify());
+        }
+
+        [[nodiscard]] constexpr const std::shared_ptr<ByteArray> &last_value() const {
+            return _value;
+        }
+
+        virtual void ruby_mark() const;
+    };
+} // RuBLE
+

data/ext/ruble/concerns/Rubyable.cpp

@@ -0,0 +1,4 @@
+#include "Rubyable.hpp"
+
+namespace RuBLE {
+} // RuBLE

data/ext/ruble/concerns/Rubyable.hpp

@@ -0,0 +1,46 @@
+#pragma once
+#include <iostream>
+#include <concepts>
+#include "types/ruby.hpp"
+#include "utils/human_type_names.hpp"
+#include "utils/ruby_context.hpp"
+#include "utils/hexadecimal.hpp"
+
+namespace RuBLE {
+    // TODO: Use this for Adapter/Peripheral/Service/Characteristic/Descriptor
+    template <class T>
+    class Rubyable {
+    protected:
+        VALUE _self = Qnil;
+
+        virtual constexpr VALUE &get_or_allocate_rb_object() {
+            if (_self != Qnil) return _self;
+            if (in_ruby) {
+                _self = Rice::Data_Object<T>(*dynamic_cast<T*>(this));
+                std::cerr << "Note: allocated ruby object for ";
+                std::cerr << Utils::human_type_name(*this) << " (";
+                std::cerr << Utils::ptr_to_hex_addr(this) << ") with VALUE ";
+                std::cerr << _self << "." << std::endl;
+            } else {
+                std::cerr << "Warning: could not allocate ruby object for ";
+                std::cerr << Utils::human_type_name(*this) << " (";
+                std::cerr << Utils::ptr_to_hex_addr(this) << ") because ";
+                std::cerr << "inRuby is false." << std::endl;
+            }
+            return _self;
+        }
+    public:
+        constexpr Rubyable() = default;
+
+        template<class U = Rice::Data_Object<T>> requires std::is_base_of_v<Rice::Object, U>
+        U self() const {
+            if (_self == Qnil) _self = get_or_allocate_rb_object();
+            return { _self };
+        }
+
+        virtual void ruby_mark() const {
+            if (_self != Qnil) rb_gc_mark(_self);
+        }
+    };
+} // RuBLE
+