Serial

begin()

Enables serial channel with specified configuration.

// SYNTAX
Serial.begin();          // via USB port

// Photon, P1, Electron, and E-Series only
USBSerial1.begin();      // via USB port 

Serial1.begin(speed);         // via TX/RX pins
Serial1.begin(speed, config); //  "

Serial1.begin(9600, SERIAL_9N1); // via TX/RX pins, 9600 9N1 mode
Serial1.begin(9600, SERIAL_DATA_BITS_8 | SERIAL_STOP_BITS_1_5 | SERIAL_PARITY_EVEN); // via TX/RX pins, 9600 8E1.5

// P2, Photon 2, Photon, P1, Electron, and E-Series
#include "Serial2/Serial2.h"
Serial2.begin(speed);         // RGB-LED green(TX) and blue (RX) pins
Serial2.begin(speed, config); //  "

Serial2.begin(9600);         // via RGB Green (TX) and Blue (RX) LED pins
Serial2.begin(9600, SERIAL_DATA_BITS_8 | SERIAL_STOP_BITS_1_5 | SERIAL_PARITY_EVEN); // via RGB Green (TX) and Blue (RX) LED pins, 9600 8E1.5

// Electron and E-Series only
#include "Serial4/Serial4.h"
Serial4.begin(speed);         // via C3(TX)/C2(RX) pins
Serial4.begin(speed, config); //  "

// Electron and E-Series only
#include "Serial5/Serial5.h"
Serial5.begin(speed);         // via C1(TX)/C0(RX) pins
Serial5.begin(speed, config); //  "

