crubyflie 0.1.0

data/README.md

@@ -0,0 +1,99 @@
+Crubyflie - A Ruby client and libraries for Crazyflie
+=====================================================
+
+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.
+
+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
+
+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).
+
+Fyling the Crazyflie
+--------------------
+
+The easiest way to do it is to 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
+
+A template/default configuration file (which works for me and my PS3-like controller :)) is provided with the gem (in the `configs/` folder). 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.
+
+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,85 @@
+#!/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')
+  end
+
+include Crubyflie
+# Uncomment to turn on debugging
+# $debug = true
+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
+
+while cf.active? && !exit do
+    # We should be good sending 10 ticks per second
+    # it says that somewhere in the docs
+    joystick.read_input()
+    joystick.apply_input(cf)
+    sleep 0.1
+end
+
+joystick.quit()
+cf.close_link()
+warn "\n"
+logger.info("Bye bye!")

data/configs/joystick_default.yaml

@@ -0,0 +1,48 @@
+# Default joystick configuration file. It mimics the PS3_Mode2 original
+# configuration file
+: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: "-200:200"
+    :max_change_rate: 800
+    :dead_zone: "-1000:1000"
+    :invert: false
+    :calibration: 0
+  3:
+    :description: "Thrust axis"
+    :action: :thrust
+    :input_range: "-32768:32767"
+    :output_range: "0:80" # Exception: Min/max thrust output is represented in 0-100%!
+    # Max change rate per second when lowering thrust. Note that this
+    # is a change ranging between ranges 9500 and 60000
+    :max_change_rate: 40000
+    :dead_zone: "-100:100" # Deadzone, within input range
+    :invert: true
+    :calibration: 0
+
+:buttons:
+  0:
+    :action: :switch_xmode
+  1:
+    :action: :close_link

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          = "crubyflie"
+    spec.version       = Crubyflie::VERSION
+    spec.authors       = ["Hector Sanjuan"]
+    spec.email         = ["hector@convivencial.org"]
+    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       = "Crazyflie ruby client"
+    spec.homepage      = "https://github.com/hsanjuan/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 "rubysdl"
+    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"
+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