usb_com.h File Reference

#include <time.h>
#include <com.h>

Go to the source code of this file.

Typedefs
typedef void(	HandlerFunction) (void)

Functions
uint8	usbComRxControlSignals (void)
void	usbComTxControlSignals (uint8 signals)
void	usbComTxControlSignalEvents (uint8 signalEvents)
void	usbComService (void)
uint8	usbComRxAvailable (void)
uint8	usbComRxReceiveByte (void)
void	usbComRxReceive (uint8 XDATA *buffer, uint8 size)
uint8	usbComTxAvailable (void)
void	usbComTxSendByte (uint8 byte)
void	usbComTxSend (const uint8 XDATA *buffer, uint8 size)

Variables
ACM_LINE_CODING XDATA	usbComLineCoding
HandlerFunction *	usbComLineCodingChangeHandler

Detailed Description

The usb_com.lib library implements a virtual COM/serial port over USB using the CDC ACM class. See also com.h.

Definition in file usb_com.h.

Function Documentation

uint8 usbComRxAvailable

(

void

)

Returns

The number of bytes in the RX buffer that can be received immediately.

You can use this function to see if any bytes have been received, and then use usbComRxReceiveByte() to actually get the byte and process it.

The return value of this function might be lower than the actual number of bytes that the USB host is trying to send. Higher-level code should not count on the return value of this function reaching anything higher than 1.

Definition at line 299 of file usb_cdc_acm.c.

uint8 usbComRxControlSignals

(

void

)

This function returns the current state of the virtual RTS and DTR control lines. The states of these lines are controlled by the USB Host.

The default values are RTS=0 and DTR=0. In Windows, when a typical terminal program opens the COM port, both RTS and DTR go to 1. When the program closes the port, DTR goes to 0 but RTS remains at 1.

The bits of this byte are defined in com.h:

• Bit 0: ACM_CONTROL_LINE_DTR
• Bit 1: ACM_CONTROL_LINE_RTS
• Bit 2-7: Reserved (should always be zero)

Example:

if (usbComRxControlSignals() & ACM_CONTROL_LINE_DTR)
{
    // DTR is 1, which traditionally means the DTE (host) is present.
}
else
{
    // DTR is 0, which traditionally means the DTE (host) is not present.
}
if (usbComRxControlSignals() & ACM_CONTROL_LINE_RTS)
{
    // RTS is 1, which traditionally means "Activate carrier" or
    // tells DCE (device) to prepare to accept data from DTE (host).
}
else
{
    // RTS is 0, which traditionally means "Deactivate carrier".
}

Definition at line 515 of file usb_cdc_acm.c.

void usbComRxReceive	(	uint8 XDATA *	buffer,
		uint8	size
	)

Reads the specified number of bytes from USB and stores them in memory.

Parameters

buffer	The buffer to store the data in.
size	The number of bytes to read.

This is a non-blocking function: you must call usbComRxAvailable() before calling this function and be sure not to read too many bytes. The size parameter should not exceed the last value returned by usbComRxAvailable().

See also usbComRxReceiveByte().

Definition at line 343 of file usb_cdc_acm.c.

uint8 usbComRxReceiveByte

(

void

)

Returns

A byte from the RX buffer.

Bytes are returned in the order they were received from the USB host.

This is a non-blocking function: you must call usbComRxAvailable() before calling this function and be sure not to read too many bytes. The number of times you call this should not exceed the last value returned by usbComRxAvailable().

Definition at line 325 of file usb_cdc_acm.c.

void usbComService

(

void

)

This function should be called regularly (at least every 50 ms) if you are using this library. One of the things this function does is call usbPoll().

Definition at line 373 of file usb_cdc_acm.c.

uint8 usbComTxAvailable

(

void

)

Returns

The number of bytes available in the TX buffers.

The usb_cdc_acm.lib library uses a double-buffered endpoint with 64-byte buffers, so if the USB host keeps reading data from the device then this function will eventually return 128.

Definition at line 449 of file usb_cdc_acm.c.

void usbComTxControlSignalEvents

(

uint8

signalEvents

)

Allows you to report certain events to the USB host. Unlike CD and DSR, which represent the state of a control line, these represent events that happen at a particular time.

The valid bits of the signalEvents parameter are defined in com.h:

• Bit 2: ACM_SERIAL_STATE_BREAK
• Bit 3: ACM_SERIAL_STATE_RING_SIGNAL
• Bit 4: ACM_SERIAL_STATE_FRAMING
• Bit 5: ACM_SERIAL_STATE_PARITY
• Bit 6: ACM_SERIAL_STATE_OVERRUN
• Bits 0, 1, and 7: Reserved (should be zero).

You can report multiple events with one call to this function.

Example use:

if (uart0RxParityErrorOccurred)
{
    // A parity error occurred on UART 1.
    uart0RxParityErrorOccurred = 0;  // Clear the flag.
    usbComTxControlSignalEvents(ACM_SERIAL_STATE_PARITY);  // Report it to the USB host.
}

Definition at line 525 of file usb_cdc_acm.c.

void usbComTxControlSignals

(

uint8

signals

)

Sets the state of the virtual CD and DSR control lines. The value of these lines control lines are reported back to the USB host.

The valid bits of the signals parameter are defined in com.h:

• Bit 0: ACM_SERIAL_STATE_RX_CARRIER, a.k.a. CD or CdHolding
• Bit 1: ACM_SERIAL_STATE_TX_CARRIER, a.k.a. DSR or DsrHolding
• Bit 2-7: Reserved (should be zero).

Definition at line 520 of file usb_cdc_acm.c.

void usbComTxSend	(	const uint8 XDATA *	buffer,
		uint8	size
	)

Adds bytes to the TX buffers, which means they will be eventually sent to the USB host.

Parameters

buffer	A pointer to the bytes to send.
size	The number of bytes to send.

This is a non-blocking function: you must call usbComTxAvailable() before calling this function and be sure not to add too many bytes to the buffer. The size parameter should not exceed the last value returned by usbComTxAvailable().

Definition at line 477 of file usb_cdc_acm.c.

void usbComTxSendByte

(

uint8

byte

)

Adds a byte to the TX buffer, which means it will be eventually sent to the USB host.

Parameters

byte	The byte to send.

This is a non-blocking function: you must call usbComTxAvailable() before calling this function and be sure not to add too many bytes to the buffer. The number of times you call this should not exceed the last value returned by usbComTxAvailable().

Definition at line 498 of file usb_cdc_acm.c.

Variable Documentation

ACM_LINE_CODING XDATA usbComLineCoding

The current line coding. This includes information such as the desired baud rate, and is controlled by the USB host.

Definition at line 79 of file usb_cdc_acm.c.

HandlerFunction* usbComLineCodingChangeHandler

A pointer to a function that will be called whenever usbComLineCoding gets set by the USB host.

Definition at line 87 of file usb_cdc_acm.c.