libpropeller::Serial Class Reference

#include <libpropeller/libpropeller/mtk3339/serial.h>

Inheritance diagram for libpropeller::Serial:

Collaboration diagram for libpropeller::Serial:

Public Member Functions
bool	Start (const int rxpin, const int txpin, const int rate, const int ctspin=-1)
void	Stop (void)
bool	SetBaud (const int rate)
bool	SetBaudClock (const unsigned int rate, const unsigned int sysclock)
void	Put (const char character)
int	Put (const char *buffer_ptr, const int count)
int	Put (const char *buffer_ptr)
int	Get (const int timeout=-1)
int	Get (char *const buffer, const int length, const int timeout=-1)
int	Get (char *const buffer, const char terminator='\n')
void	GetFlush (void)
int	GetCount (void) const
int	PutFormatted (const char *formatString,...)
bool	Start (const int rxpin, const int txpin, const int rate, const int ctspin=-1)
void	Stop (void)
bool	SetBaud (const int rate)
bool	SetBaudClock (const unsigned int rate, const unsigned int sysclock)
void	Put (const char character)
int	Put (const char *buffer_ptr, const int count)
int	Put (const char *buffer_ptr)
int	Get (const int timeout=-1)
int	Get (char *const buffer, const int length, const int timeout=-1)
int	Get (char *const buffer, const char terminator='\n')
void	GetFlush (void)
int	GetCount (void) const
int	PutFormatted (const char *formatString,...)

Static Public Attributes
static const int	kBufferLength = 512

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)

Examples

Hello_Demo.cpp.

Definition at line 35 of file serial.h.

Member Function Documentation

Get() [1/6]

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

Get a terminated string of characters

Parameters

buffer	The buffer to store the received characters in. Note: an extra '\0' is always added to the end (null terminate).
terminator	The 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.

Definition at line 284 of file serial.h.

Here is the call graph for this function:

Get() [2/6]

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

Get a terminated string of characters

Parameters

buffer	The buffer to store the received characters in. Note: an extra '\0' is always added to the end (null terminate).
terminator	The 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.

Definition at line 284 of file serial.h.

Here is the call graph for this function:

Get() [3/6]

int libpropeller::Serial::Get	(	char *const	buffer,
		const int	length,
		const int	timeout = -1
	)

Get a buffer of characters

Parameters

buffer	The buffer to store the received characters in.
length	The maximum number of characters to read (may be less than length if timeout is enabled.
timeout	The 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.

Definition at line 261 of file serial.h.

Here is the call graph for this function:

Get() [4/6]

int libpropeller::Serial::Get	(	char *const	buffer,
		const int	length,
		const int	timeout = -1
	)

Get a buffer of characters

Parameters

buffer	The buffer to store the received characters in.
length	The maximum number of characters to read (may be less than length if timeout is enabled.
timeout	The 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.

Definition at line 261 of file serial.h.

Here is the call graph for this function:

Get() [5/6]

int libpropeller::Serial::Get

(

const int

timeout = -1

)

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

timeout

the 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

Definition at line 226 of file serial.h.

Here is the call graph for this function:

Get() [6/6]

int libpropeller::Serial::Get

(

const int

timeout = -1

)

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

timeout

the 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

Definition at line 226 of file serial.h.

Here is the call graph for this function:

Here is the caller graph for this function:

GetCount() [1/2]

int libpropeller::Serial::GetCount

(

void

)

const

Get the number of bytes in the receive buffer.

Definition at line 303 of file serial.h.

GetCount() [2/2]

int libpropeller::Serial::GetCount

(

void

)

const

Get the number of bytes in the receive buffer.

Definition at line 303 of file serial.h.

GetFlush() [1/2]

void libpropeller::Serial::GetFlush

(

void

)

Flushes receive buffer.

Definition at line 297 of file serial.h.

GetFlush() [2/2]

void libpropeller::Serial::GetFlush

(

void

)

Flushes receive buffer.

Definition at line 297 of file serial.h.

Put() [1/6]

int libpropeller::Serial::Put

(

const char *

buffer_ptr

)

Transmit a C string.

Parameters

buffer_ptr

The 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)

Definition at line 206 of file serial.h.

Here is the call graph for this function:

Put() [2/6]

int libpropeller::Serial::Put

(

const char *

buffer_ptr

)

Transmit a C string.

Parameters

buffer_ptr

The 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)

