Repository navigation
Add harp.data.timecode for decoding the Harp Time Code - #22
Open
bruno-f-cruz wants to merge 7 commits into
Open
bruno-f-cruz wants to merge 7 commits into
bruno-f-cruz wants to merge 7 commits into
Conversation
Member
Author
|
@jsiegle Leaving this as a placeholder and describing what the current blockers are that must be resolved at the specification level before this can be merged. |
Decode a recorded Harp Time Code, as specified in harp-tech/protocol TimeCode.md, into anchors mapping a non-Harp system's sample or local time to the whole Harp second that starts there. Packets are four headerless 8N1 bytes, and anchors sit on each packet's first falling edge, which the specification fixes as the start of the encoded second.
bruno-f-cruz
force-pushed
the
feat-external-timestamp-alignment
branch
from
November 20, 2026 21:37
53f6a91 to
f4e3576
Compare
harp.data.synchronization for aligning non-Harp devices to the Harp clockharp.data.timecode for decoding the Harp Time Code
bruno-f-cruz
marked this pull request as ready for review
November 20, 2026 23:19
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add
harp.data.timecodefor decoding the Harp Time CodeCloses #14. Supersedes harp-tech/harp-python#38. Implements the analysis side of the Harp Time Code specification (harp-tech/protocol#241, #258).
Why
Devices outside the Harp bus timestamp their data on their own clock. A Harp device emitting the Harp Time Code sends the current whole Harp second as a slow serial signal (typically 1 kbps) on a digital output, so acquisition systems sampling at 5–30 kHz can record it on a spare digital or analog input and be aligned afterwards. Decoding that recording is currently done with ad-hoc scripts, one per lab. This PR adds it to
harp.data.What
Two entry points, one per shape of recording, each keyed on the axis that system already timestamps its own data on:
Sample(int64)Time(time, 0/1), as event-based systems reportLocalTime(seconds)TimeTimeholds the decoded whole Harp second, the same name the readers give the Harp time axis. Each row is an anchor: the first falling edge of a packet, which the spec fixes as the start of the second it encodes. Placing the device's own timestamps on the Harp axis is left to the caller; the docs fit a line through the anchors (np.polyfit), which absorbs the clock offset and drift and extends past the first and last anchors.The wire format decoded is the one in the spec: idle high, 8N1, LSB first, four back-to-back bytes holding the whole second as a little-endian
U32, with no header or checksum.Decoding decisions worth reviewing
threshold=None(the default) the cut is the midpoint of the 0.01st and 99.99th percentiles of a fixed-seed random subsample of up to 1 M samples, so rare glitches are ignored and a 1-hour recording costs ~20 ms. This handles analog channels, including integer ADC data such as Open Ephysint16, and a line that is low only ~0.5% of the time. Passthresholdto override.baud_rate, or they look thousands of times too long, which points to sample numbers passed as seconds. It only runs when nothing decoded, so a working recording pays nothing for it.ValueErrornaming both rates (five per bit is the practical recommendation, in line with the spec's "multiple samples per bit").Tests
39 tests in
tests/data/test_timecode.py, driven by a synthetic emitter that renders packets to either transitions or a sampled waveform:3806874-5and2600957-60), including its fifth packet, which frames cleanly but carries a corrupt value.Docs
harp.data.timecodeentries on the Data API page, an "Align a non-Harp device with the Harp Time Code" section in the harp-data README, and a new example page, Align to the Harp Time Code, in the nav.ruff format/ruff check,codespellandmkdocs build --strictare clean, and the full suite passes (487 tests).pyrightreports no issues in the new code.