flic 0.0.5 → 0.0.6

data/lib/flic/protocol/events/scan_wizard_completed.rb

@@ -6,9 +6,7 @@ module Flic
   module Protocol
     module Events
       class ScanWizardCompleted < Event
-        endian :little
-
-        uint32 :scan_wizard_id
+        uint32le :scan_wizard_id
         scan_wizard_result :scan_wizard_result
       end
     end

data/lib/flic/protocol/events/scan_wizard_found_private_button.rb

@@ -5,9 +5,7 @@ module Flic
   module Protocol
     module Events
       class ScanWizardFoundPrivateButton < Event
-        endian :little
-
-        uint32 :scan_wizard_id
+        uint32le :scan_wizard_id
       end
     end
   end

data/lib/flic/protocol/events/scan_wizard_found_public_button.rb

@@ -7,9 +7,7 @@ module Flic
   module Protocol
     module Events
       class ScanWizardFoundPublicButton < Event
-        endian :little
-
-        uint32 :scan_wizard_id
+        uint32le :scan_wizard_id
 
         bluetooth_address :bluetooth_address
         device_name :name

data/lib/flic/protocol/packet_header.rb

@@ -4,9 +4,9 @@ require 'bindata'
 
 module Flic
   module Protocol
+    # Every packet starts with a packet header that includes the length of the remaining packet
     class PacketHeader < BinData::Record
-      endian :little
-      uint16 :byte_length
+      uint16le :byte_length
     end
   end
 end

data/lib/flic/protocol/primitives.rb

@@ -2,6 +2,7 @@ require 'flic/protocol'
 
 module Flic
   module Protocol
+    # A namespace module for all of the primitive classes
     module Primitives
       autoload :BluetoothAddress, 'flic/protocol/primitives/bluetooth_address'
       autoload :BluetoothAddressType, 'flic/protocol/primitives/bluetooth_address_type'

data/lib/flic/protocol/primitives/bluetooth_address.rb

@@ -6,11 +6,12 @@ require 'scanf'
 module Flic
   module Protocol
     module Primitives
+      # A bluetooth address (bdaddr_t) is encoded in little endan, 6 bytes in total. When such an address is written as a string, it is normally written in big endian, where each byte is encoded in hex and colon as separator for each byte. For example, the address 08:09:0a:0b:0c:0d is encoded as the bytes 0x0d, 0x0c, 0x0b, 0x0a, 0x09, 0x08.
       class BluetoothAddress < BinData::Primitive
         PRINTF_FORMAT_STRING = '%.2X:%.2X:%.2X:%.2X:%.2X:%.2X'.freeze
         SCANF_FORMAT_STRING = '%X:%X:%X:%X:%X:%X'.freeze
 
-        array :little_endian_octets, type: :uint8, initial_length: 6
+        array :little_endian_octets, type: :uint8le, initial_length: 6
 
         def get
           sprintf(PRINTF_FORMAT_STRING, *big_endian_octets)

data/lib/flic/protocol/primitives/bluetooth_address_type.rb

@@ -4,6 +4,9 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
+      # The server can be configured to either use the burnt-in public address stored inside the bluetooth controller, or to use a custom random static address. This custom address is a good idea if you want to be able to use your database with bonding information with a different bluetooth controller.
+      # [:public_bluetooth_address_type] burnt-in public address
+      # [:random_bluetooth_address_type] another address
       class BluetoothAddressType < Enum
         option :public_bluetooth_address_type
         option :random_bluetooth_address_type

data/lib/flic/protocol/primitives/bluetooth_controller_state.rb

@@ -4,10 +4,14 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
+      # The server software detects when the bluetooth controller is removed or is made unavailable. It will then repeatedly retry to re-established a connection to the same bluetooth controller.
+      # [:detached] The server software has lost the HCI socket to the bluetooth controller and is trying to reconnect.
+      # [:resetting] The server software has just got connected to the HCI socket and initiated a reset of the bluetooth controller.
+      # [:attached] The bluetooth controller has done initialization and is up and running.
       class BluetoothControllerState < Enum
