|
19 | 19 | 7. [Use in synchronous code](./SCHEDULE.md#7-use-in-synchronous-code) If you really must.
|
20 | 20 | 7.1 [Initialisation](./SCHEDULE.md#71-initialisation)__
|
21 | 21 | 8. [The simulate script](./SCHEDULE.md#8-the-simulate-script) Rapidly test sequences.
|
| 22 | +9. [Design note](./SCHEDULE.md#9-design-note) Notes on use under an OS. |
22 | 23 |
|
23 | 24 | Release note:
|
24 | 25 | 11th Dec 2023 Document astronomy module, allowing scheduling based on Sun and
|
25 |
| -Moon rise and set times. |
26 |
| -23rd Nov 2023 Add asynchronous iterator interface. |
| 26 | +Moon rise and set times. |
| 27 | +23rd Nov 2023 Add asynchronous iterator interface. |
27 | 28 | 3rd April 2023 Fix issue #100. Where an iterable is passed to `secs`, triggers
|
28 |
| -must now be at least 10s apart (formerly 2s). |
| 29 | +must now be at least 10s apart (formerly 2s). |
29 | 30 |
|
30 | 31 | ##### [Tutorial](./TUTORIAL.md#contents)
|
31 | 32 | ##### [Main V3 README](../README.md)
|
@@ -285,6 +286,9 @@ and duplicates when they go back. Scheduling those times will fail. A solution
|
285 | 286 | is to avoid scheduling the times in your region where this occurs (01.00.00 to
|
286 | 287 | 02.00.00 in March and October here).
|
287 | 288 |
|
| 289 | +It is believed that in other respects DST is handled correctly by the OS: see |
| 290 | +[Design note](./SCHEDULE.md#9-design-note). |
| 291 | + |
288 | 292 | ##### [Top](./SCHEDULE.md#0-contents)
|
289 | 293 |
|
290 | 294 | ## 4.5 Callback interface
|
@@ -546,3 +550,55 @@ the value of system time when the delay ends. In this instance the start of a
|
546 | 550 | sequence is delayed to ensure that the first trigger occurs at 01:00.
|
547 | 551 |
|
548 | 552 | ##### [Top](./SCHEDULE.md#0-contents)
|
| 553 | + |
| 554 | +# 9. Design note |
| 555 | + |
| 556 | +This module is primarily intended for use on a microcontroller, where the time |
| 557 | +source is a hardware RTC. This is usually set to local time and does not change |
| 558 | +for daylight saving time (DST). Changing the system time while running `asyncio` |
| 559 | +code is not recommended. |
| 560 | + |
| 561 | +A [question was raised](https://.com/peterhinch/micropython-async/pull/126) |
| 562 | +regarding the behaviour of the module when running under the Unix build - in |
| 563 | +particular whether the module's use of `time.localtime` is correct, because |
| 564 | +`.localtime` changes when DST is invoked. To test whether a problem exists, an |
| 565 | +attempt was made to write a script whose behaviour under Unix differed from that |
| 566 | +on a microcontroller. The latter has no concept of DST or timezone (TZ) so can |
| 567 | +be assumed to be free of such bugs. Unless such a reproducer can be found, it |
| 568 | +seems that usage under the Unix build should be correct. |
| 569 | + |
| 570 | +The following test script outputs the time in seconds between two fixed times |
| 571 | +separated by two months, the period being chosen to cross a DST boundary here in |
| 572 | +the UK. It passed under the following conditions: |
| 573 | + |
| 574 | +* On a Pyboard. |
| 575 | +* On an ESP32. |
| 576 | +* On Unix MicroPython. |
| 577 | +* On CPython. |
| 578 | +* On the Unix build with my laptop's location set to California. Reported time |
| 579 | +changed by -7hrs. |
| 580 | +* On CPython in California. |
| 581 | + |
| 582 | +The conclusion is that the OS ensures that DST related errors do not occur. |
| 583 | + |
| 584 | +```py |
| 585 | +from time import mktime, gmtime, localtime |
| 586 | +from sys import implementation |
| 587 | +cpython = implementation.name == 'cpython' |
| 588 | +if cpython: |
| 589 | +from time import struct_time |
| 590 | + |
| 591 | +start = [2024, 9, 5, 11, 49, 2, 3, 249, 1] |
| 592 | +sept = round(mktime(struct_time(start))) if cpython else mktime(start) |
| 593 | + |
| 594 | +end = start[:] |
| 595 | +end[1] += 2 # Same time + 2months Crosses DST boundary in the UK |
| 596 | + |
| 597 | +november = round(mktime(struct_time(end))) if cpython else mktime(end) |
| 598 | +print(november - sept) |
| 599 | + |
| 600 | +if november - sept == 5270400: |
| 601 | +print('PASS') |
| 602 | +else: |
| 603 | +print('FAIL') |
| 604 | +``` |
0 commit comments