Using the Hardware Serial Ports

The most common issue with serial ports on Teensy is use of code designed for Arduino Uno with Serial within the code. On Teensy, Serial accesses the USB only. USB and Serial1 (pins 0 & 1) are not shared on Teensy. For hardware serial ports, Serial1, Serial2, Serial3, Serial4, Serial5, Serial6, Serial7 or Serial8 must be used.

Hardware

XBAR pins may be used with attachCts() or setRX(). Each serial port can make only one connection to the XBAR for flexible pin routing, so on each port you can assign an XBAR pin to either CTS or RX, but not both. XBAR alternate pins each override use of one of the primary pins, so care should be used to avoid conflicts if using alt pins.

• Teensy 4.0: Primary XBAR Pins 1, 2, 3, 4, 5, 7, 8, 30, 31, 32, 33 - Alt Pins: 0, 34, 35, 36, 37, 38, 39
• Teensy 4.1: Primary XBAR Pins 1, 2, 3, 4, 5, 7, 8, 30, 31, 32, 33 - Alt Pins: 0, 36, 37, 42, 43, 44, 45, 46, 47
• MicroMod Teensy: Primary XBAR Pins 1, 2, 3, 4, 5, 7, 8, 30, 31, 32, 33 - Alt Pins: 0, 34, 35, 36, 37, 38, 39

* CTS polarity is inverted when connected through XBAR. Normally CTS is active low, meaning Teensy is allowed to transmit data when CTS is low, and must pause when CTS is driven high. But when using XBAR, Teensy transmits when the pin is logic high and pauses transmission while the pin is low.

The serial signals on the Rx and Tx pins are "TTL level". To convert to RS-232 level a MAX232 or similar chip is needed.

Serial connection confusion is so common that Shawn Hymel designed this badge and Drew Fustini made a purple PCB. Don't feel bad if you get it mixed up. You're not alone!

All serial ports on all Teensy boards use interrupt-based transmit and receive buffering, to allow your program to avoid waiting when writing short messages, and to allow data to be reliably received even if your program must spend time performing other tasks.

On Teensy 3.6 when running faster than 120 MHz, writing to EEPROM may momentarily interfere with Serial1 and Serial2 baud rates. Reading EEPROM does not interfere. Serial3 to Serial6 are not affected.

Commonly Used Serial Protocols

• MIDI
• ESP8266 (with fast baud rate and RTS/CTS flow control)
• SBUS
• Modbus RTU (see RS-485 transmitterEnable function)
• M-Bus
• Robotis Dynamixel AX and MX-T
• GPS NMEA0183
• DMX Lighting
• EasyTransfer library
• BlueSMiRF
• XBee

Example Code

// set this to the hardware serial port you wish to use
#define HWSERIAL Serial1

void setup() {
  Serial.begin(9600);
  HWSERIAL.begin(9600);
}

void loop() {
  int incomingByte;

  if (Serial.available() > 0) {
    incomingByte = Serial.read();
    Serial.print("USB received: ");
    Serial.println(incomingByte, DEC);
    HWSERIAL.print("USB received:");
    HWSERIAL.println(incomingByte, DEC);
  }
  if (HWSERIAL.available() > 0) {
    incomingByte = HWSERIAL.read();
    Serial.print("UART received: ");
    Serial.println(incomingByte, DEC);
    HWSERIAL.print("UART received:");
    HWSERIAL.println(incomingByte, DEC);
  }
}

Standard Serial Functions

Serial1.begin(baud)

If begin(baud) is called after serial data is already incoming, any 0 data bit may be mistakenly detected as the first start bit, resulting in corrupted reception. If started out of sync, the receiver needs an idle time of 9 bits between a stop bit and the next start bit to "get into sync". Certain 100% bandwidth utilization patterns may never sync, which is a fundamental limitation of serial communication.

Serial1.print(data) and Serial1.println(data)

  // Serial1.print() can print many different types
  int number = 1234;
  Serial1.println("string");     // string
  Serial1.println('a');          // single character
  Serial1.println(number);       // number (base 10 if 16 or 32 bit)
  Serial1.println(number, DEC);  // number, base 10 (default)
  Serial1.println(number, HEX);  // number, base 16/hexidecimal
  Serial1.println(number, OCT);  // number, base 8/octal
  Serial1.println(number, BIN);  // number, base 2/binary
  Serial1.println(3.14);         // number in floating point, 2 digits

Serial1.availableForWrite()

Serial1.write(byte)

Serial1.available()

Serial1.read()

  if (Serial1.available()) {
    incomingByte = Serial1.read();  // will not be -1
    // actually do something with incomingByte
  }

In 9 bit mode, the return value is 0 to 511, or -1 if nothing available.

Serial1.flush()

Serial1.clear()

Serial1.setTX(pin)

Serial1.setRX(pin)

Serial1.transmitterEnable(pin)

Most RS-485 chips have 2 control signals, an active-high transmitter enable and an active-low receiver enable. Normally those 2 signals are wired together and connected to the transmitter enable output.

Serial1.addMemoryForRead(buffer, size)

The buffer array must be a global or static variable. Maximum total bufer size is 64K.

Serial1.addMemoryForWrite(buffer, size)

The buffer array must be a global or static variable. Maximum total bufer size is 64K.

Serial1.attachRts(pin)

This function must be called after Serial1.begin();

The RTS output from Teensy should be connected to the CTS input on the other serial device, similarly to the TX output connecting to the other device's RX input. Do not simply connect same-named signals with serial.

Supported only on Teensy LC, 3.x, 4.x. Any digital pin may be used.

Serial1.attachCts(pin)

This function must be called after Serial1.begin();

The CTS input from Teensy should be connected to the RTS output on the other serial device, similarly to the RX input connecting to the other device's TX output. Do not simply connect same-named signals with serial.

Supported only on Teensy 3.x, 4.x. Only specific pins may be used.

Serial1.begin(baud, format)

Serial1.write9bit(word)

Teensy 3.0, 3.1, 3.2 support 9 bit mode on Serial1, Serial2 and Serial3.
Teensy 3.5, 3.6 support 9 bit mode on Serial1, Serial2, Serial3, Serial4, Serial5 and Serial6.
Teensy LC supports 9 bit mode only on Serial1. Serial2 and Serial3 do not have 9 bit mode.

In 7 and 8 bit modes, this function is the same as write(byte).

Usable Baud Rates

High Speed Baud Rates

At very high baud rates, even small software delays can allow a recive buffer to overflow which causing incoming data to be lost. RTS/CTS flow control offers the very best solution to data loss, but requires 2 extra signals and proper RTS/CTS support by the other device communicating with Teensy. The alternative is to use addMemoryForRead() to increase the receive buffer size large enough to capture all incoming data during times your program is busy with other work.

On Teensy 4 boards, the serial ports normally are limited to 6 Mbit/sec baud rate. However, maximum baud rate can be increased to 20 Mbit/sec by reconfiguring the UART clock source.

Arduino Uno at 57600 Baud - It's Actually 58824

void setup() {
  Serial1.begin(58824);  // Arduino 57600 is actually 58824
}

Alternately, if you edit the Arduino code to use "Serial.begin(57601)", Arduino will create a baud rate with only -0.79% error, which exactly matches Teensy.

The Arduino bootloader on Duemilanove and Diecimila, and the 8u2 or 16u2 chip on Arduino Uno when set to 57600, are always 58824 baud. These are not easily reconfigured, so setting Teensy to 58824 baud is the best solution if you must communicate with these.