Class: Ftdi::Context

Inherits:
FFI::ManagedStruct
  • Object
show all
Defined in:
lib/ftdi.rb

Overview

Represents libftdi context and end-user API.

Examples:

Open USB device

ctx = Ftdi::Context.new
begin
  ctx.usb_open(0x0403, 0x6001)
  begin
    ctx.baudrate = 250000
  ensure
   ctx.usb_close
  end
rescue Ftdi::Error => e
  $stderr.puts e.to_s
end

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Context

Initializes new libftdi context.

Raises:



150
151
152
153
154
 
# File 'lib/ftdi.rb', line 150

def initialize
  ptr = Ftdi.ftdi_new
  raise CannotInitializeContextError.new  if ptr.nil?
  super(ptr)
end

Class Method Details

.release(p) ⇒ NilClass

Deinitialize and free an ftdi context.

Returns:

  • (NilClass) —

    nil



158
159
160
161
 
# File 'lib/ftdi.rb', line 158

def self.release(p)
  Ftdi.ftdi_free(p)
  nil
end

Instance Method Details

#baudrate ⇒ Fixnum

Gets the chip baud rate.

Returns:

  • (Fixnum) —

    Baud rate.



228
229
230
 
# File 'lib/ftdi.rb', line 228

def baudrate
  self[:baudrate]
end

#baudrate=(new_baudrate) ⇒ NilClass

Sets the chip baud rate.

Returns:

  • (NilClass) —

    nil

Raises:

  • (StatusCodeError) —

    libftdi reports error.

  • (ArgumentError) —

    Bad arguments.



236
237
238
239
 
# File 'lib/ftdi.rb', line 236

def baudrate=(new_baudrate)
  raise ArgumentError.new('baudrate should be Fixnum')  unless new_baudrate.kind_of?(Fixnum)
  check_result(Ftdi.ftdi_set_baudrate(ctx, new_baudrate))
end

#dtr=(value) ⇒ Fixnum

Set the DTR control line value.

Parameters:

  • value (Fixnum) —

    Either 0 or 1

Returns:

  • (Fixnum) —

    The value

Raises:



386
387
388
389
 
# File 'lib/ftdi.rb', line 386

def dtr=(value)
  check_result(Ftdi.ftdi_setdtr(ctx, value))
  value
end

#error_string ⇒ String

Gets error text.

Returns:

  • (String) —

    Error text.



165
166
167
 
# File 'lib/ftdi.rb', line 165

def error_string
  self[:error_str]
end

#flowctrl=(new_flowctrl) ⇒ Fixnum

Set flow control setting for ftdi chip.

Parameters:

  • new_flowctrl (Fixnum) —

    New flow control setting.

Returns:

  • (Fixnum) —

    New flow control setting.

Raises:

See Also:



271
272
273
274
 
# File 'lib/ftdi.rb', line 271

def flowctrl=(new_flowctrl)
  check_result(Ftdi.ftdi_setflowctrl(ctx, new_flowctrl))
  new_flowctrl
end

#interface ⇒ Interface

Gets used interface of the device.

Returns:

  • (Interface) —

    Used interface of the device.



369
370
371
 
# File 'lib/ftdi.rb', line 369

def interface
  Interface[self[:interface]]
end

#interface=(new_interface) ⇒ Interface

Open selected channels on a chip, otherwise use first channel.

Parameters:

  • new_interface (Interface) —

    Interface to use for FT2232C/2232H/4232H chips.

Returns:

Raises:



377
378
379
380
 
# File 'lib/ftdi.rb', line 377

def interface=(new_interface)
  check_result(Ftdi.ftdi_set_interface(ctx, new_interface))
  new_interface
end

#read_data ⇒ String

Reads data in chunks from the chip. Returns when at least one byte is available or when the latency timer has elapsed. Automatically strips the two modem status bytes transfered during every read.

Returns:

  • (String) —

    Bytes read; Empty string if no bytes read.

Raises:

See Also:



347
348
349
350
351
352
353
354
355
 
# File 'lib/ftdi.rb', line 347

def read_data
  chunksize = read_data_chunksize
  p = FFI::MemoryPointer.new(:char, chunksize)
  bytes_read = Ftdi.ftdi_read_data(ctx, p, chunksize)
  check_result(bytes_read)
  r = p.read_bytes(bytes_read)
  r.force_encoding("ASCII-8BIT")  if r.respond_to?(:force_encoding)
  r
end

#read_data_chunksize ⇒ Fixnum

Gets read buffer chunk size.

Returns:

  • (Fixnum) —

    Read buffer chunk size.

Raises:

See Also:



324
325
326
327
328
 
# File 'lib/ftdi.rb', line 324

def read_data_chunksize
  p = FFI::MemoryPointer.new(:uint, 1)
  check_result(Ftdi.ftdi_read_data_get_chunksize(ctx, p))
  p.read_uint
end

#read_data_chunksize=(new_chunksize) ⇒ Fixnum

Note:

Default is 4096.

Configure read buffer chunk size. Automatically reallocates the buffer.

Parameters:

  • new_chunksize (Fixnum) —

    Read buffer chunk size.

Returns:

  • (Fixnum) —

    New read buffer chunk size.

Raises:



336
337
338
339
 
# File 'lib/ftdi.rb', line 336

def read_data_chunksize=(new_chunksize)
  check_result(Ftdi.ftdi_read_data_set_chunksize(ctx, new_chunksize))
  new_chunksize
end

#read_pins ⇒ Fixnum

Directly read pin state, circumventing the read buffer. Useful for bitbang mode.

Returns:

  • (Fixnum) —

    Pins state

Raises:

See Also:



361
362
363
364
365
 
# File 'lib/ftdi.rb', line 361

def read_pins
  p = FFI::MemoryPointer.new(:uchar, 1)
  check_result(Ftdi.ftdi_read_pins(ctx, p))
  p.read_uchar
end

#rts=(value) ⇒ Fixnum

Set the RTS control line value.

Parameters:

  • value (Fixnum) —

    Either 0 or 1

Returns:

  • (Fixnum) —

    The value

Raises:



395
396
397
398
 
# File 'lib/ftdi.rb', line 395

def rts=(value)
  check_result(Ftdi.ftdi_setrts(ctx, value))
  value
end

#set_bitmode(bitmask, mode) ⇒ NilClass

Set Bitbang mode for ftdi chip.

Parameters:

  • bitmask (Fixnum) —

    to configure lines. HIGH/ON value configures a line as output.

  • mode (BitbangMode) —

    Bitbang mode: use the values defined in #BitbangMode

Returns:

  • (NilClass) —

    nil

See Also:



281
282
283
 
# File 'lib/ftdi.rb', line 281

def set_bitmode(bitmask, mode)
  check_result(Ftdi.ftdi_set_bitmode(ctx, bitmask, mode))
end

#set_line_property(bits, stopbits, parity) ⇒ NilClass

Set (RS232) line characteristics. The break type can only be set via #set_line_property2 and defaults to "off".

Parameters:

Returns:

  • (NilClass) —

    nil

Raises:



248
249
250
 
# File 'lib/ftdi.rb', line 248

def set_line_property(bits, stopbits,  parity)
  check_result(Ftdi.ftdi_set_line_property(ctx, bits, stopbits, parity))
end

#set_line_property2(bits, stopbits, parity, _break) ⇒ NilClass

Set (RS232) line characteristics.

Parameters:

Returns:

  • (NilClass) —

    nil

Raises:



259
260
261
 
# File 'lib/ftdi.rb', line 259

def set_line_property2(bits, stopbits,  parity, _break)
  check_result(Ftdi.ftdi_set_line_property2(ctx, bits, stopbits, parity, _break))
end

#usb_close ⇒ NilClass

Closes the ftdi device.

Returns:

  • (NilClass) —

    nil



221
222
223
224
 
# File 'lib/ftdi.rb', line 221

def usb_close
  Ftdi.ftdi_usb_close(ctx)
  nil
end

#usb_open(vendor, product) ⇒ NilClass

Opens the first device with a given vendor and product ids.

Parameters:

  • vendor (Fixnum) —

    Vendor id.

  • product (Fixnum) —

    Product id.

Returns:

  • (NilClass) —

    nil

Raises:

  • (StatusCodeError) —

    libftdi reports error.

  • (ArgumentError) —

    Bad arguments.



175
176
177
178
179
 
# File 'lib/ftdi.rb', line 175

def usb_open(vendor, product)
  raise ArgumentError.new('vendor should be Fixnum')  unless vendor.kind_of?(Fixnum)
  raise ArgumentError.new('product should be Fixnum')  unless product.kind_of?(Fixnum)
  check_result(Ftdi.ftdi_usb_open(ctx, vendor, product))
end