-        option :detached      # The server software has lost the HCI socket to the bluetooth controller and is trying to reconnect.
-        option :resetting     # The server software has just got connected to the HCI socket and initiated a reset of the bluetooth controller.
-        option :attached      # The bluetooth controller has done initialization and is up and running.
+        option :detached
+        option :resetting
+        option :attached
       end
     end
   end

data/lib/flic/protocol/primitives/boolean.rb

@@ -3,6 +3,7 @@ require 'flic/protocol/primitives'
 module Flic
   module Protocol
     module Primitives
+      # True or false encoded as a byte where 0x00 is false and all other values are true (however, 0x01 is preferred)
       class Boolean < BinData::Primitive
         uint8 :byte
 

data/lib/flic/protocol/primitives/click_type.rb

@@ -4,13 +4,20 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
+      # The type of click registered by a button
+      # [:button_down] The button was pressed.
+      # [:button_up] The button was released.
+      # [:button_click] The button was clicked, and was held for at most 1 second between press and release.
+      # [:button_single_click] The button was clicked once.
+      # [:button_double_click] The button was clicked twice. The time between the first and second press must be at most 0.5 seconds.
+      # [:button_hold] The button was held for at least 1 second.
       class ClickType < Enum
-        option :button_down           # The button was pressed.
-        option :button_up             # The button was released.
-        option :button_click          # The button was clicked, and was held for at most 1 second between press and release.
-        option :button_single_click   # The button was clicked once.
-        option :button_double_click   # The button was clicked twice. The time between the first and second press must be at most 0.5 seconds.
-        option :button_hold           # The button was held for at least 1 second.
+        option :button_down
+        option :button_up
+        option :button_click
+        option :button_single_click
+        option :button_double_click
+        option :button_hold
       end
     end
   end

data/lib/flic/protocol/primitives/connection_status.rb

@@ -4,10 +4,13 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
-      class ConnectionStatus < Enum
-        option :disconnected  # Not currently an established connection, but will connect as soon as the button is pressed and it is in range as long as the connection channel hasn't been removed (and unless maximum number of concurrent connections has been reached or the bluetooth controller has been detached).
-        option :connected     # The physical bluetooth connection has just been established and the server and the button are currently verifying each other. As soon as this is done, it will switch to the ready status.
-        option :ready         # The verification is done and button events may now arrive.
+      # [:disconnected] Not currently an established connection, but will connect as soon as the button is pressed and it is in range as long as the connection channel hasn't been removed (and unless maximum number of concurrent connections has been reached or the bluetooth controller has been detached).
+      # [:connected] The physical bluetooth connection has just been established and the server and the button are currently verifying each other. As soon as this is done, it will switch to the ready status.
+      # [:ready] The verification is done and button events may now arrive.
+    class ConnectionStatus < Enum
+        option :disconnected
+        option :connected
+        option :ready
       end
     end
   end

data/lib/flic/protocol/primitives/create_connection_channel_error.rb

@@ -4,9 +4,11 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
+      # :no_error - There were space in the bluetooth controller's white list to accept a physical pending connection for this button
+      # :maximum_pending_connections_reached - There were no space left in the bluetooth controller to allow a new pending connection
       class CreateConnectionChannelError < Enum
-        option :no_error                              # There were space in the bluetooth controller's white list to accept a physical pending connection for this button
-        option :maximum_pending_connections_reached   # There were no space left in the bluetooth controller to allow a new pending connection
+        option :no_error
+        option :maximum_pending_connections_reached
       end
     end
   end

data/lib/flic/protocol/primitives/device_name.rb

@@ -5,11 +5,12 @@ require 'bindata'
 module Flic
   module Protocol
     module Primitives
+      # The name of a device (up to 16 character string)
       class DeviceName < BinData::Primitive
         BYTE_LENGTH = 16
 
         uint8 :byte_length
-        array :bytes, type: :int8, initial_length: BYTE_LENGTH
+        array :bytes, type: :int8le, initial_length: BYTE_LENGTH
 
         def get
           ''.tap do |string|

data/lib/flic/protocol/primitives/disconnect_reason.rb

