aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-08-16 06:11:03 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2011-08-16 06:11:03 -0400
commit1529927c59ee12f390bec9eb612343a982e1f43c (patch)
tree8b5a3f66552f13350b3f95c4ab4d5f05f3397d27
parent5dad37433f3ed4a81baf7bc2a89f38f2db7e4af1 (diff)
downloadlibrambutan-1529927c59ee12f390bec9eb612343a982e1f43c.tar.gz
librambutan-1529927c59ee12f390bec9eb612343a982e1f43c.zip
serial: Add tutorial style content, fix method signatures.
-rw-r--r--source/lang/api/serial.rst164
1 files changed, 122 insertions, 42 deletions
diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst
index a08c9b7..8c9ebc7 100644
--- a/source/lang/api/serial.rst
+++ b/source/lang/api/serial.rst
@@ -1,31 +1,104 @@
+.. highlight:: cpp
+
.. _lang-serial:
Serial Ports (``Serial1``, ``Serial2``, ``Serial3``)
====================================================
-Used for communication between the Maple board and a computer or other
-devices.
+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:
-Introduction
-------------
-
-.. FIXME [0.0.12/Maple Native] UART4, UART5
-
-To use a serial port to communicate with an external serial device,
-connect the TX pin to your device's RX pin, the RX to your device's TX
-pin, and your Maple board's ground to your device's ground.
-
-.. warning:: Don't connect these pins directly to an RS232 serial
- port; they operate at +/- 12V and can damage your board.
+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
---------------------
-.. FIXME [0.1.0] Tutorial-style usage introduction
-
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``,
@@ -36,14 +109,14 @@ means that you can use any of these functions on any of ``Serial1``,
Serial port class. Predefined instances are ``Serial1``,
``Serial2``, and ``Serial3``.
-.. cpp:function:: HardwareSerial::begin(unsigned int baud)
+.. 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:: HardwareSerial::end()
+.. cpp:function:: void HardwareSerial::end()
Disables the USART associated with this object, allowing any
associated communication pins to be used for other purposes.
@@ -59,107 +132,106 @@ means that you can use any of these functions on any of ``Serial1``,
<HardwareSerial::available>`), the call will block until one
becomes available.
-.. cpp:function:: HardwareSerial::flush()
+.. 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:: HardwareSerial::print(unsigned char b)
+.. cpp:function:: void HardwareSerial::print(unsigned char b)
Print the given byte over the USART.
-.. cpp:function:: HardwareSerial::print(char c)
+.. 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:: HardwareSerial::print(const char *str)
+.. cpp:function:: void HardwareSerial::print(const char *str)
Print the given null-terminated string over the USART.
-.. cpp:function:: HardwareSerial::print(int n)
+.. 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:: HardwareSerial::print(unsigned int n)
+.. cpp:function:: void HardwareSerial::print(unsigned int n)
Print the argument's digits over the USART, in decimal format.
-.. cpp:function:: HardwareSerial::print(long n)
+.. 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:: HardwareSerial::print(unsigned long n)
+.. cpp:function:: void HardwareSerial::print(unsigned long n)
Print the argument's digits over the USART, in decimal format.
-.. cpp:function:: HardwareSerial::print(long n, int base)
+.. 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:: HardwareSerial::print(double n)
+.. cpp:function:: void HardwareSerial::print(double n)
Print ``n``, accurate to 2 digits after the decimal point.
.. _lang-serial-println:
-.. cpp:function:: HardwareSerial::println(char c)
+.. cpp:function:: void HardwareSerial::println(char c)
Like ``print(c)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(const char *c)
+.. cpp:function:: void HardwareSerial::println(const char *c)
Like ``print(c)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(unsigned char b)
+.. cpp:function:: void HardwareSerial::println(unsigned char b)
Like ``print(b)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(int n)
+.. cpp:function:: void HardwareSerial::println(int n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(unsigned int n)
+.. cpp:function:: void HardwareSerial::println(unsigned int n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(long n)
+.. cpp:function:: void HardwareSerial::println(long n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(unsigned long n)
+.. cpp:function:: void HardwareSerial::println(unsigned long n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(long n, int base)
+.. cpp:function:: void HardwareSerial::println(long n, int base)
Like ``print(n, b)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println(double n)
+.. cpp:function:: void HardwareSerial::println(double n)
Like ``print(n)``, followed by ``"\r\n"``.
-.. cpp:function:: HardwareSerial::println()
+.. cpp:function:: void HardwareSerial::println()
Prints ``"\r\n"`` over the USART.
-.. cpp:function:: HardwareSerial::write(unsigned char ch)
+.. cpp:function:: void HardwareSerial::write(unsigned char ch)
Sends one character over the USART. This function is currently
- blocking, although nonblocking writes are a planned future
- extension.
+ 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:: HardwareSerial::write(const char* str)
+.. cpp:function:: void HardwareSerial::write(const char* str)
Send the given null-terminated character string over the USART.
@@ -167,7 +239,7 @@ means that you can use any of these functions on any of ``Serial1``,
``println()`` functions is likely to be more useful when printing
multiple characters, when formatting numbers for printing, etc.
-.. cpp:function:: HardwareSerial::write(void *buf, unsigned int size)
+.. 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.
@@ -176,6 +248,14 @@ means that you can use any of these functions on any of ``Serial1``,
``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
--------------------------