#usb_open_desc(vendor, product, description, serial) ⇒ NilClass

Opens the first device with a given vendor and product ids, description and serial.

Parameters:

  • vendor (Fixnum) —

    Vendor id.

  • product (Fixnum) —

    Product id.

  • description (String) —

    Description to search for. Use nil if not needed.

  • serial (String) —

    Serial to search for. Use nil if not needed.

Returns:

  • (NilClass) —

    nil

Raises:

  • (StatusCodeError) —

    libftdi reports error.

  • (ArgumentError) —

    Bad arguments.



189
190
191
192
193
 
# File 'lib/ftdi.rb', line 189

def usb_open_desc(vendor, product, description, serial)
  raise ArgumentError.new('vendor should be Fixnum')  unless vendor.kind_of?(Fixnum)
  raise ArgumentError.new('product should be Fixnum')  unless product.kind_of?(Fixnum)
  check_result(Ftdi.ftdi_usb_open_desc(ctx, vendor, product, description, serial))
end

#usb_open_desc_index(vendor, product, description, serial, index) ⇒ NilClass

Opens the index-th device with a given vendor and product ids, description and serial.

Parameters:

  • vendor (Fixnum) —

    Vendor id.

  • product (Fixnum) —

    Product id.

  • description (String) —

    Description to search for. Use nil if not needed.

  • serial (String) —

    Serial to search for. Use nil if not needed.

  • index (Fixnum) —

    Number of matching device to open if there are more than one, starts with 0.

Returns:

  • (NilClass) —

    nil

Raises:

  • (StatusCodeError) —

    libftdi reports error.

  • (ArgumentError) —

    Bad arguments.



204
205
206
207
208
209
210
 
# File 'lib/ftdi.rb', line 204

def usb_open_desc_index(vendor, product, description, serial, index)
  raise ArgumentError.new('vendor should be Fixnum')  unless vendor.kind_of?(Fixnum)
  raise ArgumentError.new('product should be Fixnum')  unless product.kind_of?(Fixnum)
  raise ArgumentError.new('index should be Fixnum')  unless index.kind_of?(Fixnum)
  raise ArgumentError.new('index should be greater than or equal to zero')  if index < 0
  check_result(Ftdi.ftdi_usb_open_desc_index(ctx, vendor, product, description, serial, index))
end

#usb_reset ⇒ NilClass

Resets the ftdi device.

Returns:

  • (NilClass) —

    nil

Raises:



215
216
217
 
# File 'lib/ftdi.rb', line 215

def usb_reset
  check_result(Ftdi.ftdi_usb_reset(ctx))
end

#write_data(bytes) ⇒ Fixnum

Writes data.

Parameters:

  • bytes (String, Array) —

    String or array of integers that will be interpreted as bytes using pack('c*').

Returns:

  • (Fixnum) —

    Number of written bytes.

Raises:



310
311
312
313
314
315
316
317
318
 
# File 'lib/ftdi.rb', line 310

def write_data(bytes)
  bytes = bytes.pack('c*')  if bytes.respond_to?(:pack)
  size = bytes.respond_to?(:bytesize) ? bytes.bytesize : bytes.size
  mem_buf = FFI::MemoryPointer.new(:char, size)
  mem_buf.put_bytes(0, bytes)
  bytes_written = Ftdi.ftdi_write_data(ctx, mem_buf, size)
  check_result(bytes_written)
  bytes_written
end

#write_data_chunksize ⇒ Fixnum

Gets write buffer chunk size.

Returns:

  • (Fixnum) —

    Write buffer chunk size.

Raises:

See Also:



289
290
291
292
293
 
# File 'lib/ftdi.rb', line 289

def write_data_chunksize
  p = FFI::MemoryPointer.new(:uint, 1)
  check_result(Ftdi.ftdi_write_data_get_chunksize(ctx, p))
  p.read_uint
end

#write_data_chunksize=(new_chunksize) ⇒ Fixnum

Note:

Default is 4096.

Configure write buffer chunk size. Automatically reallocates the buffer.

Parameters:

  • new_chunksize (Fixnum) —

    Write buffer chunk size.

Returns:

  • (Fixnum) —

    New write buffer chunk size.

Raises:



301
302
303
304
 
# File 'lib/ftdi.rb', line 301

def write_data_chunksize=(new_chunksize)
  check_result(Ftdi.ftdi_write_data_set_chunksize(ctx, new_chunksize))
  new_chunksize
end