Detailed Description

ClearCore ARM Serial Port base class.

This class is used to create a buffered serial port.

ClearCore ARM Serial Port base class. More...

#include <SerialBase.h>

Inheritance diagram for ClearCore::SerialBase:

Collaboration diagram for ClearCore::SerialBase:

Classes
union	SerialErrorStatusRegister

Public Types
enum	DataOrders { COM_MSB_FIRST = 0, COM_LSB_FIRST = 1 }

enum	PortModes { UART, SPI }

enum	SpiClockPolarities { SCK_LOW = 0, SCK_HIGH }

enum	SpiClockPhases { LEAD_SAMPLE = 0, LEAD_CHANGE }

enum	CtrlLineModes { LINE_OFF, LINE_ON, LINE_HW }

Public Types inherited from ClearCore::ISerial
enum	_Parities { PARITY_E = 0, PARITY_O, PARITY_N }

typedef enum ClearCore::ISerial::_Parities	Parities

Public Member Functions
bool	PortMode (PortModes newMode)
	Setup the port mode. More...

void	Flush () override

void	FlushInput () override

virtual void	PortOpen () override

virtual void	PortClose () override

virtual bool	Speed (uint32_t bitsPerSecond) override
	Change the baud rate for the port. More...

virtual uint32_t	Speed () override
	Gets the baud rate of the port. More...

int16_t	CharGet () override
	Attempt to read the next character from serial channel. More...

int16_t	CharPeek () override
	Attempt to get the next character from the serial channel without pulling the character out of the buffer. More...

bool	SendChar (uint8_t charToSend) override
	Send an ascii character on the serial channel. More...

int32_t	AvailableForRead () override

int32_t	AvailableForWrite () override
	Determines the number of characters available in the transmit buffer. More...

void	WaitForTransmitIdle () override

bool	PortIsOpen () override
	Return whether or not the port is open. More...

void	FlowControl (bool useFlowControl)
	Set UART CTS/RTS flow control. More...

bool	FlowControl ()
	Return whether UART CTS/RTS flow control is enabled. More...

bool	RtsMode (CtrlLineModes mode)
	Change the serial RTS mode. More...

bool	CtsState ()
	Read the serial CTS state. More...

void	SerialBreak (bool enable)
	Initiate a Serial Break. More...

bool	Parity (Parities newParity) override
	Set UART transmission parity format. More...

Parities	Parity () override
	Return current port UART transmission format. More...

bool	StopBits (uint8_t bits) override

bool	CharSize (uint8_t size) override
	Change the number of bits in a character. More...

void	SpiClock (SpiClockPolarities polarity, SpiClockPhases phase)
	Change the polarity and phase for the SPI clock. More...

bool	SpiSsMode (CtrlLineModes mode)
	Change the SPI Slave Select mode. More...

uint8_t	SpiTransferData (uint8_t data)

int32_t	SpiTransferData (uint8_t const writeBuf, uint8_t readBuf, int32_t len)
	SPI's multi-byte transmit and receive function. More...

bool	SpiTransferDataAsync (uint8_t const writeBuf, uint8_t readBuf, int32_t len)
	SPI's asynchronous multi-byte transmit and receive function. More...

bool	SpiAsyncWaitComplete ()
	Block until asynchronous transfers are completed. More...

void	DataOrder (DataOrders newOrder)
	Change the data order for the port. More...

void	HandleFrameError ()

void	HandleParityError ()

void	HandleOverflow ()

SerialErrorStatusRegister	ErrorStatusAccum (SerialErrorStatusRegister mask=UINT32_MAX)
	Accumulating clear on read accessor for any error status bits that were asserted sometime since the previous invocation of this function. More...

Public Member Functions inherited from ClearCore::ISerial
bool	SendLine ()
	Send carriage return and newline characters. More...

bool	Send (const char *buffer, size_t bufferSize)
	Send the array of characters out the port. More...

bool	SendLine (const char *buffer, size_t bufferSize)
	Send the array of characters out the port. Terminate the line with carriage return and newline characters. More...

bool	Send (const char *nullTermStr)
	Send a string of characters out the port. More...

bool	SendLine (const char *nullTermStr)
	Send a string of characters out the port. Terminate the line with carriage return and newline characters. More...

bool	Send (char theChar)
	Send a character to be printed to the serial port. More...

bool	SendLine (char theChar)
	Send a character to be printed to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (double number, uint8_t precision=2)
	Send a floating point number to the serial port. More...

bool	SendLine (double number, uint8_t precision=2)
	Send a floating point number to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (int8_t number, uint8_t radix=10)
	Send an 8-bit signed number to be printed to the serial port. More...

bool	SendLine (int8_t number, uint8_t radix=10)
	Send an 8-bit signed number to be printed to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (uint8_t number, uint8_t radix=10)
	Send an 8-bit unsigned number to be printed to the serial port. More...

bool	SendLine (uint8_t number, uint8_t radix=10)
	Send an 8-bit unsigned number to be printed to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (int16_t number, uint8_t radix=10)
	Send a 16-bit signed number to be printed to the serial port. More...

bool	SendLine (int16_t number, uint8_t radix=10)
	Send a 16-bit signed number to be printed to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (uint16_t number, uint8_t radix=10)
	Send a 16-bit unsigned number to be printed to the serial port. More...

bool	SendLine (uint16_t number, uint8_t radix=10)
	Send a 16-bit unsigned number to be printed to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (int32_t number, uint8_t radix=10)
	Send a 32-bit signed number to be printed to the serial port. More...

bool	SendLine (int32_t number, uint8_t radix=10)
	Send a 32-bit signed number to be printed to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (uint32_t number, uint8_t radix=10)
	Send a 32-bit unsigned number to be printed to the serial port. More...

bool	SendLine (uint32_t number, uint8_t radix=10)
	Send a 32-bit unsigned number to be printed to the serial port. Terminate the line with carriage return and newline characters. More...

bool	Send (int number, uint8_t radix=10)
	Send an integer to be printed to the serial port. More...

bool	SendLine (int number, uint8_t radix=10)
	Send an integer to be printed to the serial port. More...

virtual	operator bool ()=0

Static Public Attributes
static const int16_t	BREAK_DETECTED = int16_t(0xBDBD)

static const int16_t	EOB = -1

Member Enumeration Documentation

enum ClearCore::SerialBase::CtrlLineModes

Modes for the serial port control lines.

Enumerator
LINE_OFF	Control line is in the OFF state.
LINE_ON	Control line is in the ON state.
LINE_HW	Control line is controlled by hardware.

enum ClearCore::SerialBase::DataOrders

MSB-first or LSB-first data order.

Enumerator
COM_MSB_FIRST	Most significant bit first.
COM_LSB_FIRST	Least significant bit first.

enum ClearCore::SerialBase::PortModes

Sets the serial port into Asynchronous vs SPI mode.

Enumerator
UART	Universal Asynchronous Receiver-Transmitter (UART) mode.
SPI	Serial Peripheral Interface (SPI) mode.

enum ClearCore::SerialBase::SpiClockPhases

The SPI clock phase settings.

Enumerator
LEAD_SAMPLE	Leading edge samples, trailing edge changes.
LEAD_CHANGE	Leading edge changes, trailing edge samples.

enum ClearCore::SerialBase::SpiClockPolarities

The different polarities for the SPI clock.

Enumerator
SCK_LOW	SCK is low when idle.
SCK_HIGH	SCK is high when idle.

Member Function Documentation

int32_t ClearCore::SerialBase::AvailableForRead ( )

overridevirtual

Returns number of characters waiting in the receive buffer.

Implements ClearCore::ISerial.

int32_t ClearCore::SerialBase::AvailableForWrite ( )

overridevirtual

Determines the number of characters available in the transmit buffer.

if (ConnectorCOM0.AvailableForWrite() < 10) {
    // There are less than 10 free characters in COM-0's transmit buffer
}

Returns: Returns number of free characters in transmit buffer

Implements ClearCore::ISerial.

int16_t ClearCore::SerialBase::CharGet ( )

overridevirtual

Attempt to read the next character from serial channel.

Returns: Returns the first character in the serial buffer, or SerialBase::EOB if no data are available. If a character is found, it will be consumed and removed from the serial buffer.

Implements ClearCore::ISerial.

int16_t ClearCore::SerialBase::CharPeek ( )

overridevirtual

Attempt to get the next character from the serial channel without pulling the character out of the buffer.

Returns: Returns the first character in the serial buffer, or SerialBase::EOB if no data are available. If a character is found, it will not be consumed, and will remain in the serial buffer for reading.

Implements ClearCore::ISerial.

bool ClearCore::SerialBase::CharSize ( uint8_t size )

overridevirtual

Change the number of bits in a character.

For UART mode valid settings are: 5, 6, 7, 8, or 9. For SPI mode valid settings are: 8 or 9.

// Sets COM-0 to have a 9-bit character size

