Arduino_SerialRecord

An Arduino library for sending and receiving multiple-values records on the serial port.

View the Project on GitHub osteele/Arduino_SerialRecord

Serial Record Library for Arduino

Arduino Lint Compile Examples

The SerialRecord library for Arduino sends and receive records, containing multiple integers, over the serial port.

This library is intended for novice programmers. It is designed to be easy to use, to detect when it is used incorrectly, to detect and report when it receives invalid data. Data is sent and received as comma-separated ASCII with optional field names, for ease of inspection with the Serial Monitor and for compatibility with the Serial Plotter and with Processing sketches that also use this format.

The library can be used with the SerialRecord library for Processing 4, but does not require it.

Design Goals

Non-goals

Features

Installation

  1. In the Arduino IDE, select the Tools > Manager Libraries menu item.
  2. In the Arduino IDE, select the “Sketch > Include Library > Add .ZIP Library…” menu item. Select the downloaded ZIP file.
  3. Click “Install”.

Examples

Once you install the library, these examples are available in the File > Examples > SerialRecord submenu. You can also review them on GitHub.

SendSingleValue

This sketch repeatedly sends a record that contains a single value.

The sketch pairs well with the ReceiveSingleValue example from the [Processing SerialRecord] library.

You can also use the Serial Monitor to inspect the values that the sketch sends to the serial port.

This sketch is no different from calling Serial.println(value).

Things to try:

SendMultipleValues

This sketch repeatedly sends a record that contains two values:

This sketch pairs well with the RecieveMultipleValues example from the SerialRecord library for Processing 4 library.

You can also use the Serial Monitor to inspect the values that the sketch sends to the serial port.

Things to try:

ReceiveSingleValue

This sketch repeatedly receives a record that contains a single value, and uses it to control the builtin LED. The value should be 0 or 1.

This sketch pairs well with the SendSingleValue example from the [Processing SerialRecord] library.

You can also interact with this sketch from the Serial Monitor. Enter 0 or 1 into the text area at the top, and press “Send”. Then enter !e to ask the Arduino to send back the last values it received.

ReceiveMultipleValues

This sketch repeatedly receives a record that contains two values. Both values should be in the range 0…1023:

This sketch pairs well with the SendMultipleValues example from the [Processing SerialRecord] library.

You can also interact with this sketch from the Serial Monitor. Enter 100,200 into the text area at the top, and press “Send”. Then enter !e to ask the Arduino to send back the last values it received.

SendReceiveMultipleValues

This sketch repeatedly receives two values, and send back the same values in the opposite order as well as their sum.

(This mode of communication, where a connection is used both to send and receive, is called “full duplex”.)

This sketch pairs well with the SendReceiveMultipleValues example from the SerialRecord library for Processing 4 library.

You can also interact with this sketch from the Serial Monitor. Enter 100,200 into the text area at the top, and press “Send”.

SendFieldNames

This sketch is similar to SendMultipleValues, except that it also includes field names in the strings that it sends. These are displayed in the Serial Monitor and the Serial Console, but the SerialRecord library for Processing 4 library ignores them.

Motivation

This library was intended as a replacement for the manual use of chains of:

Serial.print(value1);
Serial.print(",");
Serial.print(value2);
Serial.print(",");
Serial.print(value3);
Serial.println();

I found while teaching an introductory course physical on computing that novice programmers often garble the order of values, commas and the newline when they add, remove, or rearrange values. Debugging the resulting errors did not contribute to the learning objectives for this particular course.

Alternatives

For alternatives that support a variety of transports and serialization formats (including higher-efficiency binary formats), browse the Communications topic of the Arduino library manager. Also note Firmata, which features declarative binding of value positions to sensors or pin numbers.

Acknowledgements

The idea of providing this code as a library was inspired by code provided to students by the NYU Shanghai IMA “Interaction Lab” course, for them to copy and paste into their sketches.

License

Copyright (C) 2020-2022 Oliver Steele. This software is made available under the terms of the GNU LGPL License.