ble 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d0d63de7a39417e54dd34e2fc70a326061d36cc6
-  data.tar.gz: ac360bfb08b81186e16840c3c7dac76f09788d6f
+  metadata.gz: 7cc1b7511a25f6f47653f9b5430a1a15c4361574
+  data.tar.gz: 776bcbf870dd96a1fb0575a8f9aefe7bcdb1199e
 SHA512:
-  metadata.gz: d4a84b8634507629242d89e81542d03e5036ca73faba52e1a4db5d128ea8140e8ac46925de9b45948e12fa6de894865a9e2835500b5ef28265aa2c597bae989a
-  data.tar.gz: ff96bdeadd3582a120bcd68b8b48864a736d611653c8754508daf08fe68f7fa5808cc7395397277c64be0c434a3a14f642f4bb2d445968f98927007e997caf4b
+  metadata.gz: 35ef023571bfd637245b82c814eaed2d08f265a14d207f29b17ad3633a9e62e30b072f4041e9b1ef4a3b6025e5607a0ed958c9cc187c98ab73eecc7534ae6cef
+  data.tar.gz: 118372609995212452776777eb03682579e5d87d57b19758cfa3e476415a10dccc2921d53e0f3ee64463876ed56edf3823f6304bece3da712f6e36d0d883afb3

data/lib/ble.rb

@@ -96,8 +96,11 @@ end
 require_relative 'ble/version'
 require_relative 'ble/uuid'
 require_relative 'ble/adapter'
+require_relative 'ble/char_desc'
+require_relative 'ble/notifications'
 require_relative 'ble/device'
 require_relative 'ble/service'
+require_relative 'ble/char_registry'
 require_relative 'ble/characteristic'
 require_relative 'ble/agent'
 

data/lib/ble/char_desc.rb

@@ -0,0 +1,63 @@
+# Encapsulates Characteristic descriptors and offers easy
+# access to characteristic related information.
+#
+module BLE
+  class CharDesc
+    attr_reader :desc
+    # @param desc [Hash] Descriptors.
+    def initialize(desc)
+      @desc= desc
+    end
+    def flags
+      @flags||= @desc[:flags]
+    end
+    def config
+      @config||= Characteristic[@desc[:uuid]]
+    end
+
+    def uuid
+      @desc[:uuid]
+    end
+    def flag?(flag_name)
+      flags.include?(flag_name)
+    end
+
+    # Does outgoing values have processors configured?
+    # If yes, the value needs to be pre-processed before being send.
+    def write_processors?
+      verifier? or write_pre_processor?
+    end
+    # Does incoming values have processors configured?
+    # If yes, the value needs to be post-processed after being received.
+    def read_processors?
+      config && read_post_processor?
+    end
+    # It has been configured a verifier preprocessor to check
+    # outgoing data?
+    def verifier?
+      config[:vrfy]
+    end
+    def write_pre_processor?
+      config[:out]
+    end
+    def read_post_processor?
+      config[:in]
+    end
+    # Is the received value verified by the verifier?
+    def verifies?(val)
+      config[:vrfy].call(val)
+    end
+    def pre_process(val)
+      if verifier? && !verifies?(val)
+        raise ArgumentError,
+          "bad value for characteristic '#{uuid}'"
+      end
+      val = config[:out].call(val) if write_pre_processor?
+    end
+
+    def post_process(val)
+      val = config[:in].call(val) if read_post_processor?
+    end
+
+  end
+end

data/lib/ble/char_registry.rb

