digiusb 1.0.1 → 1.0.2

data/bin/digiterm

@@ -11,7 +11,6 @@ spark = DigiUSB.sparks.last
 
 puts "Attached to #{spark.inspect.green}".blue
 puts "Type control + c to exit".blue
-
 begin
   loop do
     char = spark.getc
@@ -29,7 +28,11 @@ begin
   end
 rescue LIBUSB::ERROR_PIPE, LIBUSB::ERROR_NO_DEVICE
   puts "" # newline
-  puts "Digispark disconnected or crashed".white_on_red
+  puts "Digispark disconnected".white_on_red
+rescue DigiUSB::ErrorCrashed
+  puts "" # newline
+  puts "Digispark has crashed".white_on_red
+  puts " >> Probably need to call DigiUSB.refresh() more frequently in Digispark Program".blue
 rescue Interrupt
   puts ""
 end

data/lib/digiusb.rb

@@ -1,28 +1,54 @@
+# The DigiUSB class helps find, connect to, and talk with Digisparks using the DigiUSB arduino library bundled with the Digispark Arduino software.
+# This class aims to work like an IO object, letting you read and write characters, bytes, and strings as if it were a file, socket, or serial port.
+# To get started, grab a list of Digisparks with the DigiUSB.sparks method. Each spark has an inspect method with a unique identifier including the
+# USB device name (usually DigiUSB), and some numbers representing which ports and hubs each spark connects to. To begin with, DigiUSB.sparks.last
+# works well if you only intend to have one digispark connected to your computer. Eventually the device name (aka "product name") will hopefully
+# provide a simple way to differentiate different digisparks.
+#
+# Once you have a reference to a Digispark, you can start using it as if it were an IO object immediately with methods like getc and putc.
+# As soon as you start interacting with the Digispark using these reading and writing methods the Digispark will be claimed to your ruby program
+# and will be unavailable to other programs until you do one of: close the ruby program, or unplug and plug back in the Digispark.
+#
+# Note also that calling DigiUSB.sparks can sometimes disrupt program uploads, so if you're polling waiting for a digispark to appear you may see
+# some programming errors in the Digispark Arduino software.
+
 require 'libusb'
 
 # simple IO-like read/write access to a digispark using the DigiUSB library
 class DigiUSB
-  ProductID = 0x05df
-  VendorID = 0x16c0
-  Manufacturer = "digistump.com"
+  ProductID = 0x05df # product id number from Digistump
+  VendorID = 0x16c0 # vendor id number for Digistump
+  Manufacturer = "digistump.com" # manufacturer string is static
   Timeout = 1_000 # one second till device crashes due to lack of calling DigiUSB.refresh()
+  DefaultPollingFrequency = 15 # 15hz when waiting for data to be printed
   
+  # :nodoc: initialize a new DigiUSB object using a libusb device object
   def initialize device
     @device = device
     @handle = nil
+    @polling_frequency = DefaultPollingFrequency
   end
   
-  def self.sparks
+  # polling frequency describes how aggressively ruby will ask for new bytes when waiting for the device to print something
+  # a lower value is faster (it is in hertz)
+  attr_accessor :polling_frequency
+  
+  # Returns an array of all Digisparks connected to this computer. Optionally specify a device name string to return only Digisparks with
+  # that name. At the time of writing there is no easy way to customize the device name in the Digispark Arduino software, but hopefully
+  # there will be in the future.
+  def self.sparks product_name = false
     usb = LIBUSB::Context.new
     usb.devices.select { |device|
-      device.idProduct == ProductID && device.idVendor == VendorID && device.manufacturer == "digistump.com"
+      device.idProduct == ProductID && device.idVendor == VendorID && device.manufacturer == "digistump.com" && (product_name == false || product_name.to_s == device.product)
     }.map { |handle|
       self.new(handle)
     }
   end
   
   
-  # read a single character
+  # Attempt to read a single character from the Digispark. Returns a string either zero or one characters long.
+  # A zero character string means there are no characters available to read - the Digispark hasn't printed anything for you to consume yet.
+  # Returns next time Digispark calls DigiUSB.refresh() regardless of how many characters are available.
   def getc
     control_transfer(
       bRequest: 0x01, # hid get report
@@ -30,7 +56,8 @@ class DigiUSB
     )
   end
   
-  # write a single character
+  # Send a single character in to the Digispark's memory. Argument may be either a single byte String, or an integer between 0 and 255 inclusive.
+  # Returns next time Digispark calls DigiUSB.refresh()
   def putc character
     character = [character % 256].pack('c') if character.is_a? Integer
     raise "Cannot putc more than one byte" if character.bytesize > 1
@@ -42,20 +69,29 @@ class DigiUSB
     )
   end
   
-  # get a string up until the first newline
+  # Read a string fromt he Digispark until a newline is received (eg, from the println function in Digispark's DigiUSB library)
+  # The returned string includes a newline character on the end.
   def gets
     chars = ""
-    chars += getc() until chars.include? "\n"
+    until chars.include? "\n"
+      char = getc()
+      chars += char
+      sleep 1.0 / PollingFrequency if char == ""
+    end
     return chars
   end
+  alias_method :getln, :gets
+  alias_method :get_line, :gets
   
-  # write a string followed by a newline
+  # Send a String to the Digispark followed by a newline.
   def puts string = ""
     write "#{string}\n"
   end
   alias_method :println, :puts
+  alias_method :print_line, :puts
+  alias_method :write_line, :puts
   
-  # write a string
+  # Send a String to the Digispark
   def write string
     string.each_byte do |byte|
       putc byte
@@ -63,20 +99,45 @@ class DigiUSB
     string
   end
   alias_method :print, :write
+  alias_method :send, :write
   
-  # read a certain number of bytes and return them as a string
+  # Recieve a specific number of bytes and return them as a String. Unlike #getc read will wait until
+  # the specified number of bytes are available before returning.
   def read bytes = 1
     chars = ""
+    
+    until chars.include? "\n"
+      char = getc()
+      chars += char
+      sleep 1.0 / PollingFrequency if char == ""
+    end
+    
     chars += getc() until chars.length == bytes
     return chars
   end
   
+  # A friendly textual representation of this specific Digispark. Can be called without claiming the digispark for this program
   def inspect
-    "<Digispark:#{@device.product}:@#{@device.bus_number}.#{@device.device_address}>"
+    "<Digispark:#{name}:@#{address}>"
   end
   alias_method :to_s, :inspect
   
+  # Return the device name as a String
+  def name
+    @device.product
+  end
+  
+  # Returns the device's bus number and address on the computer's USB interface as a string
+  def address
+    "#{@device.bus_number}.#{@device.device_address}"
+  end
   
+  # Release this Digispark so other programs can read and write to it.
+  def close
+    @handle.close
+    @handle = nil
+  end
+  alias_method :release, :close
   
   private
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: digiusb
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors: