Skip to content

Commit 4bc1cb5

Browse files
committed
v3/docs/SCHEDULE.md fix links, add section 7.
1 parent 7784a9f commit 4bc1cb5

File tree

1 file changed

+37
-9
lines changed

1 file changed

+37
-9
lines changed

v3/docs/SCHEDULE.md

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,18 @@
22
2. [Overview](./SCHEDULE.md#2-overview)
33
3. [Installation](./SCHEDULE.md#3-installation)
44
4. [The cron object](./SCHEDULE.md#4-the-cron-object)
5-
4.1 [Time specifiers](./SCHEDULE.md#41-time-specifiers)..
5+
4.1 [Time specifiers](./SCHEDULE.md#41-time-specifiers)
66
4.2 [The time to an event](./SCHEDULE.md#42-the-time-to-an-event)
77
4.3 [How it works](./SCHEDULE.md#43-how-it-works)
88
4.4 [Calendar behaviour](./SCHEDULE.md#44-calendar-behaviour)
99
4.5 [Limitations](./SCHEDULE.md#45-limitations)
1010
4.6 [The Unix build](./SCHEDULE.md#46-the-unix-build)
11-
5. [The schedule function](./SCHEDULE.md#5-the schedule-function)
12-
6. [Use in synchronous code](./SCHEDULE.md#6-use-in-synchronous-code)
11+
5. [The schedule function](./SCHEDULE.md#5-the-schedule-function) The primary interface for uasyncio
12+
6. [Use in synchronous code](./SCHEDULE.md#6-use-in-synchronous-code) If you really must
13+
7. [Hardware timing limitations](./SCHEDULE,md#7-hardware-timing-limitations)
1314

14-
###### [Tutorial](./TUTORIAL.md#contents)
15-
###### [Main V3 README](../README.md)
15+
##### [Tutorial](./TUTORIAL.md#contents)
16+
##### [Main V3 README](../README.md)
1617

1718
# 1. Scheduling tasks
1819

@@ -46,6 +47,8 @@ function takes a `cron` instance and a callback and causes that callback to run
4647
at the times specified by the `cron`. A coroutine may be substituted for the
4748
callback - at the specified times it will be promoted to a `Task` and run.
4849

50+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)
51+
4952
# 3. Installation
5053

5154
Copy the `sched` directory and contents to the target's filesystem. It requires
@@ -74,6 +77,8 @@ numbers are shown as inclusive ranges.
7477
5. `month=None` Months (1..12).
7578
6. `wday=None` Weekday (0..6 Mon..Sun).
7679

80+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)
81+
7782
## 4.1 Time specifiers
7883

7984
The args may be of the following types.
@@ -109,6 +114,8 @@ now = int(time.time()) # Unix build returns a float here
109114
tnext = min(cron1(now), cron2(now), cron3(now)) # Seconds until 1st event
110115
```
111116

117+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)
118+
112119
## 4.3 How it works
113120

114121
When a cron instance is run it seeks a future time and date relative to the
@@ -159,6 +166,8 @@ my_cron(month=(2, 7, 10), hrs=1, mins=59) # moves forward 1 day
159166
t_wait = my_cron(time.time()) # but month may be disallowed
160167
```
161168

169+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)
170+
162171
## 4.5 Limitations
163172

164173
The `cron` code has a resolution of 1 second. It is intended for scheduling
@@ -175,10 +184,6 @@ On hardware platforms the MicroPython `time` module does not handle daylight
175184
saving time. Scheduled times are relative to system time. This does not apply
176185
to the Unix build.
177186

178-
It has been tested on ESP8266 but this platform has poor time stability so is
179-
not well suited to long term timing applications. On my reference board timing
180-
drifted by 1.4mins/hr, an error of 2.3%.
181-
182187
## 4.6 The Unix build
183188

184189
Asynchronous use requires `uasyncio` V3, so ensure this is installed on a Linux
@@ -200,6 +205,8 @@ adapt `cron.py` to account for this: its design focus is small lightweight code
200205
to run on bare metal targets. I could adapt `crontest.py` but it would surely
201206
fail in other countries.
202207

208+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)
209+
203210
# 5. The schedule function
204211

205212
This enables a callback or coroutine to be run at intervals specified by a
@@ -256,6 +263,8 @@ finally:
256263
_ = asyncio.new_event_loop()
257264
```
258265

266+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)
267+
259268
# 6. Use in synchronous code
260269

261270
It is possible to use the `cron` closure in synchronous code. This involves
@@ -315,3 +324,22 @@ In my opinion the asynchronous version is cleaner and easier to understand. It
315324
is also more versatile because the advanced features of `uasyncio` are
316325
available to the application. The above code is incompatible with `uasyncio`
317326
because of the blocking calls to `time.sleep`.
327+
328+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)
329+
330+
# 7. Hardware timing limitations
331+
332+
The code has been tested on Pyboard 1.x, Pyboard D, ESP32 and ESP8266. All
333+
except ESP8266 have good timing performance. Pyboards can be calibrated to
334+
timepiece precision using a cheap DS3231 and
335+
[this utility](https://github.com/peterhinch/micropython-samples/tree/master/DS3231).
336+
337+
The ESP8266 has poor time stability so is not well suited to long term timing
338+
applications. On my reference board timing drifted by 1.4mins/hr, an error of
339+
2.3%.
340+
341+
Boards with internet connectivity can periodically synchronise to an NTP server
342+
but this carries a risk of sudden jumps in the system time which may disrupt
343+
`uasyncio` and the scheduler.
344+
345+
##### [Top](./SCHEDULE.md#1-scheduling-tasks)

0 commit comments

Comments
 (0)