Skip to content

Commit 2ec7ef7

Browse files
peterhinchpeterhinch
committed
Improvements to tutorial.
1 parent ae06634 commit 2ec7ef7

File tree

1 file changed

+64
-58
lines changed

1 file changed

+64
-58
lines changed

‎TUTORIAL.md

Lines changed: 64 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,70 @@
11
# Application of uasyncio to hardware interfaces
22

3+
# Contents
4+
5+
0. [Introduction](./TUTORIAL.md#0-introduction)
6+
0.1 [Installing uasyncio on bare metal](./TUTORIAL.md#01-installing-uasyncio-on-bare-metal)
7+
1. [Cooperative scheduling](./TUTORIAL.md#1-cooperative-scheduling)
8+
1.1 [Modules](./TUTORIAL.md#11-modules)
9+
2. [uasyncio](./TUTORIAL.md#2-uasyncio)
10+
2.1 [Program structure: the event loop](./TUTORIAL.md#21-program-structure-the-event-loop)
11+
2.2 [Coroutines (coros)](./TUTORIAL.md#22-coroutines-coros)
12+
2.2.1 [Queueing a coro for scheduling](./TUTORIAL.md#221-queueing-a-coro-for-scheduling)
13+
2.2.2 [Running a callback function](./TUTORIAL.md#222-running-a-callback-function)
14+
2.2.3 [Notes](./TUTORIAL.md#223-notes) Coros as bound methods. Returning values.
15+
2.3 [Delays](./TUTORIAL.md#23-delays)
16+
3. [Synchronisation](./TUTORIAL.md#3-synchronisation)
17+
3.1 [Lock](./TUTORIAL.md#31-lock)
18+
3.1.1 [Locks and timeouts](./TUTORIAL.md#311-locks-and-timeouts)
19+
3.2 [Event](./TUTORIAL.md#32-event)
20+
3.2.1 [The event's value](./TUTORIAL.md#321-the-events-value)
21+
3.3 [Barrier](./TUTORIAL.md#33-barrier)
22+
3.4 [Semaphore](./TUTORIAL.md#34-semaphore)
23+
3.4.1 [BoundedSemaphore](./TUTORIAL.md#341-boundedsemaphore)
24+
3.5 [Queue](./TUTORIAL.md#35-queue)
25+
3.6 [Task cancellation](./TUTORIAL.md#36-task-cancellation)
26+
3.7 [Other synchronisation primitives](./TUTORIAL.md#37-other-synchronisation-primitives)
27+
4. [Designing classes for asyncio](./TUTORIAL.md#4-designing-classes-for-asyncio)
28+
4.1 [Awaitable classes](./TUTORIAL.md#41-awaitable-classes)
29+
4.1.1 [Use in context managers](./TUTORIAL.md#411-use-in-context-managers)
30+
4.1.2 [Awaiting a coro](./TUTORIAL.md#412-awaiting-a-coro)
31+
4.2 [Asynchronous iterators](./TUTORIAL.md#42-asynchronous-iterators)
32+
4.3 [Asynchronous context managers](./TUTORIAL.md#43-asynchronous-context-managers)
33+
4.4 [Coroutines with timeouts](./TUTORIAL.md#44-coroutines-with-timeouts)
34+
4.5 [Exceptions](./TUTORIAL.md#45-exceptions)
35+
5. [Interfacing hardware](./TUTORIAL.md#5-interfacing-hardware)
36+
5.1 [Timing issues](./TUTORIAL.md#51-timing-issues)
37+
5.2 [Polling hardware with a coroutine](./TUTORIAL.md#52-polling-hardware-with-a-coroutine)
38+
5.3 [Using the stream mechnanism](./TUTORIAL.md#53-using-the-stream-mechanism)
39+
5.3.1 [A UART driver example](./TUTORIAL.md#531-a-uart-driver-example)
40+
5.4 [Writing streaming device drivers](./TUTORIAL.md#54-writing-streaming-device-drivers)
41+
5.5 [A complete example: aremote.py](./TUTORIAL.md#55-a-complete-example-aremotepy)
42+
A driver for an IR remote control receiver.
43+
5.6 [Driver for HTU21D](./TUTORIAL.md#56-htu21d-environment-sensor) A
44+
temperature and humidity sensor.
45+
6. [Hints and tips](./TUTORIAL.md#6-hints-and-tips)
46+
6.1 [Program hangs](./TUTORIAL.md#61-program-hangs)
47+
6.2 [uasyncio retains state](./TUTORIAL.md#62-uasyncio-retains-state)
48+
6.3 [Garbage Collection](./TUTORIAL.md#63-garbage-collection)
49+
6.4 [Testing](./TUTORIAL.md#64-testing)
50+
6.5 [A common error](./TUTORIAL.md#65-a-common-error) This can be hard to find.
51+
6.6 [Socket programming](./TUTORIAL.md#66-socket-programming)
52+
7. [Notes for beginners](./TUTORIAL.md#7-notes-for-beginners)
53+
7.1 [Problem 1: event loops](./TUTORIAL.md#71-problem-1:-event-loops)
54+
7.2 [Problem 2: blocking methods](./TUTORIAL.md#7-problem-2:-blocking-methods)
55+
7.3 [The uasyncio approach](./TUTORIAL.md#73-the-uasyncio-approach)
56+
7.4 [Scheduling in uasyncio](./TUTORIAL.md#74-scheduling-in-uasyncio)
57+
7.5 [Why cooperative rather than pre-emptive?](./TUTORIAL.md#75-why-cooperative-rather-than-pre-emptive)
58+
7.6 [Communication](./TUTORIAL.md#76-communication)
59+
7.7 [Polling](./TUTORIAL.md#77-polling)
60+
61+
###### [Main README](./README.md)
62+
63+
# 0. Introduction
64+
365
Most of this document assumes some familiarity with asynchronous programming.
466
For those new to it an introduction may be found
5-
[here](./TUTORIAL.md#7-notes-for-beginners).
67+
[in section 7](./TUTORIAL.md#7-notes-for-beginners).
668

769
The MicroPython `uasyncio` library comprises a subset of Python's `asyncio`
870
library. It is designed for use on microcontrollers. As such it has a small RAM
@@ -20,7 +82,7 @@ Except where detailed below, `asyncio` features of versions >3.4 are
2082
unsupported. As stated above it is a subset; this document identifies supported
2183
features.
2284

23-
# Installing uasyncio on bare metal
85+
## 0.1 Installing uasyncio on bare metal
2486

2587
MicroPython libraries are located on [PyPi](https://pypi.python.org/pypi).
2688
Libraries to be installed are:
@@ -61,62 +123,6 @@ and rebuilding.
61123

62124
###### [Main README](./README.md)
63125

64-
# Contents
65-
66-
1. [Cooperative scheduling](./TUTORIAL.md#1-cooperative-scheduling)
67-
1.1 [Modules](./TUTORIAL.md#11-modules)
68-
2. [uasyncio](./TUTORIAL.md#2-uasyncio)
69-
2.1 [Program structure: the event loop](./TUTORIAL.md#21-program-structure-the-event-loop)
70-
2.2 [Coroutines (coros)](./TUTORIAL.md#22-coroutines-coros)
71-
2.2.1 [Queueing a coro for scheduling](./TUTORIAL.md#221-queueing-a-coro-for-scheduling)
72-
2.2.2 [Running a callback function](./TUTORIAL.md#222-running-a-callback-function)
73-
2.2.3 [Notes](./TUTORIAL.md#223-notes) Coros as bound methods. Returning values.
74-
2.3 [Delays](./TUTORIAL.md#23-delays)
75-
3. [Synchronisation](./TUTORIAL.md#3-synchronisation)
76-
3.1 [Lock](./TUTORIAL.md#31-lock)
77-
3.1.1 [Locks and timeouts](./TUTORIAL.md#311-locks-and-timeouts)
78-
3.2 [Event](./TUTORIAL.md#32-event)
79-
3.2.1 [The event's value](./TUTORIAL.md#321-the-events-value)
80-
3.3 [Barrier](./TUTORIAL.md#33-barrier)
81-
3.4 [Semaphore](./TUTORIAL.md#34-semaphore)
82-
3.4.1 [BoundedSemaphore](./TUTORIAL.md#341-boundedsemaphore)
83-
3.5 [Queue](./TUTORIAL.md#35-queue)
84-
3.6 [Task cancellation](./TUTORIAL.md#36-task-cancellation)
85-
3.7 [Other synchronisation primitives](./TUTORIAL.md#37-other-synchronisation-primitives)
86-
4. [Designing classes for asyncio](./TUTORIAL.md#4-designing-classes-for-asyncio)
87-
4.1 [Awaitable classes](./TUTORIAL.md#41-awaitable-classes)
88-
4.1.1 [Use in context managers](./TUTORIAL.md#411-use-in-context-managers)
89-
4.1.2 [Awaiting a coro](./TUTORIAL.md#412-awaiting-a-coro)
90-
4.2 [Asynchronous iterators](./TUTORIAL.md#42-asynchronous-iterators)
91-
4.3 [Asynchronous context managers](./TUTORIAL.md#43-asynchronous-context-managers)
92-
4.4 [Coroutines with timeouts](./TUTORIAL.md#44-coroutines-with-timeouts)
93-
4.5 [Exceptions](./TUTORIAL.md#45-exceptions)
94-
5. [Interfacing hardware](./TUTORIAL.md#5-interfacing-hardware)
95-
5.1 [Timing issues](./TUTORIAL.md#51-timing-issues)
96-
5.2 [Polling hardware with a coroutine](./TUTORIAL.md#52-polling-hardware-with-a-coroutine)
97-
5.3 [Using the stream mechnanism](./TUTORIAL.md#53-using-the-stream-mechanism)
98-
5.3.1 [A UART driver example](./TUTORIAL.md#531-a-uart-driver-example)
99-
5.4 [Writing streaming device drivers](./TUTORIAL.md#54-writing-streaming-device-drivers)
100-
5.5 [A complete example: aremote.py](./TUTORIAL.md#55-a-complete-example-aremotepy)
101-
A driver for an IR remote control receiver.
102-
5.6 [Driver for HTU21D](./TUTORIAL.md#56-htu21d-environment-sensor) A
103-
temperature and humidity sensor.
104-
6. [Hints and tips](./TUTORIAL.md#6-hints-and-tips)
105-
6.1 [Program hangs](./TUTORIAL.md#61-program-hangs)
106-
6.2 [uasyncio retains state](./TUTORIAL.md#62-uasyncio-retains-state)
107-
6.3 [Garbage Collection](./TUTORIAL.md#63-garbage-collection)
108-
6.4 [Testing](./TUTORIAL.md#64-testing)
109-
6.5 [A common error](./TUTORIAL.md#65-a-common-error) This can be hard to find.
110-
6.6 [Socket programming](./TUTORIAL.md#66-socket-programming)
111-
7. [Notes for beginners](./TUTORIAL.md#7-notes-for-beginners)
112-
7.1 [Problem 1: event loops](./TUTORIAL.md#71-problem-1:-event-loops)
113-
7.2 [Problem 2: blocking methods](./TUTORIAL.md#7-problem-2:-blocking-methods)
114-
7.3 [The uasyncio approach](./TUTORIAL.md#73-the-uasyncio-approach)
115-
7.4 [Scheduling in uasyncio](./TUTORIAL.md#74-scheduling-in-uasyncio)
116-
7.5 [Why cooperative rather than pre-emptive?](./TUTORIAL.md#75-why-cooperative-rather-than-pre-emptive)
117-
7.6 [Communication](./TUTORIAL.md#76-communication)
118-
7.7 [Polling](./TUTORIAL.md#77-polling)
119-
120126
# 1. Cooperative scheduling
121127

122128
The technique of cooperative multi-tasking is widely used in embedded systems.

0 commit comments

Comments
 (0)