Class: DigiUSB

Inherits:
Object
  • Object
show all
Defined in:
lib/digiusb.rb

Overview

simple IO-like read/write access to a digispark using the DigiUSB library

Direct Known Subclasses

DigiBlink

Defined Under Namespace

Classes: ErrorCrashed

Constant Summary collapse

ProductID =

product id number from Digistump

0x05df
VendorID =

vendor id number for Digistump

0x16c0
Timeout =

spark needs to DigiUSB.refresh or DigiUSB.sleep every second

1_000
DefaultPollingFrequency =

15hz when waiting for data to be printed

15

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(device) ⇒ DigiUSB

:nodoc: initialize a new DigiUSB object using a libusb device object



34
35
36
37
38
 
# File 'lib/digiusb.rb', line 34

def initialize device
  @device = device
  @handle = nil
  @polling_frequency = DefaultPollingFrequency
end

Instance Attribute Details

#polling_frequency ⇒ Object

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)



43
44
45
 
# File 'lib/digiusb.rb', line 43

def polling_frequency
  @polling_frequency
end

Class Method Details

.connect(product_name = false) ⇒ Object

Connect to a Digispark. Usually the most recently plugged in one.



59
60
61
 
# File 'lib/digiusb.rb', line 59

def self.connect product_name = false
  sparks(product_name).last
end

.sparks(product_name = false) ⇒ Object

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.



49
50
51
52
53
54
55
56
 
# File 'lib/digiusb.rb', line 49

def self.sparks product_name = false
  usb = LIBUSB::Context.new
  usb.devices.select { |device|
    device.idProduct == ProductID && device.idVendor == VendorID && (product_name == false || product_name.to_s == device.product)
  }.map { |handle|
    self.new(handle)
  }
end

Instance Method Details

#address ⇒ Object

Returns the device’s bus number and address on the computer’s USB interface as a string



147
148
149
 
# File 'lib/digiusb.rb', line 147

def address
  "#{@device.bus_number}.#{@device.device_address}"
end

#close ⇒ Object Also known as: release

Release this Digispark so other programs can read and write to it.



152
153
154
155
 
# File 'lib/digiusb.rb', line 152

def close
  @handle.close
  @handle = nil
end

#getc ⇒ Object

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.



68
69
70
71
72
73
 
# File 'lib/digiusb.rb', line 68

def getc
  control_transfer(
    bRequest: 0x01, # hid get report
    dataIn: 1
  )
end

#gets ⇒ Object Also known as: getln, get_line

Read a string from the 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.



93
94
95
96
97
98
99
100
101
 
# File 'lib/digiusb.rb', line 93

def gets
  chars = ""
  until chars.include? "\n"
    char = getc()
    chars += char
    sleep 1.0 / @polling_frequency if char == ""
  end
  return chars
end

#inspect ⇒ Object Also known as: to_s

A friendly textual representation of this specific Digispark. Can be called without claiming the digispark for this program



135
136
137
 
# File 'lib/digiusb.rb', line 135

def inspect
  "<Digispark:#{name}:@#{address}>"
end

#name ⇒ Object

Return the device name as a String



141
142
143
 
# File 'lib/digiusb.rb', line 141

def name
  @device.product
end

#putc(character) ⇒ Object

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()



79
80
81
82
83
84
85
86
87
88
 
# File 'lib/digiusb.rb', line 79

def putc character
  character = [character % 256].pack('C') if character.is_a? Integer
  raise "Cannot putc more than one byte" if character.bytesize > 1
  raise "Cannot putc fewer than one byte" if character.bytesize < 1
  
  control_transfer(
    bRequest: 0x09, # hid set report
    wIndex: character.ord
  )
end

#puts(string = "") ⇒ Object Also known as: println, print_line, write_line

Send a String to the Digispark followed by a newline.



106
107
108
 
# File 'lib/digiusb.rb', line 106

def puts string = ""
  write "#{string}\n"
end

#read(bytes = 1, timeout = nil) ⇒ Object

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. Optionally specify a timeout



126
127
128
129
130
131
 
# File 'lib/digiusb.rb', line 126

def read bytes = 1, timeout = nil
  start_time = Time.now.to_f
  chars = ""
  chars += getc() until chars.length >= bytes || (timeout && Time.now.to_f - start_time > timeout)
  return chars
end

#write(string) ⇒ Object Also known as: print, send

Send a String to the Digispark



114
115
116
117
118
119
 
# File 'lib/digiusb.rb', line 114

def write string
  string.each_byte do |byte|
    putc byte
  end
  string
end