SerialUSB — Maple v0.0.9 Documentation

### Navigation

- next
- previous |
- LeafLabs |
- Docs Home |
- Index »
- Complete Language Index »

# `SerialUSB`

Used for communication between the Maple board and a computer.

Contents

- Introduction
- Library Documentation
- Examples

## Introduction

In addition to three serial ports, 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 deciphering the port status using the DTR and RTS line status; 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!")`.

class `USBSerial`

  Emulated serial-over-USB class. `SerialUSB` is the predefined (singleton) instance.

`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()`.

`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 perpetual bootloader mode.

unsigned int `USBSerial::``available`()

  Returns the number of bytes available for reading.

unsigned char `USBSerial::``read`()

  Returns the next available, unread character. If there are no available characters (you can check this with `available`), the call will block until one becomes available.

`USBSerial::``flush`()

  Removes the contents of the Serial’s associated input buffer. That is, clears any buffered characters, so that the next character read is guaranteed to be new.

`USBSerial::``print`(unsigned char b)

  Print the given byte over the USB connection.

`USBSerial::``print`(char c)

  Print the given character over the USB connection. 7-bit clean characters are typically interpreted as ASCII text.

`USBSerial::``print`(const char* str)

  Print the given null-terminated string over the USB connection.

`USBSerial::``print`(int n)

  Print the argument’s digits over the USB connection, in decimal format. Negative values will be prefixed with a `'-'` character.

`USBSerial::``print`(unsigned int n)

  Print the argument’s digits over the USB connection, in decimal format.

`USBSerial::``print`(long n)

  Print the argument’s digits over the USB connection, in decimal format. Negative values will be prefixed with a `'-'` character.

`USBSerial::``print`(unsigned long n)

  Print the argument’s digits over the USB connection, in decimal format.

`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.

`USBSerial::``print`(double n)

  Print `n`, accurate to 2 digits after the decimal point.

`USBSerial::``println`(char c)

  Like `print(c)`, followed by `"\r\n"`.

`USBSerial::``println`(const char* c)

  Like `print(c)`, followed by `"\r\n"`.

`USBSerial::``println`(unsigned char b)

  Like `print(b)`, followed by `"\r\n"`.

`USBSerial::``println`(int n)

  Like `print(n)`, followed by `"\r\n"`.

`USBSerial::``println`(unsigned int n)

  Like `print(n)`, followed by `"\r\n"`.

`USBSerial::``println`(long n)

  Like `print(n)`, followed by `"\r\n"`.

`USBSerial::``println`(unsigned long n)

  Like `print(n)`, followed by `"\r\n"`.

`USBSerial::``println`(long n, int base)

  Like `print(n, b)`, followed by `"\r\n"`.

`USBSerial::``println`(double n)

  Like `print(n)`, followed by `"\r\n"`.

`USBSerial::``println`()

  Prints `"\r\n"` over the USB connection.

`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.

`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.

`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

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);
    }

### Navigation

- next
- previous |
- LeafLabs |
- Docs Home |
- Index »
- Complete Language Index »