Built-in UART peripheral. More...
Public Member Functions | |
| Task | SendAsync (byte data) |
| Send a byte out of the UART More... | |
| async Task | SendAsync (byte[] dataToSend) |
| Send data More... | |
| async Task< byte[]> | ReceiveAsync (int oneWireNumBytes) |
| Receive bytes from the UART in UART or One-Wire mode More... | |
| async Task< bool > | OneWireResetAsync () |
| Reset the One Wire bus More... | |
| async Task< List< ulong > > | OneWireSearchAsync () |
| Search for One Wire devices on the bus More... | |
| async Task | OneWireResetAndMatchAddressAsync (ulong address) |
| Reset and match a device on the One-Wire bus More... | |
| Task | StartOneWireAsync () |
| Start one-wire mode on this interface More... | |
| override string | ToString () |
| Gets a string representing the UART's state More... | |
| Task< byte[]> | ReceiveAsync () |
| Receive bytes from the UART in UART mode More... | |
| Task | StartUartAsync (int baud) |
| Start the UART with the specified baud More... | |
Properties | |
| UartMode | Mode [get, set] |
| Gets or sets the UART mode More... | |
| bool | Enabled [get, set] |
| Enable or disable the UART More... | |
| int | Baud [get, set] |
| Set or get the baud of the UART. More... | |
| bool | UseOpenDrainTx [get, set] |
| Whether to use an open-drain TX pin or not. 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
◆ SendAsync() [1/2]
| Task SendAsync | ( | byte | data | ) |
Send a byte out of the UART
- Parameters
-
data The byte to send
- Returns
- An awaitable task that completes upon transmission of the byte
Implements OneWire.
◆ SendAsync() [2/2]
| async Task SendAsync | ( | byte [] | dataToSend | ) |
Send data
- Parameters
-
dataToSend The data to send
- Returns
- An awaitable task that completes upon transmission of the data
Implements OneWire.
◆ ReceiveAsync() [1/2]
| async Task<byte[]> ReceiveAsync | ( | int | oneWireNumBytes | ) |
Receive bytes from the UART in UART or One-Wire mode
- Parameters
-
oneWireNumBytes In One-Wire mode, the number of bytes to receive. Not used in UART mode.
- 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 OneWire.
◆ OneWireResetAsync()
| async Task<bool> OneWireResetAsync | ( | ) |
Reset the One Wire bus
- Returns
- True if at least one device was found. False otherwise.
Implements OneWire.
◆ OneWireSearchAsync()
| async Task<List<ulong> > OneWireSearchAsync | ( | ) |
◆ OneWireResetAndMatchAddressAsync()
| async Task OneWireResetAndMatchAddressAsync | ( | ulong | address | ) |
Reset and match a device on the One-Wire bus
- Parameters
-
address The address to reset and match
- Returns
Implements OneWire.
◆ StartOneWireAsync()
| Task StartOneWireAsync | ( | ) |
Start one-wire mode on this interface
Implements OneWire.
◆ ToString()
| override string ToString | ( | ) |
Gets a string representing the UART's state
- Returns
- the UART's string
◆ ReceiveAsync() [2/2]
| Task<byte[]> ReceiveAsync | ( | ) |
Receive bytes from the UART in UART mode
- 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.
◆ StartUartAsync()
| Task StartUartAsync | ( | int | baud | ) |
Property Documentation
◆ Mode
|
getset |
Gets or sets the UART mode
◆ Enabled
|
getset |
Enable or disable the UART
◆ Baud
|
getset |
Set or get the baud of the UART.
Baud can range from 7813 - 2400000 baud, but values less than 2000000 (2 Mbaud) are recommended.
◆ UseOpenDrainTx
|
getset |
Whether to use an open-drain TX pin or not.
The documentation for this class was generated from the following file:
- F:/Git/treehopper-sdk/NET/API/Treehopper/HardwareUart.cs