\mainpage libftdi API documentation
Library to talk to FTDI chips. You find the latest versions of libftdi at
- http://www.intra2net.com/de/produkte/opensource/ftdi/
+ http://www.intra2net.com/en/developer/libftdi/
The library is easy to use. Have a look at this short example:
\include simple.c
}
/**
+ Allocate and initialize a new ftdi_context
+
+ \return a pointer to a new ftdi_context, or NULL on failure
+*/
+struct ftdi_context *ftdi_new()
+{
+ struct ftdi_context * ftdi = (struct ftdi_context *)malloc(sizeof(struct ftdi_context));
+
+ if (ftdi == NULL) {
+ return NULL;
+ }
+
+ if (ftdi_init(ftdi) != 0) {
+ free(ftdi);
+ return NULL;
+ }
+
+ return ftdi;
+}
+
+/**
Open selected channels on a chip, otherwise use first channel.
\param ftdi pointer to ftdi_context
}
/**
+ Deinitialize and free an ftdi_context.
+
+ \param ftdi pointer to ftdi_context
+*/
+void ftdi_free(struct ftdi_context *ftdi)
+{
+ ftdi_deinit(ftdi);
+ free(ftdi);
+}
+
+/**
Use an already open libusb device.
\param ftdi pointer to ftdi_context
curdev = devlist;
*curdev = NULL;
- for (bus = usb_busses; bus; bus = bus->next) {
+ for (bus = usb_get_busses(); bus; bus = bus->next) {
for (dev = bus->devices; dev; dev = dev->next) {
if (dev->descriptor.idVendor == vendor
&& dev->descriptor.idProduct == product)
}
/**
+ Frees a usb device list.
+
+ \param devlist USB device list created by ftdi_usb_find_all()
+*/
+void ftdi_list_free2(struct ftdi_device_list *devlist)
+{
+ ftdi_list_free(&devlist);
+}
+
+/**
Return device ID strings from the usb device.
The parameters manufacturer, description and serial may be NULL
\param dev libusb usb_dev to use
\retval 0: all fine
+ \retval -3: unable to config device
\retval -4: unable to open device
\retval -5: unable to claim device
\retval -6: reset failed
ftdi_error_return(-4, "usb_open() failed");
#ifdef LIBUSB_HAS_GET_DRIVER_NP
- // Try to detach ftdi_sio kernel module
- // Returns ENODATA if driver is not loaded
+ // Try to detach ftdi_sio kernel module.
+ // Returns ENODATA if driver is not loaded.
+ //
+ // The return code is kept in a separate variable and only parsed
+ // if usb_set_configuration() or usb_claim_interface() fails as the
+ // detach operation might be denied and everything still works fine.
+ // Likely scenario is a static ftdi_sio kernel module.
if (usb_detach_kernel_driver_np(ftdi->usb_dev, ftdi->interface) != 0 && errno != ENODATA)
detach_errno = errno;
#endif
+ // set configuration (needed especially for windows)
+ // tolerate EBUSY: one device with one configuration, but two interfaces
+ // and libftdi sessions to both interfaces (e.g. FT2232)
+ if (dev->descriptor.bNumConfigurations > 0 &&
+ usb_set_configuration(ftdi->usb_dev, dev->config[0].bConfigurationValue) &&
+ errno != EBUSY)
+ {
+ usb_close (ftdi->usb_dev);
+ if (detach_errno == EPERM) {
+ ftdi_error_return(-8, "inappropriate permissions on device!");
+ } else {
+ ftdi_error_return(-3, "unable to set usb configuration. Make sure ftdi_sio is unloaded!");
+ }
+ }
+
if (usb_claim_interface(ftdi->usb_dev, ftdi->interface) != 0) {
usb_close (ftdi->usb_dev);
if (detach_errno == EPERM) {
if (usb_find_devices() < 0)
ftdi_error_return(-2, "usb_find_devices() failed");
- for (bus = usb_busses; bus; bus = bus->next) {
+ for (bus = usb_get_busses(); bus; bus = bus->next) {
for (dev = bus->devices; dev; dev = dev->next) {
if (dev->descriptor.idVendor == vendor
&& dev->descriptor.idProduct == product) {
*/
int ftdi_usb_reset(struct ftdi_context *ftdi)
{
- if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 0, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
+ if (usb_control_msg(ftdi->usb_dev, SIO_RESET_REQUEST_TYPE,
+ SIO_RESET_REQUEST, SIO_RESET_SIO,
+ ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
ftdi_error_return(-1,"FTDI reset failed");
// Invalidate data in the readbuffer
}
/**
- Clears the buffers on the chip.
+ Clears the read buffer on the chip and the internal read buffer.
\param ftdi pointer to ftdi_context
\retval 0: all fine
- \retval -1: write buffer purge failed
- \retval -2: read buffer purge failed
+ \retval -1: read buffer purge failed
*/
-int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
+int ftdi_usb_purge_rx_buffer(struct ftdi_context *ftdi)
{
- if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 1, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
+ if (usb_control_msg(ftdi->usb_dev, SIO_RESET_REQUEST_TYPE,
+ SIO_RESET_REQUEST, SIO_RESET_PURGE_RX,
+ ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
ftdi_error_return(-1, "FTDI purge of RX buffer failed");
// Invalidate data in the readbuffer
ftdi->readbuffer_offset = 0;
ftdi->readbuffer_remaining = 0;
- if (usb_control_msg(ftdi->usb_dev, 0x40, 0, 2, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
- ftdi_error_return(-2, "FTDI purge of TX buffer failed");
+ return 0;
+}
+
+/**
+ Clears the write buffer on the chip.
+
+ \param ftdi pointer to ftdi_context
+
+ \retval 0: all fine
+ \retval -1: write buffer purge failed
+*/
+int ftdi_usb_purge_tx_buffer(struct ftdi_context *ftdi)
+{
+ if (usb_control_msg(ftdi->usb_dev, SIO_RESET_REQUEST_TYPE,
+ SIO_RESET_REQUEST, SIO_RESET_PURGE_TX,
+ ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
+ ftdi_error_return(-1, "FTDI purge of TX buffer failed");
+
+ return 0;
+}
+
+/**
+ Clears the buffers on the chip and the internal read buffer.
+
+ \param ftdi pointer to ftdi_context
+
+ \retval 0: all fine
+ \retval -1: read buffer purge failed
+ \retval -2: write buffer purge failed
+*/
+int ftdi_usb_purge_buffers(struct ftdi_context *ftdi)
+{
+ int result;
+
+ result = ftdi_usb_purge_rx_buffer(ftdi);
+ if (result < 0)
+ return -1;
+
+ result = ftdi_usb_purge_tx_buffer(ftdi);
+ if (result < 0)
+ return -2;
return 0;
}
: (baudrate * 21 < actual_baudrate * 20)))
ftdi_error_return (-1, "Unsupported baudrate. Note: bitbang baudrates are automatically multiplied by 4");
- if (usb_control_msg(ftdi->usb_dev, 0x40, 3, value, index, NULL, 0, ftdi->usb_write_timeout) != 0)
+ if (usb_control_msg(ftdi->usb_dev, SIO_SET_BAUDRATE_REQUEST_TYPE,
+ SIO_SET_BAUDRATE_REQUEST, value,
+ index, NULL, 0, ftdi->usb_write_timeout) != 0)
ftdi_error_return (-2, "Setting new baudrate failed");
ftdi->baudrate = baudrate;
}
/**
- Set (RS232) line characteristics by Alain Abbas
+ Set (RS232) line characteristics.
+ The break type can only be set via ftdi_set_line_property2()
+ and defaults to "off".
\param ftdi pointer to ftdi_context
\param bits Number of bits
int ftdi_set_line_property(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity)
{
+ return ftdi_set_line_property2(ftdi, bits, sbit, parity, BREAK_OFF);
+}
+
+/**
+ Set (RS232) line characteristics
+
+ \param ftdi pointer to ftdi_context
+ \param bits Number of bits
+ \param sbit Number of stop bits
+ \param parity Parity mode
+ \param break_type Break type
+
+ \retval 0: all fine
+ \retval -1: Setting line property failed
+*/
+int ftdi_set_line_property2(struct ftdi_context *ftdi, enum ftdi_bits_type bits,
+ enum ftdi_stopbits_type sbit, enum ftdi_parity_type parity,
+ enum ftdi_break_type break_type)
+{
unsigned short value = bits;
switch(parity) {
break;
}
- if (usb_control_msg(ftdi->usb_dev, 0x40, 0x04, value, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
+ switch(break_type) {
+ case BREAK_OFF:
+ value |= (0x00 << 14);
+ break;
+ case BREAK_ON:
+ value |= (0x01 << 14);
+ break;
+ }
+
+ if (usb_control_msg(ftdi->usb_dev, SIO_SET_DATA_REQUEST_TYPE,
+ SIO_SET_DATA_REQUEST, value,
+ ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
ftdi_error_return (-1, "Setting new line property failed");
return 0;
caller of completion or error - but this is not done yet, volunteers welcome.
Works around libusb and directly accesses functions only available on Linux.
+ Only available if compiled with --with-async-mode.
\param ftdi pointer to ftdi_context
\param buf Buffer with the data
}
/**
+ Poll modem status information
+
+ This function allows the retrieve the two status bytes of the device.
+ The device sends these bytes also as a header for each read access
+ where they are discarded by ftdi_read_data(). The chip generates
+ the two stripped status bytes in the absence of data every 40 ms.
+
+ Layout of the first byte:
+ - B0..B3 - must be 0
+ - B4 Clear to send (CTS)
+ 0 = inactive
+ 1 = active
+ - B5 Data set ready (DTS)
+ 0 = inactive
+ 1 = active
+ - B6 Ring indicator (RI)
+ 0 = inactive
+ 1 = active
+ - B7 Receive line signal detect (RLSD)
+ 0 = inactive
+ 1 = active
+
+ Layout of the second byte:
+ - B0 Data ready (DR)
+ - B1 Overrun error (OE)
+ - B2 Parity error (PE)
+ - B3 Framing error (FE)
+ - B4 Break interrupt (BI)
+ - B5 Transmitter holding register (THRE)
+ - B6 Transmitter empty (TEMT)
+ - B7 Error in RCVR FIFO
+
+ \param ftdi pointer to ftdi_context
+ \param status Pointer to store status information in. Must be two bytes.
+
+ \retval 0: all fine
+ \retval -1: unable to retrieve status information
+*/
+int ftdi_poll_modem_status(struct ftdi_context *ftdi, unsigned short *status)
+{
+ char usb_val[2];
+
+ if (usb_control_msg(ftdi->usb_dev, 0xC0, 0x05, 0, ftdi->index, usb_val, 2, ftdi->usb_read_timeout) != 2)
+ ftdi_error_return(-1, "getting modem status failed");
+
+ *status = (usb_val[1] << 8) | usb_val[0];
+
+ return 0;
+}
+
+/**
+ Set flowcontrol for ftdi chip
+
+ \param ftdi pointer to ftdi_context
+ \param flowctrl flow control to use. should be
+ SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
+
+ \retval 0: all fine
+ \retval -1: set flow control failed
+*/
+int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
+{
+ if (usb_control_msg(ftdi->usb_dev, SIO_SET_FLOW_CTRL_REQUEST_TYPE,
+ SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->index),
+ NULL, 0, ftdi->usb_write_timeout) != 0)
+ ftdi_error_return(-1, "set flow control failed");
+
+ return 0;
+}
+
+/**
+ Set dtr line
+
+ \param ftdi pointer to ftdi_context
+ \param state state to set line to (1 or 0)
+
+ \retval 0: all fine
+ \retval -1: set dtr failed
+*/
+int ftdi_setdtr(struct ftdi_context *ftdi, int state)
+{
+ unsigned short usb_val;
+
+ if (state)
+ usb_val = SIO_SET_DTR_HIGH;
+ else
+ usb_val = SIO_SET_DTR_LOW;
+
+ if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
+ SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
+ NULL, 0, ftdi->usb_write_timeout) != 0)
+ ftdi_error_return(-1, "set dtr failed");
+
+ return 0;
+}
+
+/**
+ Set rts line
+
+ \param ftdi pointer to ftdi_context
+ \param state state to set line to (1 or 0)
+
+ \retval 0: all fine
+ \retval -1 set rts failed
+*/
+int ftdi_setrts(struct ftdi_context *ftdi, int state)
+{
+ unsigned short usb_val;
+
+ if (state)
+ usb_val = SIO_SET_RTS_HIGH;
+ else
+ usb_val = SIO_SET_RTS_LOW;
+
+ if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
+ SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
+ NULL, 0, ftdi->usb_write_timeout) != 0)
+ ftdi_error_return(-1, "set of rts failed");
+
+ return 0;
+}
+
+/**
+ Set dtr and rts line in one pass
+
+ \param ftdi pointer to ftdi_context
+ \param dtr DTR state to set line to (1 or 0)
+ \param rts RTS state to set line to (1 or 0)
+
+ \retval 0: all fine
+ \retval -1 set dtr/rts failed
+ */
+int ftdi_setdtr_rts(struct ftdi_context *ftdi, int dtr, int rts)
+{
+ unsigned short usb_val;
+
+ if (dtr)
+ usb_val = SIO_SET_DTR_HIGH;
+ else
+ usb_val = SIO_SET_DTR_LOW;
+
+ if (rts)
+ usb_val |= SIO_SET_RTS_HIGH;
+ else
+ usb_val |= SIO_SET_RTS_LOW;
+
+ if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
+ SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->index,
+ NULL, 0, ftdi->usb_write_timeout) != 0)
+ ftdi_error_return(-1, "set of rts/dtr failed");
+
+ return 0;
+}
+
+/**
+ Set the special event character
+
+ \param ftdi pointer to ftdi_context
+ \param eventch Event character
+ \param enable 0 to disable the event character, non-zero otherwise
+
+ \retval 0: all fine
+ \retval -1: unable to set event character
+*/
+int ftdi_set_event_char(struct ftdi_context *ftdi,
+ unsigned char eventch, unsigned char enable)
+{
+ unsigned short usb_val;
+
+ usb_val = eventch;
+ if (enable)
+ usb_val |= 1 << 8;
+
+ if (usb_control_msg(ftdi->usb_dev, 0x40, 0x06, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
+ ftdi_error_return(-1, "setting event character failed");
+
+ return 0;
+}
+
+/**
+ Set error character
+
+ \param ftdi pointer to ftdi_context
+ \param errorch Error character
+ \param enable 0 to disable the error character, non-zero otherwise
+
+ \retval 0: all fine
+ \retval -1: unable to set error character
+*/
+int ftdi_set_error_char(struct ftdi_context *ftdi,
+ unsigned char errorch, unsigned char enable)
+{
+ unsigned short usb_val;
+
+ usb_val = errorch;
+ if (enable)
+ usb_val |= 1 << 8;
+
+ if (usb_control_msg(ftdi->usb_dev, 0x40, 0x07, usb_val, ftdi->index, NULL, 0, ftdi->usb_write_timeout) != 0)
+ ftdi_error_return(-1, "setting error character failed");
+
+ return 0;
+}
+
+/**
Set the eeprom size
\param ftdi pointer to ftdi_context
output[0x07] = 0x02;
// Addr 08: Config descriptor
- // Bit 1: remote wakeup if 1
- // Bit 0: self powered if 1
- //
- j = 0;
+ // Bit 7: always 1
+ // Bit 6: 1 if this device is self powered, 0 if bus powered
+ // Bit 5: 1 if this device uses remote wakeup
+ // Bit 4: 1 if this device is battery powered
+ j = 0x80;
if (eeprom->self_powered == 1)
- j = j | 1;
+ j |= 0x40;
if (eeprom->remote_wakeup == 1)
- j = j | 2;
+ j |= 0x20;
output[0x08] = j;
// Addr 09: Max power consumption: max power = value * 2 mA
output[0x09] = eeprom->max_power;
- ;
// Addr 0A: Chip configuration
// Bit 7: 0 - reserved
return ftdi->error_str;
}
-/*
- Flow control code by Lorenz Moesenlechner (lorenz@hcilab.org)
- and Matthias Kranz (matthias@hcilab.org)
-*/
-/**
- Set flowcontrol for ftdi chip
-
- \param ftdi pointer to ftdi_context
- \param flowctrl flow control to use. should be
- SIO_DISABLE_FLOW_CTRL, SIO_RTS_CTS_HS, SIO_DTR_DSR_HS or SIO_XON_XOFF_HS
-
- \retval 0: all fine
- \retval -1: set flow control failed
-*/
-int ftdi_setflowctrl(struct ftdi_context *ftdi, int flowctrl)
-{
- if (usb_control_msg(ftdi->usb_dev, SIO_SET_FLOW_CTRL_REQUEST_TYPE,
- SIO_SET_FLOW_CTRL_REQUEST, 0, (flowctrl | ftdi->interface),
- NULL, 0, ftdi->usb_write_timeout) != 0)
- ftdi_error_return(-1, "set flow control failed");
-
- return 0;
-}
-
-/**
- Set dtr line
-
- \param ftdi pointer to ftdi_context
- \param state state to set line to (1 or 0)
-
- \retval 0: all fine
- \retval -1: set dtr failed
-*/
-int ftdi_setdtr(struct ftdi_context *ftdi, int state)
-{
- unsigned short usb_val;
-
- if (state)
- usb_val = SIO_SET_DTR_HIGH;
- else
- usb_val = SIO_SET_DTR_LOW;
-
- if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
- SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->interface,
- NULL, 0, ftdi->usb_write_timeout) != 0)
- ftdi_error_return(-1, "set dtr failed");
-
- return 0;
-}
-
-/**
- Set rts line
-
- \param ftdi pointer to ftdi_context
- \param state state to set line to (1 or 0)
-
- \retval 0: all fine
- \retval -1 set rts failed
-*/
-int ftdi_setrts(struct ftdi_context *ftdi, int state)
-{
- unsigned short usb_val;
-
- if (state)
- usb_val = SIO_SET_RTS_HIGH;
- else
- usb_val = SIO_SET_RTS_LOW;
-
- if (usb_control_msg(ftdi->usb_dev, SIO_SET_MODEM_CTRL_REQUEST_TYPE,
- SIO_SET_MODEM_CTRL_REQUEST, usb_val, ftdi->interface,
- NULL, 0, ftdi->usb_write_timeout) != 0)
- ftdi_error_return(-1, "set of rts failed");
-
- return 0;
-}
-
/* @} end of doxygen libftdi group */