libpropeller
Making PropellerGCC Easier
 All Classes Files Functions Variables Enumerations Enumerator Macros Pages
Public Member Functions | Static Public Attributes | List of all members
Serial Class Reference

A high speed and high accuracy serial driver. More...

#include <serial.h>

Public Member Functions

 ~Serial ()
 
bool Start (const int rxpin, const int txpin, const int rate, const int ctspin=-1)
 Start Serial driver in a new cog. More...
 
void Stop (void)
 Stops the Serial PASM engine, if it is running. More...
 
bool SetBaud (const int rate)
 Does a live update of the baud rate in the Serial engine. More...
 
bool SetBaudClock (const unsigned int rate, const unsigned int sysclock)
 Does a live update of the baud rate in the Serial engine. More...
 
void Put (const char character)
 Transmit a single character. More...
 
int Put (const char *buffer_ptr, const int count)
 Transmit a set of bytes. More...
 
int Put (const char *buffer_ptr)
 Transmit a C string. More...
 
int PutFormatted (const char *format,...)
 Transmit a string (printf function-alike). More...
 
int Get (const int timeout=-1)
 Receive a byte (wait) or timeout. More...
 
int Get (char *const buffer, const int length, const int timeout=-1)
 Get a buffer of characters. More...
 
int Get (char *const buffer, const char terminator= '\n')
 Get a terminated string of characters. More...
 
void GetFlush (void)
 Flushes receive buffer. More...
 
int GetCount (void) const
 Get the number of bytes in the receive buffer. More...
 

Static Public Attributes

static const int kBufferLength = 512
 Size of the RX buffer in bytes. More...
 

Detailed Description

A high speed and high accuracy serial driver.

Based on Fast Full-Duplex Serial 1 (FFDS1) version 0.9 by Jonathan Dummer (lonesock). C++ Port done by SRLM.

Serial provides a fast and stable serial interface using a single cog.

Max baudrate = clkfreq / (86 * 2)

Clock | MaxBaud | Standard ----—+------—+------— 96 MHz | 558_139 | 500_000 - 6MHz XTAL at 16x PLL 80 MHz | 465_116 | 460_800 - 5MHz XTAL at 16x PLL (most common) 12 MHz | 69_767 | 57_600 - approx RCFAST 20 kHz | 116 | hah hah - approx RCSLOW

Bit period is calculated to the nearest 2 clocks. So, the bit period should be within 1 clock, or 12.5 ns at 80 MHz.

Author
SRLM (srlm@.nosp@m.srlm.nosp@m.produ.nosp@m.ctio.nosp@m.ns.co.nosp@m.m)

Constructor & Destructor Documentation

Serial::~Serial ( )
inline

Here is the call graph for this function:

Member Function Documentation

int Serial::Get ( const int  timeout = -1)
inline

Receive a byte (wait) or timeout.

Warning
This function may block indefinitely if timeout is set to a negative value, and no data is received.

The timeout duration is a minimum, not a precise number. Experimental results indicate that a timeout of 10ms results in a total function time of 10.047ms.

Parameters
timeoutthe number of milliseconds to wait. Defaults to forever wait (negative timeout). Maximum value is 53000 milliseconds (no bounds checking).
Returns
-1 if no byte received, 0x00..0xFF if byte
int Serial::Get ( char *const  buffer,
const int  length,
const int  timeout = -1 
)
inline

Get a buffer of characters.

