dino 0.10.0 → 0.11.2

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 0.11.2
+
+* Make servos work better by using the existing Arduino Servo library.
+  * Up to 12 servos can be controlled.
+  * On MEGA boards, servos may be used on pins 22-33 ONLY.
+  * On other boards, servos may be used on pins 2-13 ONLY.
+  * Flashing the updated sketch to the board is required.
+
+## 0.11.1
+ 
+### New Features
+
+* Support for the Arduino Ethernet shield and compatibles (Wiznet W5100 chipset).
+
+* Added a `dino` command-line tool for generating and customizing the different Arduino sketches.
+
+* Instead of reading the value of a pin by repeatedly sending messages to ask for its value, we can now set up "listeners". We tell the board which pin we'd like to listen to, and it will periodically send us the pin's value.
+  * By default, digital listeners are polled every ~4ms (~250Hz).
+  * Analog listeners are on a 4x divider, so they update every ~16ms (~63Hz).
+  * These can be changed with the `Board#heart_rate=` and `Board#analog_divider=` methods respectively.
+  * Digital listeners only send a message if the value has changed since the last check.
+  * Analog listeners always  send a message.
+  * Digital listeners can be set up on any pin, including analog pins. Analog listeners should only be set up on analog pins.
+
+* Registering a listener is now the default for read components such as `Sensor` and `Button`. No changes need to be made for existing or future components. Anything using `Board#add_analog_hardware` or `Board#add_digital_hardware` will set up a listener.
+
+  __NOTE__: Because of these changes, you'll need to upload the newest version of the sketch to your board for this version of the gem to work properly.
+
+* Support for all 70 pins on the Arduino Mega boards.
+
+* Built-in pullup resistors on the Arduino are now configurable in Ruby. Disabled by default.
+
+* Support up to COM9 on Windows.
+
+* Connect to a specific serial device by setting `device:` in the options hash when calling `Dino::TxRx::Serial.new`.
+
+* Baud rate for serial connections is now configurable. Use the `--baud XXXXXX` option for `dino` to set the rate before uploading the sketch. Set `baud: XXXXXX` in the options hash for Dino::TxRx::Serial.new` to set the rate when connecting. Both values need to match.
+
+* Added color methods to `RgbLed` for cyan, yellow, magenta, white and off.
+
+### Major Changes
+
+* All Arduino code that interacts with components has been extracted into an Arduino library. The sketches now only handle communication between a `Dino::TxRx::` class in Ruby and this library. Writing new sketches for arbitray protocols should be simpler.
+
+* Arduino-level debug messages now use preprocessor directives instead of `if(debug)` statements. The performance and memory usage of sketches with debugging disabled is improved.
+
+* As a result, enabling and disabling Arduino-level debug messages can no longer be done in Ruby. You'll need to enable debug messages before uploading a sketch by using the `--debug` option when generating the sketch with `dino`.
+
+* Removed `TxRx::Telnet`. `TxRx::TCP`, written for the Ethernet shield, works even better for ser2net.
+
+### Minor Changes
+
+* Handshake protocol: The first command sent to the Arduino resets the board to defaults. It acknowledges and responds with the raw pin number of its first analog pin, 'A0' (pin 14 on an UNO).
+
+* When sending messages between Ruby and the Arduino, all pins are now referenced by this numerical syntax. The value received in the handshake is used by `Dino::Board` to calculate values on the fly, so the more friendly 'A0' syntax may be used everywhere else in Ruby. This was done mostly to replace some complicated Arduino code and support > 10 analog pins.
+
+* The Arduino's read and write operations no longer implicitly set the mode of a pin. Calling `board#set_pin_mode` when initializing a component is now required. `board#add_analog_hardware` or `board#add_digital_hardware` for read components will take care of this as well.
+
+* The syntax of the messages sent from the Arduino to Ruby has changed slightly from "PP::VVVV\r\n" to "PP:VVVV\n" where PP and VVVV represent the pin and value respectively. The increase in (serial) throughput is usable when many analog listeners are set or polling at high rates.
+
+* Sensors accept blocks instead of procs now.
+
+### Fixes
+
+* `Board#set_pin_mode` works correctly now. Input and output were swapped previously and this error was being hidden by the implicit operations mentioned above.

