search

duff2013 / UartEvent

Event Based Hardware Serial for Teensy 3.1
18 stars 11 forks source link

readme

UartEvent

Teensy 3.1 UartEvent Library v6.6

This library is only intended for Teensy 3.1 Hardware Serial, (no USB) since it has enough DMA channels for all 3 serial ports. While you can use it with the Teensy 3.0 the limited memory and DMA channels make it more suited for the Teensy3.1. This is not for use with the USB Serial. Teensy LC is not supported.

Events that are supported currently are:

  1. Receive Buffer Size
  2. Receive Bytes Until
  3. 1 Byte Receive
  4. Transmit Complete

Transmitting:

While traditional sending of serial data is byte by byte based this uses a packet based sending. By using the Teensy's DMA engine, UartEvent allows the user to send data and move on very quickly, thus freeing up CPU overhead. Since the base class is "Stream" most of the normal print statements work as you would expect. A couple of caveats need to be expressed now.
The reason the library use this setup, it allows you to just copy the data to its buffers and move on, not having to wait for each character to send. This makes it non-blocking. The biggest overhead in sending is only just coping data to the transmit buffer which has been optimized for speed.

Receiving:

Users have more control over how they want to capture data using this library using events instead of polling methods. While you can use polling, registering events can be quite useful. The three events that are currently implemented are explained below:

  1. Receive Buffer Size: This will call an event handler function when the user defined buffer is size is reached.
  2. Read Bytes Until: This will call an event handler function when a termination character is detected.
  3. 1 Byte Receive: This will call an event handler function when a byte is present.

    The DMA engine allows you to receive data which will signal an event handler that is just a function that you define in the main sketch.

Performance:

The performance is on par with the Hardware Serial Class in the Teensyduino core, with the biggest advantage is being able to send a data and move on very quickly. Sending a 5000 byte packet takes only ~260uS @24MHz to get through the print statement code while this would take much longer using the standard Serial print..

Usage:

Since your event functions are called from interrupts make sure you declare any variables used in the event handler as volatile! Also make sure any code inside a event is fast as possible since it is called from the an ISR. DO NOT use any delay functions!