aboutsummaryrefslogtreecommitdiffstats
path: root/source/lang/api/serial.rst
blob: e287015ced0186b2d1d4010e0bc09fa9e08bed9f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
.. 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 <usart-circuit>`. (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()
   <lang-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
   <HardwareSerial::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 <lang-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 <http://arduino.cc/en/Tutorial/ASCIITable>`_
.. -  `Dimmer <http://arduino.cc/en/Tutorial/Dimmer>`_
.. -  `Graph <http://arduino.cc/en/Tutorial/Graph>`_
.. -  `Physical Pixel <http://arduino.cc/en/Tutorial/PhysicalPixel>`_
.. -  `Virtual Color Mixer <http://arduino.cc/en/Tutorial/VirtualColorMixer>`_
.. -  `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_
.. -  `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_

.. include:: /arduino-cc-attribution.txt