ConnectorCOM1.CharSize(9);

Implements ClearCore::ISerial.

bool ClearCore::SerialBase::CtsState ( )

Read the serial CTS state.

if (ConnectorCOM0.CtsState()) {
    // COM-0's CTS pin is logical LINE_ON.
}

Returns: Returns true if the CTS pin is LINE_ON.

void ClearCore::SerialBase::DataOrder ( DataOrders newOrder )

Change the data order for the port.

For UART, this should most likely be set to COM_LSB_FIRST.

SerialErrorStatusRegister ClearCore::SerialBase::ErrorStatusAccum ( SerialErrorStatusRegister mask = UINT32_MAX )

Accumulating clear on read accessor for any error status bits that were asserted sometime since the previous invocation of this function.

// See if an overflow error has occurred on COM-0 since the last poll.
bool serialOverflowError =
    ConnectorCOM0.ErrorStatusAccum().bit.SerialOverflowError;
if (serialOverflowError) {
    // Deal with the overflow.
}

Parameters

[in] mask (optional) A SerialErrorStatusRegister whose asserted bits indicate which of the error status bits to check for an asserted state. If one of the bit members of this mask are deasserted, that bit will be ignored when checking for asserted status bits. If no mask is provided, it's equivalent to passing a SerialErrorStatusRegister with all bits asserted, in which case this function would report any accumulated asserted error status bits.

Returns: SerialErrorStatusRegister whose asserted bits indicate which serial error status bits have been asserted since the last poll.

void ClearCore::SerialBase::FlowControl ( bool useFlowControl )

Set UART CTS/RTS flow control.

ConnectorCOM0.FlowControl(true);

Parameters

[in] useFlowControl The new flow control setting.

Note: Flow control is off by default. Some XBee devices have flow control enabled by default. If using an XBee device, the ClearCore flow control setting should match the XBee device setting.

bool ClearCore::SerialBase::FlowControl ( )

inline

Return whether UART CTS/RTS flow control is enabled.

if (ConnectorCOM0.FlowControl()) {
    // COM-0's flow control is enabled
}

Returns: Returns true if port flow control setting is enabled.

void ClearCore::SerialBase::Flush ( )

overridevirtual

Flush the serial port's transmit buffer

// Flush COM-0's transmit buffer

ConnectorCOM0.Flush();

Implements ClearCore::ISerial.

void ClearCore::SerialBase::FlushInput ( )

overridevirtual

Flush the serial port's receive buffer

// Flush COM-0's receive buffer

ConnectorCOM0.FlushInput();

Implements ClearCore::ISerial.

void ClearCore::SerialBase::HandleFrameError ( )

Handles frame errors by clearing the error flag and raising an internal warning flag.

void ClearCore::SerialBase::HandleOverflow ( )

Handles overflow errors by clearing the error flag and raising an internal warning flag.

void ClearCore::SerialBase::HandleParityError ( )

Handles parity errors by clearing the error flag and raising an internal warning flag.

bool ClearCore::SerialBase::Parity ( Parities newParity )

overridevirtual

Set UART transmission parity format.

if (ConnectorCOM1.Parity(SerialBase::PARITY_O)) {
    // Setting COM-1's parity format to odd was successful
}

Returns: Returns true if port accepted the format change request.

Implements ClearCore::ISerial.

Parities ClearCore::SerialBase::Parity ( )

inlineoverridevirtual

Return current port UART transmission format.

if (ConnectorCOM0.Parity() == SerialBase::PARITY_O) {
    // COM-0's parity format is set to odd
}

Returns: Returns transmission format enumeration.

Implements ClearCore::ISerial.

virtual void ClearCore::SerialBase::PortClose ( )

overridevirtual

Shut down the port

// Close COM-0's serial port

ConnectorCOM0.PortClose();

Implements ClearCore::ISerial.

Reimplemented in ClearCore::SerialDriver.

bool ClearCore::SerialBase::PortIsOpen ( )

overridevirtual

Return whether or not the port is open.

if (ConnectorCOM0.PortIsOpen()) {
    // COM-0's port is currently open
}

Returns: True if the port is open, and false otherwise.

Implements ClearCore::ISerial.

bool ClearCore::SerialBase::PortMode ( PortModes newMode )

Setup the port mode.

Puts the port into SPI or UART mode for subsequent transfers.

if (ConnectorCOM1.PortMode(SerialBase::UART)) {
    // Setting COM-1's mode to UART was successful
}

Parameters

[in] newMode The requested serial mode.

