Hardware serial class. More...
#include <HardwareSerial.h>
Public Member Functions | |||||||
HardwareSerial (int uartPort) | |||||||
Create instance of a hardware serial port object. More... | |||||||
~HardwareSerial () | |||||||
void | setPort (int uartPort) | ||||||
int | getPort () | ||||||
void | begin (uint32_t baud=9600) | ||||||
Initialise the serial port. More... | |||||||
void | begin (uint32_t baud, SerialConfig config) | ||||||
Initialise and set its configuration. More... | |||||||
void | begin (uint32_t baud, SerialConfig config, SerialMode mode) | ||||||
Initialise, set its configuration and mode. More... | |||||||
void | begin (uint32_t baud, SerialConfig config, SerialMode mode, uint8_t txPin) | ||||||
Initialise, set its configuration and mode. More... | |||||||
void | end () | ||||||
De-inits the current UART if it is already used. More... | |||||||
size_t | setRxBufferSize (size_t size) | ||||||
Sets receiving buffer size. More... | |||||||
size_t | setTxBufferSize (size_t size) | ||||||
Sets transmit buffer size. More... | |||||||
void | setTxWait (bool wait) | ||||||
Governs write behaviour when UART transmit buffers are full. More... | |||||||
void | swap () | ||||||
Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX. More... | |||||||
void | swap (uint8_t tx_pin) | ||||||
Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX. More... | |||||||
void | setTx (uint8_t tx_pin) | ||||||
Toggle between use of GPIO1 and GPIO2 as TX on UART 0. More... | |||||||
void | pins (uint8_t tx, uint8_t rx) | ||||||
Sets the transmission and receiving PINS. More... | |||||||
int | available () override | ||||||
Get quantity characters available from serial input. More... | |||||||
int | read () override | ||||||
Read a character from serial port. More... | |||||||
uint16_t | readMemoryBlock (char *buf, int max_len) override | ||||||
Read a block of characters from serial port. More... | |||||||
bool | seek (int len) override | ||||||
Move read cursor. More... | |||||||
bool | isFinished () override | ||||||
Check if all data has been read. More... | |||||||
int | peek () override | ||||||
Read a character from serial port without removing from input buffer. More... | |||||||
void | clear (SerialMode mode=SERIAL_FULL) | ||||||
Clear the serial port transmit/receive buffers. More... | |||||||
void | flush () override | ||||||
Flush all pending data to the serial port. More... | |||||||
size_t | write (const uint8_t *buffer, size_t size) override | ||||||
write multiple characters to serial port More... | |||||||
void | systemDebugOutput (bool enabled) | ||||||
Configure serial port for system debug output and redirect output from debugf. More... | |||||||
void | commandProcessing (bool reqEnable) | ||||||
Configure serial port for command processing. More... | |||||||
bool | setCallback (StreamDataReceivedDelegate dataReceivedDelegate) | ||||||
Set handler for received data. More... | |||||||
bool | onDataReceived (StreamDataReceivedDelegate dataReceivedDelegate) | ||||||
Set handler for received data. More... | |||||||
bool | onTransmitComplete (TransmitCompleteDelegate transmitCompleteDelegate) | ||||||
Set handler for received data. More... | |||||||
void | setUartCallback (smg_uart_callback_t callback, void *param=nullptr) | ||||||
Set callback ISR for received data. More... | |||||||
bool | isTxEnabled () | ||||||
Checks if the current UART can transmit(print) information. More... | |||||||
bool | isRxEnabled () | ||||||
Checks if the current UART can receive information. More... | |||||||
uint32_t | baudRate () | ||||||
Get the current baud rate. More... | |||||||
uint32_t | setBaudRate (uint32_t baudrate) | ||||||
Attempt to set the requested baud rate. More... | |||||||
operator bool () const | |||||||
Operator that returns true if the uart structure is set. More... | |||||||
int | indexOf (char c) override | ||||||
Returns the location of the searched character. More... | |||||||
smg_uart_t * | getUart () | ||||||
Returns a pointer to the internal uart object. Use with care. More... | |||||||
unsigned | getStatus () | ||||||
Get status error flags and clear them. More... | |||||||
size_t | write (uint8_t charToWrite) override | ||||||
Write a single character to the stream. More... | |||||||
size_t | write (const char *str) | ||||||
Writes a c-string to output stream. More... | |||||||
size_t | write (const char *buffer, size_t size) | ||||||
Writes characters from a buffer to output stream. More... | |||||||
virtual size_t | copyFrom (IDataSourceStream *source, size_t size) | ||||||
Copy data from a source stream. More... | |||||||
virtual StreamType | getStreamType () const | ||||||
Get the stream type. More... | |||||||
virtual bool | isValid () const | ||||||
Determine if the stream object contains valid data. More... | |||||||
virtual int | seekFrom (int offset, unsigned origin) | ||||||
Change position in stream. More... | |||||||
int | length () | ||||||
Return the total length of the stream. More... | |||||||
virtual String | id () const | ||||||
Returns unique id of the resource. More... | |||||||
virtual String | getName () const | ||||||
Returns name of the resource. More... | |||||||
String | readString (size_t maxLen=UINT16_MAX) | ||||||
Overrides Stream method for more efficient reading. More... | |||||||
String | readString () | ||||||
void | setTimeout (unsigned long timeout) | ||||||
bool | find (char *target) | ||||||
bool | find (char *target, size_t length) | ||||||
bool | findUntil (char *target, char *terminator) | ||||||
bool | findUntil (char *target, size_t targetLen, char *terminate, size_t termLen) | ||||||
long | parseInt () | ||||||
float | parseFloat () | ||||||
size_t | readBytes (char *buffer, size_t length) | ||||||
size_t | readBytesUntil (char terminator, char *buffer, size_t length) | ||||||
String | readStringUntil (char terminator) | ||||||
int | getWriteError () | ||||||
Gets last error. More... | |||||||
void | clearWriteError () | ||||||
Clears the last write error. More... | |||||||
size_t | print (char c) | ||||||
Prints a single character to output stream. More... | |||||||
size_t | print (const char str[]) | ||||||
Prints a c-string to output stream. More... | |||||||
size_t | print (double num, int digits=2) | ||||||
Print a floating-point number to output stream. More... | |||||||
size_t | print (const Printable &p) | ||||||
Prints a Printable object to output stream. More... | |||||||
size_t | print (const String &s) | ||||||
Prints a String to output stream. More... | |||||||
size_t | println () | ||||||
Prints a newline to output stream. More... | |||||||
size_t | println (const char str[]) | ||||||
Prints a c-string to output stream, appending newline. More... | |||||||
size_t | println (char c) | ||||||
Prints a single character to output stream, appending newline. More... | |||||||
size_t | println (double num, int digits=2) | ||||||
Print a floating-point number to output stream, appending newline. More... | |||||||
size_t | println (const Printable &p) | ||||||
Prints a Printable object to output stream, appending newline. More... | |||||||
size_t | println (const String &s) | ||||||
Prints a String to output stream, appending newline. More... | |||||||
size_t | printf (const char *fmt,...) __attribute__((format(printf | ||||||
Prints a formatted c-string to output stream. More... | |||||||
Print an integral number to output stream | |||||||
| |||||||
size_t | print (unsigned long num, int base=DEC) | ||||||
size_t | print (const unsigned long long &num, int base=DEC) | ||||||
size_t | print (long, int base=DEC) | ||||||
size_t | print (const long long &, int base=DEC) | ||||||
size_t | print (unsigned int num, int base=DEC) | ||||||
size_t | print (unsigned char num, int base=DEC) | ||||||
size_t | print (int num, int base=DEC) | ||||||
Print an integral number to output stream, appending newline | |||||||
| |||||||
size_t | println (unsigned char num, int base=DEC) | ||||||
size_t | println (unsigned int num, int base=DEC) | ||||||
size_t | println (unsigned long num, int base=DEC) | ||||||
size_t | println (const unsigned long long &num, int base=DEC) | ||||||
size_t | println (int num, int base=DEC) | ||||||
size_t | println (long num, int base=DEC) | ||||||
size_t | println (const long long &num, int base=DEC) | ||||||
Protected Member Functions | |
int | timedRead () |
int | timedPeek () |
int | peekNextDigit () |
long | parseInt (char skipChar) |
float | parseFloat (char skipChar) |
void | setWriteError (int err=1) |
Protected Attributes | |
unsigned long | receiveTimeout = 1000 |
unsigned long | startMillis = 0 |
Detailed Description
Hardware serial class.
Constructor & Destructor Documentation
◆ HardwareSerial()
|
inline |
Create instance of a hardware serial port object.
- Parameters
-
uartPort UART number [0 | 1]
- Note
- A global instance of UART 0 is already defined as Serial
◆ ~HardwareSerial()
HardwareSerial::~HardwareSerial | ( | ) |
Member Function Documentation
◆ available()
|
inlineoverridevirtual |
Get quantity characters available from serial input.
- Return values
-
int Quantity of characters in receive buffer
Reimplemented from IDataSourceStream.
◆ baudRate()
|
inline |
Get the current baud rate.
- Return values
-
uint32_t baud rate
◆ begin() [1/4]
|
inline |
Initialise the serial port.
- Parameters
-
baud BAUD rate of the serial port (Default: 9600)
◆ begin() [2/4]
|
inline |
Initialise and set its configuration.
- Parameters
-
baud Baud rate to use config can be 5, 6, 7, 8 data bits, odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the desired mode, call Serial.begin(baudrate, SERIAL_8N1), Serial.begin(baudrate, SERIAL_6E2), etc.
◆ begin() [3/4]
|
inline |
Initialise, set its configuration and mode.
- Parameters
-
baud Baud rate to use config can be 5, 6, 7, 8 data bits, odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the desired mode, call Serial.begin(baudrate, SERIAL_8N1), Serial.begin(baudrate, SERIAL_6E2), etc. mode specifies if the UART supports receiving (RX), transmitting (TX) or both (FULL) operations
◆ begin() [4/4]
void HardwareSerial::begin | ( | uint32_t | baud, |
SerialConfig | config, | ||
SerialMode | mode, | ||
uint8_t | txPin | ||
) |
Initialise, set its configuration and mode.
- Parameters
-
baud Baud rate to use config mode txPin Can specify alternate pin for TX
◆ clear()
|
inline |
Clear the serial port transmit/receive buffers.
- Parameters
-
mode Whether to flush TX, RX or both (the default)
- Note
- All un-read buffered data is removed and any error condition cleared
◆ clearWriteError()
|
inlineinherited |
Clears the last write error.
◆ commandProcessing()
void HardwareSerial::commandProcessing | ( | bool | reqEnable | ) |
Configure serial port for command processing.
- Parameters
-
reqEnable True to enable command processing
- Note
- Command processing provides a CLI to the system
- See also
- commandHandler
◆ copyFrom()
|
virtualinherited |
Copy data from a source stream.
- Parameters
-
source Stream to read data from size Quantity of chars to write, determines size of intermediate buffer to use
- Return values
-
size_t Quantity of chars actually written, may be less than requested
◆ end()
void HardwareSerial::end | ( | ) |
De-inits the current UART if it is already used.
◆ find() [1/2]
|
inherited |
◆ find() [2/2]
|
inherited |
◆ findUntil() [1/2]
|
inherited |
◆ findUntil() [2/2]
|
inherited |
◆ flush()
|
inlineoverridevirtual |
Flush all pending data to the serial port.
- Note
- Not to be confused with uart_flush() which is different. See clear() method.
Reimplemented from IDataSourceStream.
◆ getName()
|
inlinevirtualinherited |
Returns name of the resource.
- Return values
-
String
- Note
- Commonly used to obtain name of file
Reimplemented in TemplateStream, FileStream, StreamTransformer, GdbFileStream, and HostFileStream.
◆ getPort()
|
inline |
◆ getStatus()
unsigned HardwareSerial::getStatus | ( | ) |
Get status error flags and clear them.
- Return values
-
unsigned Status flags, combination of SerialStatus bits
- See also
- SerialStatus
◆ getStreamType()
|
inlinevirtualinherited |
Get the stream type.
- Return values
-
StreamType The stream type.
Reimplemented in FileStream, TemplateStream, StreamTransformer, HostFileStream, FSTR::Stream, CircularBuffer, JsonObjectStream, LimitedMemoryStream, MemoryDataStream, EndlessMemoryStream, UrlencodedOutputStream, and MultiStream.
◆ getUart()
|
inline |
Returns a pointer to the internal uart object. Use with care.
- Return values
-
pointer to uart_t
◆ getWriteError()
|
inlineinherited |
Gets last error.
- Return values
-
int Error number of last write error
◆ id()
|
inlinevirtualinherited |
Returns unique id of the resource.
- Return values
-
String the unique id of the stream.
Reimplemented in FileStream, GdbFileStream, and CircularBuffer.
◆ indexOf()
|
inlineoverridevirtual |
Returns the location of the searched character.
- Parameters
-
c - character to search for
- Return values
-
int -1 if not found 0 or positive number otherwise
Reimplemented from Stream.
◆ isFinished()
|
inlineoverridevirtual |
◆ isRxEnabled()
|
inline |
Checks if the current UART can receive information.
- Return values
-
bool true if receiving is allowed
◆ isTxEnabled()
|
inline |
Checks if the current UART can transmit(print) information.
- Return values
-
bool true if transmitting is allowed
◆ isValid()
|
inlinevirtualinherited |
Determine if the stream object contains valid data.
- Return values
-
bool true if valid, false if invalid
- Note
- Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)
Reimplemented in FileStream, GdbFileStream, and HostFileStream.
◆ length()
|
inlineinherited |
Return the total length of the stream.
- Return values
-
int -1 is returned when the size cannot be determined
- Deprecated:
- Use
available()
instead
◆ onDataReceived()
|
inline |
Set handler for received data.
- Parameters
-
dataReceivedDelegate Function to handle received data
- Return values
-
bool Returns true if the callback was set correctly
◆ onTransmitComplete()
|
inline |
Set handler for received data.
- Parameters
-
transmitCompleteDelegate Function to handle received data
- Return values
-
bool Returns true if the callback was set correctly
◆ operator bool()
|
inline |
Operator that returns true if the uart structure is set.
◆ parseFloat() [1/2]
|
inherited |
◆ parseFloat() [2/2]
|
protectedinherited |
◆ parseInt() [1/2]
|
inherited |
◆ parseInt() [2/2]
|
protectedinherited |
◆ peek()
|
inlineoverridevirtual |
Read a character from serial port without removing from input buffer.
- Return values
-
int Character read from serial port or -1 if buffer empty
- Note
- The character remains in serial port input buffer
Reimplemented from IDataSourceStream.
◆ peekNextDigit()
|
protectedinherited |
◆ pins()
|
inline |
Sets the transmission and receiving PINS.
- Parameters
-
tx Transmission pin number rx Receiving pin number
- Note
- UART 0 possible options are (1, 3), (2, 3) or (15, 13)
- UART 1 allows only TX on 2 if UART 0 is not (2, 3)
◆ print() [1/12]
|
inlineinherited |
Prints a single character to output stream.
- Parameters
-
c Character to print
- Return values
-
size_t Quantity of characters written to stream
◆ print() [2/12]
|
inlineinherited |
Prints a c-string to output stream.
- Parameters
-
str c-string to print
- Return values
-
size_t Quantity of characters written to output stream
◆ print() [3/12]
◆ print() [4/12]
◆ print() [5/12]
◆ print() [6/12]
◆ print() [7/12]
◆ print() [8/12]
◆ print() [9/12]
◆ print() [10/12]
|
inlineinherited |
Print a floating-point number to output stream.
- Parameters
-
num Number to print digits The decimal places to print (Default: 2, e.g. 21.35)
- Return values
-
size_t Quantity of characters written to stream
◆ print() [11/12]
|
inlineinherited |
Prints a Printable object to output stream.
- Parameters
-
p Object to print
- Return values
-
size_t Quantity of characters written to stream
◆ print() [12/12]
|
inlineinherited |
◆ printf()
|
inherited |
Prints a formatted c-string to output stream.
- Parameters
-
fmt Pointer to formated c-string to print ... Parameters for placeholders within formated string
- Return values
-
size_t Quantity of characters written to stream
- Note
- Use standard printf placeholders, e.g. d for integer, s for c-string, etc.
◆ println() [1/13]
|
inlineinherited |
Prints a newline to output stream.
- Return values
-
size_t Quantity of characters written to stream
◆ println() [2/13]
|
inlineinherited |
Prints a c-string to output stream, appending newline.
- Parameters
-
str c-string to print
- Return values
-
size_t Quantity of characters written to stream
◆ println() [3/13]
|
inlineinherited |
Prints a single character to output stream, appending newline.
- Parameters
-
c Character to print
- Return values
-
size_t Quantity of characters written to stream
◆ println() [4/13]
◆ println() [5/13]
◆ println() [6/13]
◆ println() [7/13]
◆ println() [8/13]
◆ println() [9/13]
◆ println() [10/13]
◆ println() [11/13]
|
inlineinherited |
Print a floating-point number to output stream, appending newline.
- Parameters
-
num Number to print digits The decimal places to print (Default: 2, e.g. 21.35)
- Return values
-
size_t Quantity of characters written to stream
◆ println() [12/13]
|
inlineinherited |
Prints a Printable object to output stream, appending newline.
- Parameters
-
p Object to print
- Return values
-
size_t Quantity of characters written to stream
◆ println() [13/13]
|
inlineinherited |
◆ read()
|
inlineoverridevirtual |
Read a character from serial port.
- Return values
-
int Character read from serial port or -1 if buffer empty
- Note
- The character is removed from the serial port input buffer
Reimplemented from IDataSourceStream.
◆ readBytes()
|
inherited |
◆ readBytesUntil()
|
inherited |
◆ readMemoryBlock()
Read a block of characters from serial port.
- Parameters
-
buf Pointer to buffer to hold received data max_len Maximum quantity of characters to read
- Return values
-
uint16_t Quantity of characters read
- Note
- Although this shares the same name as the method in IDataSourceStream, behaviour is different because in effect the 'seek' position is changed by this call.
Implements IDataSourceStream.
◆ readString() [1/2]
|
inherited |
◆ readString() [2/2]
|
inherited |
Overrides Stream method for more efficient reading.
- Note
- Content is read using
readMemoryBlock()
so read position (for seekable streams) is not changed
◆ readStringUntil()
|
inherited |
◆ seek()
Move read cursor.
- Parameters
-
len Relative cursor adjustment
- Return values
-
bool True on success.
Reimplemented from IDataSourceStream.
◆ seekFrom()
Change position in stream.
- Parameters
-
offset origin SEEK_SET, SEEK_CUR, SEEK_END
- Return values
-
New position, < 0 on error
- Note
- This method is implemented by streams which support random seeking, such as files and memory streams.
Reimplemented in FileStream, MemoryDataStream, HostFileStream, FSTR::Stream, and GdbFileStream.
◆ setBaudRate()
|
inline |
Attempt to set the requested baud rate.
- Return values
-
uint32_t the actual baud rate in force
- Note
- Return value may differ from requested baud rate due to clock division errors
◆ setCallback()
|
inline |
Set handler for received data.
- Parameters
-
dataReceivedDelegate Function to handle received data
- Return values
-
bool Returns true if the callback was set correctly
- Deprecated:
- Use
onDataReceived
instead
◆ setPort()
|
inline |
◆ setRxBufferSize()
size_t HardwareSerial::setRxBufferSize | ( | size_t | size | ) |
Sets receiving buffer size.
- Parameters
-
size requested size
- Return values
-
size_t actual size
◆ setTimeout()
|
inherited |
◆ setTx()
|
inline |
Toggle between use of GPIO1 and GPIO2 as TX on UART 0.
- Parameters
-
tx_pin
- Note
- : UART 1 can't be used if GPIO2 is used with UART 0!
- : If UART1 is not used and UART0 is not swapped - TX for UART0 can be mapped to GPIO2 by calling .setTx(2) after .begin or directly with .begin(baud, config, mode, 2).
◆ setTxBufferSize()
size_t HardwareSerial::setTxBufferSize | ( | size_t | size | ) |
Sets transmit buffer size.
- Parameters
-
size requested size
- Return values
-
size_t actual size
◆ setTxWait()
|
inline |
Governs write behaviour when UART transmit buffers are full.
- Parameters
-
wait If false, writes will return short count; applications can use the txComplete callback to send more data. If true, writes will wait for more buffer space so that all requested data is written
◆ setUartCallback()
|
inline |
Set callback ISR for received data.
- Parameters
-
callback Function to handle received data param Set as return value for uart_get_callback_param()
- Note
- callback is invoked directly from serial ISR and bypasses any registered delgates
◆ setWriteError()
|
inlineprotectedinherited |
◆ swap() [1/2]
|
inline |
Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX.
- Note
- UART0 uses pins GPIO1 (TX) and GPIO3 (RX). It may be swapped to GPIO15 (TX) and GPIO13 (RX) by calling .swap() after .begin. C
- Calling swap again maps UART0 back to GPIO1 and GPIO3.
◆ swap() [2/2]
|
inline |
Toggle between use of GPIO13/GPIO15 or GPIO3/GPIO(1/2) as RX and TX.
- Parameters
-
tx_pin Pin number.
◆ systemDebugOutput()
void HardwareSerial::systemDebugOutput | ( | bool | enabled | ) |
Configure serial port for system debug output and redirect output from debugf.
- Parameters
-
enabled True to enable this port for system debug output
- Note
- If enabled, port will issue system debug messages
◆ timedPeek()
|
protectedinherited |
◆ timedRead()
|
protectedinherited |
◆ write() [1/4]
|
inlineoverridevirtualinherited |
Write a single character to the stream.
- Parameters
-
charToWrite
- Return values
-
size_t Number of chars written (1 on success, 0 on failure)
Reimplemented from IDataSourceStream.
◆ write() [2/4]
|
inlineinherited |
Writes a c-string to output stream.
- Parameters
-
str Pointer to c-string
- Return values
-
size_t Quantity of characters written to stream
◆ write() [3/4]
|
inlineinherited |
Writes characters from a buffer to output stream.
- Parameters
-
buffer Pointer to character buffer size Quantity of characters to write
- Return values
-
size_t Quantity of characters written to stream
◆ write() [4/4]
|
inlineoverridevirtual |
write multiple characters to serial port
- Parameters
-
buffer data to write size number of characters to write
- Return values
-
size_t Quantity of characters written, may be less than size
Implements ReadWriteStream.
Member Data Documentation
◆ receiveTimeout
|
protectedinherited |
◆ startMillis
|
protectedinherited |
The documentation for this class was generated from the following file: