1 files changed, 243 insertions, 0 deletions
diff --git a/docs/source/lang/api/serialusb.rst b/docs/source/lang/api/serialusb.rst
new file mode 100644
index 0000000..3bb8c00
--- /dev/null
+++ b/docs/source/lang/api/serialusb.rst
@@ -0,0 +1,243 @@
+.. highlight:: cpp
+
+.. _lang-serialusb:
+
+``SerialUSB``
+=============
+
+Used for communication between the Maple board and a computer.
+
+.. contents:: Contents
+   :local:
+
+Introduction
+------------
+
+In addition to three :ref:`serial ports <lang-serial>`, the Maple's
+STM32 microprocessor includes a dedicated USB peripheral.  This
+peripheral is used to emulate a regular serial port for use as a
+terminal (text read/write).  The emulated terminal is relatively slow
+and inefficient; it is best for transferring data at regular serial
+speeds (kilobaud).
+
+Library access to the emulated serial port is provided through the
+``SerialUSB`` object.  You can mostly use ``SerialUSB`` as a drop-in
+replacement for ``Serial1``, ``Serial2``, and ``Serial3``.
+
+.. warning:: The ``SerialUSB`` functionality includes a 50 millisecond
+   timeout for writes, and does not try to detect if the USB host is
+   "really" connected, or just enumerated and initialized.
+
+   This means that if you have a number of calls to one of the
+   ``SerialUSB`` ``write()`` or ``print()`` functions in your code,
+   and you are not monitoring the emulated on a computer, your program
+   will run much, much slower than if it is being monitored or totally
+   disconnected (run off of a battery).
+
+   You can avoid this behavior by :ref:`deciphering the port status
+   using the DTR and RTS line status <lang-serialusb-safe-print>`; the
+   behavior of these control lines is platform dependent and we no
+   longer interpret them by default.
+
+Library Documentation
+---------------------
+
+The ``SerialUSB`` object is an instance of the ``USBSerial`` class,
+which is documented in this section.  This means that you can use any
+of these functions by writing
+``SerialUSB.functionName(arguments...)``.  For example, to print the
+message "hello, world!", you can write ``USBSerial.println("hello,
+world!")``.
+
+.. cpp:class:: USBSerial
+
+   Emulated serial-over-USB class.  ``SerialUSB`` is the predefined
+   (singleton) instance.
+
+.. _lang-serialusb-begin:
+
+.. cpp:function:: USBSerial::begin()
+
+   Set up the USB peripheral for emulated serial communication.  The
+   peripheral is configured this way by default; calling this function
+   should only be necessary if you have disabled the peripheral using
+   ``SerialUSB.end()``.
+
+.. _lang-serialusb-end:
+
+.. cpp:function:: USBSerial::end()
+
+   Disables the USB peripheral.  Note that using this function will
+   terminate all USB communications between the Maple and the USB
+   host; in particular, it implies that you won't be able to upload
+   any new programs without resetting the board or using
+   :ref:`perpetual bootloader mode
+   <troubleshooting-perpetual-bootloader>`.
+
+.. cpp:function:: unsigned int USBSerial::available()
+
+   Returns the number of bytes available for reading.
+
+.. _lang-serialusb-read:
+
+.. cpp:function:: unsigned char USBSerial::read()
+
+   Returns the next available, unread character.  If there are no
+   available characters (you can check this with :cpp:func:`available
+   <USBSerial::available>`), the call will block until one
+   becomes available.
+
+.. cpp:function:: USBSerial::print(unsigned char b)
+
+   Print the given byte over the USB connection.
+
+.. cpp:function:: USBSerial::print(char c)
+
+   Print the given character over the USB connection.  7-bit clean characters
+   are typically interpreted as ASCII text.
+
+.. cpp:function:: USBSerial::print(const char *str)
+
+   Print the given null-terminated string over the USB connection.
+
+.. cpp:function:: USBSerial::print(int n)
+
+   Print the argument's digits over the USB connection, in decimal format.
+   Negative values will be prefixed with a ``'-'`` character.
+
+.. cpp:function:: USBSerial::print(unsigned int n)
+
+   Print the argument's digits over the USB connection, in decimal format.
+
+.. cpp:function:: USBSerial::print(long n)
+
+   Print the argument's digits over the USB connection, in decimal
+   format.  Negative values will be prefixed with a ``'-'`` character.
+
+.. cpp:function:: USBSerial::print(unsigned long n)
+
+   Print the argument's digits over the USB connection, in decimal
+   format.
+
+.. cpp:function:: USBSerial::print(long n, int base)
+
+   Print the digits of ``n`` over the USB connection, 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:: USBSerial::print(double n)
+
+   Print ``n``, accurate to 2 digits after the decimal point.
+
+.. _lang-serialusb-println:
+
+.. cpp:function:: USBSerial::println(char c)
+
+   Like ``print(c)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(const char *c)
+
+   Like ``print(c)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(unsigned char b)
+
+   Like ``print(b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(int n)
+
+   Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(unsigned int n)
+
+   Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(long n)
+
+   Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(unsigned long n)
+
+   Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(long n, int base)
+
+   Like ``print(n, b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(double n)
+
+   Like ``print(n)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println()
+
+   Prints ``"\r\n"`` over the USB connection.
+
+.. cpp:function:: USBSerial::write(unsigned char ch)
+
+   Sends one character over the USB connection.  This function is
+   currently blocking, although nonblocking writes are a planned
+   future extension.
+
+   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:: USBSerial::write(const char* str)
+
+   Send the given null-terminated character string over the USB
+   connection.
+
+   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:: USBSerial::write(void *buf, unsigned int size)
+
+   Writes the first ``size`` bytes of ``buf`` over the USB connection.
+   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.
+
+Examples
+--------
+
+.. _lang-serialusb-safe-print:
+
+**Safe print**: This function should run smoothly and not block; the
+LED should blink at roughly the same speed whether being monitored,
+running from battery, or connected but not monitored. You may need to
+experiment with the DTR/RTS logic for your platform and device
+configuration. ::
+
+    #define LED_PIN 13
+
+    void setup() {
+        /* Set up the LED to blink  */
+        pinMode(LED_PIN, OUTPUT);
+    }
+
+    void loop() {
+        // LED will stay off if we are disconnected;
+        // will blink quickly if USB is unplugged (battery etc)
+        if(SerialUSB.isConnected()) {
+            digitalWrite(LED_PIN, 1);
+        }
+        delay(100);
+
+        // If this logic fails to detect if bytes are going to
+        // be read by the USB host, then the println() will fully
+        // many times, causing a very slow LED blink.
+        // If the characters are printed and read, the blink will
+        // only slow a small amount when "really" connected, and fast
+        // when the virtual port is only configured.
+        if(SerialUSB.isConnected() && (SerialUSB.getDTR() || SerialUSB.getRTS())) {
+            for(int i=0; i<10; i++) {
+               SerialUSB.println(123456,BIN);
+            }
+        }
+        digitalWrite(LED_PIN, 0);
+        delay(100);
+    }
+