Treehopper Java API
io.treehopper.HardwareUart Class Reference

Built-in UART peripheral. More...

Inheritance diagram for io.treehopper.HardwareUart:
io.treehopper.interfaces.IOneWire

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
addressthe 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
oneWireNumBytesthe 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
dataThe 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
dataToSendbyte 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
baudthe desired baud, in bits per second.

◆ setEnabled()

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

Sets whether the UART should be enabled.

Parameters
enabledwhether the UART should be enabled.

◆ setMode()

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

Sets the mode to operate the UART in.

Parameters
modethe mode to use.

◆ setOpenDrainTx()

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

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

Parameters
openDrainTxwhether 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: