Release Arduino Programs Guide 1.0.3

.zenodo.json

@@ -2,8 +2,8 @@
   "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": "<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",
+  "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.3). Zenodo. <a href=\"https://doi.org/10.5281/zenodo.21853286\">https://doi.org/10.5281/zenodo.21853286</a></p>",
+  "version": "1.0.3",
   "keywords": ["Arduino", "education", "course", "Uno", "safety", "PWM", "motor control", "embedded", "serial", "state machine", "curriculum"],
   "license": "mit",
   "upload_type": "software",

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.0.3] - 2026-08-12
+
+### Changed
+
+- Soft-start Exercise F so the first motion command requires the speed pot near minimum.
+- Clarify Exercise D full-on motor wiring and enable-pin safety expectations.
+- Strengthen Bluetooth warm-up guidance for 3.3 V RX level shifting.
+
 ## [1.0.2] - 2026-08-09
 
 ### Changed
@@ -23,4 +33,5 @@
 
 [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.3]: https://github.com/devkyato/Arduino-Programs-Guide/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/devkyato/Arduino-Programs-Guide/compare/v1.0.1...v1.0.2

CITATION.cff

@@ -4,8 +4,8 @@ title: "Arduino Programs Guide: safety-first compile-checked Arduino Uno course"
 authors:
   - name: "@dev.mako (devkyato)"
     affiliation: "MATA Company"
-version: 1.0.2
-date-released: 2026-08-09
+version: 1.0.3
+date-released: 2026-08-12
 license: MIT
 repository-code: "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/devkyato/Arduino-Programs-Guide"
 url: "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/devkyato/Arduino-Programs-Guide"
@@ -37,8 +37,8 @@ preferred-citation:
   authors:
     - name: "@dev.mako (devkyato)"
       affiliation: "MATA Company"
-  version: 1.0.2
-  date-released: 2026-08-09
+  version: 1.0.3
+  date-released: 2026-08-12
   repository-code: "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/devkyato/Arduino-Programs-Guide"
   doi: 10.5281/zenodo.21853286
   license: MIT

README.md

@@ -4,7 +4,7 @@
 [![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)
 
-Arduino Programs Guide 1.0.2 is a progressive, safety-first Arduino Uno course covering
+Arduino Programs Guide 1.0.3 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.
@@ -96,7 +96,7 @@ only when verified on hardware.
 ## Citation
 
 ```text
-@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
+@dev.mako (devkyato). (2026). Arduino Programs Guide: safety-first compile-checked Arduino Uno course (Version 1.0.3). Zenodo. https://doi.org/10.5281/zenodo.21853286
 ```
 
 See [CITATION.cff](CITATION.cff) for machine-readable metadata.

VERSION

@@ -1 +1 @@
-1.0.2
+1.0.3

docs/README.md

@@ -1,6 +1,6 @@
 # Documentation index
 
-Arduino Programs Guide 1.0.2 documentation for instructors, students, and offline archive users.
+Arduino Programs Guide 1.0.3 documentation for instructors, students, and offline archive users.
 
 ## Course setup
 
@@ -30,4 +30,4 @@ Arduino Programs Guide 1.0.2 documentation for instructors, students, and offlin
 
 ## 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.
+Release ZIP `Arduino-Programs-Guide-1.0.3.zip` includes exercises, extras, docs, citation metadata, changelog, and governance files so the course can be taught without a live GitHub session.

docs/lessons/bluetooth-warmup.md

@@ -18,19 +18,20 @@ Use [`extras/basic-bluetooth-led`](../../extras/basic-bluetooth-led/).
 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.
+5. If the module RX pin is 3.3 V logic (common for HC-05/HC-06 class modules), level-shift Arduino TX before connecting. See [Serial control](../serial-control.md).
+6. 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.
+3. Power down, connect the Bluetooth module with correct voltage/level shifting, 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).
+This warm-up is serial diagnostics only. It does not authorize motor wiring. Keep motor lessons gated behind [Hardware safety](../hardware-safety.md). Do not drive a 3.3 V RX pin with unshifted 5 V UART.
 
 ## Next step
 