@@ -0,0 +1,142 @@
+# To add a new characteristic description:
+#   BLE::Characteristic.add 'c4935338-4307-47cf-ae1f-feac9e2b3ae7',
+#       name: 'Controlled mind',
+#       type: 'net.cortex-minus.characteristic.controlled_mind'
+#       vrfy: ->(x) { x >= 0 },
+#         in: ->(s) { s.unpack('s<').first },
+#        out: ->(v) { [ v ].pack('s<') }
+#
+# Returned characteristic description will be a hash:
+#   {
+#      name: "Bluetooth characteristic name",
+#      type: "org.bluetooth.characteristic.name",
+#      uuid: "128bit-uuid-string",
+#      vrfy: ->(x) { verify_value(x) },
+#        in: ->(s) { s.unpack(....) ... },
+#       out: ->(v) { [ v ].pack(....) ... }
+#   }
+#
+module BLE
+  module CharRegistry
+
+    private
+
+    DB_UUID     = {}
+    DB_TYPE     = {}
+    DB_NICKNAME = {}
+
+    public
+    def self.included(klass)
+      class << klass
+        # Get characteristic description from nickname.
+        #
+        # @param id [Symbol] nickname
+        # @return [CharDesc] characteristic description
+        def by_nickname(id)
+          DB_NICKNAME[id]
+        end
+
+        # Get characteristic description from uuid.
+        #
+        # @param id [String] uuid
+        # @return [CharDesc] characteristic description
+        def by_uuid(id)
+          DB_UUID[id]
+        end
+
+        # Get characteristic description from type
+        #
+        # @param id [Strig] type
+        # @return [CharDesc] characteristic description
+        def by_type(id)
+          DB_TYPE[id]
+        end
+
+        # Get a characteristic description from it's id
+        # @param id [Symbol,String]
+        # @return [CharDesc]
+        def [](id)
+          case id
+          when Symbol      then DB_NICKNAME[id]
+          when UUID::REGEX then DB_UUID[id]
+          when String      then DB_TYPE[id]
+          when Integer     then DB_UUID[BLE::UUID(id)]
+          else raise ArgumentError, "invalid type for characteristic id"
+          end
+        end
+
+
+        # Add a characteristic description.
+        # @example Add a characteristic description with a 16-bit uuid
+        #   module Characteristic
+        #       add 0x2A6E,
+        #           name: 'Temperature',
+        #           type: 'org.bluetooth.characteristic.temperature',
+        #           vrfy: ->(x) { (0..100).include?(x) },
+        #             in: ->(s) { s.unpack('s<').first.to_f / 100 },
+        #            out: ->(v) { [ v*100 ].pack('s<') }
+        #   end
+        #
+        # @example Add a characteristic description with a 128-bit uuid
+        #   module Characteristic
+        #       add 'c4935338-4307-47cf-ae1f-feac9e2b3ae7',
+        #           name: 'Controlled mind',
+        #           type: 'net.cortex-minus.characteristic.controlled_mind',
+        #           vrfy: ->(x) { x >= 0 },
+        #             in: ->(s) { s.unpack('s<').first },
+        #            out: ->(v) { [ v ].pack('s<') }
+        #   end
+        #
+        # @param uuid [Integer, String] 16-bit, 32-bit or 128-bit uuid
+        # @param name [String]
+        # @option opts :type [String] type
+        # @option opts :nick [Symbol] nickname
+        # @option opts :in   [Proc] convert to ruby
+        # @option opts :out  [Proc] convert to bluetooth data
+        # @option opts :vry  [Proc] verify
+        # @return [CharDesc] characteristic description
+        def add(uuid, name:, **opts)
+          uuid = BLE::UUID(uuid)
+          type =  opts.delete :type
+          nick = opts.delete :nick
+          _in  = opts.delete :in
+          _out = opts.delete :out
+          vrfy = opts.delete :vrfy
+          if opts.first
+            raise ArgumentError, "unknown keyword: #{opts.first[0]}"
+          end
+
+          char_config= DB_UUID[uuid] = {
+            uuid: uuid,
+            name: name,
+            in: _in,
+            out: _out,
+            vrfy: vrfy
+          }
+
+          # Add type if specified
+          if type
+            type = type.downcase
+            char_config.merge!(type: type)
+            DB_TYPE[type] = char_config
+          end
+
+          # Add nickname if specified or can be derived from type
+          if nick.nil? && type && type =~ /\.(?<key>[^.]+)$/
+            nick = $1.to_sym if type.start_with? 'org.bluetooth.characteristic'
+          end
+          if nick
+            if DB_NICKNAME.include?(nick)
+              raise ArgumentError,
+                "nickname '#{nick}' already registered (uuid: #{uuid})"
+            end
+            DB_NICKNAME[nick] = char_config
+          end
+        end
+
+
+      end
+    end
+
+  end
+end

