crazyflie-zmq 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d66cb857aef6754e059f95c041f710ae4962788cca2cc04295d3c08918d0dc2
-  data.tar.gz: b95bc3c3e7bde75285b918944e1595656201870b4517766d412d7ff86c53b567
+  metadata.gz: 72ac0134ded573f08008637f80c872a6a034de84016efc57c9195245d51be191
+  data.tar.gz: 1559e33582d8abf856f93e75b6e57510877e3eab544a710e4de6b28b1f3e22c5
 SHA512:
-  metadata.gz: fe7570047d818b80e8ffe0d0cfc2638f2bb5af8fce34074a2486c25f61ce1497060928a50ad8c44c910f4447d4e9367c0bf1a598155637e15fc5e78f0622e75f
-  data.tar.gz: d87c4ca1f8aedf65c22c3dd631e5c18df4dbb25a6b6b675a9b5ce3b0e4353420c36e3c4073f10aa724265dfa8f2b86dd4f4c0254213ba8bdfe9453b9f2e9545f
+  metadata.gz: 8892dd565405dba9078ad8961bb602b9fcf1f84dda6b4b03f8c7c386b2a79700ac4e3ad641b290563a2852ade6467a42f78704d7b4964083f26e5b8a01ec3f22
+  data.tar.gz: 11fdc478146ab16903c9eacf58905a0b51fae8860612bd7a1da3fb9ecd8543cf235a80b734cd2fcdbc3f4d0c091d8d31cb718a1fe35ebd0030ee930297655cac

data/crazyflie-zmq.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency "yard"
   s.add_development_dependency "rake"
+  s.add_development_dependency "redcarpet"
 
   s.has_rdoc      = 'yard'
 

data/lib/crazyflie-zmq.rb

@@ -1,19 +1,46 @@
+# coding: utf-8
+
 require 'thread'
 require 'json'
 require 'csv'
 require 'ffi-rzmq'
 
+
+# Allow control of a {https://www.bitcraze.io/crazyflie-2/ Crazyflie}
+# drone using the ZMQ protocol.
+#
+# To use this you need to have a ZMQ server running, it is started
+# using the crazyflie python clients API
+# ({https://github.com/bitcraze/crazyflie-clients-python/
+# crazyflie-clients-python}):
+#
+#   crazyflie-clients-python/bin/cfzmq --url tcp://* -d
+#
+# @see https://wiki.bitcraze.io/doc:crazyflie:client:cfzmq:index
+# @see https://wiki.bitcraze.io/doc:crazyflie:dev:arch:logparam
+# @see https://wiki.bitcraze.io/projects:crazyflie:firmware:comm_protocol
+# @see https://wiki.bitcraze.io/doc:crazyflie:crtp:log
 class CrazyflieZMQ
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"  # CrazyflieZMQ version
 
+    # Standard error for {CrazyflieZMQ}
     class Error        < StandardError ; end
+
+    # Error related to ZMQ protocol
     class ZMQError     < Error         ; end
+
+    # Error generated when trying to communicate with a crazyflie
+    # and the connection is not active
     class NotConnected < Error         ; end
+
+    # Error while communicating with the crazyflie
     class RequestError < Error         ; end
 
 
-    attr_reader :connected
-    
+
+    # Create a CrazyflieZMQ instance
+    #
+    # @param url [String] the url to connect to the ZMQ socket
     def initialize(url, log: nil)
         @url          = url
         @log_cb       = log
@@ -77,13 +104,17 @@ class CrazyflieZMQ
     end
 
     
-
+    # Returns the list of available crazyflie
     def scan()
         _request(cmd: :scan)
     end
 
 
-    
+    # Establish a connection with a crazyflie
+    #
+    # @param uri [String] crazyflie URI
+    # @param log_blocks [Hash{Symbol=>Hash}] predefined log blocks
+    # @return [self]
     def connect(uri, log_blocks: nil)
         toc = _request(cmd: :connect, uri: uri)
         @param     = toc['param'] || {}
@@ -107,6 +138,9 @@ class CrazyflieZMQ
         self
     end
 
+    # Disconnect from the crazyflie
+    #
+    # @return [self]
     def disconnect()
         @log_blocks&.each_key {|key| self.log_delete(key) }
         _request(cmd: :disconnect)
@@ -114,22 +148,51 @@ class CrazyflieZMQ
         self
     end
 
+    # Are we connected to the crazyflie
+    #
+    # @return [Boolean] connection status
     def is_connected?
         !@connected.nil?
     end
 
+    # Ensure we are in a connect state
+    #
+    # @raise [NotConnected] if not connected to a crazyflie
+    # @return [self] 
     def is_connected!
         raise NotConnected unless is_connected?
+        self
     end
        
-
-
+    
+    # Create a log block
+    # @note logging is usually done through the crazyflie radio link
+    #       so you are limited in the number of variable that you
+    #       can log at the same time as well as the minimal logging
+    #       period that you can use
+    #
+    # @param name [Symbole,String] log block name
+    # @param variables [Array<String>] name of the variable to logs
+    # @param period [Integer] milliseconds between consecutive logs
+    # @return  [self]
     def log_create(name, *variables, period: 1000)
         _request(cmd: :log, action: :create, name: name,
                  variables: variables, period: period)
         self
     end
 
+
+    # Start logging information
+    #
+    # It is possible to automatically create a log file using the `file`
+    # parameter, in this case you can specify the file name to use for logging
+    # (must end in .csv as for now only CSV format is supported), or you
+    # can use :csv and a filename will be generated using timestamp and counter
+    #
+    # @param name [Symbol, String]    name of the log block to start
+    # @param file [String, :csv, nil] name or type of file where to automatically log data
+    # @param block                    block called on each new log
+    # @return [self]
     def log_start(name, file: nil, &block)
         count = (@log_count[name] || 0) + 1
 
@@ -170,7 +233,11 @@ class CrazyflieZMQ
         @log_count[name] = count
         self
     end
-   
+
+    
+    # Stop logging of the specified log block
+    # @param name [Symbol,String] name of the log block 
+    # @return [self]
     def log_stop(name)
         _request(cmd: :log, action: :stop,   name: name)
         @log_data_cb.delete(name)
@@ -178,17 +245,38 @@ class CrazyflieZMQ
         self
     end
 
+    # Delete a registerd log block
+    # @param name [Symbol,String] name of the log block
+    # @return [self]
     def log_delete(name)
         _request(cmd: :log, action: :delete, name: name)
         self
     end
 
+
+    # Assign a parameter value to the crazyflie
+    #
+    # If a parameter group is not specified it is possible
+    # to use a +.+ in the parameter name to indicate it:
+    # +"group.name"+
+    #
+    # @param group [String,nil] group on which the parameter belongs
+    # @param name  [String]     parameter name
+    # @param value 
     def []=(group=nil, name, value)
         name = [ group, name ].join('.') if group
         _request(cmd: :param, name: name, value: value)
         value
     end
 
+    # Get a parameter value from the crazyflie
+    #
+    # If a parameter group is not specified it is possible
+    # to use a +'.'+ in the parameter name to indicate it:
+    # +"group.name"+
+    #
+    # @param group [String,nil] group on which the parameter belongs
+    # @param name  [String]     parameter name
     def [](group=nil, name)
         group, name = name.split('.', 2) if group.nil?
         @param.dig(group, name, 'value')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crazyflie-zmq
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Stephane D'Alu
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - stephane.dalu@insa-lyon.fr