@@ -4,11 +4,15 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
+      # [:unspecified] Unknown reason
+      # [:connection_establishment_failed] The bluetooth controller established a connection, but the Flic button didn't answer in time.
+      # [:timed_out] The connection to the Flic button was lost due to either being out of range or some radio communication problems.
+      # [:bonding_keys_mismatch] The server and the Flic button for some reason don't agree on the previously established bonding keys.
       class DisconnectReason < Enum
-        option :unspecified                       # Unknown reason
-        option :connection_establishment_failed   # The bluetooth controller established a connection, but the Flic button didn't answer in time.
-        option :timed_out                         # The connection to the Flic button was lost due to either being out of range or some radio communication problems.
-        option :bonding_keys_mismatch             # The server and the Flic button for some reason don't agree on the previously established bonding keys.
+        option :unspecified
+        option :connection_establishment_failed
+        option :timed_out
+        option :bonding_keys_mismatch
       end
     end
   end

data/lib/flic/protocol/primitives/disconnect_time.rb

@@ -3,13 +3,12 @@ require 'flic/protocol/primitives'
 module Flic
   module Protocol
     module Primitives
+      # Time in seconds after the Flic button may disconnect after the latest press or release. The button will reconnect automatically when it is later pressed again and deliver its enqueued events. Valid values are 0 - 511.
       class DisconnectTime < BinData::Primitive
-        endian :little
-
-        uint16 :time, initial_value: 512
+        uint16le :time, initial_value: 511
 
         def get
-          if time == 512
+          if time == 511
             nil
           else
             time
@@ -17,12 +16,12 @@ module Flic
         end
 
         def set(value)
-          if value == 512
-            raise RangeError, '512 is a special value that cannot be used for disconnect_time'
-          elsif value
-            self.time = value
+          if value == nil
+            self.time = 511
+          elsif value >= 511
+            raise RangeError, 'disconnect_time must be less than 511 seconds (or nil for never)'
           else
-            self.time = 512
+            self.time = value
           end
         end
       end

data/lib/flic/protocol/primitives/enum.rb

@@ -5,32 +5,39 @@ require 'bindata'
 module Flic
   module Protocol
     module Primitives
+      # An abstract class for 1 byte enums
       class Enum < BinData::Primitive
         class Error < StandardError; end
         class InvalidOptionError < Error; end
         class InvalidOctetError < Error; end
 
         class << self
+          # @return [Hash] a map of options to byte values
           def option_octet
             @option_octet ||= {}
           end
 
+          # @return [Hash] a map of byte values to options
           def octet_option
             @octet_option ||= {}
           end
 
+          # @return [Array] the valid options for this enum
           def options
             option_octet.keys
           end
 
+          # @return [Array] the valid byte values for this enum
           def octets
             octet_option.keys
           end
 
+          # @return [Integer] the byte value for the option with the largest byte value
           def max_octet
             octets.max
           end
 
+          # @return [Integer] the next available byte value (starting at 0x00)
           def next_available_octet
             if max_octet
               1 + max_octet
@@ -41,18 +48,22 @@ module Flic
 
           private
 
+          # Associates an option with a byte value of the enum
+          # @param option [Symbol]
+          # @param octet [Integer] (defaults to the next available byte value)
           def option(option, octet = next_available_octet)
             option_octet[option] = octet
             octet_option[octet] = option
           end
 
+          # Associates a byte value of an enum with an option
           def octet(octet, option)
             octet_option[octet] = option
             option_octet[option] = octet
           end
         end
 
-        uint8 :octet
+        uint8le :octet
 
         def get
           if octet_option.has_key?(octet)

data/lib/flic/protocol/primitives/latency_mode.rb

@@ -4,10 +4,14 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
+      # This specifies the accepted latency mode for the corresponding connection channel. The physical bluetooth connection will use the lowest mode set by any connection channel. The battery usage for the Flic button is normally about the same for all modes if the connection is stable. However lower modes will have higher battery usage if the connection is unstable. Lower modes also consumes more power for the client, which is normally not a problem since most computers run on wall power or have large batteries.
+      # [:normal] Up to 100 ms latency.
+      # [:low] Up to 17.5 ms latency.
+      # [:high] Up to 275 ms latency.
       class LatencyMode < Enum
