Serial Wombat Arduino Library
Public Member Functions | List of all members
SerialWombatUART Class Reference

A class for the Serial Wombat 4B which creates an I2C to UART Bridge. More...

#include <SerialWombatUART.h>

Inheritance diagram for SerialWombatUART:

Public Member Functions

 SerialWombatUART (SerialWombat &serialWombat)
 Constructor for the SerialWombatUART class. Only one instance is allowed per SerialWombat 4B. More...
 
void begin (int baudRate, uint8_t pin, uint8_t rxPin, uint8_t txPin)
 Initalize the SerialWombatUART.
More...
 
int available ()
 Queries the Serial Wombat for number bytes available to read. More...
 
int read ()
 Reads a byte from the Serial Wombat. More...
 
void flush ()
 Discard all received bytes. More...
 
int peek ()
 Query the Serial Wombat for the next avaialble byte, but don't remove it from the queue. More...
 
size_t write (uint8_t data)
 Write a byte to the Serial Wombat UART for Transmit. More...
 
size_t write (const uint8_t *buffer, size_t size)
 Write bytes to the Serial Wombat UART for Transmit. More...
 
int availableForWrite ()
 Queries the Serial Wombat for the amount of free TX queue space. More...
 
size_t readBytes (char *buffer, size_t length)
 Reads a specified number of bytes from the Serial Wombat RX queue. More...
 

Detailed Description

A class for the Serial Wombat 4B which creates an I2C to UART Bridge.

This class allows use of the Serial Wombat 4B's internal UART hardware to send and receive data at standard baud rates in 8-N-1 format.

A Tutorial video is avaialble:

https://youtu.be/C1FjcaiBYZs

The class inherits from the Arduino Sream class, so functions such as println() can be used once the UART is initialized.

The Serial Wombat 4B has a 64 byte transmit buffer and 128 byte receive buffer. Therefore, up to 64 bytes can be sent to the Serial Wombat at a time. Attempts to send more than that will result in the write, print, etc command blocking until space is available on the Serial Wombat to buffer the data.

Received data is buffered on the Serial Wombat until it is retreived from the host.

Warning
Due to the overhead of querying and retreiving data from the Serial Wombat, data loss is likely when receiving streams of data greater than the buffer size at higher baud rates.

To minimize this possiblity, read data frequently from the Serial Wombat, and set I2C frequency to 400kHz to maximize throughput.

This class can Send, Receive, or both. A single instance of this class is allowed per Serial Wombat 4B due to the fact that it relies on the PIC16F15214's UART module, of which there is only one on the micro.

A full Serial Wombat packet send / receive sequence (8 bytes in each direction) over I2C is necessary to query the status of the queues or to read or receive a byte of data.

The protocol becomes more efficient if multiple bytes are read or written using the readBytes or write(const uint8_t* buffer, size_t size) interfaces rather than read() or write(uint8_t data).

The class must be assigned to a pin. This may be either the receive or transmit pin.

Pin 0 on the Serial Wombat 4B is suggested as a receive pin as it has only input capability.

Available baud rates are:

Constructor & Destructor Documentation

◆ SerialWombatUART()

SerialWombatUART::SerialWombatUART ( SerialWombat serialWombat)

Constructor for the SerialWombatUART class. Only one instance is allowed per SerialWombat 4B.

Parameters
serialWombatThe Serial Wombat on which the SerialWombatUART instance will run.

Member Function Documentation

◆ available()

int SerialWombatUART::available ( )

Queries the Serial Wombat for number bytes available to read.

Returns
Number of bytes available to read.

◆ availableForWrite()

int SerialWombatUART::availableForWrite ( )

Queries the Serial Wombat for the amount of free TX queue space.

Returns
A value between 0 and 64 for the SW4B

◆ begin()

void SerialWombatUART::begin ( int  baudRate,
uint8_t  pin,
uint8_t  rxPin,
uint8_t  txPin 
)

Initalize the SerialWombatUART.

Parameters
baudRate300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
pinThe pin that will host the state machine. This can be either the rxPin or txPin
rxPinThe pin that will receive. All 4 pins on the SW4B may be used. 255 if no receive function is needed
txPinThe pin that will transmit. Valid values for the SW4B are 1-3. 255 if no transmit function is needed

◆ flush()

void SerialWombatUART::flush ( )

Discard all received bytes.

◆ peek()

int SerialWombatUART::peek ( )

Query the Serial Wombat for the next avaialble byte, but don't remove it from the queue.

Returns
A byte from 0-255, or -1 if no bytes were avaialble

◆ read()

int SerialWombatUART::read ( )

Reads a byte from the Serial Wombat.

Returns
A byte from 0-255, or -1 if no bytes were avaialble

◆ readBytes()

size_t SerialWombatUART::readBytes ( char *  buffer,
size_t  length 
)

Reads a specified number of bytes from the Serial Wombat RX queue.

Parameters
bufferAn array into which to put received bytes
lengthThe maximum number of bytes to be received
Returns
the number of bytes written to buffer

This function will read bytes from the Serial Wombat RX queue into buffer. If 'length' characters are not available to read then the value returned will be less than length.

◆ write() [1/2]

size_t SerialWombatUART::write ( const uint8_t *  buffer,
size_t  size 
)

Write bytes to the Serial Wombat UART for Transmit.

Parameters
bufferAn array of uint8_t bytes to send
sizethe number of bytes to send
Returns
the number of bytes sent

This function queries the Serial Wombat for avaialble TX buffer space, and sends bytes as buffer space is avaialble. If avaialable buffer space is not sufficient to send the entire array then the function will block and continue trying until the entire message has been sent to the Serial Wombat transmit queue.

◆ write() [2/2]

size_t SerialWombatUART::write ( uint8_t  data)

Write a byte to the Serial Wombat UART for Transmit.

Parameters
dataByte to write
Returns
Number of bytes written

This does not check to see if space is avaialble in order to improve perfomance . This isn't an issue at high baud rates, as overhead to transmit one byte at a time allows sufficent time for queuing data to be sent by the UART. This could be a problem at very low baud rates and high I2C bus speeds.