Parameters
bufferThe buffer to store the received characters in.
lengthThe maximum number of characters to read (may be less than length if timeout is enabled.
timeoutThe maximum amount of time to wait for each character, not the total time of the function.
Returns
the number of characters read. If less than length, then a timeout occurred.

Here is the call graph for this function:

int Serial::Get ( char *const  buffer,
const char  terminator = '\n' 
)
inline

Get a terminated string of characters.

Parameters
bufferThe buffer to store the received characters in. Note: an extra '\0' is always added to the end (null terminate).
terminatorThe last character to put into the buffer. On the first instance of this character, the function returns.
Returns
The number of characters read, including terminator. Does not include null terminator.

Here is the call graph for this function:

int Serial::GetCount ( void  ) const
inline

Get the number of bytes in the receive buffer.

void Serial::GetFlush ( void  )
inline

Flushes receive buffer.

void Serial::Put ( const char  character)
inline

Transmit a single character.

Parameters
characterthe byte to send.
int Serial::Put ( const char *  buffer_ptr,
const int  count 
)
inline

Transmit a set of bytes.

Parameters
buffer_ptrThe array of bytes to send.
countThe number of bytes to send.
Returns
The number of bytes actually sent. An error has occurred if this is less than strlen(buffer_ptr)

Here is the call graph for this function:

int Serial::Put ( const char *  buffer_ptr)
inline

Transmit a C string.

Parameters
buffer_ptrThe null terminated string to put. Note: does not transmit the trailing null.
Returns
The number of bytes actually sent. An error has occurred if this is less than strlen(buffer_ptr)

Here is the call graph for this function:

int Serial::PutFormatted ( const char *  format,
  ... 
)
inline

Transmit a string (printf function-alike).

This function is based on the requirements found on this page: http://www.cplusplus.com/reference/cstdio/printf/

Warning
This function does not implement the full printf functionality.

Formatters must follow the following prototype: %[flags][width]specifier The following flags are supported

  • 0 (only with x,X,b,B). Sets padding to the 0 character instead of space. This function supports the following specifiers:
  • d or i : signed decimal integer. The width specifier will pad with spaces if necessary.
  • x or X : hexadecimal integer. All caps (with either). The width specifier will pad with spaces (or 0s if the 0 flag is set) if necessary
  • c : output a single character.
  • s : output a string of characters, 0 terminated.
  • % : output a % symbol.

Each specifier must have a matching typed optional argument.

Behavior is undefined if % is used without a specifier.

Parameters
formatthe string to send, optionally with specifiers.
...additional arguments. Depending on the format string, the function may expect a sequence of additional arguments.
Returns
on success, the total number of characters written. On error, a negative number is returned.

Here is the call graph for this function:

bool Serial::SetBaud ( const int  rate)
inline

Does a live update of the baud rate in the Serial engine.

Parameters
ratedesired baud rate of the Serial engine.
Returns
true if the baud rate was achieved

Here is the call graph for this function:

bool Serial::SetBaudClock ( const unsigned int  rate,
const unsigned int  sysclock 
)
inline

Does a live update of the baud rate in the Serial engine.

Examples: got_desired_rate = SetBaudClock( 9600, CLKFREQ ) got_desired_rate = SetBaudClock( 9600, actual_sys_clock_freq )

Parameters
ratedesired baud rate of the Serial engine.
sysclockthe system clock (use CLKFREQ), or provide your own (useful when using RCFAST).
Returns
true if the baud rate was achieved
bool Serial::Start ( const int  rxpin,
const int  txpin,
const int  rate,
const int  ctspin = -1 
)
inline

Start Serial driver in a new cog.

Set any pin to -1 to disable it. No pin can match any other pin.

Parameters
rxpinthe pin [0..31] for incoming data.
txpinthe pin [0..31] for outgoing data.
ratethe initial baud rate in bits per second.
ctspincts is an input for control of flow from the tx pin. If high, it disables transmissions.
Returns
Returns true if the cog started OK, false otherwise

Here is the call graph for this function:

void Serial::Stop ( void  )
inline

Stops the Serial PASM engine, if it is running.

Frees a cog.

Member Data Documentation

const int Serial::kBufferLength = 512
static

Size of the RX buffer in bytes.

No restrictions on size (well, Hub RAM limits [8^) Does not need to be a power of 2. There is no TX buffer, Serial sends directly from Hub RAM.

For some reason, 117 seems to be the minimum buffer size before the tests start to lock up. Originally, it was 512. Seems safe to change, as long as it's >= 117.


The documentation for this class was generated from the following file: