Skip to content

Conversation

@chalkers
Copy link

@chalkers chalkers commented Aug 28, 2025

Summary

  • Add kaluma flash read using size-first strategy: .flash -s then .flash -r.
  • Handle CRLF normalization and strip ANSI/console noise during read.
  • Options:
    • --stdout: write program to stdout
    • --timestamp (-t): append -YYYYMMDDTHHMMSS or backup-.js in a directory
    • --quiet (-q): suppress progress output
  • Node 20/22 support via serialport@^12 and API updates.
  • Reliability: grow buffered serial capacity and add timed reads.
  • Docs: README/CHANGELOG updated, CLI help examples extended, AGENTS.md added.
  • Meta: license aligned to Apache-2.0; add contributor Andrew Chalkley.

Behavior/Compatibility

  • No breaking changes; kaluma flash unchanged.
  • kaluma flash read requires a destination path or --stdout.

Testing

  • Verified on Node 20: kaluma ports, kaluma flash read backup.js, timestamped save, stdout piping.
  • Size-first logic works with devices that print logs during transfer.

@chalkers chalkers marked this pull request as draft August 28, 2025 18:51
…ptions: --stdout, --timestamp, --quiet\n\nfeat(compat): support Node 20/22 via serialport@^12 and API updates\nfix(serial): grow buffered serial capacity and add timed reads\n\ndocs: update README (usage), CHANGELOG, and add AGENTS.md\nmeta: align license to Apache-2.0; add contributor Andrew Chalkley
@chalkers chalkers force-pushed the feat/flash-read-node20 branch from b1aedad to 1494a9c Compare August 28, 2025 19:42
@chalkers chalkers marked this pull request as ready for review August 28, 2025 19:45
@chalkers
Copy link
Author

chalkers commented Aug 28, 2025

Squashed fix into previous commit and force-pushed to feat/flash-read-node20.

  • Fix: implement BufferedSerial.readAwaitWithTimeout used by flash read
  • Head: 1494a9c
  • Sanity: CLI loads locally; Tested flash read and write on-device.

…ing bytes

- Cap read request to remaining bytes (remove +10 slack).
- Fixes intermittent mid-run timeouts when device returns exactly the last chunk.
- No changes to CRLF normalization, ANSI stripping, or progress reporting.
@chalkers
Copy link
Author

Summary - Small issue tweak found on another MCU

  • Fixes intermittent end-of-transfer timeouts in kaluma flash read .
  • Root cause: the read loop requested more bytes than remain (remaining + 10),
    causing a wait for bytes that never arrive when the device returns exactly the
    last chunk.
  • Fix: cap each read request to the remaining byte count; keep CRLF normalization and ANSI stripping unchanged.

Reproduction (before)

  • node bin/kaluma.js ports to find the port.
  • node bin/kaluma.js flash read -p /dev/tty.usbmodem101 ./backup-nes.js
  • Observed: progress stops near the end and errors with a timeout.

Validation (after)

  • node bin/kaluma.js flash read -p /dev/tty.usbmodem101 backup-nes.js -q
  • Result: completes reliably; example output size: 23259 bytes.
  • Also verified that backup-nes.js same size.

Notes

  • On macOS, SerialPort.list() may not include VID/PID, so the default @2e8a
    lookup can fail. Use an explicit port path from kaluma ports (e.g., /dev/
    tty.usbmodem101).
  • Flags: --stdout to stream program to terminal, -t to add a timestamped
    filename, -q to suppress progress dots.

Risk/Impact

  • Low. Only read-loop request size changed; file content and normalization
    behavior remain the same.

Should be good to go. I'll do other PR if there's anything big.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant