turtleshell 1.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0020ab1903bd5ebd8bf3338fbf008ed6c8496411
+  data.tar.gz: 1243d95e4ae08009ff350e827fd03876d1f93a93
+SHA512:
+  metadata.gz: 7ff72851c7c4aac05e27ae19a2ae84872d454e9342565a63c084449b87b2d0cf0f8f53ffe7e9ff5c380fd364616bf67f069ab9109e965f74b156723849f47df0
+  data.tar.gz: c2ebcfd7eb0001075f1645f87e2a16e5c0a2952a738c1dcd2b2cc175223ade07feefd047d8be95d7774fa420285c3f2bd89227a0ea08e7c7ed37a3b27f21b49e

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+**/*.bundle
+**/*.o
+tmp
+Gemfile.lock
+.rvmrc

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+### 1.0.0 (2013-12-28)
+
+* Added sample rate, gain, center frequency getters / setters
+* Added `read_samples` method to read syncronously from the device
+* Added `read_samples_async` to read asyncronously

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'rake-compiler'
+
+group :development do
+  gem 'rspec'
+  gem 'pry'
+  gem 'pry-nav'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Tim Jarratt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,46 @@
+[![Build Status](https://travis-ci.org/tjarratt/turtleshell.png)](https://travis-ci.org/tjarratt/turtleshell) turRTLshell
+============
+
+Overview
+--------
+Turtleshell is a ruby wrapper around librtlsdr, a C library for interfacing with Realtek RTL2832 DVB USB devices. More information about librtlsdr can be found [on their website](http://sdr.osmocom.org/trac/wiki/rtl-sdr).
+
+Usage
+-----
+Turtleshell is available on rubygems. You can install it with `gem install turtleshell` or by adding it to your `Gemfile`.
+
+Most of the key functions in librtlsdr are available, more will be added as development continues.
+
+Examples
+--------
+Getting a reference to a device and reading from it could not be easier
+```ruby
+require 'turtleshell'
+sdr = TurtleShell::Device.new
+
+# configure device properties
+sdr.sample_rate = 2.4e6
+sdr.center_frequency = 100e6
+sdr.gain = 10
+
+# read samples from the device
+samples = sdr.read_samples
+puts "signal mean:   #{samples.inject(:+)/samples.length}"
+```
+
+More examples are available in the [examples directory](https://github.com/tjarratt/turtleshell/tree/master/examples).
+
+Dependencies
+------------
+* ruby (version 1.9.2 or later)
+* librtlsdr
+
+License
+-------
+Turtleshell is released under the permissive MIT license.
+
+Credit
+------
+The idea for this project came to me when I was watching [@0xabad1dea's](https://github.com/0xabad1dea) talk at Defcon 21. Without that initial idea and inspiration, this wouldn't exist!
+
+Credit is due to [@roger-](https://github.com/roger-) for writing pyrtlsdr, which provided a great reference when working on Turtleshell.

data/Rakefile

@@ -0,0 +1,25 @@
+require 'bundler/setup'
+require 'rspec/core/rake_task'
+require 'rake/extensiontask'
+
+task :default => 'compile:librtlsdr'
+task :default => :spec
+task :spec    => 'spec:progress'
+
+Rake::ExtensionTask.new(:librtlsdr) do |ext|
+  ext.lib_dir = "lib/librtlsdr"
+end
+
+namespace :spec do
+  desc 'Run all specs in spec directory (format=progress)'
+  RSpec::Core::RakeTask.new(:progress) do |t|
+    t.pattern = 'spec/**/*_spec.rb'
+    t.rspec_opts = %w{ --color --format=progress }
+  end
+
+  desc 'Run all specs in spec directory (format=documentation)'
+  RSpec::Core::RakeTask.new(:documentation) do |t|
+    t.pattern = 'spec/**/*_spec.rb'
+    t.rspec_opts = %w{ --color --format=documentation }
+  end
+end

data/examples/async_read_from_device.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+lib = File.expand_path('../../lib', __FILE__)
+$:.unshift lib unless $:.include? lib
+
+require 'turtleshell'
+
+begin
+  sdr = TurtleShell::Device.new
+rescue TurtleShell::DeviceNotFoundError
+  puts 'No compatible devices found. bailing!'
+  exit 1
+end
+
+
+sdr.sample_rate = 2.4e6
+sdr.center_frequency = 100e6
+sdr.gain = 8
+
+count = 0
+puts "\n\nTesting async callbacks..."
+sdr.read_samples_async(512) do |buffer|
+  count += 1
+  puts "\t in async callback with buffer of length #{buffer.length}"
+  puts "\t signal mean:   #{buffer.inject(:+)/buffer.length}"
+
+  count == 3 # exit when this has been called three times
+end
+
+sdr.close_device

data/examples/listing_devices.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+lib = File.expand_path('../../lib', __FILE__)
+$:.unshift lib unless $:.include? lib
+
+require 'turtleshell'
+
+puts "Found #{TurtleShell.count_of_devices} devices connected"
+
+TurtleShell.all_devices.each_with_index do |device_name, index|
+  puts "#{index} : #{device_name}"
+end

data/examples/simple_read_from_device.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+lib = File.expand_path('../../lib', __FILE__)
+$:.unshift lib unless $:.include? lib
+
+require 'turtleshell'
+
+begin
+  sdr = TurtleShell::Device.new
+rescue TurtleShell::DeviceNotFoundError
+  puts 'No compatible devices found. bailing!'
+  exit 1
+end
+
+puts "\n\nConfiguring SDR device\n"
+
+sdr.sample_rate = 2.4e6
+sdr.center_frequency = 100e6
+sdr.gain = 10
+
+puts "\t sample rate:       #{sdr.sample_rate / 1e6} MHz"
+puts "\t center frequency:  #{sdr.center_frequency / 1e6} MHz"
+puts "\t gain:              #{sdr.gain} dB"
+
+puts "\n\n"
+puts "Reading Samples..."
+samples = sdr.read_samples(1024)
+print "\t signal mean:   #{samples.inject(:+)/samples.length}"
+
+sdr.close_device

data/ext/librtlsdr/Makefile

@@ -0,0 +1,217 @@
+
+SHELL = /bin/sh
+
+# V=0 quiet, V=1 verbose.  other values don't work.
+V = 0
+Q1 = $(V:1=)
+Q = $(Q1:0=@)
+n=$(NULLCMD)
+ECHO1 = $(V:1=@$n)
+ECHO = $(ECHO1:0=@echo)
+
+#### Start of system configuration section. ####
+
+srcdir = .
+topdir = /Users/tjarratt/.rvm/rubies/ruby-1.9.3-p327/include/ruby-1.9.1
+hdrdir = /Users/tjarratt/.rvm/rubies/ruby-1.9.3-p327/include/ruby-1.9.1
+arch_hdrdir = /Users/tjarratt/.rvm/rubies/ruby-1.9.3-p327/include/ruby-1.9.1/$(arch)
+VPATH = $(srcdir):$(arch_hdrdir)/ruby:$(hdrdir)/ruby
+prefix = $(DESTDIR)/Users/tjarratt/.rvm/rubies/ruby-1.9.3-p327
+rubylibprefix = $(libdir)/$(RUBY_BASE_NAME)
+exec_prefix = $(prefix)
+vendorhdrdir = $(rubyhdrdir)/vendor_ruby
+sitehdrdir = $(rubyhdrdir)/site_ruby
+rubyhdrdir = $(includedir)/$(RUBY_BASE_NAME)-$(ruby_version)
+vendordir = $(rubylibprefix)/vendor_ruby
+sitedir = $(rubylibprefix)/site_ruby
+ridir = $(datarootdir)/$(RI_BASE_NAME)
+mandir = $(datarootdir)/man
+localedir = $(datarootdir)/locale
+libdir = $(exec_prefix)/lib
+psdir = $(docdir)
+pdfdir = $(docdir)
+dvidir = $(docdir)
+htmldir = $(docdir)
+infodir = $(datarootdir)/info
+docdir = $(datarootdir)/doc/$(PACKAGE)
+oldincludedir = $(DESTDIR)/usr/include
+includedir = $(prefix)/include
+localstatedir = $(prefix)/var
+sharedstatedir = $(prefix)/com
+sysconfdir = $(DESTDIR)/etc
+datadir = $(datarootdir)
+datarootdir = $(prefix)/share
+libexecdir = $(exec_prefix)/libexec
+sbindir = $(exec_prefix)/sbin
+bindir = $(exec_prefix)/bin
+rubylibdir = $(rubylibprefix)/$(ruby_version)
+archdir = $(rubylibdir)/$(arch)
+sitelibdir = $(sitedir)/$(ruby_version)
+sitearchdir = $(sitelibdir)/$(sitearch)
+vendorlibdir = $(vendordir)/$(ruby_version)
+vendorarchdir = $(vendorlibdir)/$(sitearch)
+
+NULLCMD = :
+
+CC = /usr/bin/gcc-4.2
+CXX = g++
+LIBRUBY = $(LIBRUBY_A)
+LIBRUBY_A = lib$(RUBY_SO_NAME)-static.a
+LIBRUBYARG_SHARED = 
+LIBRUBYARG_STATIC = -l$(RUBY_SO_NAME)-static
+empty =
+OUTFLAG = -o $(empty)
+COUTFLAG = -o $(empty)
+
+RUBY_EXTCONF_H = 
+cflags   =  $(optflags) $(debugflags) $(warnflags)
+optflags = -O3
+debugflags = -ggdb
+warnflags = -Wall -Wextra -Wno-unused-parameter -Wno-parentheses -Wno-long-long -Wno-missing-field-initializers -Wpointer-arith -Wwrite-strings -Wdeclaration-after-statement -Wshorten-64-to-32 -Wimplicit-function-declaration
+CFLAGS   = -fno-common -I/Users/mpapis/.sm/pkg/active/include -pipe $(ARCH_FLAG)
+INCFLAGS = -I. -I$(arch_hdrdir) -I$(hdrdir)/ruby/backward -I$(hdrdir) -I$(srcdir)
+DEFS     = 
+CPPFLAGS =  -D_XOPEN_SOURCE -D_DARWIN_C_SOURCE $(DEFS) $(cppflags)
+CXXFLAGS = $(CFLAGS) $(cxxflags)
+ldflags  = -L. -Bstatic -L/Users/mpapis/.sm/pkg/active/lib
+dldflags = -Wl,-undefined,dynamic_lookup -Wl,-multiply_defined,suppress -Wl,-flat_namespace
+ARCH_FLAG =  -arch x86_64
+DLDFLAGS = $(ldflags) $(dldflags) $(ARCH_FLAG)
+LDSHARED = $(CC) -dynamic -bundle
+LDSHAREDXX = $(CXX) -dynamic -bundle
+AR = ar
+EXEEXT = 
+
+RUBY_BASE_NAME = ruby
+RUBY_INSTALL_NAME = ruby
+RUBY_SO_NAME = ruby
+arch = x86_64-darwin12.2.0
+sitearch = $(arch)
+ruby_version = 1.9.1
+ruby = /Users/tjarratt/.rvm/rubies/ruby-1.9.3-p327/bin/ruby
+RUBY = $(ruby)
+RM = rm -f
+RM_RF = $(RUBY) -run -e rm -- -rf
+RMDIRS = rmdir -p
+MAKEDIRS = mkdir -p
+INSTALL = /usr/bin/install -c
+INSTALL_PROG = $(INSTALL) -m 0755
+INSTALL_DATA = $(INSTALL) -m 644
+COPY = cp
+TOUCH = exit >
+
+#### End of system configuration section. ####
+
+preload = 
+
+libpath = . $(libdir)
+LIBPATH =  -L. -L$(libdir)
+DEFFILE = 
+
+CLEANFILES = mkmf.log
+DISTCLEANFILES = 
+DISTCLEANDIRS = 
+
+extout = 
+extout_prefix = 
+target_prefix = 
+LOCAL_LIBS = 
+LIBS =   -lpthread -ldl -lobjc 
+SRCS = librtlsdr.c
+OBJS = librtlsdr.o
+TARGET = librtlsdr
+DLLIB = $(TARGET).bundle
+EXTSTATIC = 
+STATIC_LIB = 
+
+BINDIR        = $(bindir)
+RUBYCOMMONDIR = $(sitedir)$(target_prefix)
+RUBYLIBDIR    = $(sitelibdir)$(target_prefix)
+RUBYARCHDIR   = $(sitearchdir)$(target_prefix)
+HDRDIR        = $(rubyhdrdir)/ruby$(target_prefix)
+ARCHHDRDIR    = $(rubyhdrdir)/$(arch)/ruby$(target_prefix)
+
+TARGET_SO     = $(DLLIB)
+CLEANLIBS     = $(TARGET).bundle 
+CLEANOBJS     = *.o  *.bak
+
+all:    $(DLLIB)
+static: $(STATIC_LIB)
+.PHONY: all install static install-so install-rb
+.PHONY: clean clean-so clean-rb
+
+clean-rb-default::
+clean-rb::
+clean-so::
+clean: clean-so clean-rb-default clean-rb
+		@-$(RM) $(CLEANLIBS) $(CLEANOBJS) $(CLEANFILES)
+
+distclean-rb-default::
+distclean-rb::
+distclean-so::
+distclean: clean distclean-so distclean-rb-default distclean-rb
+		@-$(RM) Makefile $(RUBY_EXTCONF_H) conftest.* mkmf.log
+		@-$(RM) core ruby$(EXEEXT) *~ $(DISTCLEANFILES)
+		@-$(RMDIRS) $(DISTCLEANDIRS) 2> /dev/null || true
+
+realclean: distclean
+install: install-so install-rb
+
+install-so: $(RUBYARCHDIR)/$(DLLIB)
+$(RUBYARCHDIR)/$(DLLIB): $(DLLIB)
+	-$(Q)$(MAKEDIRS) $(@D)
+	$(INSTALL_PROG) $(DLLIB) $(@D)
+clean-static::
+	-$(Q)$(RM) $(STATIC_LIB)
+install-rb: pre-install-rb install-rb-default
+install-rb-default: pre-install-rb-default
+pre-install-rb: Makefile
+pre-install-rb-default: Makefile
+pre-install-rb-default:
+	$(ECHO) installing default librtlsdr libraries
+./.RUBYARCHDIR.time:
+	$(Q) $(MAKEDIRS) $(RUBYARCHDIR)
+	$(Q) $(TOUCH) $@
+
+site-install: site-install-so site-install-rb
+site-install-so: install-so
+site-install-rb: install-rb
+
+.SUFFIXES: .c .m .cc .mm .cxx .cpp .C .o
+
+.cc.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
+
+.mm.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
+
+.cxx.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
+
+.cpp.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
+
+.C.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CXX) $(INCFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(COUTFLAG)$@ -c $<
+
+.c.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $<
+
+.m.o:
+	$(ECHO) compiling $(<)
+	$(Q) $(CC) $(INCFLAGS) $(CPPFLAGS) $(CFLAGS) $(COUTFLAG)$@ -c $<
+
+$(DLLIB): $(OBJS) Makefile
+	$(ECHO) linking shared-object $(DLLIB)
+	-$(Q)$(RM) $(@)
+	$(Q) $(LDSHARED) -o $@ $(OBJS) $(LIBPATH) $(DLDFLAGS) $(LOCAL_LIBS) $(LIBS)
+
+
+
+$(OBJS): $(hdrdir)/ruby.h $(hdrdir)/ruby/defines.h $(arch_hdrdir)/ruby/config.h

data/ext/librtlsdr/extconf.rb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+require 'mkmf'
+
+have_library('rtlsdr')
+extension_name = 'librtlsdr'
+
+dir_config('librtlsdr')
+create_makefile('librtlsdr/librtlsdr')

data/ext/librtlsdr/librtlsdr.c

@@ -0,0 +1,233 @@
+#include "ruby.h"
+#include "rtl-sdr.h"
+
+VALUE m_turtleshell = Qnil;
+VALUE c_device;
+static VALUE m_rtlsdr;
+
+static VALUE turtleshell_count() {
+  return INT2NUM(rtlsdr_get_device_count());
+}
+
+static VALUE turtleshell_first_device() {
+  rtlsdr_dev_t *device = NULL;
+  VALUE wrapped_device;
+  VALUE hash;
+  int count = rtlsdr_get_device_count();
+
+  // ensure we have at least one device
+  if (!count) { return Qnil; }
+
+  rtlsdr_open(&device, 0);
+  wrapped_device = Data_Wrap_Struct(c_device, NULL, NULL, device);
+
+  hash = rb_hash_new();
+  rb_hash_aset(hash, rb_str_new2("name"), rb_str_new2(rtlsdr_get_device_name(0)));
+  rb_hash_aset(hash, rb_str_new2("device_handle"), wrapped_device);
+
+  return hash;
+}
+
+static VALUE turtleshell_all_devices() {
+  int i, count;
+  VALUE devices_array = rb_ary_new();
+  count = rtlsdr_get_device_count();
+
+  for (i = 0; i < count; ++i) {
+    rb_ary_push(devices_array, rb_str_new2(rtlsdr_get_device_name(i)));
+  }
+
+  return devices_array;
+}
+
+static VALUE turtleshell_nth_device(VALUE self, VALUE n) {
+  int open_success;
+  uint32_t int_n = NUM2UINT(n);
+  rtlsdr_dev_t *device = NULL;
+  VALUE wrapped_device, hash = rb_hash_new();
+  uint32_t device_count = (uint32_t)rtlsdr_get_device_count();
+
+  if (int_n >= device_count) { return Qnil; }
+
+  open_success = rtlsdr_open(&device, int_n);
+  if (open_success != 0) {
+    return Qnil;
+  }
+
+  wrapped_device = Data_Wrap_Struct(c_device, NULL, NULL, device);
+
+  rb_hash_aset(hash, ID2SYM(rb_intern("name")), rb_str_new2(rtlsdr_get_device_name(0)));
+  rb_hash_aset(hash, ID2SYM(rb_intern("device")), wrapped_device);
+
+  return hash;
+}
+
+static VALUE turtleshell_close(VALUE self, VALUE device) {
+  rtlsdr_dev_t *dev = NULL;
+  Data_Get_Struct(device, rtlsdr_dev_t, dev);
+  rtlsdr_close(dev);
+  return Qnil;
+}
+
+static VALUE turtleshell_read_synchronous(VALUE self,
+                                          VALUE device,
+                                          VALUE bytes_to_read) {
+  int success, i;
+  int bytes_read;
+  VALUE buffer = rb_ary_new();
+  int length = NUM2INT(bytes_to_read);
+  uint8_t *p_buffer = malloc(sizeof(uint8_t) * bytes_to_read);
+  rtlsdr_dev_t *p_device;
+
+  Data_Get_Struct(device, rtlsdr_dev_t, p_device);
+
+  rtlsdr_reset_buffer(p_device);
+  success = rtlsdr_read_sync(p_device, p_buffer, length, &bytes_read);
+  if (success != 0) {
+    printf("error reading bytes. read_sync returned %d\n", success);
+    free(p_buffer);
+    return buffer;
+  }
+
+  for (i = 0; i < bytes_read; ++i) {
+    rb_ary_push(buffer, UINT2NUM((uint8_t)p_buffer[i]));
+  }
+
+  free(p_buffer);
+  return buffer;
+}
+
+struct turtleshell_context {
+  VALUE callback;
+  rtlsdr_dev_t *device;
+};
+
+typedef struct turtleshell_context turtleshell_context;
+
+static void turtleshell_callback(unsigned char *buffer, uint32_t length, void *context) {
+  uint32_t i;
+  rtlsdr_dev_t *device;
+  VALUE buffer_array, callback, bool_value;
+  struct turtleshell_context unwrapped_context;
+
+  unwrapped_context = *(struct turtleshell_context *)context;
+
+  if (!unwrapped_context.callback || !unwrapped_context.device) {
+    printf("unexpected error: could not read callback / device from unwrapped context\n");
+    exit(1);
+  }
+
+  device = unwrapped_context.device;
+  callback = unwrapped_context.callback;
+
+  buffer_array = rb_ary_new();
+  for (i = 0; i < length; ++i) {
+    rb_ary_push(buffer_array, UINT2NUM((uint8_t)buffer[i]));
+  }
+
+  // TODO: do we need to free(buffer) or context ?
+  bool_value = RTEST(rb_funcall(callback, rb_intern("call"), 1, buffer_array));
+
+  if (!bool_value) {
+    rtlsdr_cancel_async(device);
+  }
+}
+
+static VALUE turtleshell_read_asynchronous(VALUE self,
+                                          VALUE device,
+                                          VALUE bytes_to_read,
+                                          VALUE callback) {
+  int success, length = NUM2INT(bytes_to_read);
+  rtlsdr_dev_t *p_device;
+  struct turtleshell_context context;
+  void *wrapped_context;
+
+  Data_Get_Struct(device, rtlsdr_dev_t, p_device);
+
+  context.device = p_device;
+  context.callback = callback;
+  wrapped_context = (void *)&context;
+
+  rtlsdr_reset_buffer(p_device);
+  success = rtlsdr_read_async(p_device, turtleshell_callback, wrapped_context, 0, length);
+
+  if (success != 0) {
+    printf("error reading async: return code %d\n", success);
+  }
+
+  return Qnil;
+}
+
+static VALUE turtleshell_get_sample_rate(VALUE self, VALUE wrapped_device) {
+  rtlsdr_dev_t *device;
+  Data_Get_Struct(wrapped_device, rtlsdr_dev_t, device);
+  return UINT2NUM(rtlsdr_get_sample_rate(device));
+}
+
+static VALUE turtleshell_set_sample_rate(VALUE self,
+                                        VALUE wrapped_device,
+                                        VALUE value) {
+  uint32_t rate = NUM2UINT(value);
+  rtlsdr_dev_t *device;
+  Data_Get_Struct(wrapped_device, rtlsdr_dev_t, device);
+  rtlsdr_set_sample_rate(device, rate);
+
+  return Qnil;
+}
+
+static VALUE turtleshell_get_center_frequency(VALUE self, VALUE wrapped_device) {
+  rtlsdr_dev_t *device;
+  Data_Get_Struct(wrapped_device, rtlsdr_dev_t, device);
+  return UINT2NUM(rtlsdr_get_center_freq(device));
+}
+
+static VALUE turtleshell_set_center_frequency(VALUE self,
+                                             VALUE wrapped_device,
+                                             VALUE value) {
+  uint32_t freq = NUM2UINT(value);
+  rtlsdr_dev_t *device;
+  Data_Get_Struct(wrapped_device, rtlsdr_dev_t, device);
+  rtlsdr_set_center_freq(device, freq);
+  return Qnil;
+}
+
+static VALUE turtleshell_get_gain(VALUE self, VALUE wrapped_device) {
+  rtlsdr_dev_t *device;
+  Data_Get_Struct(wrapped_device, rtlsdr_dev_t, device);
+  return INT2NUM(rtlsdr_get_tuner_gain(device));
+}
+
+static VALUE turtleshell_set_gain(VALUE self, VALUE wrapped_device, VALUE value) {
+  int gain = NUM2INT(value);
+  rtlsdr_dev_t *device;
+  Data_Get_Struct(wrapped_device, rtlsdr_dev_t, device);
+  rtlsdr_set_tuner_gain(device, gain);
+  return Qnil;
+}
+
+void Init_librtlsdr() {
+  m_turtleshell = rb_define_module("TurtleShell");
+  m_rtlsdr = rb_define_module_under(m_turtleshell, "RTLSDR");
+  c_device = rb_define_class_under(m_rtlsdr, "Device", rb_cObject);
+
+  // count of devices
+  rb_define_module_function(m_rtlsdr, "count", turtleshell_count, 0);
+
+  // life cycle of devices
+  rb_define_module_function(m_rtlsdr, "first_device", turtleshell_first_device, 0);
+  rb_define_module_function(m_rtlsdr, "all_devices", turtleshell_all_devices, 0);
+  rb_define_module_function(m_rtlsdr, "nth_device", turtleshell_nth_device, 1);
+  rb_define_module_function(m_rtlsdr, "close_device", turtleshell_close, 1);
+
+  // reading bytes
+  rb_define_module_function(m_rtlsdr, "read_sync", turtleshell_read_synchronous, 2);
+  rb_define_module_function(m_rtlsdr, "read_async", turtleshell_read_asynchronous, 3);
+
+  // getters and setters
+  rb_define_module_function(m_rtlsdr, "get_sample_rate", turtleshell_get_sample_rate, 1);
+  rb_define_module_function(m_rtlsdr, "set_sample_rate", turtleshell_set_sample_rate, 2);
+  rb_define_module_function(m_rtlsdr, "get_center_freq", turtleshell_get_center_frequency, 1);
+  rb_define_module_function(m_rtlsdr, "set_center_freq", turtleshell_set_center_frequency, 2);
+  rb_define_module_function(m_rtlsdr, "get_gain", turtleshell_get_gain, 1);
+  rb_define_module_function(m_rtlsdr, "set_gain", turtleshell_set_gain, 2);
+}

data/lib/turtleshell.rb

@@ -0,0 +1,22 @@
+module TurtleShell
+end
+
+Dir.entries(Dir.pwd).select do |f|
+  File.directory?(f) && f[0] != '.'
+end.each do |dir|
+  lib = File.expand_path("../#{dir}", __FILE__)
+  $:.unshift lib unless $:.include? lib
+end
+
+require 'librtlsdr/librtlsdr'
+require 'turtleshell/device'
+
+module TurtleShell
+  def self.all_devices
+    TurtleShell::RTLSDR.all_devices
+  end
+
+  def self.count_of_devices
+    TurtleShell::RTLSDR.count
+  end
+end

data/lib/turtleshell/device.rb

@@ -0,0 +1,104 @@
+module TurtleShell
+
+  class DeviceNotFoundError < Exception; end
+
+  class Device
+    attr_reader :name
+
+    def initialize(n = 0)
+      raise ArgumentError.new('TurtleShell::Device.new expects a number') unless n.is_a? Fixnum
+
+      unless raw_device_attrs = TurtleShell::RTLSDR.nth_device(n)
+        raise TurtleShell::DeviceNotFoundError
+      end
+
+      @name = raw_device_attrs[:name]
+      @device = raw_device_attrs[:device]
+    end
+
+    def self.device_with_name(name)
+      unless index = TurtleShell.all_devices.index(name)
+        raise ArgumentError.new('No device with that name')
+      end
+
+      new(index)
+    end
+
+    def sample_rate
+      TurtleShell::RTLSDR.get_sample_rate(@device)
+    end
+
+    def sample_rate=(rate)
+      TurtleShell::RTLSDR.set_sample_rate(@device, rate)
+    end
+
+    def center_frequency
+      TurtleShell::RTLSDR.get_center_freq(@device)
+    end
+
+    def center_frequency=(freq)
+      TurtleShell::RTLSDR.set_center_freq(@device, freq)
+    end
+
+    def gain
+      TurtleShell::RTLSDR.get_gain(@device)
+    end
+
+    def gain=(gain)
+      TurtleShell::RTLSDR.set_gain(@device, gain)
+    end
+
+    # read specified number of complex samples from tuner
+    # real and imaginary parts are normalized between [-1, 1]
+    def read_samples(number_of_samples = 1024)
+      number_of_bytes = 2 * number_of_samples
+      raw_data = read_bytes(number_of_bytes)
+      packed_bytes_to_complex(raw_data)
+    end
+
+    # read specified number of complex samples from tuner into a block
+    # real and imaginary parts are normalized between [-1, 1]
+    def read_samples_async(number_of_samples = 1024, &block)
+      block = proc { } unless block_given?
+      wrapped_block = proc do |raw_data|
+        block.call(packed_bytes_to_complex(raw_data))
+      end
+
+      number_of_bytes_to_read = 2 * number_of_samples
+
+      begin
+          TurtleShell::RTLSDR.read_async(@device, number_of_bytes_to_read, wrapped_block)
+      rescue SignalException => e
+        puts 'Caught signal, cancelling async callback.'
+        TurtleShell::RTLSDR.end_async(@device)
+        raise e
+      end
+    end
+
+    def close_device
+      unless @device.nil?
+        TurtleShell::RTLSDR.close_device(@device)
+      end
+    end
+
+    private
+    def read_bytes(bytes_to_read)
+      buffer = TurtleShell::RTLSDR.read_sync(@device, bytes_to_read)
+
+      if buffer.size != bytes_to_read
+        close_device
+        raise IOError.new("Error reading from device. Requested #{bytes_to_read} but got #{buffer.size} back")
+      end
+
+      buffer
+    end
+
+    # converts an array of bytes to a list of complex numbers
+    # and normalizes them within the range [-1, 1]
+    def packed_bytes_to_complex(bytes)
+      bytes.each_slice(2).map do |i, r|
+        Complex(i / 127.5 - 1, r / 127.5 - 1)
+      end
+    end
+  end
+end

data/spec/device_spec.rb

@@ -0,0 +1,184 @@
+require 'turtleshell'
+
+describe 'TurtleShell:Device behavior' do
+  it 'should return the name' do
+    TurtleShell::RTLSDR.
+      should_receive(:nth_device).
+      and_return({:name => 'slippery-slope'})
+
+    expect(TurtleShell::Device.new.name).to eq('slippery-slope')
+  end
+end
+
+describe 'creating devices' do
+  describe 'finding a device by index' do
+    it 'should create a new device' do
+      TurtleShell::RTLSDR.
+        should_receive(:nth_device).
+        with(750).
+        and_return({:name => 'ill-sorted-limbic-system'})
+
+      expect(TurtleShell::Device.new(750)).to be_an_instance_of TurtleShell::Device
+    end
+  end
+
+  describe 'finding a device by name' do
+    before do
+      TurtleShell.
+        should_receive(:all_devices).
+        and_return(['electro-positive-self-activity', 'dry-shod-leze-majesty'])
+    end
+
+    it 'should create a new device' do
+      TurtleShell::RTLSDR.
+        should_receive(:nth_device).
+        with(1).
+        and_return({:name => 'dry-shod-leze-majesty'})
+
+      expect(TurtleShell::Device.device_with_name('dry-shod-leze-majesty')).
+        to be_an_instance_of TurtleShell::Device
+    end
+
+    it 'should raise an ArgumentError when there is matching device' do
+      expect { TurtleShell::Device.device_with_name('clincher-built-parity-check') }.
+        to raise_error(ArgumentError, 'No device with that name')
+    end
+  end
+
+  describe 'creating a new device' do
+    it 'should create a new device' do
+      TurtleShell::RTLSDR.
+        should_receive(:nth_device).
+        with(437).
+        and_return({:name => 'self-applying-cat-silver'})
+
+      expect(TurtleShell::Device.new(437)).to be_an_instance_of TurtleShell::Device
+    end
+
+    it 'should raise an error if the first argument is not an integer' do
+      expect { TurtleShell::Device.new('a') }.
+        to raise_error ArgumentError, 'TurtleShell::Device.new expects a number'
+
+      expect { TurtleShell::Device.new(nil) }.
+        to raise_error ArgumentError, 'TurtleShell::Device.new expects a number'
+    end
+  end
+end
+
+def create_mock_device
+  TurtleShell::RTLSDR.
+    should_receive(:nth_device).
+    with(0).
+    and_return({
+      :name => 'self-applying-cat-silver',
+      :sample_rate => 666,
+      :center_frequency => 70e6,
+      :gain => :auto,
+    })
+
+  TurtleShell::Device.new(0)
+end
+
+describe 'device attribues' do
+  describe 'getting and setting the sample rate' do
+    describe 'getting the value' do
+      before do
+        @device = create_mock_device
+        TurtleShell::RTLSDR.
+          should_receive(:get_sample_rate).
+          and_return(666)
+      end
+
+      it 'gets the value' do
+        expect(@device.sample_rate).to eq(666)
+      end
+    end
+
+    describe 'setting the value' do
+      before do
+        @device = create_mock_device
+        TurtleShell::RTLSDR.
+          should_receive(:set_sample_rate)
+          .with(nil, 12) ### mocked out device struct
+
+        TurtleShell::RTLSDR.
+          should_receive(:get_sample_rate)
+          .and_return(12)
+      end
+
+      it 'sets the value' do
+        @device.sample_rate = 12
+        expect(@device.sample_rate).to eq(12)
+      end
+    end
+  end
+
+  describe 'getting and setting the center frequency' do
+    describe 'getting the value' do
+      before do
+        @device = create_mock_device
+
+        TurtleShell::RTLSDR.
+          should_receive(:get_center_freq)
+          .and_return(70e6)
+
+        it 'gets the value' do
+          expect(@device.center_frequency).to eq(70e6)
+        end
+      end
+    end
+
+    describe 'setting the value' do
+      before do
+        @device = create_mock_device
+
+        TurtleShell::RTLSDR.
+          should_receive(:set_center_freq).
+          with(nil, 12e12)
+
+        TurtleShell::RTLSDR.
+          should_receive(:get_center_freq).
+          and_return(12e12)
+      end
+
+      it 'sets the value' do
+        @device.center_frequency = 12e12
+        expect(@device.center_frequency).to eq(12e12)
+      end
+    end
+  end
+
+  describe 'getting and setting the gain' do
+    describe 'getting the value' do
+      before do
+        @device = create_mock_device
+        TurtleShell::RTLSDR.
+          should_receive(:get_gain).
+          and_return(:auto)
+      end
+
+      it 'gets the gain' do
+        expect(@device.gain).to eq(:auto)
+      end
+    end
+
+    describe 'setting the value' do
+      before do
+        @device = create_mock_device
+
+        TurtleShell::RTLSDR.
+          should_receive(:set_gain).
+          with(nil, 4) # xxx mocked out device
+
+        TurtleShell::RTLSDR.
+          should_receive(:get_gain).
+          and_return(4)
+      end
+
+      it 'sets the value' do
+        @device.gain = 4
+        expect(@device.gain).to eq(4)
+      end
+    end
+  end
+end

data/spec/turtleshell_spec.rb

@@ -0,0 +1,22 @@
+require 'turtleshell'
+
+describe 'TurtleShell' do
+  it 'tells you how many devices are connected' do
+    TurtleShell::RTLSDR.
+      should_receive(:count).
+      and_return(886)
+
+    expect(TurtleShell.count_of_devices).to eq(886)
+  end
+
+  it 'tells you which devices are at which index' do
+    TurtleShell::RTLSDR.
+      should_receive(:all_devices).
+      and_return(['guilt-ridden-humpback-whale', 'four-ply-self-repellency', 'lute-backed-cross-stone'])
+
+    names = TurtleShell.all_devices
+    expect(names[0]).to eq('guilt-ridden-humpback-whale')
+    expect(names[1]).to eq('four-ply-self-repellency')
+    expect(names[2]).to eq('lute-backed-cross-stone')
+  end
+end

data/turtleshell.gemspec

@@ -0,0 +1,28 @@
+Gem::Specification.new do |s|
+  s.name = 'turtleshell'
+  s.version = '1.0.4'
+  s.date = '2013-11-05'
+  s.summary = 'A ruby wrapper for librtlsdr'
+  s.description = 'turtleshell is an interface for realtek USB software defined radio devices'
+  s.authors = ['Tim Jarratt']
+  s.email = 'tjarratt@gmail.com'
+  s.files = ['lib/turtleshell.rb']
+  s.homepage = 'http://github.com/tjarratt/turtleshell'
+  s.license = 'MIT'
+  s.require_path = 'lib'
+
+  s.extensions = ['ext/librtlsdr/extconf.rb']
+
+  s.add_dependency 'rake',              '~> 10.1'
+  s.add_dependency 'rake-compiler',     '~> 0.9'
+  s.add_development_dependency 'rspec', '~> 2.14'
+
+  ignores  = File.readlines('.gitignore').grep(/\S+/).map(&:chomp)
+  dotfiles = %w[.gitignore]
+
+  all_files_without_ignores = Dir['**/*'].reject { |f|
+    File.directory?(f) || ignores.any? { |i| File.fnmatch(i, f) }
+  }
+
+  s.files = (all_files_without_ignores + dotfiles).sort
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: turtleshell
+version: !ruby/object:Gem::Version
+  version: 1.0.4
+platform: ruby
+authors:
+- Tim Jarratt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-11-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.1'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+description: turtleshell is an interface for realtek USB software defined radio devices
+email: tjarratt@gmail.com
+executables: []
+extensions:
+- ext/librtlsdr/extconf.rb
+extra_rdoc_files: []
+files:
+- .gitignore
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- examples/async_read_from_device.rb
+- examples/listing_devices.rb
+- examples/simple_read_from_device.rb
+- ext/librtlsdr/Makefile
+- ext/librtlsdr/extconf.rb
+- ext/librtlsdr/librtlsdr.c
+- lib/turtleshell.rb
+- lib/turtleshell/device.rb
+- spec/device_spec.rb
+- spec/turtleshell_spec.rb
+- tmp/x86_64-darwin13.0.0/librtlsdr/2.0.0/Makefile
+- tmp/x86_64-darwin13.0.0/librtlsdr/2.0.0/mkmf.log
+- turtleshell.gemspec
+homepage: http://github.com/tjarratt/turtleshell
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.11
+signing_key: 
+specification_version: 4
+summary: A ruby wrapper for librtlsdr
+test_files: []