diff options
Diffstat (limited to 'source/lang/api/serial.rst')
| -rw-r--r-- | source/lang/api/serial.rst | 282 |
1 files changed, 0 insertions, 282 deletions
diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst deleted file mode 100644 index e287015..0000000 --- a/source/lang/api/serial.rst +++ /dev/null @@ -1,282 +0,0 @@ -.. 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 |