.. FIXME [0.0.13] This doesn't include UART4/5, or USART6 .. highlight:: cpp .. _lang-serial: Serial Ports (``Serial1``, ``Serial2``, ``Serial3``) ==================================================== This page describes how to use the built-in serial ports (also known as USARTs). For more information about serial ports, see :ref:`usart`. .. contents:: Contents :local: Getting Started --------------- First, decide which serial port you wish to use, and :ref:`connect its pins to the device you're communicating with `. (The TX and RX pins for a serial port are labeled on your board's silkscreen; for example, serial port 2 has pins labeled "TX2" and "RX2"). The variable for controlling a serial port is the word ``Serial``, plus the serial port's number. For example, you can control serial port 1 with the variable ``Serial1``, serial port 2 with ``Serial2``, and so on. In order to get started using your serial port, you'll first need to turn it on. Do this by calling your serial port's ``begin()`` function, giving it the baud rate you wish it to communicate at. If you're not sure what baud rate to use, 9600 is a safe (although slow) value to try. Put this call to ``begin()`` in your :ref:`lang-setup`, like in the following example:: void setup() { // 9600 is the baud rate to use. The baud rate determines how // fast the communication goes. Serial2.begin(9600); } void loop() { // Communicate using Serial2 here } Communicating Over Serial ------------------------- Now that your serial port is set up, it's time to start communicating. One common use for serial ports is to print strings and other debugging information to a computer. You can print numbers or strings using ``print()`` and ``println()``, like this:: void printSomeInformation() { Serial2.print("First, print this string. Then print a number: "); Serial2.print(42); Serial2.print(". You can print floating point values, too: "); Serial2.print(3.14); Serial2.println(". Using println() instead of print() ends the line."); Serial2.println("This sentence starts on a new line."); } This sort of communication can go both ways: you can send characters from a computer to a serial port as well. You can check how many characters are waiting for you to read using the ``available()`` function, and read them out one at a time using ``read()``. The following example program uses these functions to "echo" back anything sent to ``Serial2``:: void setup() { Serial2.begin(9600); } void echoCharacter() { // Check to see if we have received any information. numUnread // will hold the number of bytes we've received, but haven't // looked at yet. int numUnread = Serial2.available(); // numUnread > 0 means that there are some unread bytes waiting if (numUnread > 0) { // Read a single byte out: byte b = Serial2.read(); // And then print it back: Serial2.print(b); } } void loop() { echoCharacter(); } Function Reference ------------------ This section gives a full listing of functions available for use with serial ports. Library Documentation --------------------- All of the ``Serial[1,2,3]`` objects are instances of the ``HardwareSerial`` class, which is documented in this section. (This means that you can use any of these functions on any of ``Serial1``, ``Serial2``, and ``Serial3``). .. cpp:class:: HardwareSerial Serial port class. Predefined instances are ``Serial1``, ``Serial2``, and ``Serial3``. .. cpp:function:: void HardwareSerial::begin(unsigned int baud) Set up a ``HardwareSerial`` object for communications. This method must be called before attempting to use the ``HardwareSerial`` object (typically, you call this in your :ref:`setup() ` function). .. cpp:function:: void HardwareSerial::end() Disables the USART associated with this object, allowing any associated communication pins to be used for other purposes. .. cpp:function:: unsigned int HardwareSerial::available() Returns the number of bytes available for reading. .. cpp:function:: unsigned char HardwareSerial::read() Returns the next available, unread character. If there are no available characters (you can check this with :cpp:func:`available `), the call will block until one becomes available. .. cpp:function:: void HardwareSerial::flush() Throw away the contents of the serial port's receiver (RX) buffer. That is, clears any buffered characters, so that the next character read is guaranteed to be new. .. cpp:function:: void HardwareSerial::print(unsigned char b) Print the given byte over the USART. .. cpp:function:: void HardwareSerial::print(char c) Print the given character over the USART. 7-bit clean characters are typically interpreted as ASCII text. .. cpp:function:: void HardwareSerial::print(const char *str) Print the given null-terminated string over the USART. .. cpp:function:: void HardwareSerial::print(int n) Print the argument's digits over the USART, in decimal format. Negative values will be prefixed with a ``'-'`` character. .. cpp:function:: void HardwareSerial::print(unsigned int n) Print the argument's digits over the USART, in decimal format. .. cpp:function:: void HardwareSerial::print(long n) Print the argument's digits over the USART, in decimal format. Negative values will be prefixed with a ``'-'`` character. .. cpp:function:: void HardwareSerial::print(unsigned long n) Print the argument's digits over the USART, in decimal format. .. cpp:function:: void HardwareSerial::print(long n, int base) Print the digits of ``n`` over the USART, in base ``base`` (which may be between 2 and 16). The ``base`` value 2 corresponds to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal. Negative values will be prefixed with a ``'-'`` character. .. cpp:function:: void HardwareSerial::print(double n) Print ``n``, accurate to 2 digits after the decimal point. .. _lang-serial-println: .. cpp:function:: void HardwareSerial::println(char c) Like ``print(c)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(const char *c) Like ``print(c)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(unsigned char b) Like ``print(b)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(int n) Like ``print(n)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(unsigned int n) Like ``print(n)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(long n) Like ``print(n)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(unsigned long n) Like ``print(n)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(long n, int base) Like ``print(n, b)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println(double n) Like ``print(n)``, followed by ``"\r\n"``. .. cpp:function:: void HardwareSerial::println() Prints ``"\r\n"`` over the USART. .. cpp:function:: void HardwareSerial::write(unsigned char ch) Sends one character over the USART. This function is currently blocking. This is a low-level function. One of the ``print()`` or ``println()`` functions is likely to be more useful when printing multiple characters, when formatting numbers for printing, etc. .. cpp:function:: void HardwareSerial::write(const char* str) Send the given null-terminated character string over the USART. This is a low-level function. One of the ``print()`` or ``println()`` functions is likely to be more useful when printing multiple characters, when formatting numbers for printing, etc. .. cpp:function:: void HardwareSerial::write(void *buf, unsigned int size) Writes the first ``size`` bytes of ``buf`` over the USART. Each byte is transmitted as an individual character. This is a low-level function. One of the ``print()`` or ``println()`` functions is likely to be more useful when printing multiple characters, when formatting numbers for printing, etc. .. cpp:function:: int HardwareSerial::txPin() Return the number of the TX (transmit) pin. .. cpp:function:: int HardwareSerial::rxPin() Return the number of the RX (receive) pin. Arduino Compatibility Note -------------------------- Unlike the Arduino, none of the Maple's serial ports is connected to the USB port on the Maple board. If you want to communicate using the built-in USB port, use :ref:`SerialUSB ` instead. You will need an additional USB-to-serial adapter to communicate between a USART and your computer. .. FIXME [0.1.0] port these examples over .. Examples .. -------- .. - `ASCII Table `_ .. - `Dimmer `_ .. - `Graph `_ .. - `Physical Pixel `_ .. - `Virtual Color Mixer `_ .. - `Serial Call Response `_ .. - `Serial Call Response ASCII `_ .. include:: /arduino-cc-attribution.txt