docs/lessons/exercise-d.md

@@ -23,8 +23,11 @@ using a different driver may require changing the four logic values.
 
 ## Verify
 
-With motor power disconnected, check each driver input and direction LED. With
-the vehicle lifted so wheels are clear, connect motor power at low voltage and
+With motor power disconnected, check each driver input and direction LED. This
+base sketch drives direction pins fully on or off (`digitalWrite`); it does not
+yet use PWM enable pins. On boards with ENA/ENB jumpers, remove those jumpers or
+keep enable pins at the lowest safe PWM before connecting motor power. With the
+vehicle lifted so wheels are clear, connect motor power at low voltage and
 verify one direction at a time. Confirm a stop command is accepted while the
 reverse LEDs are blinking.
 

docs/lessons/exercise-f.md

@@ -22,18 +22,22 @@ a rated dual H-bridge, external supply, protection, and common ground.
 ## Behavior
 
 `F`, `B`, `L`, and `R` request motion; any other command requests stop. A 50 ms
-stop interval occurs before a new direction is energized. Pressing the emergency
+stop interval occurs before a new direction is energized. The first motion
+command is refused until the speed potentiometer is near its minimum so a
+centered or high pot cannot launch motors at full PWM. Pressing the emergency
 button stops all motor PWM immediately, flashes the direction LEDs, and discards
 the old direction. Releasing the button does not resume motion—a new command is
 required.
 
 ## Verify
 
 1. Keep motor power disconnected and verify every indicator and driver input.
-2. Press emergency stop during every requested direction.
-3. Hold the button, send commands, then release it; the motors must remain stopped.
-4. Turn the potentiometer through its range and check reported PWM.
-5. Secure the vehicle before cautious powered testing.
+2. Leave the potentiometer away from minimum and send `F`; the sketch must refuse motion.
+3. Turn the potentiometer to minimum, then send a direction and raise speed gradually.
+4. Press emergency stop during every requested direction.
+5. Hold the button, send commands, then release it; the motors must remain stopped.
+6. Turn the potentiometer through its range and check reported PWM.
+7. Secure the vehicle before cautious powered testing.
 
 ## Challenge
 

exercises/exercise-f-full-system-integration/exercise-f-full-system-integration.ino

@@ -13,6 +13,7 @@ constexpr uint8_t kRightB = 9;
 constexpr uint8_t kEmergencyButton = 12;
 constexpr uint8_t kSpeedPot = A0;
 constexpr uint16_t kDirectionDeadTimeMs = 50;
+constexpr uint16_t kSoftStartMaxRaw = 40;
 
 enum class Direction : uint8_t { kStop, kForward, kBackward, kLeft, kRight };
 
@@ -24,6 +25,7 @@ uint32_t telemetryAt = 0;
 uint8_t speedPwm = 0;
 bool emergencyActive = false;
 bool emergencyLightsOn = false;
+bool softStartCleared = false;
 
 void stopMotors() {
   analogWrite(kLeftA, 0);
@@ -97,23 +99,33 @@ void updateMotors() {
 }
 
 void handleCommand(char command) {
+  Direction next = Direction::kStop;
   switch (command) {
     case 'F':
-      requestDirection(Direction::kForward);
+      next = Direction::kForward;
       break;
     case 'B':
-      requestDirection(Direction::kBackward);
+      next = Direction::kBackward;
       break;
     case 'L':
-      requestDirection(Direction::kLeft);
+      next = Direction::kLeft;
       break;
     case 'R':
-      requestDirection(Direction::kRight);
+      next = Direction::kRight;
       break;
     default:
-      requestDirection(Direction::kStop);
+      next = Direction::kStop;
       break;
   }
+
+  if (next != Direction::kStop && !softStartCleared) {
+    if (analogRead(kSpeedPot) > kSoftStartMaxRaw) {
+      Serial.println(F("Turn speed pot to minimum before first motion"));
+      return;
+    }
+    softStartCleared = true;
+  }
+  requestDirection(next);
 }
 
 const __FlashStringHelper* directionName(Direction direction) {