-        option :normal    # Up to 100 ms latency.
-        option :low       # Up to 17.5 ms latency.
-        option :high      # Up to 275 ms latency.
+        option :normal
+        option :low
+        option :high
       end
     end
   end

data/lib/flic/protocol/primitives/removed_reason.rb

@@ -4,14 +4,21 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
+      # [:removed_by_this_client] The connection channel was removed by this client.
+      # [:force_disconnected_by_this_client] The connection channel was removed due to a force disconnect by this client.
+      # [:force_disconnected_by_other_client] Another client force disconnected the button used in this connection channel.
+      # [:button_is_private] The button is not in public mode. Hold it down for 7 seconds while not trying to establish a connection, then try to reconnect by creating a new connection channel.
+      # [:verify_timeout] After the connection was established, the bonding procedure didn't complete in time.
+      # [:internet_backend_error] The internet request to the Flic backend failed.
+      # [:invalid_data] According to the Flic backend, this Flic button supplied invalid identity data.
       class RemovedReason < Enum
-        option :removed_by_this_client                # The connection channel was removed by this client.
-        option :force_disconnected_by_this_client     # The connection channel was removed due to a force disconnect by this client.
-        option :force_disconnected_by_other_client    # Another client force disconnected the button used in this connection channel.
-        option :button_is_private                     # The button is not in public mode. Hold it down for 7 seconds while not trying to establish a connection, then try to reconnect by creating a new connection channel.
-        option :verify_timeout                        # After the connection was established, the bonding procedure didn't complete in time.
-        option :internet_backend_error                # The internet request to the Flic backend failed.
-        option :invalid_data                          # According to the Flic backend, this Flic button supplied invalid identity data.
+        option :removed_by_this_client
+        option :force_disconnected_by_this_client
+        option :force_disconnected_by_other_client
+        option :button_is_private
+        option :verify_timeout
+        option :internet_backend_error
+        option :invalid_data
       end
     end
   end

data/lib/flic/protocol/primitives/scan_wizard_result.rb

@@ -4,14 +4,21 @@ require 'flic/protocol/primitives/enum'
 module Flic
   module Protocol
     module Primitives
-      class ScanWizardResult < Enum
-        option :success                 # Indicates that a button was successfully paired and verified. You may now create a connection channel to that button.
-        option :cancelled_by_user       # A CmdCancelScanWizard was sent.
-        option :timeout                 # The scan wizard did not make any progress for some time. Current timeouts are 20 seconds for finding any button, 20 seconds for finding a public button (in case of a private button was found), 10 seconds for connecting the button, 30 seconds for pairing and verifying the button.
-        option :button_private          # First the button was advertising public status, but after connecting it reports private. Probably it switched from public to private just when the connection attempt was started.
-        option :bluetooth_unavailable   # The bluetooth controller is not attached.
-        option :internet_backend_error  # The internet request to the Flic backend failed.
-        option :invalid_data            # According to the Flic backend, this Flic button supplied invalid identity data.
+      # [:success] Indicates that a button was successfully paired and verified. You may now create a connection channel to that button.
+      # [:cancelled_by_user] A CmdCancelScanWizard was sent.
+      # [:timeout] The scan wizard did not make any progress for some time. Current timeouts are 20 seconds for finding any button, 20 seconds for finding a public button (in case of a private button was found), 10 seconds for connecting the button, 30 seconds for pairing and verifying the button.
+      # [:button_private] First the button was advertising public status, but after connecting it reports private. Probably it switched from public to private just when the connection attempt was started.
+      # [:bluetooth_unavailable] The bluetooth controller is not attached.
+      # [:internet_backend_error] The internet request to the Flic backend failed.
+      # [:invalid_data] According to the Flic backend, this Flic button supplied invalid identity data.
+    class ScanWizardResult < Enum
+        option :success
+        option :cancelled_by_user
+        option :timeout
+        option :button_private
+        option :bluetooth_unavailable
+        option :internet_backend_error
+        option :invalid_data
       end
     end
   end

data/lib/flic/protocol/primitives/uuid.rb

@@ -6,18 +6,28 @@ require 'scanf'
 module Flic
   module Protocol
     module Primitives
+      # The uuid of a button (nil is represented as all zeros)
       class Uuid < BinData::Primitive
+        NULL_UUID_OCTETS = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0].freeze
         PRINTF_FORMAT_STRING = '%.2X%.2X%.2X%.2X-%.2X%.2X-%.2X%.2X-%.2X%.2X-%.2X%.2X%.2X%.2X%.2X%.2X'.freeze
         SCANF_FORMAT_STRING = '%X%X%X%X-%X%X-%X%X-%X%X-%X%X%X%X%X%X'.freeze
 
-        array :octets, type: :uint8, initial_length: 16
+        array :octets, type: :uint8le, initial_length: 16
 
         def get
-          sprintf(PRINTF_FORMAT_STRING, *octets)
+          if NULL_UUID_OCTETS == octets
+            nil
+          else
+            sprintf(PRINTF_FORMAT_STRING, *octets)
+          end
         end
 
         def set(value)
-          self.octets = value.scanf(SCANF_FORMAT_STRING)
+          if value
+            self.octets = value.scanf(SCANF_FORMAT_STRING)
+          else
+            self.octets = NULL_UUID_OCTETS
+          end
         end
       end
     end

data/lib/flic/simple_client.rb

@@ -5,121 +5,159 @@ require 'thread'
 module Flic
   class SimpleClient
     class Error < StandardError; end
-    class ConnectionChannelRemoved; end
-    
-    attr_reader :client
+    class Shutdown < Error; end
+    class ConnectionChannelRemoved < Error; end
+    class ButtonIsPrivateError < Error; end
 
-    def initialize(*client_args)
-      @semaphore = Mutex.new
-      @client = Client.new(*client_args)
+    attr_reader :host, :port, :thread
+
+    def initialize(host = 'localhost', port = 5551)
+      @host, @port = host, port
+      
+      @blocker = Blocker.new
+      @client = Client.new(host, port)
+
+      @listen_queues_semaphore = Mutex.new
+      @listen_queues = []
+
+      @thread = Thread.new do
+        begin
+          @client.enter_main_loop
+        rescue Client::Shutdown
+            nil
+        ensure
+          shutdown
+        end
+      end
+
+      @is_shutdown = false
+    end
+
+    def shutdown?
+      @is_shutdown
     end
 
     def shutdown
-      @semaphore.synchronize do
-        client.shutdown
+      @listen_queues_semaphore.synchronize do
+        unless @listen_queues.frozen?
+          @listen_queues.each { |queue| queue << :shutdown }.clear
+          @listen_queues.freeze
+        end
       end
+
+      @blocker.unblock_all! Shutdown, 'The client has shutdown'
+
+      @client.shutdown
+
+      @thread.join unless Thread.current == @thread
+
+      @is_shutdown = true
     end
 
     def buttons
-      @semaphore.synchronize do
-        server_info = process_events_until do |callback|
-          client.get_info(&callback)
+      @blocker.block_until_callback do |callback|
+        @client.get_info do |server_info|
+          callback.call server_info.verified_buttons_bluetooth_addresses
         end
-
-        server_info.verified_buttons_bluetooth_addresses
       end
+    rescue Client::Shutdown
+      raise  Shutdown, 'The client has shutdown'
     end
 
     def connect_button
-      @semaphore.synchronize do
-        scan_wizard = Client::ScanWizard.new
+      scan_wizard = Client::ScanWizard.new
+      saw_only_private_button = false
 
-        begin
-          process_events_until do |callback|
-            scan_wizard.removed do |result, bluetooth_address, *|
-              if result == :success
-                callback.call(bluetooth_address)
-              else
-                callback.call(nil)
-              end
-            end
-
-            client.add_scan_wizard(scan_wizard)
+      begin
+        @blocker.block_until_callback do |callback|
+          scan_wizard.found_private_button do
+            saw_only_private_button = true
           end
-        ensure
-          client.remove_scan_wizard(scan_wizard)
+
+          scan_wizard.found_public_button do
+            saw_only_private_button = false
+          end
+
+          scan_wizard.removed do
+            callback.call
+          end
+
+          @client.add_scan_wizard(scan_wizard)
         end