data/README.md

@@ -1,23 +1,39 @@
-# Welcome to Dino
+# Dino 0.11.2
 [![Build Status](https://secure.travis-ci.org/austinbv/dino.png)](http://travis-ci.org/austinbv/dino)
 
 ## Get Started In No Time
 
-Dino was designed to help you start working with your Arduino in minutes.
+Dino lets you start programming your Arduino with Ruby in minutes.
 
 #### Install the Gem
 
-```
+```shell
 gem install dino
 ```
 
-#### Upload the Bootstrapper
+#### Prepare the Bootstrapper
+
+Use the included command line tool to create a folder with the Arduino sketch you want to use and optionally configure it.
+
+```shell
+# If connecting via serial, USB or ser2net, this is all you should need:
+dino generate-sketch serial
+
+# If usng the ethernet shield, you'll want to specify unique MAC and IP addresses:
+dino generate-sketch ethernet --mac XX:XX:XX:XX:XX:XX --ip XXX.XXX.XXX.XXX
+
+# For more options:
+dino help
+```
+
+__Note:__ Current Ethernet shields come with a sticker indicating the MAC address you should use with them. For older shields without a dedicated MAC address, inventing a random one should work, but don't use the same one for multiple boards. Valid IP addresses depend on the configuration of your network.
+
+#### Upload The Bootstrapper
 
+* Connect the Arduino to a USB port on your machine, regardless of which sketch you're using.
 * Open [the normal Arduino IDE](http://arduino.cc/en/Main/Software)
-* Download the bootstrapper [src/du.ino](https://raw.github.com/austinbv/dino/master/src/du.ino)
-* Open the file in the Arduino IDE
-* Plug in your Arduino via USB
-* Click the upload button (an arrow)
+* Open the `.ino` file in the sketch folder you just generated.
+* Click the upload button (an arrow).
 
 #### Verify Install
 

data/bin/dino

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+require "pathname"
+require "fileutils"
+
+$options = {}
+$options[:sketch_names] = []
+
+def error(message)
+  $stderr.puts "Error: " + message
+  usage
+end
+
+def usage
+  $stderr.puts "Usage: #{File.basename($0)} COMMAND [command-specific-options]"
+  $stderr.puts
+  $stderr.puts "Commands:"
+  $stderr.puts "  generate-sketch SKETCH [options]"
+  $stderr.puts
+  $stderr.puts "    Sketches:"
+  $stderr.puts "      serial"
+  $stderr.puts "      ethernet"
+  $stderr.puts
+  $stderr.puts "    Options:"
+  $stderr.puts "      --baud BAUD"
+  $stderr.puts "      --mac XX:XX:XX:XX:XX:XX"
+  $stderr.puts "      --ip XXX.XXX.XXX.XXX"
+  $stderr.puts "      --port PORT"
+  $stderr.puts "      --debug"
+  $stderr.puts
+  exit(2)
+end
+
+# Command must be the first argument.
+$options[:command] = ARGV.shift
+usage if $options[:command].match /help/
+
+# Parse the rest loosely.
+loop do
+  case ARGV[0]
+    when 'serial'
+      ARGV.shift; $options[:sketch_names] << "du" unless $options[:sketch_names].include? "du"
+    when 'ethernet'
+      ARGV.shift; $options[:sketch_names] << "du_ethernet" unless $options[:sketch_names].include? "du_ethernet"
+    when '--baud'
+      ARGV.shift; $options[:baud] = ARGV.shift
+   when '--mac'
+      ARGV.shift; $options[:mac] = ARGV.shift
+    when '--ip'
+      ARGV.shift; $options[:ip] = ARGV.shift
+    when '--port'
+      ARGV.shift; $options[:port] = ARGV.shift
+    when '--debug'
+      ARGV.shift; $options[:debug] = true
+    when /^-/
+      error "Invalid argument '#{ARGV[0]}'"
+    else break
+  end
+end
+
+error "Invalid command '#{$options[:command]}'" unless $options[:command] == "generate-sketch"
+error "No sketches or invalid sketches specified" if $options[:sketch_names].empty?
+
+$options[:sketch_names].each do |sketch_name|
+  # Define the sources.
+  sketch_dir = sketch_name
+  sketch_file = sketch_name + ".ino"
+  src_dir = Pathname.new(__FILE__).realpath.to_s.chomp("/bin/dino") + "/src"
+  src_header = File.join src_dir, "lib", "Dino.h"
+  src_implementation = File.join src_dir, "lib", "Dino.cpp"
+  src_sketch = File.join src_dir, sketch_dir, sketch_file
+
+  # Read the files.
+  header = File.read(src_header)
+  implementation = File.read(src_implementation)
+  sketch = File.read(src_sketch)
+
+  # Modify them based on the arguments.
+  if $options[:baud]
+    sketch.gsub! "115200", $options[:baud]
+  end
+  if $options[:mac]
+    octets = $options[:mac].split(':')
+    bytes = octets.map { |o| "0x#{o.upcase}" }
+    sketch.gsub! "{ 0xDE, 0xAD, 0xBE, 0x30, 0x31, 0x32 }", bytes.inspect.gsub("[", "{").gsub("]", "}").gsub("\"", "")
+  end
+  if $options[:ip]
+    sketch.gsub! "192,168,0,77", $options[:ip].gsub(".", ",")
+  end
+  if $options[:port]
+    sketch.gsub! "int port = 3466", "int port = #{$options[:port]}"
+  end
+  if $options[:debug]
+    header.gsub! "// #define debug true", "#define debug true"
+  end
+
+  # Define the destinations.
+  working_dir = Dir.pwd
+  dest_dir = File.join working_dir, sketch_dir
+  Dir::mkdir dest_dir
+  dest_header = File.join dest_dir, "Dino.h"
+  dest_implementation = File.join dest_dir, "Dino.cpp"
+  dest_sketch = File.join dest_dir, sketch_file
+
+  # Write the files.
+  File.open(dest_header, 'w')         { |f| f.write header }
+  File.open(dest_implementation, 'w') { |f| f.write implementation }
+  File.open(dest_sketch, 'w')         { |f| f.write sketch }
+end

data/dino.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |gem|
   gem.email         = ["austinbv@gmail.com"]
   gem.description   = %q{A utility library for interfacting with an Arduino.
   Designed for control, expansion, and with love.}
-  gem.summary       = %q{Control your arduino through a serial port}
+  gem.summary       = %q{Control your Arduino with Ruby.}
   gem.homepage      = 'https://github.com/austinbv/dino'
 
   gem.files         = `git ls-files`.split($\)
@@ -14,6 +14,7 @@ Gem::Specification.new do |gem|
   gem.name          = "dino"
   gem.require_paths = ["lib"]
   gem.version       = Dino::VERSION
+  gem.executables   = ["dino"]
 
   gem.add_dependency 'serialport'
 end

data/examples/button/button.rb

@@ -4,9 +4,10 @@
 # sleep or in someway keep running or your program
 # will exit before any callbacks can be called
 #
-require File.expand_path('../../../lib/dino', __FILE__)
+require 'bundler/setup'
+require 'dino'
 
-board = Dino::Board.new(Dino::TxRx.new)
+board = Dino::Board.new(Dino::TxRx::Serial.new)
 button = Dino::Components::Button.new(pin: 13, board: board)
 
 button.down do

data/examples/ethernet.rb

@@ -0,0 +1,15 @@
+#
+# This example shows how to use an Arduino with an Ethernet shield and the du_ethernet.ino sketch loaded.
+# Replace the IP address in this example with the IP you used when uploading the sketch.
+# The Ethernet shield uses up pin 13, so you'll need an LED on pin 5 to make sure it's working.
+#
+require File.expand_path('../../lib/dino', __FILE__)
+
+connection = Dino::TxRx::TCP.new("192.168.0.77")
+board = Dino::Board.new(connection)
+led = Dino::Components::Led.new(pin: 5, board: board)
+
+[:on, :off].cycle do |switch|
+  led.send(switch)
+  sleep 0.5
+end

data/examples/{ir_receiver.rb → ir_receiver/ir_receiver.rb}

@@ -4,9 +4,10 @@
 # sleep or in someway keep running or your program
 # will exit before any callbacks can be called
 #
-require File.expand_path('../../lib/dino', __FILE__)
+require 'bundler/setup'
+require 'dino'
 
-board = Dino::Board.new(Dino::TxRx.new)
+board = Dino::Board.new(Dino::TxRx::Serial.new)
 ir = Dino::Components::IrReceiver.new(pin: 2, board: board)
 led = Dino::Components::Led.new(pin: 13, board: board)
 

data/examples/led/led.rb

@@ -2,10 +2,10 @@
 # This is a simple example to blink an led
 # every half a second
 #
+require 'bundler/setup'
+require 'dino'
 
-require File.expand_path('../../../lib/dino', __FILE__)
-
-board = Dino::Board.new(Dino::TxRx.new)
+board = Dino::Board.new(Dino::TxRx::Serial.new)
 led = Dino::Components::Led.new(pin: 13, board: board)
 
 [:on, :off].cycle do |switch|

data/examples/{potentiometer.rb → potentiometer/potentiometer.rb}

@@ -4,21 +4,19 @@
 # LED. The set_delay callback reads from the potentiometer
 # and changes the sleep delay for the LED on/off cycle.  
 #  
+require 'bundler/setup'
+require 'dino'
 
-require File.expand_path('../../lib/dino', __FILE__)
-
-board = Dino::Board.new(Dino::TxRx.new)
+board = Dino::Board.new(Dino::TxRx::Serial.new)
 led = Dino::Components::Led.new(pin: 13, board: board)
 potentiometer = Dino::Components::Sensor.new(pin: 'A0', board: board)
 
 delay = 500.0
 
-set_delay = Proc.new do |data|
+potentiometer.when_data_received do |data|
   puts "DATA: #{delay = data.to_i}"
 end
 
-potentiometer.when_data_received(set_delay)
-
 [:on, :off].cycle do |switch|
   puts "DELAY: #{seconds = (delay / 1000.0)}"
   led.send(switch)

data/examples/{rgb_led.rb → rgb_led/rgb_led.rb}

@@ -2,23 +2,21 @@
 # This is a simple example to blink an led
 # every half a second
 #
+require 'bundler/setup'
+require 'dino'
 
-require File.expand_path('../../lib/dino', __FILE__)
-
-board = Dino::Board.new(Dino::TxRx.new)
+board = Dino::Board.new(Dino::TxRx::Serial.new)
 led = Dino::Components::RgbLed.new(pins: {red: 11, green: 10, blue: 9}, board: board)
 potentiometer = Dino::Components::Sensor.new(pin: 'A0', board: board)
 
 
 delay = 500.0
 
-set_delay = Proc.new do |data|
+potentiometer.when_data_received do |data|
   sleep 0.5
   puts "DATA: #{delay = data.to_i}"
 end
 
-potentiometer.when_data_received(set_delay)
-
   sleep(2)
 loop do
   puts "DELAY: #{seconds = (delay / 1000.0)}"

data/examples/{sensor.rb → sensor/sensor.rb}

@@ -4,15 +4,14 @@
 # sleep or in someway keep running or your program
 # will exit before any callbacks can be called
 #
-require File.expand_path('../../lib/dino', __FILE__)
+require 'bundler/setup'
+require 'dino'
 
-board = Dino::Board.new(Dino::TxRx.new)
+board = Dino::Board.new(Dino::TxRx::Serial.new)
 sensor = Dino::Components::Sensor.new(pin: 'A0', board: board)
 
-on_data = Proc.new do |data|
-    puts data
+sensor.when_data_received do |data|
+  puts data
 end
 
-sensor.when_data_received(on_data)
-
 sleep

data/examples/ser2net.rb

@@ -0,0 +1,31 @@
+#
+# This example shows how to use an Arduino on a remote machine via ser2net.
+# Running ser2net serves up the serial connection over the network interface,
+# so you can communicate with the Arduino over your local network or the Internet.
+# 
+# Example ser2net command for an Arduino UNO on Mac:
+# ser2net -u -C "3466:raw:0:/dev/cu.usbmodem621:115200"
+#
+# Note that we're using ser2net in raw TCP mode and not telnet mode which is more common.
+# 
+# Replace /dev/cu.usbmodem621 with your Arduino device.
+# Arduino UNOs are usually /dev/ttyACM0 under Linux.
+#
+# ser2net is preinstalled on many Linuxes. Install ser2net at the Mac Terminal with:
+# brew install ser2net
+#
+# http://sourceforge.net/projects/ser2net/ for more info on installing and configuring ser2net.
+#
+
+require File.expand_path('../../lib/dino', __FILE__)
+
+# The remote ser2net host is the first argument for a new TxRx::TCP.
+# The second argument, port number, is optional. 3466 is default. This must match the port ser2net uses on the remote machine.
+connection = Dino::TxRx::TCP.new("127.0.0.1", 3466)
+board = Dino::Board.new(connection)
+led = Dino::Components::Led.new(pin: 13, board: board)
+
+[:on, :off].cycle do |switch|
+  led.send(switch)
+  sleep 0.5
+end

data/examples/servo/servo.rb

@@ -0,0 +1,16 @@
+#
+# This is an example of how to use the servo class
+#
+require 'bundler/setup'
+require 'dino'
+
+board = Dino::Board.new(Dino::TxRx::Serial.new)
+servo = Dino::Components::Servo.new(pin: 9, board: board)
+
+# Add different angles (in degrees) to the array below to try out your servo.
+# Note: Some servos may not have a full 180 degree sweep.
+
+[0, 90].cycle do |angle|
+  servo.position = angle
+  sleep 0.5
+end

data/examples/stepper/stepper.rb

@@ -1,10 +1,10 @@
 #
 # This is a simple example to move a stepper motor using the sparkfun easydriver shield: https://www.sparkfun.com/products/10267?
 #
+require 'bundler/setup'
+require 'dino'
 
-require File.expand_path('../../../lib/dino', __FILE__)
-
-board = Dino::Board.new(Dino::TxRx.new)
+board = Dino::Board.new(Dino::TxRx::Serial.new)
 stepper = Dino::Components::Stepper.new(board: board, pins: { step: 10, direction: 8 })
 
   1600.times do

data/lib/dino/board.rb

@@ -1,37 +1,28 @@
 module Dino
   class Board
-    attr_reader :digital_hardware, :analog_hardware
+    attr_reader :digital_hardware, :analog_hardware, :analog_zero
     LOW, HIGH = 000, 255
 
     def initialize(io)
       @io, @digital_hardware, @analog_hardware = io, [], []
       io.add_observer(self)
-      send_clearing_bytes
-      start_heart_beat
+      handshake
     end
 
-    def update(pin, msg)
-      (@digital_hardware + @analog_hardware).each do |part|
-        part.update(msg) if normalize_pin(pin) == normalize_pin(part.pin)
-      end
-    end
-
-    def add_digital_hardware(part)
-      set_pin_mode(part.pin, :in)
-      @digital_hardware << part
-    end
-
-    def remove_digital_hardware(part)
-      @digital_hardware.delete(part)
+    def handshake
+      @analog_zero = @io.handshake
     end
 
-    def add_analog_hardware(part)
-      set_pin_mode(part.pin, :in)
-      @analog_hardware << part
+    def analog_divider=(value)
+      unless [1, 2, 4, 8, 16, 32, 64, 128].include? value
+        puts "Analog divider must be in 1, 2, 4, 8, 16, 32, 64, 128"
+      else
+        write "9700#{normalize_value(value)}"
+      end
     end
 
-    def remove_analog_hardware(part)
-      @analog_hardware.delete(part)
+    def heart_rate=(value)
+      write "9800#{normalize_value(value)}"
     end
 
     def start_read
@@ -47,39 +38,76 @@ module Dino
       @io.write(formatted_msg)
     end
 
-    def digital_write(pin, value)
-      pin, value = normalize_pin(pin), normalize_value(value)
-      write("01#{pin}#{value}")
+    def update(pin, msg)
+      (@digital_hardware + @analog_hardware).each do |part|
+        part.update(msg) if normalize_pin(pin) == normalize_pin(part.pin)
+      end
     end
 
-    def digital_read(pin)
-      pin, value = normalize_pin(pin), normalize_value(0)
-      write("02#{pin}#{value}")
+    def add_digital_hardware(part)
+      set_pin_mode(part.pin, :in, part.pullup)
+      digital_listen(part.pin)
+      @digital_hardware << part
     end
 
-    def analog_write(pin, value)
-      pin, value = normalize_pin(pin), normalize_value(value)
-      write("03#{pin}#{value}")
+    def remove_digital_hardware(part)
+      stop_listener(part.pin)
+      @digital_hardware.delete(part)
     end
 
-    def analog_read(pin)
-      pin, value = normalize_pin(pin), normalize_value(0)
-      write("04#{pin}#{value}")
+    def add_analog_hardware(part)
+      set_pin_mode(part.pin, :in)
+      analog_listen(part.pin)
+      @analog_hardware << part
     end
 
-    def set_pin_mode(pin, mode)
-      pin, value = normalize_pin(pin), normalize_value(mode == :out ? 1 : 0)
-      write("00#{pin}#{value}")
+    def remove_analog_hardware(part)
+      stop_listener(part.pin)
+      @analog_hardware.delete(part)
     end
 
-    def set_debug(on_off)
-      pin, value = normalize_pin(0), normalize_value(on_off == :on ? 1 : 0)
-      write("99#{pin}#{value}")
+    def set_pin_mode(pin, mode, pullup=nil)
+      pin, value = normalize_pin(pin), normalize_value(mode == :out ? 0 : 1)
+      write("00#{pin}#{value}")
+      set_pullup(pin, pullup) if mode == :in
+    end
+
+    def set_pullup(pin, pullup)
+      pullup ? digital_write(pin, HIGH) : digital_write(pin, LOW)
+    end
+      
+    PIN_COMMANDS = {
+      digital_write:   '01',
+      digital_read:    '02',
+      analog_write:    '03',
+      analog_read:     '04',
+      digital_listen:  '05',
+      analog_listen:   '06',
+      stop_listener:   '07',
+      servo_toggle:    '08',
+      servo_write:     '09'
+    }
+
+    PIN_COMMANDS.each_key do |command|
+      define_method(command) do |pin, value=nil|
+        cmd = normalize_cmd(PIN_COMMANDS[command])
+        write "#{cmd}#{normalize_pin(pin)}#{normalize_value(value)}"
+      end
     end
 
     def normalize_pin(pin)
-      raise Exception.new('pins can only be two digits') if pin.to_s.length > 2
-      normalize(pin, 2)
+      if pin.to_s.match /\Aa/i
+        int_pin = @analog_zero + pin.to_s.gsub(/\Aa/i, '').to_i
+      else
+        int_pin = pin
+      end
+      raise Exception.new('pin number must be in 0-99') if int_pin.to_i > 99
+      return normalize(int_pin, 2)
+    end
+
+    def normalize_cmd(cmd)
+      raise Exception.new('commands can only be two digits') if cmd.to_s.length > 2
+      normalize(cmd, 2)
     end
 
     def normalize_value(value)
@@ -89,26 +117,8 @@ module Dino
 
     private
 
-    def start_heart_beat
-      @heart_beat ||= Thread.new do
-        loop do
-          sleep 0.005
-          @digital_hardware.each do |part|
-            digital_read(part.pin)
-          end
-          @analog_hardware.each do |part|
-            analog_read(part.pin)
-          end
-        end
-      end
-    end
-
     def normalize(pin, spaces)
       pin.to_s.rjust(spaces, '0')
     end
-
-    def send_clearing_bytes
-      write('00000000', no_wrap: true)
-    end
   end
 end