Arduino Programs Guide is a progressive, safety-first Arduino Uno course covering serial commands, LED patterns, PWM motor control, state machines, and emergency-stop behaviour. Each lesson pairs a compile-checked sketch with wiring, safety, verification, and extension guidance.
millis().arduino-cli compile --fqbn arduino:avr:uno exercises/exercise-a-arrow-controllerExercise A accepts simple arrow commands at 9600 baud:
// USB Serial or TTL Bluetooth serial at 9600 baud\n// U D L R C control four LEDs and a clear commandThe course targets Arduino Uno and the Arduino AVR Boards core. CI compiles every sketch; that is not hardware validation. Never connect a DC motor directly to an Arduino pin. Motor lessons require a suitable driver, flyback protection, an external motor supply, and a shared ground. Other boards may differ in PWM pins, voltage levels, serial ports, or ADC ranges.
ArduinoPatterns is the companion library for optional non-blocking abstractions after Exercise B.
@dev.mako (devkyato). (2026). Arduino Programs Guide: safety-first compile-checked Arduino Uno course (Version 1.0.2). Zenodo. https://doi.org/10.5281/zenodo.21853286
", + "version": "1.0.2", + "keywords": ["Arduino", "education", "course", "Uno", "safety", "PWM", "motor control", "embedded", "serial", "state machine", "curriculum"], "license": "mit", "upload_type": "software", "access_right": "open", "language": "eng", "related_identifiers": [ {"identifier": "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/devkyato/Arduino-Programs-Guide", "relation": "isSupplementTo", "resource_type": "software"}, - {"identifier": "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/devkyato/Datary", "relation": "references", "resource_type": "software"}, - {"identifier": "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/devkyato/OpenNet", "relation": "references", "resource_type": "software"}, - {"identifier": "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/devkyato/TapAuth", "relation": "references", "resource_type": "software"}, - {"identifier": "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/devkyato/Lowpack", "relation": "references", "resource_type": "software"}, - {"identifier": "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/devkyato/Relay", "relation": "references", "resource_type": "software"}, + {"identifier": "10.5281/zenodo.21853286", "relation": "isVersionOf", "scheme": "doi"}, {"identifier": "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/devkyato/Custom-Arduino-Libraries", "relation": "references", "resource_type": "software"} ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index b50bc40..0751a4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [1.0.2] - 2026-08-09 + +### Changed + +- Overhaul Zenodo HTML description, README, citation metadata, and documentation index for archival presentation. +- Add instructor guidance, Bluetooth warm-up lesson notes, and an Exercise B path into ArduinoPatterns. +- Package `CITATION.cff` in the offline course ZIP and align attribution on `@dev.mako (devkyato)`. +- Record the Zenodo concept DOI `10.5281/zenodo.21853286`. + ## [1.0.1] - 2026-08-09 - Add Zenodo and Citation File Format metadata for archival citation. @@ -14,3 +23,4 @@ [1.0.0]: https://github.com/devkyato/Arduino-Programs-Guide/releases/tag/v1.0.0 [1.0.1]: https://github.com/devkyato/Arduino-Programs-Guide/compare/v1.0.0...v1.0.1 +[1.0.2]: https://github.com/devkyato/Arduino-Programs-Guide/compare/v1.0.1...v1.0.2 diff --git a/CITATION.cff b/CITATION.cff index bc86901..352a906 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,18 +2,43 @@ cff-version: 1.2.0 message: "If you use this software, please cite it using the metadata from this file." title: "Arduino Programs Guide: safety-first compile-checked Arduino Uno course" authors: - - family-names: devkyato + - name: "@dev.mako (devkyato)" affiliation: "MATA Company" -version: 1.0.1 +version: 1.0.2 +date-released: 2026-08-09 license: MIT repository-code: "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/devkyato/Arduino-Programs-Guide" url: "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/devkyato/Arduino-Programs-Guide" -abstract: "A safety-first compile-checked Arduino Uno course." -keywords: [Arduino, education, course, Uno, safety, PWM, motor control, embedded, serial] +doi: 10.5281/zenodo.21853286 +identifiers: + - type: doi + value: 10.5281/zenodo.21853286 +abstract: >- + Arduino Programs Guide is a progressive, safety-first Arduino Uno course covering + serial commands, LED patterns, PWM motor control, state machines, and emergency-stop + behaviour. Each lesson pairs a compile-checked sketch with wiring contracts, hardware + safety guidance, verification checklists, and extension ideas for classroom and + independent study. +keywords: + - Arduino + - education + - course + - Uno + - safety + - PWM + - motor control + - embedded systems + - serial + - state machine + - curriculum preferred-citation: type: software title: "Arduino Programs Guide: safety-first compile-checked Arduino Uno course" authors: - - family-names: devkyato + - name: "@dev.mako (devkyato)" affiliation: "MATA Company" - version: 1.0.1 + version: 1.0.2 + date-released: 2026-08-09 + repository-code: "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/devkyato/Arduino-Programs-Guide" + doi: 10.5281/zenodo.21853286 + license: MIT diff --git a/README.md b/README.md index 6b8a15d..41f9191 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ # Arduino Programs Guide [](https://github.com/devkyato/Arduino-Programs-Guide/actions/workflows/compile.yml) +[](https://doi.org/10.5281/zenodo.21853286) [](LICENSE) -A progressive, hands-on Arduino Uno course covering serial commands, LED patterns, -PWM motor control, state machines, and emergency-stop behavior. Each lesson -includes a compile-checked sketch, wiring contract, test procedure, and extension -ideas. +Arduino Programs Guide 1.0.2 is a progressive, safety-first Arduino Uno course covering +serial commands, LED patterns, PWM motor control, state machines, and emergency-stop +behaviour. Each lesson includes a compile-checked sketch, wiring contract, test procedure, +and extension ideas. > [!CAUTION] > Never connect a DC motor directly to an Arduino pin. Motor lessons require a @@ -14,6 +15,13 @@ ideas. > supply, and a shared ground. Read [Hardware safety](docs/hardware-safety.md) > before Exercises C–F. +## Learning outcomes + +- Map serial commands to digital outputs and reusable functions. +- Build non-blocking LED patterns with arrays, bit masks, and `millis()`. +- Drive motors safely with PWM, drivers, and fail-safe stops. +- Integrate analog sensing, emergency override, and telemetry in Exercise F. + ## Learning path | Lesson | Project | Main concepts | Hardware | @@ -25,55 +33,82 @@ ideas. | [E](docs/lessons/exercise-e.md) | Synchronized scanner | numeric parsing, `map()`, animation | 4 LEDs, driver, motor | | [F](docs/lessons/exercise-f.md) | Integrated vehicle | analog input, emergency override, telemetry | full circuit | -There is also a small [Bluetooth LED warm-up](extras/basic-bluetooth-led/) -for testing a serial module before starting the main exercises. +There is also a [Bluetooth LED warm-up](docs/lessons/bluetooth-warmup.md) for testing a +serial module before starting the main exercises. ## Start here -1. Read [Getting started](docs/getting-started.md). +1. Read [Getting started](docs/getting-started.md) and [Hardware safety](docs/hardware-safety.md). 2. Build Exercise A with the board disconnected from power. 3. Upload the sketch and test it in Serial Monitor before adding Bluetooth. 4. Complete the lesson's verification checklist. -5. Commit your observations and improvements in your own fork. +5. After Exercise B, optionally try the companion [ArduinoPatterns](https://github.com/devkyato/Custom-Arduino-Libraries) library. All sketches use `9600` baud and accept the same characters from USB Serial or a TTL serial Bluetooth module. On an Uno, the hardware serial pins are shared with -USB; disconnect the module from pins 0/1 while uploading. See -[Serial control](docs/serial-control.md). - -## Repository layout +USB; disconnect the module from pins 0/1 while uploading. -```text -exercises/ Six progressively more involved Arduino sketches -extras/ Small setup and diagnostic sketches -docs/lessons/ Objectives, wiring tables, tests, and challenges -docs/ Setup, safety, serial, and troubleshooting guides -.github/ Contribution templates and automated compile checks +```bash +arduino-cli compile --fqbn arduino:avr:uno exercises/exercise-a-arrow-controller ``` -## Supported environment +## Instructor guidance + +| Item | Guidance | +| --- | --- | +| Prerequisites | Arduino Uno or compatible board, breadboard, LEDs/resistors, and for C–F a motor driver, flyback protection, and separate motor supply | +| Suggested pacing | one lesson per session for A–B; one to two sessions for each motor lesson | +| Assessment | require completed wiring checklists, Serial Monitor verification, and a short reflection on safety or non-blocking behaviour | +| Safety gate | do not begin Exercises C–F until students can explain why motors need drivers and shared ground | -The examples target the Arduino Uno and the Arduino AVR Boards core. CI compiles -every sketch with the official Arduino toolchain. Other boards may use different -PWM pins, voltage levels, serial ports, or ADC ranges; porting notes are welcome +## Companion library progression + +Exercise B teaches non-blocking patterns by hand. After students understand the timing model, +they can optionally refactor LED banks and timed sequences with +[ArduinoPatterns](https://github.com/devkyato/Custom-Arduino-Libraries). The course itself remains +complete without the library. + +## Applications + +- Introductory Arduino Uno coursework and maker-space labs. +- Safety-first PWM and H-bridge motor lessons. +- Compile-checked embedded systems laboratories. +- Independent practice with serial, state machines, and digital outputs. + +## Compatibility and limitations + +The examples target the Arduino Uno and the Arduino AVR Boards core. CI compiles every sketch +with the official Arduino toolchain; that is not hardware validation. Other boards may use +different PWM pins, voltage levels, serial ports, or ADC ranges. Porting notes are welcome only when verified on hardware. -## Citation +## Documentation index -If you use this software in research or teaching, please cite the Zenodo archive / this repository: +- [Documentation index](docs/README.md) +- [Getting started](docs/getting-started.md) +- [Hardware safety](docs/hardware-safety.md) +- [Serial control](docs/serial-control.md) +- [Troubleshooting](docs/troubleshooting.md) +- [Lessons A–F](docs/lessons/) +- [Bluetooth warm-up](docs/lessons/bluetooth-warmup.md) +- [Changelog](CHANGELOG.md) + +## Citation ```text -devkyato. (2026). Arduino Programs Guide: safety-first compile-checked Arduino Uno course (Version 1.0.1). +@dev.mako (devkyato). (2026). Arduino Programs Guide: safety-first compile-checked Arduino Uno course (Version 1.0.2). Zenodo. https://doi.org/10.5281/zenodo.21853286 ``` See [CITATION.cff](CITATION.cff) for machine-readable metadata. -## Applications +## Connected projects -- Introductory Arduino Uno coursework. -- Safety-first PWM motor-control lessons. -- Compile-checked embedded systems laboratories. -- Independent practice with serial, state machines, and digital outputs. +| Project | Role | +| --- | --- | +| **[ArduinoPatterns](https://github.com/devkyato/Custom-Arduino-Libraries)** | Optional non-blocking LED and digital-output library | +| **[Relay](https://github.com/devkyato/Relay)** | Timing-risk source review for control programs | +| **[OpenNet](https://github.com/devkyato/OpenNet)** | Typed ONP/1 messaging for ESP32, Raspberry Pi, and backends | +| **[Datary](https://github.com/devkyato/Datary)** | Local-first laboratory for reproducible program evidence | ## Contributing diff --git a/VERSION b/VERSION index 7dea76e..6d7de6e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.1 +1.0.2 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..41a0656 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ +# Documentation index + +Arduino Programs Guide 1.0.2 documentation for instructors, students, and offline archive users. + +## Course setup + +1. [Getting started](getting-started.md) — clone, toolchain, first upload. +2. [Hardware safety](hardware-safety.md) — mandatory before motor lessons. +3. [Serial control](serial-control.md) — USB and Bluetooth serial notes. +4. [Troubleshooting](troubleshooting.md) — common wiring and upload failures. + +## Lessons + +| Lesson | Document | Sketch | +| --- | --- | --- | +| A | [exercise-a.md](lessons/exercise-a.md) | `exercises/exercise-a-arrow-controller` | +| B | [exercise-b.md](lessons/exercise-b.md) | `exercises/exercise-b-pattern-selector` | +| C | [exercise-c.md](lessons/exercise-c.md) | `exercises/exercise-c-smart-fan` | +| D | [exercise-d.md](lessons/exercise-d.md) | `exercises/exercise-d-wheel-simulation` | +| E | [exercise-e.md](lessons/exercise-e.md) | `exercises/exercise-e-synchronized-scanner` | +| F | [exercise-f.md](lessons/exercise-f.md) | `exercises/exercise-f-integrated-vehicle` | +| Warm-up | [bluetooth-warmup.md](lessons/bluetooth-warmup.md) | `extras/basic-bluetooth-led` | + +## Instructor notes + +- Keep Exercises A–B LED-only so students learn serial and timing before power electronics. +- Gate Exercises C–F on a short safety quiz or checklist review. +- After Exercise B, introduce [ArduinoPatterns](https://github.com/devkyato/Custom-Arduino-Libraries) as an optional abstraction, not a required dependency. +- Prefer verification checklists over grading wiring aesthetics; unsafe motor wiring fails the lesson. + +## Offline archive contents + +Release ZIP `Arduino-Programs-Guide-1.0.2.zip` includes exercises, extras, docs, citation metadata, changelog, and governance files so the course can be taught without a live GitHub session. diff --git a/docs/lessons/bluetooth-warmup.md b/docs/lessons/bluetooth-warmup.md new file mode 100644 index 0000000..7d498b5 --- /dev/null +++ b/docs/lessons/bluetooth-warmup.md @@ -0,0 +1,37 @@ +# Bluetooth LED warm-up + +Use this short setup lesson before Exercise A when students will later control sketches over a TTL Bluetooth serial module. + +## Goals + +- Confirm the Bluetooth module pairs and exchanges characters at 9600 baud. +- Prove that the same serial commands work over USB Serial and Bluetooth. +- Avoid confusing upload failures caused by leaving the module on pins 0/1. + +## Sketch + +Use [`extras/basic-bluetooth-led`](../../extras/basic-bluetooth-led/). + +## Wiring checklist + +1. Power the Arduino from USB while configuring and testing. +2. Wire the Bluetooth module `TX` to Arduino `RX` (pin 0) and module `RX` to Arduino `TX` (pin 1) only after upload succeeds. +3. Share ground between the module and Arduino. +4. Confirm the module voltage matches the board and module documentation. +5. Disconnect the module from pins 0/1 before every new upload. + +## Test procedure + +1. Upload the warm-up sketch with the Bluetooth module disconnected from pins 0/1. +2. Open Serial Monitor at 9600 baud and verify LED commands over USB. +3. Power down, connect the Bluetooth module, pair from the host device, and reconnect serial. +4. Send the same characters and confirm identical LED behaviour. +5. Disconnect the module before returning to Exercise A uploads. + +## Safety and limitations + +This warm-up is serial diagnostics only. It does not authorize motor wiring. Keep motor lessons gated behind [Hardware safety](../hardware-safety.md). + +## Next step + +Continue with [Exercise A](exercise-a.md). diff --git a/docs/lessons/exercise-b.md b/docs/lessons/exercise-b.md index 74ac6c7..a626252 100644 --- a/docs/lessons/exercise-b.md +++ b/docs/lessons/exercise-b.md @@ -30,3 +30,12 @@ extended validation; unsigned elapsed-time arithmetic keeps it safe. Add a pattern by defining a mask array and selecting it in `selectPattern()`. Avoid adding new `digitalWrite()` sequences or blocking delays. + +## Optional progression: ArduinoPatterns + +After this lesson works without blocking delays, students may optionally try the +companion library [ArduinoPatterns](https://github.com/devkyato/Custom-Arduino-Libraries). +Map the same pin bank and timed masks onto `LedBank` and `LedAnimator`, then compare +the hand-written Exercise B sketch with the library examples such as +`ScanningLight` and `AlternatingPatterns`. The course remains complete without the +library; the goal is to recognize the abstraction, not to replace the learning exercise. diff --git a/tools/build_release.py b/tools/build_release.py index b6c7be6..9b21923 100644 --- a/tools/build_release.py +++ b/tools/build_release.py @@ -13,6 +13,7 @@ "docs", "README.md", "CHANGELOG.md", + "CITATION.cff", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md", @@ -45,9 +46,18 @@ def main() -> None: archive.writestr(info, path.read_bytes()) with zipfile.ZipFile(output) as archive: - sketches = [name for name in archive.namelist() if name.endswith(".ino")] + names = set(archive.namelist()) + sketches = [name for name in names if name.endswith(".ino")] if len(sketches) != 7: raise RuntimeError(f"expected 7 sketches, found {len(sketches)}") + required = { + "Arduino-Programs-Guide/CITATION.cff", + "Arduino-Programs-Guide/docs/README.md", + "Arduino-Programs-Guide/VERSION", + } + missing = required.difference(names) + if missing: + raise RuntimeError(f"release archive is missing: {sorted(missing)}") print(output)