Built-in UART peripheral. More...

Inheritance diagram for io.treehopper.HardwareUart:

Classes
enum	UartCommand

enum	UartConfig

Public Member Functions
UartMode	getMode ()
	Get the current mode the UART is operating in. More...

void	setMode (UartMode mode)
	Sets the mode to operate the UART in. More...

boolean	isEnabled ()
	Gets whether the UART is enabled. More...

void	setEnabled (boolean enabled)
	Sets whether the UART should be enabled. More...

int	getBaud ()
	Get the baud of the UART. More...

void	setBaud (int baud)
	Set the baud of the UART. More...

boolean	isOpenDrainTx ()
	Determine whether the UART is using open-drain Tx mode. More...

void	setOpenDrainTx (boolean openDrainTx)
	Sets whether the UART should use open-drain Tx mode. More...

String	toString ()
	Gets a string representation of the current state of the UART. More...

void	send (byte data)
	Send a byte of data out the UART in UART or One-Wire mode. More...

void	send (byte[] dataToSend)
	Send an array of data out the UART in UART or One-Wire mode. More...

byte []	receive ()
	Receive the UART's entire RX buffer. More...

byte []	receive (int oneWireNumBytes)
	Receive bytes from the UART in One-Wire Mode. More...

boolean	oneWireReset ()
	Send a One-Wire reset command. More...

ArrayList< Long >	oneWireSearch ()
	Search for devices on the One-Wire bus. More...

void	oneWireResetAndMatchAddress (long address)
	Reset and match a device on the OneWire bus. More...

void	startOneWire ()
	Enable the UART and put it in One-Wire mode. More...

Detailed Description

Built-in UART peripheral.

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

◆ getBaud()

int io.treehopper.HardwareUart.getBaud ( )

Get the baud of the UART.

Returns: the current baud, in bits per second.

◆ getMode()

UartMode io.treehopper.HardwareUart.getMode ( )

Get the current mode the UART is operating in.

Returns: the UART's current mode.

◆ isEnabled()

boolean io.treehopper.HardwareUart.isEnabled ( )

Gets whether the UART is enabled.

Returns: whether the UART is enabled.

◆ isOpenDrainTx()

boolean io.treehopper.HardwareUart.isOpenDrainTx ( )

Determine whether the UART is using open-drain Tx mode.

Returns: whether the UART is using open-drain Tx mode.

◆ oneWireReset()

boolean io.treehopper.HardwareUart.oneWireReset ( )

Send a One-Wire reset command.

Returns: True if at least one device was found.

Implements io.treehopper.interfaces.IOneWire.

◆ oneWireResetAndMatchAddress()

void io.treehopper.HardwareUart.oneWireResetAndMatchAddress ( long address )

Reset and match a device on the OneWire bus.

Parameters

address the address to reset and match.

Implements io.treehopper.interfaces.IOneWire.

◆ oneWireSearch()

ArrayList<Long> io.treehopper.HardwareUart.oneWireSearch ( )

Search for devices on the One-Wire bus.

Returns: a list of device addresses found on the One-Wire bus.

Implements io.treehopper.interfaces.IOneWire.

◆ receive() [1/2]

byte [] io.treehopper.HardwareUart.receive ( )

Receive the UART's entire RX buffer.

Returns: the bytes in the RX buffer

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.

◆ receive() [2/2]

byte [] io.treehopper.HardwareUart.receive ( int oneWireNumBytes )

Receive bytes from the UART in One-Wire Mode.

Parameters

oneWireNumBytes the number of bytes to request from the One-Wire device

Returns: the bytes received This function overload should only be called when the UART is in One-Wire mode. Treehopper will request oneWireNumBytes from the device, and return this data as an array.

Implements io.treehopper.interfaces.IOneWire.

◆ send() [1/2]

void io.treehopper.HardwareUart.send ( byte data )

Send a byte of data out the UART in UART or One-Wire mode.

Parameters

data	The byte to send

Implements io.treehopper.interfaces.IOneWire.

◆ send() [2/2]

void io.treehopper.HardwareUart.send ( byte [] dataToSend )

Send an array of data out the UART in UART or One-Wire mode.

Parameters

dataToSend byte array of the data to send

Implements io.treehopper.interfaces.IOneWire.

◆ setBaud()

void io.treehopper.HardwareUart.setBaud ( int baud )

Set the baud of the UART.

Parameters

baud	the desired baud, in bits per second.

◆ setEnabled()

void io.treehopper.HardwareUart.setEnabled ( boolean enabled )

Sets whether the UART should be enabled.

Parameters

enabled whether the UART should be enabled.

◆ setMode()

void io.treehopper.HardwareUart.setMode ( UartMode mode )

Sets the mode to operate the UART in.

Parameters

mode	the mode to use.

◆ setOpenDrainTx()

void io.treehopper.HardwareUart.setOpenDrainTx ( boolean openDrainTx )

Sets whether the UART should use open-drain Tx mode.

Parameters

openDrainTx whether the UART should use open-drain Tx mode.

◆ startOneWire()

void io.treehopper.HardwareUart.startOneWire ( )

Enable the UART and put it in One-Wire mode.

Implements io.treehopper.interfaces.IOneWire.

◆ toString()

String io.treehopper.HardwareUart.toString ( )

Gets a string representation of the current state of the UART.

Returns

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

F:/Git/treehopper-sdk/Java/api/treehopper/src/main/java/io/treehopper/HardwareUart.java

Classes

Public Member Functions

Detailed Description

Pins

One-Wire Mode

Implementation Details

Other Considerations

Member Function Documentation

◆ getBaud()

◆ getMode()

◆ isEnabled()

◆ isOpenDrainTx()

◆ oneWireReset()

◆ oneWireResetAndMatchAddress()

◆ oneWireSearch()

◆ receive() [1/2]

◆ receive() [2/2]

◆ send() [1/2]

◆ send() [2/2]

◆ setBaud()

◆ setEnabled()

◆ setMode()

◆ setOpenDrainTx()

◆ startOneWire()

◆ toString()