Parameters:

  • speed: parameter that specifies the baud rate (long) (optional for Serial and USBSerial1
  • config: parameter that specifies the number of data bits used, parity and stop bits (long) (not used with Serial and USBSerial1)
// EXAMPLE USAGE
void setup()
{
  Serial.begin(9600);   // open serial over USB

  // Wait for a USB serial connection for up to 30 seconds
  waitFor(Serial.isConnected, 30000);

  Serial1.begin(9600);  // open serial over TX and RX pins

  Serial.println("Hello Computer");
  Serial1.println("Hello Serial 1");
}

void loop() {}

Since 0.5.0: 28800 baudrate set by the Host on Serial will put the device in Listening Mode, where a YMODEM download can be started by additionally sending an f character. Baudrate 14400 can be used to put the device into DFU Mode.

When using hardware serial channels (Serial1, Serial2, etc.), the configuration of the serial channel may also specify the number of data bits, stop bits, parity, flow control and other settings. The default is SERIAL_8N1 (8 data bits, no parity and 1 stop bit) and does not need to be specified to achieve this configuration. To specify one of the following configurations, add one of these defines as the second parameter in the begin() function, e.g. Serial1.begin(9600, SERIAL_8E1); for 8 data bits, even parity and 1 stop bit.

Pre-defined Serial configurations available:


Gen 3 Devices (nRF52) (B-Series SoM, Tracker SoM, Tracker One, Boron, Argon, and E404X):

On Gen 3 (Argon, Boron, B-Series SoM, Tracker SoM) devices:

Hardware serial port baud rates are: 1200, 2400, 4800, 9600, 19200, 28800, 38400, 57600, 76800, 115200, 230400, 250000, 460800, 921600 and 1000000.

Configuration options include:

  • SERIAL_8N1 - 8 data bits, no parity, 1 stop bit (default)
  • SERIAL_8E1 - 8 data bits, even parity, 1 stop bit

Other options, including odd parity, and 7 and 9 bit modes, are not available on Gen 3 devices (Argon, Boron, B-Series SoM, Tracker SoM).

Flow control is available on Serial1 D3(CTS) and D2(RTS). If you are not using flow control (the default), then these pins can be used as regular GPIO.

  • SERIAL_FLOW_CONTROL_NONE - no flow control
  • SERIAL_FLOW_CONTROL_RTS - RTS flow control
  • SERIAL_FLOW_CONTROL_CTS - CTS flow control
  • SERIAL_FLOW_CONTROL_RTS_CTS - RTS/CTS flow control


Gen 4 Devices (RTL872x) (P2, Photon 2, and M-SoM):

On the P2, Photon 2, and M-SoM:

Supported baud rates: 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, 76800, 115200, 128000, 153600, 230400, 380400, 460800, 500000, 921600, 1000000, 1382400, 1444400, 1500000, 1843200, 2000000, 2100000, 2764800, 3000000, 3250000, 3692300, 3750000, 4000000, 6000000

Configuration options include:

  • SERIAL_8N1 - 8 data bits, no parity, 1 stop bit (default)
  • SERIAL_8N2 - 8 data bits, no parity, 2 stop bits
  • SERIAL_8E1 - 8 data bits, even parity, 1 stop bit
  • SERIAL_8E2 - 8 data bits, even parity, 2 stop bits
  • SERIAL_8O1 - 8 data bits, odd parity, 1 stop bit
  • SERIAL_8O2 - 8 data bits, odd parity, 2 stop bits
  • SERIAL_7O1 - 7 data bits, odd parity, 1 stop bit
  • SERIAL_7O2 - 7 data bits, odd parity, 1 stop bit
  • SERIAL_7E1 - 7 data bits, even parity, 1 stop bit
  • SERIAL_7E2 - 7 data bits, even parity, 1 stop bit

Flow control is available on Serial2 and Serial3. If you are not using flow control (the default), then these pins can be used as regular GPIO.

  • SERIAL_FLOW_CONTROL_NONE - no flow control
  • SERIAL_FLOW_CONTROL_RTS - RTS flow control
  • SERIAL_FLOW_CONTROL_CTS - CTS flow control
  • SERIAL_FLOW_CONTROL_RTS_CTS - RTS/CTS flow control


Gen 2 Devices (STM32) (E-Series, Electron, Photon, and P2; does not include E404X):

On Gen 2 devices (Photon, P1, Electron, E-Series):

Hardware serial port baud rates are: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, and 230400.

Configuration options include:

  • SERIAL_8N1 - 8 data bits, no parity, 1 stop bit (default)
  • SERIAL_8N2 - 8 data bits, no parity, 2 stop bits
  • SERIAL_8E1 - 8 data bits, even parity, 1 stop bit
  • SERIAL_8E2 - 8 data bits, even parity, 2 stop bits
  • SERIAL_8O1 - 8 data bits, odd parity, 1 stop bit
  • SERIAL_8O2 - 8 data bits, odd parity, 2 stop bits
  • SERIAL_9N1 - 9 data bits, no parity, 1 stop bit
  • SERIAL_9N2 - 9 data bits, no parity, 2 stop bits

Since 0.6.0:

  • SERIAL_7O1 - 7 data bits, odd parity, 1 stop bit
  • SERIAL_7O2 - 7 data bits, odd parity, 1 stop bit
  • SERIAL_7E1 - 7 data bits, even parity, 1 stop bit
  • SERIAL_7E2 - 7 data bits, even parity, 1 stop bit
  • LIN_MASTER_13B - 8 data bits, no parity, 1 stop bit, LIN Master mode with 13-bit break generation
  • LIN_SLAVE_10B - 8 data bits, no parity, 1 stop bit, LIN Slave mode with 10-bit break detection
  • LIN_SLAVE_11B - 8 data bits, no parity, 1 stop bit, LIN Slave mode with 11-bit break detection

NOTE: SERIAL_7N1 or (SERIAL_DATA_BITS_7 | SERIAL_PARITY_NO | SERIAL_STOP_BITS_1) is NOT supported

Alternatively, configuration may be constructed manually by ORing (|) the following configuration constants:

Data bits:

  • SERIAL_DATA_BITS_7 - 7 data bits
  • SERIAL_DATA_BITS_8 - 8 data bits
  • SERIAL_DATA_BITS_9 - 9 data bits

Stop bits:

  • SERIAL_STOP_BITS_1 - 1 stop bit
  • SERIAL_STOP_BITS_2 - 2 stop bits
  • SERIAL_STOP_BITS_0_5 - 0.5 stop bits
  • SERIAL_STOP_BITS_1_5 - 1.5 stop bits

Parity:

  • SERIAL_PARITY_NO - no parity
  • SERIAL_PARITY_EVEN - even parity
  • SERIAL_PARITY_ODD - odd parity

Hardware flow control, available only on Serial2 (CTS - A7, RTS - RGBR ):

  • SERIAL_FLOW_CONTROL_NONE - no flow control
  • SERIAL_FLOW_CONTROL_RTS - RTS flow control
  • SERIAL_FLOW_CONTROL_CTS - CTS flow control
  • SERIAL_FLOW_CONTROL_RTS_CTS - RTS/CTS flow control

LIN configuration:

  • LIN_MODE_MASTER - LIN Master
  • LIN_MODE_SLAVE - LIN Slave
  • LIN_BREAK_13B - 13-bit break generation
  • LIN_BREAK_10B - 10-bit break detection
  • LIN_BREAK_11B - 11-bit break detection

NOTE: LIN break detection may be enabled in both Master and Slave modes.

NOTE Since 0.6.0: When USBSerial1 is enabled by calling USBSerial1.begin() in setup() or during normal application execution, the device will quickly disconnect from Host and connect back with USBSerial1 enabled. If such behavior is undesirable, USBSerial1 may be enabled with STARTUP() macro, which will force the device to connect to the Host with both Serial and USBSerial1 by default.

// EXAMPLE USAGE
STARTUP(USBSerial1.begin());
void setup()
{
  while(!Serial.isConnected())
    Particle.process();
  Serial.println("Hello Serial!");

  while(!USBSerial1.isConnected())
    Particle.process();
  USBSerial1.println("Hello USBSerial1!");
}