SerialUSB

Used for communication between the Maple board and a computer.

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. The emulated terminal is relatively slow; 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 SerialUSB on a computer, your program will run 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::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 BOARD_LED_PIN

void setup() {
    /* Set up the LED to blink  */
    pinMode(LED_PIN, OUTPUT);
}

void loop() {
    // LED will stay off if we are disconnected, and will blink
    // quickly if USB is unplugged (battery power, 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() take a long time,
    // 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 will be fast 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);
}