devkyato · devkyato · Aug 8, 2026 · Aug 8, 2026
diff --git a/.zenodo.json b/.zenodo.json
@@ -1,21 +1,17 @@
 {
-  "creators": [{"name": "devkyato", "affiliation": "MATA Company"}],
+  "creators": [{"name": "@dev.mako (devkyato)", "affiliation": "MATA Company"}],
   "contributors": [{"name": "Cursor Agent", "type": "Other"}],
   "title": "Arduino Programs Guide: safety-first compile-checked Arduino Uno course",
-  "description": "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, test, and extension guidance. Usage: follow the lessons in order, build the documented circuits safely, compile and upload the sketches, and complete each verification checklist. Applications include classroom instruction, introductory embedded systems labs, supervised motor-control exercises, and independent Arduino study.",
-  "version": "1.0.1",
-  "keywords": ["Arduino", "education", "course", "Uno", "safety", "PWM", "motor control", "embedded", "serial"],
+  "description": "<h2>Overview</h2><p><strong>Arduino Programs Guide</strong> 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.</p><h2>Learning outcomes</h2><ul><li>Map serial commands to digital outputs and reusable functions.</li><li>Build non-blocking LED patterns with arrays, bit masks, and <code>millis()</code>.</li><li>Drive motors safely with PWM, transistor or H-bridge drivers, and fail-safe stops.</li><li>Integrate analog sensing, emergency override, and telemetry in a supervised capstone.</li></ul><h2>Getting started</h2><ul><li>Read the hardware-safety and getting-started guides.</li><li>Build Exercise A with power disconnected.</li><li>Upload and verify over Serial Monitor before adding Bluetooth.</li><li>Progress through Exercises A to F and complete each checklist.</li></ul><pre><code>arduino-cli compile --fqbn arduino:avr:uno exercises/exercise-a-arrow-controller</code></pre><h2>Quick start</h2><p>Exercise A accepts simple arrow commands at 9600 baud:</p><pre><code>// USB Serial or TTL Bluetooth serial at 9600 baud\n// U D L R C control four LEDs and a clear command</code></pre><h2>Applications</h2><ul><li>Introductory Arduino Uno coursework and maker-space labs.</li><li>Safety-first PWM and H-bridge motor lessons.</li><li>Compile-checked embedded systems instruction.</li><li>Independent practice with serial control and state machines.</li></ul><h2>Compatibility, safety, and limitations</h2><p>The 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.</p><h2>Documentation</h2><ul><li><a href=\"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/devkyato/Arduino-Programs-Guide/blob/main/docs/README.md\">Documentation index</a></li><li><a href=\"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/devkyato/Arduino-Programs-Guide/blob/main/docs/hardware-safety.md\">Hardware safety</a></li><li><a href=\"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/devkyato/Arduino-Programs-Guide/blob/main/docs/getting-started.md\">Getting started</a></li></ul><h2>Related software</h2><p><a href=\"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/devkyato/Custom-Arduino-Libraries\">ArduinoPatterns</a> is the companion library for optional non-blocking abstractions after Exercise B.</p><h2>Citation</h2><p>@dev.mako (devkyato). (2026). <strong>Arduino Programs Guide: safety-first compile-checked Arduino Uno course</strong> (Version 1.0.2). Zenodo. <a href=\"https://doi.org/10.5281/zenodo.21853286\">https://doi.org/10.5281/zenodo.21853286</a></p>",
+  "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
@@ -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
@@ -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
@@ -1,19 +1,27 @@
 # Arduino Programs Guide
 
 [![Sketch compilation](https://github.com/devkyato/Arduino-Programs-Guide/actions/workflows/compile.yml/badge.svg)](https://github.com/devkyato/Arduino-Programs-Guide/actions/workflows/compile.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21853286.svg)](https://doi.org/10.5281/zenodo.21853286)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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
 > suitable transistor or H-bridge driver, flyback protection, an external motor
 > 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
@@ -1 +1 @@
-1.0.1
+1.0.2
diff --git a/docs/README.md 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
@@ -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
@@ -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
@@ -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)