data/lib/ble/characteristic.rb

@@ -1,154 +1,85 @@
+require 'forwardable'
 module BLE
-# Build information about {https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicsHome.aspx Bluetooth Characteristics}
-#
-# To add a new characteristic description:
-#   BLE::Characteristic.add 'c4935338-4307-47cf-ae1f-feac9e2b3ae7',
-#       name: 'Controlled mind',
-#       type: 'net.cortex-minus.characteristic.controlled_mind'
-#       vrfy: ->(x) { x >= 0 },
-#         in: ->(s) { s.unpack('s<').first },
-#        out: ->(v) { [ v ].pack('s<') }    
-# 
-# Returned characteristic description will be a hash:
-#   {
-#      name: "Bluetooth characteristic name",
-#      type: "org.bluetooth.characteristic.name",
-#      uuid: "128bit-uuid-string",
-#      vrfy: ->(x) { verify_value(x) },
-#        in: ->(s) { s.unpack(....) ... },
-#       out: ->(v) { [ v ].pack(....) ... }    
-#   }
-#    
-module Characteristic
+  # Build information about {https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicsHome.aspx Bluetooth Characteristics}
+  #
+  class Characteristic
+    include CharRegistry
+    extend Forwardable
+
     # Notify of characteristic not found
-    class NotFound < BLE::NotFound 
+    class NotFound < BLE::NotFound
+    end
+
+    def initialize(desc)
+      @dbus_obj= desc[:obj]
+      @desc= CharDesc.new(desc)
     end
 
+    def_delegators :@desc, :flag?, :uuid
+
     private
     FLAGS    = [ 'broadcast',
-		 'read',
-		 'write-without-response',
-		 'write',
-		 'notify',
-		 'indicate',
-		 'authenticated-signed-writes',
-		 'reliable-write',
-		 'writable-auxiliaries',
-		 'encrypt-read',
-		 'encrypt-write',
-		 'encrypt-authenticated-read',
-		 'encrypt-authenticated-write' ]
-    
-    DB_UUID     = {}
-    DB_TYPE     = {}
-    DB_NICKNAME = {}
-    
+      'read',
+      'write-without-response',
+      'write',
+      'notify',
+      'indicate',
+      'authenticated-signed-writes',
+      'reliable-write',
+      'writable-auxiliaries',
+      'encrypt-read',
+      'encrypt-write',
+      'encrypt-authenticated-read',
+      'encrypt-authenticated-write' ]
+
+
+    #++++++++++++++++++++++++++++
     public
-    # Get characteristic description from nickname.
-    #
-    # @param id [Symbol] nickname
-    # @return [Hash] characteristic description
-    def self.by_nickname(id)
-        DB_NICKNAME[id]
+    #++++++++++++++++++++++++++++
+
+    def write(val, raw: false)
+      val= _serialize_value(val, raw: raw)
+      @dbus_obj[I_GATT_CHARACTERISTIC].WriteValue(val)
     end
 
-    # Get characteristic description from uuid.
-    #
-    # @param id [String] uuid
-    # @return [Hash] characteristic description
-    def self.by_uuid(id)
-        DB_UUID[id]
+    def read(raw: false)
+      val= @dbus_obj[I_GATT_CHARACTERISTIC].ReadValue().first
+      val= _deserialize_value(val, raw: raw)
     end
 
-    # Get characteristic description from type
-    #
-    # @param id [Strig] type
-    # @return [Hash] characteristic description
-    def self.by_type(id)
-        DB_TYPE[id]
+    # Register to this characteristic for notifications when
+    # its value changes.
+    def notify!
+      @dbus_obj[I_GATT_CHARACTERISTIC].StartNotify
     end
