Helpers for NTP server sync

[t-sasatani]

This pull request adds a module that checks whether the system is synchronized with an optional NTP server. This doesn't perform the actual sync because it's OS-dependent and requires sudo. Any additions or suggestions are welcome. For instance, I have no idea how to test this.

• Users can define the NTP server address and the allowed time offset in runtime configurations for various CLI commands (currently integrated only with the stream command).
• The prompt_ntp_sync method measures the offset between the system clock and the specified NTP server. This method can be integrated with CLI commands.
• The NTP check can be bypassed through interactive prompts. This feature is needed because NTP servers may not be connected.

Example

Add something like below to the CLI command

    if config.runtime.ntp_server is not None:
        prompt_ntp_sync(
            config.runtime.ntp_server, max_offset_seconds=config.runtime.ntp_max_offset_seconds
        )

If the specified NTP server exists and the time is synced, it proceeds:

[25-11-26T10:37:05] INFO     [mio.ntp] Checking time sync with NTP server: mio-ntp.local                       ntp.py:78
[25-11-26T10:37:22] INFO     [mio.ntp] Resolved mio-ntp.local to 192.168.10.2                                  ntp.py:33
                    INFO     [mio.ntp] Time is synchronized with NTP server mio-ntp.local (offset: 0.000s)     ntp.py:89

And if not, a query shows up:

[25-11-26T10:38:40] INFO     [mio.ntp] Checking time sync with NTP server: mio-ntp.local                       ntp.py:78
[25-11-26T10:38:57] WARNING  [mio.ntp] Could not resolve hostname mio-ntp.local to IP address.                 ntp.py:36
[25-11-26T10:38:59] WARNING  [mio.ntp] Could not query NTP server mio-ntp.local.                               ntp.py:82
System time may not be synchronized. Proceed anyway? [y/N]:

---

📚 Documentation preview 📚: https://miniscope-io--142.org.readthedocs.build/en/142/

[coveralls]

Pull Request Test Coverage Report for Build 19747502406

Details

• 18 of 49 (36.73%) changed or added relevant lines in 3 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.8%) to 79.09%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
mio/cli/stream.py	4	5	80.0%
mio/ntp.py	12	42	28.57%

Totals
Change from base Build 19316009037:	-0.8%
Covered Lines:	1982
Relevant Lines:	2506

---

💛 - Coveralls

[t-sasatani]

Gets under 1 ms of offset on Mac and around 50 ms on Windows, right after manually syncing with the specified NTP server. Unsure why Windows has such a large offset.

[t-sasatani]

Seems like installing a real NTP client on Windows may solve this. Will try out later.

[sneakers-the-rat]

Why is pillow added here? I don't see it used

[t-sasatani]

Good catch, don't need it in this PR. Got mixed up while working on this PR (#144) at the same time, trying a bunch of camera-detection stuff that works on Windows too (which I gave up for now).

I think I ended up not needing pillow for this, too, so I will remove it.

[sneakers-the-rat]

Can we make this optional? As in the dependencies for NTP are optional. Seems a bit out of scope for general use.

[t-sasatani]

Can we make this optional? As in the dependencies for NTP are optional. Seems a bit out of scope for general use.

I don't mind at all if that's better, but is it worth adding a bit of if statements for that? It only checks the NTP server when there's a host/IP in the runtime config, so it should work the same without it. Also, it's not a very heavy package like matplotlib.

[t-sasatani]

And I guess syncing is pretty generic. But that said, either way works great for me.

[sneakers-the-rat]

I think it could be pretty simple: make the NTP dependency in an optional dependency group "ntp", and then in that module do like

try:
    import ntplib
except ImportError as e:
    raise ImportError("attempted to import ntp module, but NTP dependencies not installed. Install mio like `pip install mio[ntp]`") from e

and then where its used in streamdaq like

if {ntp is configured}:
    from mio.ntp import ...
    # rest of usage

[t-sasatani]

Yes, that's exactly the few lines I was thinking about (tho not if). It doesn't hurt either way, so I will do it if it looks better.

[t-sasatani]

The native Windows time system wasn't accurate, but using Meinberg NTP on Windows keeps this synced within a few milliseconds as well.

[t-sasatani]

Ok now made NTP dependencies optional

[sneakers-the-rat]

maybe a changelog entry? But otherwise lgtm

[sneakers-the-rat]

Also forgot you were syncing windows, maybe that explains why sync couldn't get down into the microsecond range? I remember with the raspis i pretty reliably could get them down there

[t-sasatani]

Thanks, I'll add a changelog before merging.

Also forgot you were syncing windows, maybe that explains why sync couldn't get down into the microsecond range? I remember with the raspis i pretty reliably could get them down there

Yes, the Mac/Raspi sync offset is under a millisecond right after a manual sync. So we can probably get tighter synchronization by increasing the polling frequency. Windows shows more randomness even after manual syncing with a proper NTP client, but it is always under 10 ms, so it's enough for syncing 20-30 FPS imaging systems.

[sneakers-the-rat]

Windows as an OS has bad timing properties generally, the OS loves to preempt stuff in a way that can't be prevented. maybe that goes in the docs