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

- (Context) initialize

Initializes new libftdi context.

Raises:



147
148
149
150
151
 
# File 'lib/ftdi.rb', line 147

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

Class Method Details

+ (NilClass) release(p)

Deinitialize and free an ftdi context.

Returns:

  • (NilClass) —

    nil



155
156
157
158
 
# File 'lib/ftdi.rb', line 155

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

Instance Method Details

- (Fixnum) baudrate

Gets the chip baud rate.

Returns:

  • (Fixnum) —

    Baud rate.



225
226
227
 
# File 'lib/ftdi.rb', line 225

def baudrate
  self[:baudrate]
end

- (NilClass) baudrate=(new_baudrate)

Sets the chip baud rate.

Returns:

  • (NilClass) —

    nil

Raises:

  • (StatusCodeError) —

    libftdi reports error.

  • (ArgumentError) —

    Bad arguments.



233
234
235
236
 
# File 'lib/ftdi.rb', line 233

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

- (String) error_string

Gets error text.

Returns:

  • (String) —

    Error text.



162
163
164
 
# File 'lib/ftdi.rb', line 162

def error_string
  self[:error_str]
end

- (Fixnum) flowctrl=(new_flowctrl)

Set flow control setting for ftdi chip.

Parameters:

  • new_flowctrl (Fixnum) —

    New flow control setting.

Returns:

  • (Fixnum) —

    New flow control setting.

Raises:

See Also:



268
269
270
271
 
# File 'lib/ftdi.rb', line 268

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.



366
367
368
 
# File 'lib/ftdi.rb', line 366

def interface
  Interface[self[:interface]]
end

- (Interface) interface=(new_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:



374
375
376
377
 
# File 'lib/ftdi.rb', line 374

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

- (String) read_data

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:



344
345
346
347
348
349
350
351
352
 
# File 'lib/ftdi.rb', line 344

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

- (Fixnum) read_data_chunksize

Gets read buffer chunk size.

Returns:

  • (Fixnum) —

    Read buffer chunk size.

Raises:

See Also:



321
322
323
324
325
 
# File 'lib/ftdi.rb', line 321

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

- (Fixnum) read_data_chunksize=(new_chunksize)

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:



333
334
335
336
 
# File 'lib/ftdi.rb', line 333

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

- (Fixnum) read_pins

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

Returns:

  • (Fixnum) —

    Pins state

Raises:

See Also:



358
359
360
361
362
 
# File 'lib/ftdi.rb', line 358

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

- (NilClass) set_bitmode(bitmask, mode)

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:



278
279
280
 
# File 'lib/ftdi.rb', line 278

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

- (NilClass) set_line_property(bits, stopbits, parity)

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

Parameters:

Returns:

  • (NilClass) —

    nil

Raises:



245
246
247
 
# File 'lib/ftdi.rb', line 245

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

- (NilClass) set_line_property2(bits, stopbits, parity, _break)

Set (RS232) line characteristics.

Parameters:

Returns:

  • (NilClass) —

    nil

Raises:



256
257
258
 
# File 'lib/ftdi.rb', line 256

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

- (NilClass) usb_close

Closes the ftdi device.

Returns:

  • (NilClass) —

    nil



218
219
220
221
 
# File 'lib/ftdi.rb', line 218

def usb_close
  Ftdi.ftdi_usb_close(ctx)
  nil
end

- (NilClass) usb_open(vendor, product)

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.



172
173
174
175
176
 
# File 'lib/ftdi.rb', line 172

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

- (NilClass) usb_open_desc(vendor, product, description, serial)

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.



186
187
188
189
190
 
# File 'lib/ftdi.rb', line 186

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

- (NilClass) usb_open_desc_index(vendor, product, description, serial, index)

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.



201
202
203
204
205
206
207
 
# File 'lib/ftdi.rb', line 201

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

- (NilClass) usb_reset

Resets the ftdi device.

Returns:

  • (NilClass) —

    nil

Raises:



212
213
214
 
# File 'lib/ftdi.rb', line 212

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

- (Fixnum) write_data(bytes)

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:



307
308
309
310
311
312
313
314
315
 
# File 'lib/ftdi.rb', line 307

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

- (Fixnum) write_data_chunksize

Gets write buffer chunk size.

Returns:

  • (Fixnum) —

    Write buffer chunk size.

Raises:

See Also:



286
287
288
289
290
 
# File 'lib/ftdi.rb', line 286

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

- (Fixnum) write_data_chunksize=(new_chunksize)

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:



298
299
300
301
 
# File 'lib/ftdi.rb', line 298

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