eurorack-quantizer-firmware

Version 0.2.1 is a maintenance and calibration-verification patch for the 0.2.x firmware line, with no hardware changes and no intentional change to the musical Quantizer/Arpeggiator workflow. The boot-time calibration console now distinguishes RAW hardware measurements from CAL runtime-corrected values, exposes the active analogue correction constants and can verify calibrated DAC test points through the same production helpers used during normal operation. Verification has been expanded to 32 independently runnable native suites / 271 test cases, including deterministic property checks, sanitizer execution, machine-checked requirement traceability, frozen EEPROM compatibility fixtures and explicit EEPROM-wear tests. Release engineering now includes pinned build inputs, recorded build provenance, a dedicated real-hardware timing-qualification image/protocol and a 95% AVR application-flash engineering ceiling while retaining the 70% static-SRAM ceiling. The persistence-fixture checkout regression is fixed so the binary golden images required by CI are intentionally tracked despite the repository-wide build-artifact ignore rule. The existing 0.2.0 user manual remains compatible and is reused automatically by the release workflow; detailed RAW/CAL calibration procedure changes are documented in the firmware calibration guide.

Changelog

Fixed

• Made the boot-time analogue calibration console explicitly distinguish RAW hardware measurements from CAL runtime-corrected values. ADC reads now show both views, active ADC/DAC correction constants can be inspected in-console, and calibrated DAC min/mid/max verification reuses the exact production correction helpers while the existing raw diagnostic commands remain available. Regression coverage fixes the ADC offset-before-gain and DAC gain-before-offset order, non-unity gain rounding, clipping, and the shared runtime calibration wrappers. Calibration documentation also makes explicit that Quinn Freedman's original firmware has no equivalent per-channel software ADC/DAC gain/offset layer or calibration console; these are documented extensions of this implementation.
• Fixed CI checkout validation for frozen EEPROM golden fixtures by explicitly tracking test/fixtures/persistence/*.bin despite the repository-wide *.bin build-artifact ignore rule.

Added

• Expanded the default native verification set from 29 suites / 237 tests to 32 suites / 271 tests. The added hardening includes deterministic property/invariant checks, complete note/slot/parameter matrices, EEPROM compatibility and wear tests, calibration rounding/clipping cases, plus additional UI, persistence, clock and linked-channel regression coverage.
• Added AddressSanitizer/UndefinedBehaviorSanitizer host execution, machine-checked requirement traceability for all 20 acceptance criteria, and native coverage regression gates at 92% line / 70% branch coverage.
• Added frozen current/legacy EEPROM golden fixtures so supported persistent formats are loaded and migrated against known byte-for-byte images rather than only records produced by the current implementation.
• Added a documented EEPROM-wear audit and explicit write-distribution/same-value-suppression tests for the versioned asynchronous persistence paths.
• Added a dedicated non-release nanoatmega328new_timing image and oscilloscope qualification procedure. D1/TX measures scheduler-to-control-cycle completion so real ATmega328P deadline margin can be verified without adding instrumentation to normal release firmware.
• Added a versioned hardware-release qualification protocol covering functional behaviour, timing/clock capture, analogue tracking, channel isolation, trigger levels, persistence/update retention and both Nano bootloader variants.
• Added pinned CI/build inputs, release BUILD-INFO.txt provenance metadata and reproducible-build documentation; Dependabot now keeps the pinned GitHub Actions and Python CI dependencies reviewable.

Changed

• Raised the ATmega328P application-flash engineering ceiling from 92.5% to 95% of the 30,720-byte Nano application space, i.e. from 28,416 to 29,184 bytes. The hard application limit remains 30,720 bytes and the static-SRAM engineering ceiling remains 70% of 2,048 bytes.
• Tightened first-party native compilation with -Werror -Wconversion -Wsign-conversion -Wshadow -Wpedantic in addition to the existing warning set; warnings uncovered during hardening were corrected without intentional runtime behaviour changes.

Artifact integrity

Release assets include SHA256SUMS.txt and MD5SUMS.txt covering all generated release files, including user-manual ODT/PDF assets when present. Use the SHA-256 manifest for normal integrity verification; the MD5 manifest is provided as an additional compatibility checksum.

Diff

v0.2.0...v0.2.1

Version 0.2.0 turns the alternative firmware into a broader performance-oriented release while preserving the original hardware and core quantizer workflow. It introduces a complete second Arpeggiator layer with scale-aware patterns, internal and external clocking, swing, octave/length controls and optional step triggers. SHIFT double-click provides symmetrical enter/exit, while persistence now restores both live state and full configurations including Arpeggiator state, selected channel and active UI layer. Clock capture, button-ladder validation, initial hysteresis and several UI edge cases were tightened, and LED calibration/startup behaviour gained clearer feedback. The repository now includes stronger AVR resource-budget CI, 29 native test suites / 237 tests, changelog-driven release notes, checksums and the initial end-user manual for firmware 0.2.0. No PCB, component or wiring changes are required; 0.2.0 targets the existing Arduino Nano / ATmega328P hardware.

Changelog

Added

• Added end-user firmware installation/update documentation with rack-safety procedures plus a dedicated Windows 11 AVRDUDESS walkthrough using independently created numbered screenshot artwork, explicit old/new Nano bootloader settings, EEPROM-preserving normal-update configuration, troubleshooting and bootloader-recovery references.

• Added reusable CC BY-NC 4.0 SVG concept diagrams for the Quantizer signal path and core operating modes, with a directory-specific artwork license and shared use across GitHub documentation and the LibreOffice end-user manual.

• Added a cross-platform development-environment guide for VSCodium/PlatformIO on Windows 11 x64, macOS and Linux, including the Windows Python/PATH and native GCC requirements, local test/coverage workflows, Nano deployment, AVR resource checks and hardware smoke testing.

• Added project community-health infrastructure for external contributions: contribution guidelines, a code of conduct, structured bug and feature issue forms, and a pull-request template.

• Expanded the native test net with fine-grained two-channel isolation checks: in Absolute mode Channel B is verified at quantized-pitch and final DAC-code level while Channel A sweeps the complete 10-bit ADC range; the complementary Relative-mode behaviour is verified explicitly.

• Added Sample-and-Hold and reverse-direction A/B independence regression coverage so activity on either CV input cannot silently leak into the other channel's digital signal path.

• Expanded Arpeggiator documentation to describe its intended fast, scale-aware 8-bit-computer-style arpeggio character.

• Added a complete second Arpeggiator UI layer with dedicated controls for enable, rate/clock ratio, pattern, scale-degree shape, length, octave range, step trigger, FREE/RESET/CLOCK sync and swing while retaining Link/A/B navigation.

• Expanded the Arpeggiator engine from the fixed 24 ms root/third/fifth behaviour to twelve internal rates, clock division/multiplication, eight patterns, eight scale-aware shapes, 1–12 step length and 1–4 octave range; the former 24 ms 1-3-5 behaviour remains the default.

• Added external Sample/Gate clock integration per channel, including reset-only operation, phase re-anchoring on real clock edges, generated subdivisions and independent physical clock inputs for A/B.

• Added optional 5 ms output triggers for Arpeggiator steps while retaining pitch-only operation as the default.

• Added complete Arpeggiator-layer, clock/sync and persistence regression coverage, including full-config Arpeggiator restoration, stable/deterministic Random stepping and exact swing-pair timing; the regular native suite now contains 29 independently runnable suites and 237 test cases.

• Added README_ARPEGGIATOR.md as the complete second-layer operation, parameter, sync, persistence and testing reference.

• Added an AVR resource-budget CI gate to preserve engineering headroom for flash and static SRAM.

• Applied the same AVR flash/SRAM resource-budget gate to tagged release builds so published Nano artifacts cannot bypass the engineering limits enforced by CI.

• Raised the ATmega328P application-flash engineering budget from 85% to 92.5% of the 30,720-byte Nano application space; the static-SRAM budget remains unchanged at 70% of 2 KB.

• Added dedicated per-channel Arpeggiator state and regression coverage for A-only, B-only and linked operation.

• Added live green/red/amber comparison feedback to LED brightness calibration so colour balance and the resulting amber mix can be judged while either emitter is adjusted.

• Added regression coverage for the calibration comparison view, calibration colour selection and the 1500 ms startup note-ring duration ceiling.

• Extended full-configuration and live-state persistence to include both complete per-channel Arpeggiator configurations and the selected channel; automatic live restore/autosave is enabled with versioned CRC-protected wear-levelled records.

• Added changelog-driven GitHub Release notes generation: each declared release provides a short prose summary, the detailed version excerpt and a compare link instead of relying on generic generated notes.

• Added SHA256SUMS.txt and MD5SUMS.txt generation to tagged releases and documented their purpose in the generated Release notes.

• Added live GitHub Actions status badges for CI and release workflows to the main README.

• Prepared docs/manual/ as the end-user manual workspace with a dedicated CC BY-NC 4.0 manual licence and an editing README documenting LibreOffice Writer plus the required Ubuntu Font Family and Ubuntu Font Licence 1.0.

• Added the initial end-user manual for firmware 0.2.0 as the first user-facing operating guide for this firmware generation.

• Added tagged-release manual packaging: the workflow selects the newest versioned ODT manual not newer than the firmware release, publishes that source unchanged, attempts a LibreOffice/Ubuntu-font PDF export, includes available manual assets in both checksum manifests, and continues with a warning when no compatible manual exists.

Fixed

• Added the active Quantizer/Arpeggiator UI layer to full-configuration persistence without increasing the 32-byte payload; user save records now write format v5 while v4 records remain readable: a spare bit in the selected-channel byte is used. Full-config loads now restore the layer side-effect free, including the valid Arpeggiator-layer/ARP-OFF state, and legacy configs with ARP enabled are migrated to the Arpeggiator layer instead of recreating a hidden running ARP in Quantizer UI.
• Removed the fresh-channel C bias from Hysteresis by tracking whether a previous output actually exists; the first exact 0.5-semitone tie now rounds upward as specified.
• Added a ±10-count plausibility window to the original resistor-ladder decoder. Nominal values remain unchanged, while implausible gap readings and high/open readings fail safe as no button.
• Replaced millisecond-assigned external-clock edges with ISR-captured microsecond timestamps and per-tick edge counts. CLOCK period measurement is no longer quantized to the 1 kHz control loop, multiple physical edges are not collapsed into one boolean event, and multiplied-step phase no longer accumulates control-loop observation error.
• Reworked the Arpeggiator as a true second control layer: a debounced SHIFT double-click now replaces the former 3-second hold, making layer changes immediate while preserving isolated SHIFT + note modifier behaviour. Entering enables the selected Arpeggiator; returning to the Quantizer layer disables Arpeggiator playback on both channels.
• Restored one consistent front-panel grammar across both UI layers: unmodified note buttons continue to edit and display the selected scale, while SHIFT + note selects Quantizer or Arpeggiator menu functions according to the active layer; scalar parameters then use the note buttons as value selectors.
• Fixed live restore of the active UI layer: reboot now returns to the same Quantizer/Arpeggiator front-panel layer that was active before power-off, so the first SHIFT double-click after an Arpeggiator-layer reboot correctly performs OFF/exit instead of re-entering the layer. Live-state v6 stores the layer explicitly while retaining in-place v5 migration compatibility.
• Removed the separate steady Arpeggiator dashboard so the normal scale/quantized-note display remains visible in both UI layers; temporary parameter and activation feedback is retained.
• Changed Arpeggiator enable/bypass feedback to two full-ring flashes: green when enabling, red when disabling, followed automatically by restoration of the normal scale/quantized-note display.
• Removed the independent one-shot layer-change LED path that produced a single amber flash on entry and a single green flash on exit; the SHIFT double-click layer transition uses the same exact two-green / two-red full-ring Arpeggiator feedback renderer as SHIFT+C.
• Made FREE internal timing the explicit factory/default Arpeggiator sync mode; RESET and CLOCK remain user-selectable additional modes.
• Isolated layer switching from ordinary modifier use: the SHIFT double-click has its own digital debounce, rejects long presses and single clicks, is cancelled immediately by physical note/SAVE/LOAD activity, and remains blocked outside the stable main page.
• Added end-to-end regression coverage for symmetric SHIFT double-click layer control: double-click entry -> automatic Arpeggiator enable -> actual FREE-running pitch stepping, followed by the same double-click gesture for exit -> Arpeggiator disable; single-click timeout, long-press rejection, switch-bounce rejection, layer-consistent SHIFT-menu, scale-display/editing and raw-ladder cancellation are covered as well.
• Added regression checks for exactly two green enable flashes, exactly two red disable flashes, intervening dark phases and automatic return to the scale display.
• Limited every twelve-note startup animation variant to at most 1500 ms; the separate four-status-LED self-test remains independent of that note-ring limit.
• Added the per-channel Arpeggiator regression suite to the GitHub Actions matrix so the channel-isolation tests run as an explicit CI job.
• Fixed the native coverage job by explicitly linking the GCC gcov runtime for --coverage instrumented test binaries.
• Standardised the root LICENSE file for GitHub licence detection and added a GitHub security policy.
• Prevented local compile_commands.json files from being tracked because compilation databases may contain machine-specific absolute paths.

Artifact integrity

Release assets include SHA256SUMS.txt and MD5SUMS.txt covering all generated release files, including user-manual ODT/PDF assets when present. Use the SHA-256 manifest for normal integrity verification; the MD5 manifest is provided as an additional compatibility checksum.

Diff

v0.1.1...v0.2.0

Full Changelog: https://github.com/napolitano/eurorack-quantizer-firmware/compare/v0.1.0...v0.1.1