Definition at line 206 of file serial.h.

Here is the call graph for this function:

Put() [3/6]

int libpropeller::Serial::Put	(	const char *	buffer_ptr,
		const int	count
	)

Transmit a set of bytes.

Parameters

buffer_ptr	The array of bytes to send.
count	The number of bytes to send.

Returns

The number of bytes actually sent. An error has occurred if this is less than strlen(buffer_ptr)

Definition at line 191 of file serial.h.

Here is the call graph for this function:

Put() [4/6]

int libpropeller::Serial::Put	(	const char *	buffer_ptr,
		const int	count
	)

Transmit a set of bytes.

Parameters

buffer_ptr	The array of bytes to send.
count	The number of bytes to send.

Returns

The number of bytes actually sent. An error has occurred if this is less than strlen(buffer_ptr)

Definition at line 191 of file serial.h.

Here is the call graph for this function:

Put() [5/6]

void libpropeller::Serial::Put

(

const char

character

)

Transmit a single character.

Parameters

character

the byte to send.

Definition at line 178 of file serial.h.

Put() [6/6]

void libpropeller::Serial::Put

(

const char

character

)

Transmit a single character.

Parameters

character

the byte to send.

Definition at line 178 of file serial.h.

Here is the caller graph for this function:

SetBaud() [1/2]

bool libpropeller::Serial::SetBaud

(

const int

rate

)

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

Parameters

rate	desired baud rate of the Serial engine.

Returns

true if the baud rate was achieved

Definition at line 146 of file serial.h.

Here is the call graph for this function:

SetBaud() [2/2]

bool libpropeller::Serial::SetBaud

(

const int

rate

)

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

Parameters

rate	desired baud rate of the Serial engine.

Returns

true if the baud rate was achieved

Definition at line 146 of file serial.h.

Here is the call graph for this function:

SetBaudClock() [1/2]

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

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

rate	desired baud rate of the Serial engine.
sysclock	the system clock (use CLKFREQ), or provide your own (useful when using RCFAST).

Returns

true if the baud rate was achieved

Definition at line 161 of file serial.h.

Here is the caller graph for this function:

SetBaudClock() [2/2]

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

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

rate	desired baud rate of the Serial engine.
sysclock	the system clock (use CLKFREQ), or provide your own (useful when using RCFAST).

Returns

true if the baud rate was achieved

Definition at line 161 of file serial.h.

Start() [1/2]

bool libpropeller::Serial::Start	(	const int	rxpin,
		const int	txpin,
		const int	rate,
		const int	ctspin = -1
	)

Start Serial driver in a new cog.

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

Parameters

rxpin	the pin [0..31] for incoming data.
txpin	the pin [0..31] for outgoing data.
rate	the initial baud rate in bits per second.
ctspin	cts 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

Definition at line 64 of file serial.h.

Start() [2/2]

bool libpropeller::Serial::Start	(	const int	rxpin,
		const int	txpin,
		const int	rate,
		const int	ctspin = -1
	)

Start Serial driver in a new cog.

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

Parameters

rxpin	the pin [0..31] for incoming data.
txpin	the pin [0..31] for outgoing data.
rate	the initial baud rate in bits per second.
ctspin	cts 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

Definition at line 64 of file serial.h.

Here is the caller graph for this function:

Stop() [1/2]

void libpropeller::Serial::Stop

(

void

)

Stops the Serial PASM engine, if it is running. Frees a cog.

Definition at line 133 of file serial.h.

Stop() [2/2]

void libpropeller::Serial::Stop

(

void

)

Stops the Serial PASM engine, if it is running. Frees a cog.

Definition at line 133 of file serial.h.

Here is the caller graph for this function:

Member Data Documentation

kBufferLength

static const int libpropeller::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.

Definition at line 48 of file serial.h.

---

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

• libpropeller/libpropeller/mtk3339/serial.h