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", + "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, 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.3). Zenodo. https://doi.org/10.5281/zenodo.21853286
", + "version": "1.0.3", "keywords": ["Arduino", "education", "course", "Uno", "safety", "PWM", "motor control", "embedded", "serial", "state machine", "curriculum"], "license": "mit", "upload_type": "software", diff --git a/CHANGELOG.md b/CHANGELOG.md index 0751a4b..9b9f9fe 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CITATION.cff b/CITATION.cff index 352a906..195cac9 100644 --- a/CITATION.cff +++ b/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 diff --git a/README.md b/README.md index 41f9191..97f8f78 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [](https://doi.org/10.5281/zenodo.21853286) [](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. diff --git a/VERSION b/VERSION index 6d7de6e..21e8796 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.2 +1.0.3 diff --git a/docs/README.md b/docs/README.md index 41a0656..022d6ad 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/lessons/bluetooth-warmup.md b/docs/lessons/bluetooth-warmup.md index 7d498b5..a2f702c 100644 --- a/docs/lessons/bluetooth-warmup.md +++ b/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 diff --git a/docs/lessons/exercise-d.md b/docs/lessons/exercise-d.md index 24e7ffb..813729b 100644 --- a/docs/lessons/exercise-d.md +++ b/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. diff --git a/docs/lessons/exercise-f.md b/docs/lessons/exercise-f.md index 1ca78cf..4709ee6 100644 --- a/docs/lessons/exercise-f.md +++ b/docs/lessons/exercise-f.md @@ -22,7 +22,9 @@ 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. @@ -30,10 +32,12 @@ 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 diff --git a/exercises/exercise-f-full-system-integration/exercise-f-full-system-integration.ino b/exercises/exercise-f-full-system-integration/exercise-f-full-system-integration.ino index b21af51..d9d7699 100644 --- a/exercises/exercise-f-full-system-integration/exercise-f-full-system-integration.ino +++ b/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) {