hybridgroup-crubyflie 0.1.4

data/README.md

@@ -0,0 +1,127 @@
+Crubyflie - A Ruby client for Crazyflie
+=======================================
+
+[![Build Status](https://travis-ci.org/hsanjuan/crubyflie.png?branch=master)](https://travis-ci.org/hsanjuan/crubyflie) [![Coverage Status](https://coveralls.io/repos/hsanjuan/crubyflie/badge.png)](https://coveralls.io/r/hsanjuan/crubyflie)
+
+Crubyflie is a Ruby rewrite of the [Crazyflie quadcopter](http://www.bitcraze.se/category/crazyflie/) Python [client libraries](https://bitbucket.org/bitcraze/crazyflie-pc-client), with some customizations.
+
+The Crazyflie is awesome, but I did not know where to start contributing. Therefore I thought that rewriting the code in Ruby would be one way of knowing what is going on and how it works. Along the way I took the time to document all the code so that others can understand it and create tests.
+
+You may be also interested in some other unofficial Crazyflie clients:
+
+ * C++:     https://github.com/fairlight1337/libcflie
+ * Node.js: https://github.com/ceejbot/aerogel
+ * Haskell: https://github.com/orclev/crazyflie-haskell
+
+Disclaimer
+----------
+
+Crubyflie is in early stage of development, very untested.
+
+Features
+--------
+
+ * Crubyflie can be used to fly a Crazyflie device using a Joystick and the Crazyradio USB dongle
+ * Crubyflie exposes an API that allows to control the copter, read logging, parameters and console easily
+ * Crubyflie runs headless  
+ * Lightweight: If you just want to fly, Crubyflie consumes around 1/2 memory and 1/3 CPU compared to the original Python `cfheadless` utility.
+
+Not included...
+----------------
+ * No fancy UI.
+ * No flash utility (yet?).
+ * No idea how this works in other OSs that are not Linux, but in theory it should work in all with some small fixes. I welcome you to take on this task if you are interested.
+ * No support for Ruby <= 1.8.7 (maybe it works who knows... I haven't tested but since Crubyflie relies heavily on threading probably it does not work so good).
+
+Installation
+------------
+
+Crubyflie depends on `rubysdl`, for which you will need the SDL library and headers. Make sure you install `libsdl-dev` (Debian/Ubuntu), `libSDL-devel` (Opensuse) or whatever your distro calls it. Then:
+
+    gem install crubyflie
+
+That's all.
+
+Fyling the Crazyflie
+--------------------
+
+The easiest way to do it is to `gem install crubyflie` and then run the `crubyflie` command. This will connect to the first visible quadcopter using the first available joystick on your computer (you can modify this parameters with the appropiate flags):
+
+    > crubyflie2.0 -h
+    Options:
+      --joystick-id, -j <i>:   Joystick ID (default: 0)
+           --cf-uri, -f <s>:   Crazyflie URI (defaults to first one found in scan)
+           --config, -c <s>:   Joystick configuration, defaults to default cfg in configs/ (default:
+                               /usr/lib64/ruby/gems/2.0.0/gems/crubyflie-0.0.1/lib/crubyflie/input/../../../configs/joystick_default.yaml)
+                 --help, -h:   Show this message
+
+There is a [template/default configuration file](https://github.com/hsanjuan/crubyflie/blob/master/configs/joystick_default.yaml) with instructions (which works for me and my PS3-like controller :) ). You should modify this file to fit it to your needs (configuration parameters are commented). The most tricky parameter in axis is the `:max_change_rate`. Depending on your controller, you will find the input is excessively throotled or not. I recommend that you play with this value.
+
+If you are wondering about your Joystick's axis IDs, ranges etc, you will find a `sdl-joystick-axis.rb` script under `tools` that lets you open a joystick and check what the SDL library can read from it. It might come handy.
+
+If you need help just open an issue or contact me.
+
+Raspberry Pi
+------------
+
+If you want to use Crubyflie in your Raspberry Pi you need to:
+
+    sudo apt-get install ruby ruby-dev libsdl-dev
+    sudo gem install crubyflie
+
+This should provide everything you need to run the `crubyflie` command. Of course you might need to put your user in the `input` group and modify `udev` rules as explained in the [Crazyflie wiki](http://wiki.bitcraze.se/projects:crazyflie:hacks:rasberrypi).
+
+Using the Crazyflie API
+-----------------------
+
+While both Python and Ruby APIs expose access to params, logging, console and commander facilities, Crubyflie does it in sligthly different way.
+
+Crubyflie access to facilities is offered fully under the Crazyflie instance object, let's see it as code:
+
+```ruby
+require 'crubyflie'
+include Crubyflie
+
+# Connect
+@cf = Crazyflie.new()
+@cf.open_link(@radio_uri)
+
+# Interface to the logging facility
+@cf.log.create_log_block(...)
+@cf.log.start_logging(...) do |log_values|
+  ...
+end
+@cf.log.stop_logging(...)
+@cf.log.delete_log(...)
+
+
+# Interface to the param facility
+@cf.param.get_value(...) do |value|
+  ...
+end
+
+@cf.param.get_value(...) do |value|
+  ...
+end
+
+@cf.param.set_value(...)
+
+# Interface to the commander facility
+@cf.commander.send_setpoint(...)
+
+# Interface to the console facility
+@cf.console.read do |value|
+  ...
+end
+```
+
+That's pretty much all. As you see, instead of declaring callbacks, registering them etc. We let the user pass blocks, which are run when the data is available. 
+In Crubyflie, params are read and set synchronously, while the block passed to `start_logging()` will be called repeteadly and asynchrnously until `stop_logging()` is invoked. Console offers both synchronous `read()` and asynchronous `start_reading()` options.
+
+There are some examples in the `examples` folder. Read the gem documentation to get full information of the parameters for each function call.
+
+
+Contributing
+------------
+
+Contributions are awesome! :) I'd love some help here, so be invited to open issues, send pull requests or give me your opinion.

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+require "yard/rake/yardoc_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+    t.pattern = 'spec/crubyflie_spec.rb'
+end
+
+YARD::Rake::YardocTask.new(:yard)
+
+task :doc => :yard
+task :test => :spec
+task :default => [:spec, :doc]
+

data/bin/crubyflie

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+
+# Copyright (C) 2013 Hector Sanjuan
+
+# This file is part of Crubyflie.
+
+# Crubyflie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# Crubyflie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with Crubyflie.  If not, see <http://www.gnu.org/licenses/>
+
+require 'crubyflie'
+require 'trollop'
+
+# This script allows to fly the Crazyflie usingi the Joystick controller
+# and initializing a Crazyflie. It might need a bit of cleanup but it does
+# the job.
+
+opts = Trollop::options do
+    opt(:joystick_id, "Joystick ID",
+        :type => :int,
+        :default => 0,
+        :short => '-j')
+    opt(:cf_uri, "Crazyflie URI (defaults to first one found in scan)",
+        :type => :string,
+        :short => '-f')
+    opt(:config, "Joystick configuration, defaults to default cfg in configs/",
+        :type => :string,
+        :default => Crubyflie::Joystick::DEFAULT_CONFIG_PATH,
+        :short => '-c')
+    opt(:debug, "Enable debug messages",
+        :short => '-d')
+end
+
+include Crubyflie
+$debug = true if opts[:debug]
+
+cf = Crazyflie.new('/tmp/crubyflie')
+
+# Before opening any link, scan for interfaces
+uris = cf.scan_interface
+if uris.empty?
+    logger.error("No crazyflies found")
+    exit 1
+end
+logger.info("Found copters at: #{uris}")
+if uri = opts[:cf_uri] && !uris.include?(opts[:cf_uri])
+    logger.error("Provided URI not found")
+    exit 1
+end
+
+uri ||= uris.first
+
+# Open a link to the copter
+cf.open_link(uri)
+# Make sure everything is still good
+exit 1 if !cf.active?
+
+# Initialize the joystick - ID defaults to 0
+joystick = Joystick.new(opts[:config], opts[:joystick_id])
+joystick.init()
+
+exit = false
+Signal.trap("SIGINT") do
+    exit = true
+end
+
+logger.info("Cleared for take-off!")
+
+while cf.active? && !exit do
+    start_time = Time.now.to_f
+    joystick.read_input()
+    joystick.apply_input(cf)
+    # We should be good sending 10 ticks per second,
+    # as it says that somewhere in the docs, so we have
+    # 1/10 secs of time per loop. If we are fast, we can sleep
+    # a little bit
+    consumed_time = Time.now.to_f - start_time
+    sleep_time = 0.1 - consumed_time
+    sleep sleep_time if sleep_time > 0
+end
+
+joystick.quit()
+cf.close_link()
+warn "\n"
+logger.info("Bye bye!")

data/configs/joystick_default.yaml

@@ -0,0 +1,106 @@
+# Default joystick configuration file. A file looks like:
+# --------------------------------------------------------------------------
+# :type: Joystick
+# :axis:
+#   <axis_id>:
+#     :action: <action>
+#     :description: A short description to remember what this is
+#     :input_range: "<start>:<end>"
+#                   The range read from the joystick.
+#                   Defaults to -32768:32767 which is SDL-dependant
+#
+#     :output_range: "<start>:<end>"
+#                    The values we should yield to
+#                    the Crazyflie, normally degrees (roll, pitch...). For
+#                    thrust it is expressed in % of thrust
+#
+#     :max_change_rate: <number>
+#                       The output_range change rate per second. Must
+#                       e a number. Defaults to 10000 (so a lot). For thrust
+#                       it is expressed in % of thrust
+#     :dead_zone: "<start>:<end>"
+#                 The dead range around 0. Defaults to 0:0
+#
+#     :invert: true|false  - Invert this axis
+#
+#     :calibration: <number>
+#                   This value is added to the raw joystick reading
+#
+#   <axis_id2>: ...
+#
+# :buttons:
+#   <button_id>:
+#     :action: <action>
+#     :value: <value when pressed>
+#             A number, optional, defaults to 1.
+#
+#   <button_id2>: ...
+#
+# --------------------------------------------------------------------------
+# Valid actions:
+# :roll - Controls roll. Assignable a axis or a button with value tag.
+# :pitch - Controls pitch. Assignable a axis or a button with value tag.
+# :thrust - Controls thrust. Assignable a axis or a button with value tag.
+# :yaw - Controls yaw. Assignable a axis or a button with value tag.
+# :switch_xmode - Enables/disables xmode. Assignable to a button.
+# :close_link - Kills the link and shuts Crubyflie. Assignable to a button.
+# :switch_scaled_output_mode - Enables/disabled scaled output mode. Assignable
+#                              to a button with value tag (the multiplier)
+# :roll_inc_cal, :roll_dec_cal - Increase/decrease calibration for :roll axis.
+#                                Assignable to a button with optional value.
+#
+# :pitch_inc_cal, :pitch_dec_cal - Increase/decrease calibration for :pitch
+#                                  axis. Assignable to a button with optional
+#                                  value.
+# ---------------------------------------------------------------------------
+:type: "Joystick"
+:axis:
+  0:
+    :description: "Roll Axis"
+    :action: :roll
+    :input_range: "-32768:32767" # Optional - SDL dependant. Defaults to this.
+    :output_range: "-30:30" # Min/Max crazyflie angle in degrees.
+    :max_change_rate: 600 # Max angle change rate per second. Optional
+    :dead_zone: "-100:100" # Deadzone, within input range
+    :invert: false # Invert the axis
+    :calibration: 0 # This value is added to the raw value read from joystick
+  1:
+    :description: "Pitch Axis"
+    :action: :pitch
+    :input_range: "-32768:32767"
+    :output_range: "-30:30"
+    :max_change_rate: 600
+    :dead_zone: "-100:100"
+    :invert: true
+    :calibration: 0
+  2:
+    :description: "Yaw Axis"
+    :action: :yaw
+    :input_range: "-32768:32767"
+    :output_range: "-150:150"
+    :max_change_rate: 800
+    :dead_zone: "-1000:1000"
+    :invert: false
+    :calibration: 0
+  3:
+    :description: "Thrust axis"
+    :action: :thrust
+    :input_range: "-32768:32767"
+    # Exception: Min/max thrust output is represented in 0-100%!
+    :output_range: "0:80"
+    # Max change rate per second when lowering thrust in % of thrust
+    :max_change_rate: 70
+    :dead_zone: "-100:100"
+    :invert: true
+    :calibration: 0
+
+:buttons:
+  0:
+    :action: :switch_xmode
+  1:
+    :action: :close_link
+  4:
+    # When enabled, this mode will will multiply axis readings (except thrust)
+    # by the value of the button (must be a positive number)
+    :action: :switch_scaled_output_mode
+    :value: 0.50 # Softer output, useful for landing

data/crubyflie.gemspec

@@ -0,0 +1,50 @@
+# coding: utf-8
+# Copyright (C) 2013 Hector Sanjuan
+
+# This file is part of Crubyflie.
+
+# Crubyflie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# Crubyflie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with Crubyflie.  If not, see <http://www.gnu.org/licenses/>
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'crubyflie/version'
+
+Gem::Specification.new do |spec|
+    spec.name          = "hybridgroup-crubyflie"
+    spec.version       = Crubyflie::VERSION
+    spec.authors       = ["Hector Sanjuan", "Adrian Zankich"]
+    spec.email         = ["hector@convivencial.org", "adrian@hybridgroup.com"]
+    spec.description   = <<EOF
+Client library to control a Crazyflie. This library allows to talk to a
+crazyflie using the USB radio dongle.
+EOF
+    spec.summary       = "A Ruby client for the Crazyflie quadcopter"
+    spec.homepage      = "https://github.com/hybridgroup/crubyflie"
+    spec.license       = "GPLv3"
+
+    spec.files         = `git ls-files`.split($/)
+    spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+    spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+    spec.require_paths = ["lib"]
+
+    spec.add_dependency "libusb"
+    spec.add_dependency "trollop"
+
+    spec.add_development_dependency "bundler", "~> 1.3"
+    spec.add_development_dependency "rake"
+    spec.add_development_dependency "rspec"
+    spec.add_development_dependency "yard"
+    spec.add_development_dependency "simplecov"
+    spec.add_development_dependency "coveralls"
+end

data/examples/params_and_logging.rb

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+# Copyright (C) 2013 Hector Sanjuan
+
+# This file is part of Crubyflie.
+
+# Crubyflie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# Crubyflie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with Crubyflie.  If not, see <http://www.gnu.org/licenses/>
+
+# Require the Crubyflie gem
+require 'crubyflie'
+include Crubyflie # easy to use things in namespace
+
+# Create a new Crazyflie with cache folder "cache"
+cf = Crazyflie.new('cache')
+# Before opening any link, scan for interfaces
+ifaces = cf.scan_interface
+if ifaces.empty?
+    logger.error("No crazyflies found")
+    exit 1
+end
+logger.info("Found interfaces: #{ifaces}")
+
+# Open a link to the first interface
+cf.open_link(ifaces.first)
+# Make sure everything is still good
+exit 1 if !cf.active?
+
+# Write the TOCs to stdout
+puts "Log TOC"
+puts cf.log.toc.to_s
+puts
+puts "Param TOC"
+puts cf.param.toc.to_s
+
+# Read some parameters
+puts "--------"
+cf.param.get_value("attitudepid.kp_pitch") do |value|
+    puts "kp_pitch: #{value}"
+end
+cf.param.get_value("attitudepid.ki_pitch") do |value|
+    puts "ki_pitch: #{value}"
+end
+cf.param.get_value("attitudepid.kd_pitch") do |value|
+    puts "kd_pitch: #{value}"
+end
+puts "--------"
+
+
+# We use 1 variable, is_toc = true
+# The last two 7 means it is stored and fetched as float
+log_conf_var = LogConfVariable.new("stabilizer.pitch", true, 7, 7)
+
+# We create a configuration object
+# We want to fetch it every 0.1 secs
+log_conf = LogConf.new([log_conf_var], {:period => 10})
+
+# With the configuration object, register a log_block
+block_id = cf.log.create_log_block(log_conf)
+
+# Start logging
+# Counter on how many times we have logged the pitch
+logged = 0
+cf.log.start_logging(block_id) do |data|
+    warn "Pitch: #{data['stabilizer.pitch']}"
+    logged += 1
+end
+
+# Wait until we have hit the log_cb 10 times
+while (logged < 10)
+    sleep 1
+end
+
+# Stop logging
+cf.log.stop_logging(block_id)
+
+# After finishing, close the link!
+cf.close_link()

data/lib/crubyflie/crazyflie/commander.rb

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2013 Hector Sanjuan
+
+# This file is part of Crubyflie.
+
+# Crubyflie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# Crubyflie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with Crubyflie.  If not, see <http://www.gnu.org/licenses/>
+
+module Crubyflie
+    # The Commander facility is used to send control information to the
+    # Crazyflie. You want to use this class to fly your Crazyflie
+    class Commander
+        # Initialize the facility
+        def initialize(crazyflie)
+            @crazyflie = crazyflie
+        end
+
+        # Send a setpoint to the Crazyflie
+        #
+        # The roll, pitch, yaw values are floats with positive or negative
+        # values. The range should be the value read from the controller
+        # ([-1,1]) multiplied by the maximum angle change rate
+        # @param roll [float] the roll value
+        # @param pitch [float] the pitch value
+        # @param yaw [float] the yaw value
+        # @param thrust [Integer] thrust is an integer value ranging
+        #                         from 10001 (next to no power) to
+        #                         60000 (full power)
+        def send_setpoint(roll, pitch, yaw, thrust, xmode=false)
+            if xmode
+                roll = 0.707 * (roll - pitch)
+                pitch = 0.707 * (roll + pitch)
+            end
+
+            packet = CRTPPacket.new()
+            packet.modify_header(nil, Crazyflie::CRTP_PORTS[:commander], nil)
+            data = [roll, -pitch, yaw, thrust]
+            # send 3 floats and one unsigned short (16 bits) (all little endian)
+            data = data.pack('eeeS<')
+            packet.data = data.unpack('C*')
+            @crazyflie.send_packet(packet, false)
+        end
+    end
+end

data/lib/crubyflie/crazyflie/console.rb

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2013 Hector Sanjuan
+
+# This file is part of Crubyflie.
+
+# Crubyflie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# Crubyflie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with Crubyflie.  If not, see <http://www.gnu.org/licenses/>
+
+
+module Crubyflie
+    # The Console facility is used to read characters that have been
+    # printer using printf in the crazyflie firmware
+    class Console
+
+        # Initialize the console
+        # @param crazyflie [Crazyflie]
+        def initialize(crazyflie)
+            @crazyflie = crazyflie
+            @in_queue = crazyflie.crtp_queues[:console]
+            @read_thread = nil
+        end
+
+        # Reads all the characters from the Crazyflie that are queued, until
+        # the queue is empty, and then return only after executing the 
+        # given block for each packet that was in the queue.
+        # @param block [Proc] a block to call with the read information
+        def read(&block)
+            while @in_queue.size > 0 do
+                packet = @in_queue.pop() # block
+                yield(packet.data_repack) if block_given?
+            end
+        end
+
+
+        # Reads all the characters from the Crazyflie constantly
+        # and yields on the the given block is called with the payload.
+        # This call will return immediately, but the block will be
+        # called asynchronously until #stop_reading() is called.
+        # Use stop_read() to stop.
+        # @param block [Proc] a block to call with the read information
+        def start_reading(&block)
+            stop_reading()
+            @read_thread = Thread.new do
+                loop do
+                    read(&block)
+                    sleep 0.3 # no hurries?
+                end
+            end
+        end
+
+        # Stops reading characters from the Crazyflie
+        def stop_reading
+            @read_thread.kill() if @read_thread
+            @read_thread = nil
+        end
+    end
+end