Returns: Returns true if the mode is successfully set.

virtual void ClearCore::SerialBase::PortOpen ( )

overridevirtual

Set up the port to allow operations

// Open COM-0's serial port

ConnectorCOM0.PortOpen();

Implements ClearCore::ISerial.

Reimplemented in ClearCore::SerialDriver.

bool ClearCore::SerialBase::RtsMode ( CtrlLineModes mode )

Change the serial RTS mode.

if (ConnectorCOM0.RtsMode(SerialBase::LINE_ON)) {
    // COM-0's RTS line has asserted successfully
}

Parameters

[in] mode The desired RTS pin mode.

Returns: Returns true if the mode was set.

Note: Using LINE_HW with FlowControl enabled will assert RTS when the Serial Port is ready to receive data.

bool ClearCore::SerialBase::SendChar ( uint8_t charToSend )

overridevirtual

Send an ascii character on the serial channel.

Parameters

[in] charToSend The character to be sent

Returns: success

Implements ClearCore::ISerial.

void ClearCore::SerialBase::SerialBreak ( bool enable )

Initiate a Serial Break.

// Enables a serial break on COM-0

ConnectorCOM1.SerialBreak(true);

Parameters

[in] enable true enables a serial break, false disables a serial break

virtual bool ClearCore::SerialBase::Speed ( uint32_t bitsPerSecond )

overridevirtual

Change the baud rate for the port.

if (ConnectorCOM0.Speed(9600)) {
    // Setting COM-0's baud to 9600 bps was successful
}

Parameters

[in] bitsPerSecond The new speed setting

Returns: Returns true if port accepted the speed request. Will return false if the baud rate gets clipped for SPI mode.

Implements ClearCore::ISerial.

Reimplemented in ClearCore::SerialDriver.

virtual uint32_t ClearCore::SerialBase::Speed ( )

inlineoverridevirtual

Gets the baud rate of the port.

// Saves COM-0's current speed setting

uint32_t serialSpeed = ConnectorCOM1.Speed();

Returns: Returns port speed in bits per second.

Implements ClearCore::ISerial.

bool ClearCore::SerialBase::SpiAsyncWaitComplete ( )

Block until asynchronous transfers are completed.

Returns: True when all asynchronous transfers are completed. Does not return false.

void ClearCore::SerialBase::SpiClock	(	SpiClockPolarities	polarity,
		SpiClockPhases	phase
	)

Change the polarity and phase for the SPI clock.

// Set up COM-0's SPI clock

ConnectorCOM0.SpiClock(SerialBase::SCK_HIGH, SerialBase::LEAD_SAMPLE);

bool ClearCore::SerialBase::SpiSsMode ( CtrlLineModes mode )

Change the SPI Slave Select mode.

if (ConnectorCOM0.SpiSsMode(SerialBase::LINE_HIGH)) {
    // COM-0's SPI slave select mode set to high successfully
}

Parameters

[in] mode The desired SS pin mode.

Returns: Returns true if the mode was set.

uint8_t ClearCore::SerialBase::SpiTransferData ( uint8_t data )

SPI's transmit and receive function

int32_t ClearCore::SerialBase::SpiTransferData	(	uint8_t const *	writeBuf,
		uint8_t *	readBuf,
		int32_t	len
	)

SPI's multi-byte transmit and receive function.

This can be used to send/receive a buffer's worth of data. The SPI channel will be commanded to transfer a byte at a time for the given len of bytes. The data transferred out will come from the writeBuf or a dummy value, and the data received in will be written to the readBuf or a dummy value.

Parameters

[in]	writeBuf	A pointer to the beginning of the data to write
[in]	readBuf	A pointer to the beginning of a read destination for the data in the serial port
[in]	len	The maximum number of bytes to read and write

Returns: The number of bytes written or read.

bool ClearCore::SerialBase::SpiTransferDataAsync	(	uint8_t const *	writeBuf,
		uint8_t *	readBuf,
		int32_t	len
	)

SPI's asynchronous multi-byte transmit and receive function.

This can be used to send/receive a buffer's worth of data. The SPI channel will be commanded to transfer len of bytes asynchronously via the Direct Memory Access Controller. The data transferred out will come from the writeBuf or a dummy value, and the data received in will be written to the readBuf or a dummy value.

Parameters

[in]	writeBuf	A pointer to the beginning of the data to write
[in]	readBuf	A pointer to the beginning of a read destination for the data in the serial port
[in]	len	The maximum number of bytes to read and write