{"id":16508630,"url":"https://github.com/osteele/arduino_serialrecord","last_synced_at":"2026-05-15T22:02:57.391Z","repository":{"id":42459651,"uuid":"477427277","full_name":"osteele/Arduino_SerialRecord","owner":"osteele","description":"An Arduino library for sending and receiving multiple-values records on the serial port.","archived":false,"fork":false,"pushed_at":"2022-11-17T13:28:02.000Z","size":614,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-25T09:18:39.665Z","etag":null,"topics":["arduino","arduino-library"],"latest_commit_sha":null,"homepage":"https://osteele.github.io/Arduino_SerialRecord/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osteele.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-03T18:17:33.000Z","updated_at":"2023-10-12T22:43:34.000Z","dependencies_parsed_at":"2023-01-21T15:16:46.463Z","dependency_job_id":null,"html_url":"https://github.com/osteele/Arduino_SerialRecord","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2FArduino_SerialRecord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2FArduino_SerialRecord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2FArduino_SerialRecord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2FArduino_SerialRecord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osteele","download_url":"https://codeload.github.com/osteele/Arduino_SerialRecord/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241460086,"owners_count":19966511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library"],"created_at":"2024-10-11T15:46:43.378Z","updated_at":"2025-10-08T11:27:08.105Z","avatar_url":"https://github.com/osteele.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serial Record Library for Arduino\n\n[![Arduino Lint](https://github.com/osteele/Arduino_SerialRecord/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/osteele/Arduino_SerialRecord/actions/workflows/arduino-lint.yml)\n[![Compile Examples](https://github.com/osteele/Arduino_SerialRecord/actions/workflows/compile-examples.yml/badge.svg)](https://github.com/osteele/Arduino_SerialRecord/actions/workflows/compile-examples.yml)\n\nThe [SerialRecord library for\nArduino](https://osteele.github.io/Arduino_SerialRecord/) sends and receive\n*records, containing multiple* integers, over the serial port.\n\nThis library is intended for novice programmers. It is designed to be easy to\nuse, to detect when it is used incorrectly, to detect and report when it\nreceives invalid data. Data is sent in a format that is compatible with the\nSerial Montior and Serial Plotter tools: comma-separated ASCII values, with\noptional field names.\n\nThe library can be used with the [SerialRecord library for\nProcessing](https://osteele.github.io/Processing_SerialRecord/), but does not\nrequire it.\n\n![](docs/sketch.png \"Arduino IDE with example sketch\")\n\n[SerialRecord library for Processing]: https://osteele.github.io/Processing_SerialRecord/\n\n## Design Goals\n\n- Easy for novice programmers to configure and use\n- Easy to inspect the transmitted data\n- Detects and provides diagnostics for common errors\n\n### Non-goals\n\n- Efficiency. The library uses an ASCII representation of numbers. This is easy\n  to visually inspect without tools, but it is computationally expensive to read\n  and write, and requires more bandwidth than a binary representation.\n- Flexibility. All records must have the same number of values; only integers\n  are supported. These limitations make it possible to detect errors in code\n  that uses the library, but they are not appropriate for all projects. (See the\n  \"Alternatives\" section below.)\n\n## Features\n\n- Send an \"!e\" to the sketch to send received the values array back to the\n  serial port. (The \"SerialRecord for Processing\" library can be set to do this\n  periodically.)\n- Attempting to read an array position that is out of bounds prints an error to\n  the serial port, and returns the value -1.\n- If a record contains too many values or too few, the library prints an error\n  to the serial port. (The matching \"SerialRecord for Processing\" library can be\n  set to automatically display this error, and other errors, to the Processing\n  console and optionally on the canvas.)\n- If a received line cannot be parsed as a series of integers, the library\n  prints a warning is printed on the serial port.\n\n## Installation\n\n1. In the Arduino IDE, select the *Tools \u003e Manager Libraries* menu item. This\n   opens a new pane, \"Library Manager\", on the left side of the current editor\n   window.\n2. In the Library Manager pane, there is a text area with a prompt \"Filter your\n   search\". Enter \"serialrecord\" into this text field.\n3. There should be one search result, \"SerialRecord by Oliver Steele\". Move the\n   mouse over this search result, in order to disclose the \"Install\" button as\n   shown in the screenshot.\n4. Click \"Install\".\n\n![](docs/arduino-library-manager.png)\n\n## Examples\n\nOnce this library has been installed, the following examples are available in\nthe *File \u003e Examples \u003e SerialRecord* submenu. You can also [view the examples n\nGitHub](https://github.com/osteele/Arduino_SerialRecord/tree/main/examples).\n\n![](docs/arduino-examples.png)\n\nThe examples are designed to interoperate with Processing sketches, in the\n[SerialRecord library for Processing] library. The [SerialRecord for Processing\nwiki](https://github.com/osteele/Processing_SerialRecord/wiki/Examples) suggests\nwhich example from the [SerialRecord library for Processing] library is intended\nfor use with each Arduino example. (For example, the Arduino\n`ReceiveSingleValue` sketch was designed to pair with the Processing\n`SendSingleValue` sketch.)\n\n\u003e Note: The examples that send values contain a call to `delay(20)`. This\n\u003e prevents the Arduino from *sending* data faster than a Processing sketch that\n\u003e is running at the default 30 frames per second can *process* it. There are\n\u003e other ways to prevent this problem from occurring, but this is the simplest.\n\n\u003e Note: Due to a bug in the Arduino IDE 2.0.0 as of October 2022, library\n\u003e examples may not appear in the Examples menu, the first time you select the\n\u003e *File \u0026gt; Examples* menu item. If the only examples listed are the \"Built-in\n\u003e examples\", simply release the mouse button and then select the *File \u0026gt;\n\u003e Examples* menu item a second time, in order to see library examples as well.\n\n### SendSingleValue\n\nThis sketch repeatedly sends a record that contains a single value.\n\nThe sketch pairs well with the ReceiveSingleValue example from the [SerialRecord\nlibrary for Processing].\n\nYou can also use the Serial Monitor to inspect the values that the sketch sends\nto the serial port.\n\nThis sketch has the same effect as calling `Serial.println(value)`. Its\nadvantage is that it is simple to modify it to log a second value, in a format\nthat the receiving program can reliably distinguish the first from the second\nvalue. (The SendMultipleValues example demonstrates this.)\n\nThings to try:\n\n- Connect a potentiometer to the Arduino, and send its value instead.\n\n### SendMultipleValues\n\nThis sketch repeatedly sends a record that contains two values:\n\n1. The value of `millis()`, modulo 1024.\n2. The analog value that is read from pin 0. If you attach a potentiometer to\n  that pin, you can control this value by moving the pot.\n\nThis sketch pairs well with the RecieveMultipleValues example from the\n[SerialRecord library for Processing].\n\nYou can also use the Serial Monitor to inspect the values that the sketch sends\nto the serial port.\n\nThings to try:\n\n- Connect a second potentiometer to the Arduino, and send the values from both\n  potentiometers instead of sending a value that is based on `millis()`.\n- Send the value from another sensor, such as temperature or proximity.\n\n### ReceiveSingleValue\n\nThis sketch repeatedly receives a record that contains a single value, and uses\nit to control the builtin LED. The value should be 0 or 1.\n\nThis sketch pairs well with the SendSingleValue example from the [SerialRecord\nlibrary for Processing].\n\nYou can also interact with this sketch from the Serial Monitor. Enter `0` or `1`\ninto the text area at the top, and press \"Send\". Then enter `!e` to ask the\nArduino to send back the last values it received.\n\n### ReceiveMultipleValues\n\nThis sketch repeatedly receives a record that contains two values. Both values\nshould be in the range 0…1023:\n\n- The first value controls the builtin LED. The LED is turned on if the value is\n  in the upper half of the range (512…1023).\n- The second value controls a buzzer attached to pin 9. If the value is 0, the\n  buzzer is silenced; otherwise, it plays a tone at the specified frequency.\n\nThis sketch pairs well with the SendMultipleValues example from the\n[SerialRecord library for Processing].\n\nYou can also interact with this sketch from the Serial Monitor. Enter `100,200`\ninto the text area at the top, and press \"Send\". Then enter `!e` to ask the\nArduino to send back the last values it received.\n\n### SendReceiveMultipleValues\n\nThis sketch repeatedly receives two values, and send back the same values in the\nopposite order as well as their sum.\n\n(This mode of communication, where the same connection is used both to send and\nreceive data, is called \"full duplex\".)\n\nThis sketch pairs well with the SendReceiveMultipleValues example from the\n[SerialRecord library for Processing] library.\n\nYou can also interact with this sketch from the Serial Monitor. Enter `100,200`\ninto the text area at the top, and press \"Send\".\n\n### SendFieldNames\n\nThis sketch is similar to SendMultipleValues, except that it also includes field\nnames in the strings that it sends. These field names are displayed in the\nSerial Monitor and the Serial Console. The [SerialRecord library for Processing]\nlibrary stores them in a separate array, so that a program that uses that\nlibrary can either process or ignore them.\n\nExample output:\n\n```text\nmillis:12,analog:113\nmillis:24,analog: 115\n```\n\n## Motivation\n\nThis library was intended as a replacement for the manual use of seqeunces of\ncode such as:\n\n```c++\nSerial.print(value1);\nSerial.print(\",\");\nSerial.print(value2);\nSerial.print(\",\");\nSerial.print(value3);\nSerial.println();\n```\n\nWhile teaching an introductory course on physical computing, I found that novice\nprogrammers often end up with code that fails to separate values by the\nseparator character \"`,`\", omits the final `Serial.println()`, and/or places\nthis `Serial.println()` between values within the record. This resulted in\nmysterious (to the students) failure modes. Debugging the resulting errors did\nnot contribute to the learning objectives for this particular course.\n\n## Alternatives\n\nFor sending values, the simplest alternative is just to use `Serial.println()`.\n\nFor alternatives that support a variety of transports and serialization formats\n(including higher-efficiency binary formats), browse the Communications topic of\nthe Arduino library manager.\n\nIn particular, note:\n\n- [Firmata](https://github.com/firmata/arduino), which features declarative\n  binding of value positions to sensors or pin numbers.\n- [VSync Library](http://ernestum.github.io/VSync/) for the Arduino platform\n  \"magically\" synchronizes Arduino and Processing variables.\n\n## Acknowledgements\n\nThe idea of providing this code as a library was inspired by code provided to\nstudents by the NYU Shanghai IMA \"Interaction Lab\" course, for them to copy and\npaste into their sketches.\n\n## License\n\nCopyright (C) 2020-2022 Oliver Steele. This software is made available under the\nterms of the GNU LGPL License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Farduino_serialrecord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosteele%2Farduino_serialrecord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Farduino_serialrecord/lists"}