srldrvce.h

#include <srldrvce.h>

The srldrvce library adds support for reading and writing serial devices in host mode, as well as emulating a serial device in device mode. This library is built on top of the usbdrvce library - data that is not serial in nature such as pictures, video, and audio may be more suited to using the usbdrvce library directly.

Currently this library is a work-in-progress, so some functionality may not behave as expected. This means that future library versions may create backwards-incompatible changes - however the likelihood of this is rather low as long as you use the library in a reasonable manner.

Tip

Be sure to look at the provided examples for guidance on how to use this library correctly. Hopefully in the future this page will include more documentation as the library becomes more complete.

API Documentation

This library sits on top of usbdrvce to act as a driver for serial devices. In addition to handling USB serial devices while in host mode, srldrvce can also emulate a serial device itself, which is useful for communicating with a computer with minimal setup required on the other end.

Author

John “commandblockguy” Cesarz

Defines

SRL_INTERFACE_ANY

Typedefs

typedef uint8_t srl_device_type_t
typedef uint8_t srl_device_subtype_t

Enums

enum [anonymous]

Values:

enumerator SRL_TYPE_UNKNOWN

Incompatible or non-serial device.

enumerator SRL_TYPE_HOST

Calc is acting as a device.

enumerator SRL_TYPE_CDC

CDC device.

enumerator SRL_TYPE_FTDI

FTDI device.

enumerator SRL_TYPE_PL2303

PL2303 device.

enum [anonymous]

Values:

enumerator SRL_SUBTYPE_FTDI_UNKNOWN = 0
enumerator SRL_SUBTYPE_SIO
enumerator SRL_SUBTYPE_FT8U232AM
enumerator SRL_SUBTYPE_FT232BM
enumerator SRL_SUBTYPE_FT2232C
enumerator SRL_SUBTYPE_FT232RL
enumerator SRL_SUBTYPE_FTX
enumerator SRL_SUBTYPE_FT2232H
enumerator SRL_SUBTYPE_FT4232H
enumerator SRL_SUBTYPE_FT232H
enum [anonymous]

Values:

enumerator SRL_SUBTYPE_PL2303_01 = 0
enumerator SRL_SUBTYPE_PL2303_HX
enum srl_error_t

Values:

enumerator SRL_SUCCESS = 0
enumerator SRL_ERROR_INVALID_PARAM = -1
enumerator SRL_ERROR_USB_FAILED = -2
enumerator SRL_ERROR_NOT_SUPPORTED = -3
enumerator SRL_ERROR_INVALID_DEVICE = -4
enumerator SRL_ERROR_INVALID_INTERFACE = -5
enumerator SRL_ERROR_NO_MEMORY = -6
enumerator SRL_ERROR_DEVICE_DISCONNECTED = -7

Functions

srl_error_t srl_Open(srl_device_t *srl, usb_device_t dev, void *buffer, size_t size, uint8_t interface, uint24_t rate)

Initialize a USB connected serial device.

Checks if the device is a valid serial device. Will perform all necessary initialization. A user-supplied buffer is needed for internal library use. This buffer must be at least 128 bytes in size. It should not be the same buffer used by other devices and/or functions.

Warning

Do not call from a USB event handler.

Parameters

  • srl – Serial device structure.

  • dev – USB device to initialize.

  • buffer – The buffer’s address. (must be at least size bytes).

  • size – The size of the buffer. Must be divisible by 2 and at least 128, but a size of 512 is recommended.

  • interface – The USB interface number to use, or SRL_INTERFACE_ANY for the first available interface.

  • rate – The baud rate to set the device to.

Returns

SRL_SUCCESS on success, otherwise error if initialization failed.

void srl_Close(srl_device_t *srl)

Closes and deinitializes a serial device.

This function should be called on the USB_DEVICE_DISCONNECTED_EVENT in the USB handler callback.

Parameters

srl – SRL device structure.

int srl_Read(srl_device_t *srl, void *data, size_t length)

Reads data from a serial device.

This is a non-blocking buffered read - if there are less that length bytes available in the buffer, all of the bytes in the buffer will be read.

Parameters

  • srl – SRL device structure.

  • data – Buffer to read into. Should be at least length bytes long.

  • length – Number of bytes to read.

Returns

The number of bytes read, or a negative number upon error.

int srl_Write(srl_device_t *srl, const void *data, size_t length)

Writes data to a serial device.

This is a non-blocking buffered write - if there is less than length bytes of space in the output buffer, not all of the data may be written.

Parameters

  • srl – SRL device structure.

  • data – Data to write to serial.

  • length – Number of bytes to write.

Returns

The number of bytes written, or a negative number upon error.

const usb_standard_descriptors_t *srl_GetCDCStandardDescriptors(void)

Returns a pointer to CDC ACM descriptors, to be used with usb_Init.

usb_error_t srl_UsbEventCallback(usb_event_t event, void *event_data, usb_callback_data_t *callback_data)

USB callback handler.

Can either be passed as the handler argument to usb_Init, or be delegated to from a custom USB event handler.

struct ring_buf_ctrl_t

Public Members

void *buf_start
void *buf_end
void *data_start
void *data_break
void *data_end
bool dma_active
struct srl_device_t

Public Members

usb_device_t dev

USB device.

An OUT endpoint if in device mode, an IN endpoint otherwise

uint8_t rx_addr

An IN endpoint if in device mode, an OUT endpoint otherwise.

uint8_t tx_addr
srl_device_type_t type
srl_device_subtype_t subtype
ring_buf_ctrl_t rx_buf
ring_buf_ctrl_t tx_buf
srl_error_t err
uint8_t reserved[16]