-    
-    # Get a characteristic description from it's id
-    # @param id [Symbol,String]
-    # @return [Hash]
-    def self.[](id)
-        case id
-        when Symbol      then DB_NICKNAME[id]
-        when UUID::REGEX then DB_UUID[id]
-        when String      then DB_TYPE[id]
-        when Integer     then DB_UUID[BLE::UUID(id)]
-        else raise ArgumentError, "invalid type for characteristic id"
+
+    def on_change(raw: false, &callback)
+      @dbus_obj[I_PROPERTIES].on_signal('PropertiesChanged') do |intf, props|
+        case intf
+        when I_GATT_CHARACTERISTIC
+          val= _deserialize_value(props['Value'], raw: raw)
+          callback.call(val)
         end
+      end
     end
-    
+    #----------------------------
+    private
+    #----------------------------
 
-    # Add a characteristic description.
-    # @example Add a characteristic description with a 16-bit uuid
-    #   module Characteristic
-    #       add 0x2A6E,
-    #           name: 'Temperature',
-    #           type: 'org.bluetooth.characteristic.temperature',
-    #           vrfy: ->(x) { (0..100).include?(x) },
-    #             in: ->(s) { s.unpack('s<').first.to_f / 100 },
-    #            out: ->(v) { [ v*100 ].pack('s<') }
-    #   end
-    #
-    # @example Add a characteristic description with a 128-bit uuid
-    #   module Characteristic
-    #       add 'c4935338-4307-47cf-ae1f-feac9e2b3ae7',
-    #           name: 'Controlled mind',
-    #           type: 'net.cortex-minus.characteristic.controlled_mind',
-    #           vrfy: ->(x) { x >= 0 },
-    #             in: ->(s) { s.unpack('s<').first },
-    #            out: ->(v) { [ v ].pack('s<') }    
-    #   end
-    #
-    # @param uuid [Integer, String] 16-bit, 32-bit or 128-bit uuid
-    # @param name [String]
-    # @option opts :type [String] type
-    # @option opts :nick [Symbol] nickname
-    # @option opts :in   [Proc] convert to ruby
-    # @option opts :out  [Proc] convert to bluetooth data
-    # @option opts :vry  [Proc] verify
-    # @return [Hash] characteristic description
-    def self.add(uuid, name:, **opts)
-        uuid = BLE::UUID(uuid)
-        type =  opts.delete :type
-        nick = opts.delete :nick
-        _in  = opts.delete :in
-        _out = opts.delete :out
-        vrfy = opts.delete :vrfy            
-        if opts.first 
-            raise ArgumentError, "unknown keyword: #{opts.first[0]}" 
-        end
-        
-        
-        desc = DB_UUID[uuid] = {
-            uuid: uuid,
-            name: name,
-              in: _in,
-             out: _out,
-            vrfy: vrfy
-        }
-        
-        # Add type if specified
-        if type
-            type = type.downcase
-            desc.merge!(type: type)
-            DB_TYPE[type] = desc
-        end
+    # Convert Arrays of bytes returned by DBus to Strings of bytes.
+    def _serialize_value(val, raw: false)
+      if !raw && @desc.write_processors?
+        val= @desc.pre_process(val)
+      end
+      val.unpack('C*')
+    end
 
-        # Add nickname if specified or can be derived from type
-        if nick.nil? && type && type =~ /\.(?<key>[^.]+)$/
-            nick = $1.to_sym if type.start_with? 'org.bluetooth.characteristic'
-        end
-        if nick
-            if DB_NICKNAME.include?(nick)
-                raise ArgumentError,
-                      "nickname '#{nick}' already registered (uuid: #{uuid})"
-            end
-            DB_NICKNAME[nick] = desc
-        end
+    # Convert Arrays of bytes returned by DBus to Strings of bytes.
+    def _deserialize_value(val, raw: false)
+      val = val.pack('C*')
+      val = @desc.post_process(val) if !raw && @desc.read_processors?
+      val
     end
-end
+
+  end
 end