Treehopper C++ API
HardwareUart Class Reference

Built-in UART peripheral. More...

#include <HardwareUart.h>

Inheritance diagram for HardwareUart:
Uart OneWire

Public Member Functions

void startOneWire () override
 Start one wire mode. More...
 
void oneWireResetAndMatchAddress (uint64_t address) override
 Reset the One Wire bus and address the specified device. More...
 
std::vector< uint64_t > oneWireSearch () override
 Search the One Wire bus and return a vector of addresses found. More...
 
bool oneWireReset () override
 Reset the One Wire bus More...
 
std::vector< uint8_t > receive (int numBytes) override
 Receive bytes from the UART in One-Wire mode More...
 
void send (std::vector< uint8_t > dataToSend) override
 Send data More...
 
void send (uint8_t dataToSend) override
 Send a byte out of the UART More...
 
void startUart () override
 Start the UART with the specified baud More...
 
std::vector< uint8_t > receive () override
 Receive bytes from the UART in UART mode More...
 
void baud (int baud) override
 Sets the baud of the UART. More...
 
int baud () override
 Gets the baud of the UART. More...
 
void mode (UartMode mode)
 sets the UartMode of the UART peripheral More...
 
UartMode mode ()
 gets the UartMode of the UART peripheral More...
 
void enabled (bool enabled)
 Sets whether the UART is enabled. More...
 
bool enabled ()
 

Detailed Description

The UART peripheral allows you to send and receive standard-format RS-232-style asynchronous serial communications.

Pins

When the UART is enabled, the following pins will be unavailable for other use:

  • TX (Transmit): This pin carries data from Treehopper to the device you've attached to the UART.
  • RX (Receive): This pin carries data from the device to Treehopper.

Note that UART cross-over is a common problem when people are attaching devices together; always consult the documentation for the device you're attaching to Treehopper to ensure that the TX signal from Treehopper is flowing into the receive input (RX, DIN, etc) of the device, and vice-versa. Since you are unlikely to damage either device by incorrectly connecting the TX and RX pins, it is a common troubleshooting practice to simply swap TX and RX if the system doesn't appear to be functioning properly.

One-Wire Mode

Treehopper's UART has built-in support for One-Wire mode with few external circuitry requirements. When you use the UART in One-Wire mode, the TX pin will switch to an open-drain mode. You must physically tie the RX and TX pins together — this is the data pin for the One-Wire bus. Most One-Wire sensors and devices you use will require an external pull-up resistor on the bus.

Implementation Details

Treehopper's UART is designed for average baud rates; the range of supported rates is 7813 baud to 2.4 Mbaud, though communication will be less reliable above 1-2 Mbaud.

Transmitting data is straightforward: simply pass a byte array — up to 63 characters long — to the send() function once the UART is enabled.

Receiving data is more challenging, since incoming data can appear on the RX pin at any moment when the UART is enabled. Since all actions on Treehopper are initiated on the host, to get around UART's inherent asynchronicity, a 32-byte buffer holds any received data that comes in while the UART is enabled. Then, when the host wants to access this data, it can receive() it from the board to obtain the buffer.

Whenever receive() is called, the entire buffer is sent to the host, and the buffer's pointer is reset to 0 (i.e., the buffer is reset). This can be useful for clearing out any gibberish and returning the UART to a known state before you expect to receive data — for example, if you're addressing a device that you send commands to, and read responses back from, you may wish to call receive() before sending the command; that way, parsing the received data will be simpler.

Other Considerations

This ping-pong short-packet-oriented back-and-forth scenario is what Treehopper's UART is built for, as it's what's most commonly needed when interfacing with embedded devices that use a UART.

There is a tight window of possible baud rates where it is plausible to receive data continuously without interruption. For example, at 9600 baud, the receive() function only need to finish execution every 33 milliseconds, which can easily be accomplished in most operating systems. However, because data is not double-buffered on the board, under improbable circumstances, continuously-transmitted data may inadvertently be discarded.

Treehopper's UART is not designed to replace a high-quality CDC-class USB-to-serial converter, especially for high data-rate applications. In addition to streaming large volumes of data continuously, USB CDC-class UARTs should also offer lower latency for receiving data. Treehopper also has no way of exposing its UART to the operating system as a COM port, so it's most certainly not a suitable replacement for a USB-to-serial converter in most applications.

Member Function Documentation

◆ baud() [1/2]

void baud ( int  baud)
overridevirtual

Baud can range from 7813 - 2400000 baud, but values less than 2000000 (2 Mbaud) are recommended.

Implements Uart.

◆ baud() [2/2]

int baud ( )
overridevirtual

Implements Uart.

◆ enabled() [1/2]

void enabled ( bool  enabled)

◆ enabled() [2/2]

bool enabled ( )

◆ mode() [1/2]

void mode ( UartMode  mode)

◆ mode() [2/2]

UartMode mode ( )

◆ oneWireReset()

bool oneWireReset ( )
overridevirtual
Returns
True if at least one device was found. False otherwise.

Implements OneWire.

◆ oneWireResetAndMatchAddress()

void oneWireResetAndMatchAddress ( uint64_t  address)
overridevirtual

Implements OneWire.

◆ oneWireSearch()

std::vector<uint64_t> oneWireSearch ( )
overridevirtual

Implements OneWire.

◆ receive() [1/2]

std::vector<uint8_t> receive ( int  numBytes)
overridevirtual
Parameters
numBytesThe number of bytes to receive.
Returns
The bytes received

Implements OneWire.

◆ receive() [2/2]

std::vector<uint8_t> receive ( )
overridevirtual
Returns
The bytes received

As soon as the UART is enabled, any received byte will be added to a 32-byte buffer. Calling this Receive() function does two things:

  • sends the current contents of this buffer to this function.
  • reset the pointer in the buffer to the 0th element, effectively resetting it. If the buffer fills before the Receive() function is called, the existing buffer will be reset — discarding all data in the buffer. Consequently, it's important to call the Receive() function frequently when expecting data.

Owing to how it is implemented, you can clear the buffer at any point by calling Receive(). It's common to empty the buffer before requesting data from the device attached to the UART; this way, you do not have to worry about existing gibberish data that might have been inadvertently received.

Implements Uart.

◆ send() [1/2]

void send ( std::vector< uint8_t >  dataToSend)
overridevirtual
Parameters
dataToSendThe data to send
Returns
An awaitable task that completes upon transmission of the data

Implements OneWire.

◆ send() [2/2]

void send ( uint8_t  dataToSend)
overridevirtual
Parameters
dataToSendThe byte to send
Returns
An awaitable task that completes upon transmission of the byte

Implements OneWire.

◆ startOneWire()

void startOneWire ( )
overridevirtual

Implements OneWire.

◆ startUart()

void startUart ( )
overridevirtual

Implements Uart.


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