+      ensure
+        @client.remove_scan_wizard(scan_wizard)
       end
+
+      if scan_wizard.successful?
+        scan_wizard.button_bluetooth_address
+      elsif saw_only_private_button
+        raise ButtonIsPrivateError, 'A button was found, but it is private. Press and hold the button for 7 seconds to make it public and try again.'
+      end
+    rescue Client::Shutdown
+      raise  Shutdown, 'The client has shutdown'
     end
 
     def disconnect_button(button_bluetooth_address)
-      @semaphore.synchronize do
-        client.force_disconnect(button_bluetooth_address)
-      end
+      @client.force_disconnect(button_bluetooth_address)
+    rescue Client::Shutdown
+      raise  Shutdown, 'The client has shutdown'
     end
 
-    def listen(latency_mode, *button_bluetooth_addresses)
-      @semaphore.synchronize do
-        connection_channels = []
-        button_events = []
-        broken = false
+    def listen(button_bluetooth_address_or_latency_mode, *button_bluetooth_addresses)
+      if Symbol === button_bluetooth_address_or_latency_mode
+        latency_mode = button_bluetooth_address_or_latency_mode
+      else
+        latency_mode = :normal
+        button_bluetooth_addresses.unshift button_bluetooth_address_or_latency_mode
+      end
 
-        begin
-          button_bluetooth_addresses.each do |button_bluetooth_addresses|
-            connection_channel = Client::ConnectionChannel.new(button_bluetooth_addresses, latency_mode)
+      connection_channels = []
+      queue = Queue.new
 
-            connection_channel.button_up_or_down do |click_type, latency|
-              button_events << [button_bluetooth_addresses, click_type, latency]
-            end
+      @listen_queues_semaphore.synchronize { @listen_queues << queue }
 
-            connection_channel.button_single_click_or_double_click_or_hold do |click_type, latency|
-              button_events << [button_bluetooth_addresses, click_type, latency]
-            end
+      begin
+        button_bluetooth_addresses.each do |button_bluetooth_addresses|
+          connection_channel = Client::ConnectionChannel.new(button_bluetooth_addresses, latency_mode)
 
-            connection_channel.removed do
-              broken = true
-            end
+          connection_channel.button_up_or_down do |click_type, latency|
+            queue << [:button_interaction, button_bluetooth_addresses, click_type, latency]
+          end
 
-            connection_channels << connection_channel
+          connection_channel.button_single_click_or_double_click_or_hold do |click_type, latency|
+            queue << [:button_interaction, button_bluetooth_addresses, click_type, latency]
+          end
 
-            client.add_connection_channel connection_channel
+          connection_channel.removed do
+            queue << [:connection_channel_removed, connection_channel]
           end
 
-          loop do
-            client.handle_next_event while !broken && button_events.empty?
+          connection_channels << connection_channel
 
-            button_events.each do |button_event|
-              yield *button_event
-            end
+          @client.add_connection_channel connection_channel
+        end
 
-            button_events.clear
+        loop do
+          event_type, *params = queue.pop
 
-            raise ConnectionChannelRemoved, 'A connection channel was removed' if broken
-          end
-        ensure
-          connection_channels.each do |connection_channel|
-            client.remove_connection_channel connection_channel
+          case event_type
+            when :button_interaction
+              yield *params
+            when :connection_channel_removed
+              raise ConnectionChannelRemoved, 'A connection channel was removed'
+            when :shutdown
+              raise  Shutdown, 'The client has shutdown'
           end
         end
-      end
-    end
-
-    private
-
-    def process_events_until
-      done = false
-      result = nil
+      ensure
+        connection_channels.each do |connection_channel|
+          @client.remove_connection_channel connection_channel
+        end
 
-      callback = proc do |_result|
-        done = true
-        result = _result
+        @listen_queues_semaphore.synchronize { @listen_queues.delete queue unless @listen_queues.frozen? }
       end
-
-      yield callback
-
-      client.handle_next_event until done
-
-      result
+    rescue Client::Shutdown
+      raise  Shutdown, 'The client has shutdown'
     end
   end
 end