8000
Skip to content

Precise time-synchronization.#208

Merged
BrianPugh merged 15 commits intomainfrom
time-sync
Dec 6, 2025
Merged

Precise time-synchronization.#208
BrianPugh merged 15 commits intomainfrom
time-sync

Conversation

@BrianPugh
Copy link
Copy Markdown
Owner
@BrianPugh BrianPugh commented Nov 19, 2025

Summary:

  • Adds a new CLI command belay latency that tests/reports the connection latency.
    • Update README with example real-world latency values.
  • Adds a sNTP-like mechanism for figuring out the precise offset between the device's clock and the host's clock (compensating for communication latency).
    • I imagine this could result in sensor-readings with sub-millisecond accuracy, but it would probably be a pain to confirm this physically.
    • For those who do not need this level of precision (e.g. <5mS error), it's much simpler just to use host time and ignore device latency.
    • See Example 12.
  • This PR does NOT modify the device's time.

@roaldarbol play around with this PR and let me know what you think!

BrianPugh and others added 12 commits November 16, 2025 21:02
@BrianPugh
Add initial time-sync code.
8f01411
@BrianPugh
piggybacking time-sync code.
cc524c4
@BrianPugh
move time import into startup
acff055
@BrianPugh
remove unnecessary time-syncing
c5039b6
@BrianPugh
Fix tests.
dba8df8
@BrianPugh
Add latency command.
b8a3d1e
@BrianPugh
Add timing flag to latency command.
4331a0a
@BrianPugh
Update README with latencies
080452a
@BrianPugh
Swap to using milliseconds, saving a device-side divide. Much faster.
6d09b09
@BrianPugh
Add time-sync example
d406679
@BrianPugh @claude
Fix stdout forwarding tests for time-sync response format
2f55f69 
The time-sync feature added a timestamp field to all _BELAYR responses,
changing the format from:
  _BELAYR|{value}
to:
  _BELAYR|{timestamp}|{value}

Updated test_stdout_forwarding.py to use regex pattern matching to
handle the variable timestamp value in the response.

πŸ€– Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@BrianPugh
Add small delay to mock_pyboard_time.
88635a5
@codecov
Copy link
Copy Markdown
codecov bot commented Nov 19, 2025 •
edited
Loading

Codecov Report

❌ Patch coverage is 98.85057% with 2 lines in your changes missing coverage. Please review.
βœ… Project coverage is 65.87%. Comparing base (f1c552e) to head (b7d2969).
⚠️ Report is 25 commits behind head on main.

Files with missing lines Patch % Lines
belay/device_support.py 96.07% 1 Missing and 1 partial ⚠️
Additional details and impacted files 
@@            Coverage Diff             @@
##             main     #208      +/-   ##
==========================================
+ Coverage   63.41%   65.87%   +2.45%     
==========================================
  Files          40       41       +1     
  Lines        2288     2444     +156     
  Branches      505      519      +14     
==========================================
+ Hits         1451     1610     +159     
+ Misses        743      736       -7     
- Partials       94       98       +4
Flag Coverage Ξ”
unittests 65.83% <98.85%> (+2.46%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

β˜” View full report in Codecov by Sentry.
πŸ“’ Have feedback on the report? Share it here.

πŸš€ New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@roaldarbol
Copy link
Copy Markdown
roaldarbol commented Nov 19, 2025

Damn Brian, that was quick!!!😍

I'm off sick today, and might be in the coming days too, but I'll give it a spin as soon as I can!

From looking at the PR I have a few questions, comments and wishes.

I really like that it outputs the mean, variance etc. for N connections (10000?). But for further analysis and visualisation, it would be cool if it was possible to have a --raw flag or something to export all the individual connection latencies which one could pipe into a .txt or .csv file.

Secondly, is this functionality available also from Python? So, e.g. just like we haveDevice.setup and Device.teardown is/could there be a Device.latency (or as the decorator to existing tasks? Then users could check how long a task takes and maybe get a breakdown of how much is connection latency and how much is running the code on the board.

I'm looking forward to trying it out!!!

@BrianPugh
Copy link
Copy Markdown
Owner Author
BrianPugh commented Nov 20, 2025

or further analysis and visualisation, it would be cool if it was possible to have a --raw flag or something to export all the individual connection latencies which one could pipe into a .txt or .csv file.

This is already implemented by passing in --output (or -o) to the command.

Secondly, is this functionality available also from Python?

It's currently not, but I can make it a function Device.latency that returns a list of latencies in seconds. It would be up to the caller to compute statistics that they care about.

@roaldarbol
Copy link
Copy Markdown
roaldarbol commented Nov 20, 2025 •
edited
Loading

Awesome.

I'm a little fuzzy on how exactly decorators work, but could there be a way that one could pass latency=True as an input to a task? So you wouldn't have to change the method, but simply by passing a latency argument, one would get latencies returned? And maybe instead of a new decorator, it could be part of the Device.task decorator, similar to autoinit for Device.setup? These are just ideas though...

And I would then always just expect them to simply run the function once like normal and give latency for that single run - it would then be up to the user to run it many times if they wanted statistics on it.

@roaldarbol
Copy link
Copy Markdown
roaldarbol commented Nov 24, 2025 •
edited
Loading

Just tried it out, and I'm really impressed with it! The only comments I have relate to the documentation.

I think it makes sense that auto_sync_time is on by default; if users don't worry about tight < 5 ms precision, then adding < 1 ms of extra delay (based on my tests) will not matter. And when high precision is needed then downsides of the extra < 1 ms added latency is generally outweighed by the upsides of gaining the knowledge of when the signals were sent and received.

So just because you want client side timing, then I don't think it warrants settings auto_sync_time=False - this is of course up to the user, but for the docs I think that's an added layer that isn't needed to be covered in the basic example.

Other than that I think it's super. I do think that if it was possible to add an extra decorator, or an argument to @device.task to return the time, then that would remove the extra layer of having to add separate timing code for each function. But for now, it's a small issue and I don't think it's a deal-breaker at all - I'd be happy to see this go through.

I didn't look through the exact implementation details everywhere, just so you know.

EDIT: I now also tried the Python example, and this is so so useful.

@BrianPugh
Copy link
Copy Markdown
Owner Author
BrianPugh commented Nov 24, 2025

thanks for the feedback! i'll address some of these issues and i'll try and merge this in this week!

@BrianPugh
8000 Copy link
Copy Markdown
Owner Author
BrianPugh commented Dec 6, 2025

I added a return_time parameter to the task decorator; gonna merge this in once CI is done running. I'll then people to pursue the other feature requests this evening.

@BrianPugh BrianPugh merged commit 01ea788 into main Dec 6, 2025
11 checks passed
@BrianPugh BrianPugh deleted the time-sync branch December 6, 2025 21:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@BrianPugh @roaldarbol
0