From 9e2bc39e16e10abc01a863af739e8d29968c2ec1 Mon Sep 17 00:00:00 2001 From: Jon Froehlich Date: Fri, 26 Jun 2026 10:32:02 -0700 Subject: [PATCH] Rewrite README as an educational landing page Replace the 3-line stub with a proper README following open-source/education best practices: textbook-first framing (prominent callouts to the physcomp textbook and the MakeabilityLab Arduino library up top), a getting-started walkthrough, a folder map grouped by topic / board / helpers, and contributor conventions pointing at docs/. Verified the lesson and library links resolve. Co-Authored-By: Claude Opus 4.8 --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8951b9f..adae62d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,86 @@ -# arduino -All things Arduino +# Makeability Lab Β· Arduino Examples -To learn how to use Arduino and the code in this repo, see https://makeabilitylab.github.io/physcomp/ +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +A teaching collection of **~260 Arduino sketches** β€” plus supporting Python, PowerShell, and Processing helpers β€” that accompany the **Makeability Lab Physical Computing textbook**. Everything here is instructional material, written to be *read*: clarity and pedagogical value matter as much as correctness. + +> ## πŸ“– New here? Start with the textbook. +> These sketches are meant to be used **alongside the lessons**, which explain the wiring, the concepts, and the code step by step. +> +> ### πŸ‘‰ [makeabilitylab.github.io/physcomp](https://makeabilitylab.github.io/physcomp/) +> +> Textbook source & issues: [github.com/makeabilitylab/physcomp](https://github.com/makeabilitylab/physcomp) + +> ## 🧩 Most sketches use our shared Arduino library +> The **MakeabilityLab Arduino Library** provides reusable classes for physical computing β€” joystick input, OLED graphics and shapes, signal filters, scrolling graphs, and more. Many sketches `#include` its headers, so install it before compiling them. +> +> ### πŸ‘‰ [github.com/makeabilitylab/makelab-arduino-lib](https://github.com/makeabilitylab/makelab-arduino-lib) +> +> Install from the Arduino IDE: **Sketch β†’ Include Library β†’ Manage Libraries…**, search **"MakeabilityLab"**, and click **Install** (it pulls in Adafruit GFX + SSD1306 automatically). + +## Getting started + +1. **Install the [Arduino IDE](https://www.arduino.cc/en/software).** See the textbook's [Arduino IDE setup lesson](https://makeabilitylab.github.io/physcomp/arduino/arduino-ide.html) for a guided walkthrough. +2. **Install the MakeabilityLab library** (above) and any third-party libraries a sketch lists in its header comment (most commonly Adafruit GFX + SSD1306 for the OLED examples). +3. **Open a sketch's `.ino` file.** Each one lives in its own folder of the same name (an Arduino requirement). +4. **Select your board and port** via `Tools β†’ Board` and `Tools β†’ Port`, then click **Upload**. +5. **Read the header comment** at the top of every sketch β€” it documents the circuit (board + wiring), the required libraries, and a link to the matching textbook lesson. + +> πŸ’‘ Different sketches target different boards (Uno, Leonardo, ESP32, Feather, …). Always check the header comment for the intended board. A few board-specific sketches also carry a small `sketch.yaml` that records their exact target. + +## What's inside + +Folders are grouped by topic or hardware platform. Every sketch is self-contained β€” there's no shared application or build graph. + +### Learn-by-topic + +| Folder | What it covers | +|---|---| +| [`Basics/`](Basics) | `analogRead`/`analogWrite`, `digitalRead`/`digitalWrite`, serial, and `tone()` β€” the core I/O primitives | +| [`OLED/`](OLED) | SSD1306 OLED graphics, animation, and small games | +| [`AddressableLEDs/`](AddressableLEDs) | NeoPixel and APA102 (DotStar) addressable RGB LEDs | +| [`Sensors/`](Sensors) | Accelerometers, microphones, color sensors, and more | +| [`Filters/`](Filters) | Smoothing and filtering noisy sensor input | +| [`Servo/`](Servo) | Driving servo motors | +| [`Serial/`](Serial) Β· [`Bluetooth/`](Bluetooth) | Serial and Bluetooth communication | +| [`GameController/`](GameController) Β· [`HumanInterfaceDevice/`](HumanInterfaceDevice) | USB HID β€” emulating a mouse/keyboard/game controller (Leonardo-class boards) | +| [`PlayingMusic/`](PlayingMusic) | Playing tones and MP3 audio | + +### Board-specific + +| Folder | Board | +|---|---| +| [`ESP32/`](ESP32) | ESP32 dev boards (WiFi/Bluetooth) | +| [`UnoR4WiFi/`](UnoR4WiFi) | Arduino Uno R4 WiFi | +| [`CPX/`](CPX) | Adafruit Circuit Playground Express | +| [`nRF52840/`](nRF52840) | Adafruit nRF52840 Feather | +| [`RedBearDuo/`](RedBearDuo) | RedBear Duo *(legacy)* | + +### Helpers & supporting material + +| Folder | What it is | +|---|---| +| [`Python/`](Python) | Host-side serial readers and tools (Python 3 + `pyserial`) | +| [`PowerShell/`](PowerShell) | Windows helper scripts | +| [`Processing/`](Processing) | Processing sketches *(legacy β€” the project has shifted to [p5.js](https://p5js.org/))* | +| [`templates/`](templates) | A copy-paste starting point for new sketches | +| [`docs/`](docs) | Repository conventions and maintenance notes | + +## For contributors & maintainers + +This repo is being modernized for the textbook's **v2.0** release. If you're editing or adding sketches, please match the existing conventions: + +- **Sketch headers** follow a standard template β€” see [`docs/sketch-header-template.md`](docs/sketch-header-template.md), with a compile-checked starting point at [`templates/SketchTemplate/`](templates/SketchTemplate). +- **Textbook links** in headers point to *specific* lessons; keep them in lockstep with the live textbook. +- **Naming**: member/global variables use a leading underscore (`_display`); constants use `UPPER_SNAKE_CASE`. +- Some sketches are intentionally kept but not expected to compile on current toolchains β€” these are tracked in [`docs/legacy-sketches.md`](docs/legacy-sketches.md). + +Bug reports and suggestions are welcome via [GitHub Issues](https://github.com/makeabilitylab/arduino/issues). + +## About + +Created and maintained by [Jon Froehlich](https://jonfroehlich.github.io/) and the [Makeability Lab](https://makeabilitylab.cs.washington.edu/) at the University of Washington, for use in physical computing courses and the accompanying [Physical Computing textbook](https://makeabilitylab.github.io/physcomp/). + +## License + +Released under the [MIT License](LICENSE). Β© 2020–present Jon Froehlich and the Makeability Lab.