Skip to content

Commit d19c256

Browse files
dpgeorgedpgeorge
committed
docs: Imported tutorials from previous documentation system.
1 parent 6162bea commit d19c256

16 files changed

Lines changed: 1358 additions & 7 deletions

‎docs/general.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
General information about the pyboard
2+
=====================================
3+
4+
Local filesystem and SD card
5+
----------------------------
6+
7+
There is a small internal filesystem (a drive) on the pyboard, called ``/flash``,
8+
which is stored within the microcontroller's flash memory. If a micro SD card
9+
is inserted into the slot, it is available as ``/sd``.
10+
11+
When the pyboard boots up, it needs to choose a filesystem to boot from. If
12+
there is no SD card, then it uses the internal filesystem ``/flash`` as the boot
13+
filesystem, otherwise, it uses the SD card ``/sd``.
14+
15+
(Note that on older versions of the board, ``/flash`` is called ``0:/`` and ``/sd``
16+
is called ``1:/``).
17+
18+
The boot filesystem is used for 2 things: it is the filesystem from which
19+
the ``boot.py`` and ``main.py`` files are searched for, and it is the filesystem
20+
which is made available on your PC over the USB cable.
21+
22+
The filesystem will be available as a USB flash drive on your PC. You can
23+
save files to the drive, and edit ``boot.py`` and ``main.py``.
24+
25+
*Remember to eject (on Linux, unmount) the USB drive before you reset your
26+
pyboard.*
27+
28+
Boot modes
29+
----------
30+
31+
If you power up normally, or press the reset button, the pyboard will boot
32+
into standard mode: the ``boot.py`` file will be executed first, then the
33+
USB will be configured, then ``main.py`` will run.
34+
35+
You can override this boot sequence by holding down the user switch as
36+
the board is booting up. Hold down user switch and press reset, and then
37+
as you continue to hold the user switch, the LEDs will count in binary.
38+
When the LEDs have reached the mode you want, let go of the user switch,
39+
the LEDs for the selected mode will flash quickly, and the board will boot.
40+
41+
The modes are:
42+
43+
1. Green LED only, *standard boot*: run ``boot.py`` then ``main.py``.
44+
2. Orange LED only, *safe boot*: don't run any scripts on boot-up.
45+
3. Green and orange LED together, *filesystem reset*: resets the flash
46+
filesystem to its factory state, then boots in safe mode.
47+
48+
If your filesystem becomes corrupt, boot into mode 3 to fix it.
49+
50+
Errors: flashing LEDs
51+
---------------------
52+
53+
There are currently 2 kinds of errors that you might see:
54+
55+
1. If the red and green LEDs flash alternatively, then a Python script
56+
(eg ``main.py``) has an error. Use the REPL to debug it.
57+
2. If all 4 LEDs cycle on and off slowly, then there was a hard fault.
58+
This cannot be recovered from and you need to do a hard reset.
59+

‎docs/index.rst‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,37 @@
1-
.. Micro Python documentation master file, created by
2-
sphinx-quickstart on Sun Sep 21 11:42:03 2014.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
1+
.. Micro Python documentation master file
52
6-
Welcome to Micro Python's documentation!
7-
========================================
3+
Micro Python documentation and references
4+
=========================================
85

9-
Contents:
6+
Here you can find documentation for Micro Python and the pyboard.
7+
8+
Software
9+
--------
1010

1111
.. toctree::
1212
:maxdepth: 2
1313

14+
general.rst
15+
tutorial/index.rst
16+
17+
..
18+
.. - Reference for the [pyb module](module/pyb/ "pyb module").
19+
.. - Reference for [all modules](module/ "all modules").
20+
.. - [Guide for setting up the pyboard on Windows](/static/doc/Micro-Python-Windows-setup.pdf), including DFU programming (PDF).
21+
22+
The pyboard hardware
23+
--------------------
24+
25+
.. - PYBv1.0 [schematics and layout](/static/doc/PYBv10b.pdf "PYBv1.0") (2.4MiB PDF).
26+
.. - PYBv1.0 [metric dimensions](/static/doc/PYBv10b-metric-dimensions.pdf "metric dimensions") (360KiB PDF).
27+
.. - PYBv1.0 [imperial dimensions](/static/doc/PYBv10b-imperial-dimensions.pdf "imperial dimensions") (360KiB PDF).
28+
29+
Datasheets for the components on the pyboard
30+
--------------------------------------------
31+
32+
.. - The microcontroller: [STM32F405RGT6](http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144) (external link).
33+
.. - The accelerometer: [Freescale MMA7660](/static/doc/MMA7660FC.pdf) (800kiB PDF).
34+
.. - The LDO voltage regulator: [Microchip MCP1802](/static/doc/MCP1802-22053C.pdf) (400kiB PDF).
1435
1536
1637
Indices and tables

‎docs/tutorial/accel.rst‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
The accelerometer
2+
=================
3+
4+
Here you will learn how to read the accelerometer and signal using LEDs states like tilt left and tilt right.
5+
6+
Using the accelerometer
7+
-----------------------
8+
9+
The pyboard has an accelerometer (a tiny mass on a tiny spring) that can be used
10+
to detect the angle of the board and motion. There is a different sensor for
11+
each of the x, y, z directions. To get the value of the accelerometer, create a
12+
pyb.Accel() object and then call the x() method. ::
13+
14+
>>> accel = pyb.Accel()
15+
>>> accel.x()
16+
7
17+
18+
This returns a signed integer with a value between around -30 and 30. Note that
19+
the measurement is very noisy, this means that even if you keep the board
20+
perfectly still there will be some variation in the number that you measure.
21+
Because of this, you shouldn't use the exact value of the x() method but see if
22+
it is in a certain range.
23+
24+
We will start by using the accelerometer to turn on a light if it is not flat. ::
25+
26+
accel = pyb.Accel()
27+
light = pyb.LED(3)
28+
SENSITIVITY = 3
29+
30+
while True:
31+
x = accel.x()
32+
if abs(x) > SENSITIVITY:
33+
light.on()
34+
else:
35+
light.off()
36+
37+
pyb.delay(100)
38+
39+
We create Accel and LED objects, then get the value of the x direction of the
40+
accelerometer. If the magnitude of x is bigger than a certain value ``SENSITIVITY``,
41+
then the LED turns on, otherwise it turns off. The loop has a small ``pyb.delay()``
42+
otherwise the LED flashes annoyingly when the value of x is close to
43+
``SENSITIVITY``. Try running this on the pyboard and tilt the board left and right
44+
to make the LED turn on and off.
45+
46+
**Exercise: Change the above script so that the blue LED gets brighter the more
47+
you tilt the pyboard. HINT: You will need to rescale the values, intensity goes
48+
from 0-255.**
49+
50+
Making a spirit level
51+
---------------------
52+
53+
The example above is only sensitive to the angle in the x direction but if we
54+
use the ``y()`` value and more LEDs we can turn the pyboard into a spirit level. ::
55+
56+
xlights = (pyb.LED(2), pyb.LED(3))
57+
ylights = (pyb.LED(1), pyb.LED(4))
58+
59+
accel = pyb.Accel()
60+
SENSITIVITY = 3
61+
62+
while True:
63+
x = accel.x()
64+
if x > SENSITIVITY:
65+
xlights[0].on()
66+
xlights[1].off()
67+
elif x < -SENSITIVITY:
68+
xlights[1].on()
69+
xlights[0].off()
70+
else:
71+
xlights[0].off()
72+
xlights[1].off()
73+
74+
y = accel.y()
75+
if y > SENSITIVITY:
76+
ylights[0].on()
77+
ylights[1].off()
78+
elif y < -SENSITIVITY:
79+
ylights[1].on()
80+
ylights[0].off()
81+
else:
82+
ylights[0].off()
83+
ylights[1].off()
84+
85+
pyb.delay(100)
86+
87+
We start by creating a tuple of LED objects for the x and y directions. Tuples
88+
are immutable objects in python which means they can't be modified once they are
89+
created. We then proceed as before but turn on a different LED for positive and
90+
negative x values. We then do the same for the y direction. This isn't
91+
particularly sophisticated but it does the job. Run this on your pyboard and you
92+
should see different LEDs turning on depending on how you tilt the board.

‎docs/tutorial/amp_skin.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
The AMP audio skin
2+
==================
3+
4+
Soldering and using the AMP audio skin.
5+
6+
[<img src="/static/doc/skin-amp-1.jpg" alt="AMP skin" style="width:250px; border:1px solid black; display:inline-block;"/>](/static/doc/skin-amp-1.jpg)
7+
[<img src="/static/doc/skin-amp-3.jpg" alt="AMP skin" style="width:250px; border:1px solid black; display:inline-block;"/>](/static/doc/skin-amp-3.jpg)
8+
9+
The following video shows how to solder the headers, microphone and speaker onto the AMP skin.
10+
11+
<iframe style="margin-left:3em;" width="560" height="315" src="//www.youtube.com/embed/fjB1DuZRveo?rel=0" frameborder="0" allowfullscreen></iframe>
12+
13+
Example code
14+
------------
15+
16+
The AMP skin has a speaker which is connected to DAC(1) via a small
17+
power amplifier. The volume of the amplifier is controlled by a digital
18+
potentiometer, which is an I2C device with address 46 on the IC2(1) bus.
19+
20+
To set the volume, define the following function::
21+
22+
def volume(val):
23+
pyb.I2C(1, pyb.I2C.MASTER).mem_write(val, 46, 0)
24+
25+
Then you can do::
26+
27+
>>> volume(0) # minimum volume
28+
>>> volume(127) # maximum volume
29+
30+
To play a sound, use the ``write_timed`` method of the ``DAC`` object.
31+
For example::
32+
33+
import math
34+
from pyb import DAC
35+
36+
# create a buffer containing a sine-wave
37+
buf = bytearray(100)
38+
for i in range(len(buf)):
39+
buf[i] = 128 + int(127 * math.sin(2 * math.pi * i / len(buf)))
40+
41+
# output the sine-wave at 400Hz
42+
dac = DAC(1)
43+
dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
44+
45+
You can also play WAV files using the Python ``wave`` module. You can get
46+
the wave module [here](/static/doc/examples/wave.py) and you will also need
47+
the chunk module available [here](/static/doc/examples/chunk.py). Put these
48+
on your pyboard (either on the flash or the SD card in the top-level
49+
directory). You will need an 8-bit WAV file to play, such as
50+
[this one](/static/doc/examples/test.wav). Then you can do::
51+
52+
>>> import wave
53+
>>> from pyb import DAC
54+
>>> dac = DAC(1)
55+
>>> f = wave.open('test.wav')
56+
>>> dac.write_timed(f.readframes(f.getnframes()), f.getframerate())
57+
58+
This should play the WAV file.

‎docs/tutorial/assembler.rst‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
Inline assembler
2+
================
3+
4+
Here you will learn how to write inline assembler in Micro Python.
5+
6+
**Note**: this is an advanced tutorial, intended for those who already
7+
know a bit about microcontrollers and assembly language.
8+
9+
Micro Python includes an inline assembler. It allows you to write
10+
assembly routines as a Python function, and you can call them as you would
11+
a normal Python function.
12+
13+
Returning a value
14+
-----------------
15+
16+
Inline assembler functions are denoted by a special function decorator.
17+
Let's start with the simplest example::
18+
19+
@micropython.asm_thumb
20+
def fun():
21+
movw(r0, 42)
22+
23+
You can enter this in a script or at the REPL. This function takes no
24+
arguments and returns the number 42. ``r0`` is a register, and the value
25+
in this register when the function returns is the value that is returned.
26+
Micro Python always interprets the ``r0`` as an integer, and converts it to an
27+
integer object for the caller.
28+
29+
If you run ``print(fun())`` you will see it print out 42.
30+
31+
Accessing peripherals
32+
---------------------
33+
34+
For something a bit more complicated, let's turn on an LED::
35+
36+
@micropython.asm_thumb
37+
def led_on():
38+
movwt(r0, stm.GPIOA)
39+
movw(r1, 1 << 13)
40+
strh(r1, [r0, stm.GPIO_BSRRL])
41+
42+
This code uses a few new concepts:
43+
44+
- ``stm`` is a module which provides a set of constants for easy
45+
access to the registers of the pyboard's microcontroller. Try
46+
running ``import stm`` and then ``help(stm)`` at the REPL. It will
47+
give you a list of all the available constants.
48+
49+
- ``stm.GPIOA`` is the address in memory of the GPIOA peripheral.
50+
On the pyboard, the red LED is on port A, pin PA13.
51+
52+
- ``movwt`` moves a 32-bit number into a register. It is a convenience
53+
function that turns into 2 thumb instructions: ``movw`` followed by ``movt``.
54+
The ``movt`` also shifts the immediate value right by 16 bits.
55+
56+
- ``strh`` stores a half-word (16 bits). The instruction above stores
57+
the lower 16-bits of ``r1`` into the memory location ``r0 + stm.GPIO_BSRRL``.
58+
This has the effect of setting high all those pins on port A for which
59+
the corresponding bit in ``r0`` is set. In our example above, the 13th
60+
bit in ``r0`` is set, so PA13 is pulled high. This turns on the red LED.
61+
62+
Accepting arguments
63+
-------------------
64+
65+
Inline assembler functions can accept up to 3 arguments. If they are
66+
used, they must be named ``r0``, ``r1`` and ``r2`` to reflect the registers
67+
and the calling conventions.
68+
69+
Here is a function that adds its arguments::
70+
71+
@micropython.asm_thumb
72+
def asm_add(r0, r1):
73+
add(r0, r0, r1)
74+
75+
This performs the computation ``r0 = r0 + r1``. Since the result is put
76+
in ``r0``, that is what is returned. Try ``asm_add(1, 2)``, it should return
77+
3.
78+
79+
Loops
80+
-----
81+
82+
We can assign labels with ``label(my_label)``, and branch to them using
83+
``b(my_label)``, or a conditional branch like ``bgt(my_label)``.
84+
85+
The following example flashes the green LED. It flashes it ``r0`` times. ::
86+
87+
@micropython.asm_thumb
88+
def flash_led(r0):
89+
# get the GPIOA address in r1
90+
movwt(r1, stm.GPIOA)
91+
92+
# get the bit mask for PA14 (the pin LED #2 is on)
93+
movw(r2, 1 << 14)
94+
95+
b(loop_entry)
96+
97+
label(loop1)
98+
99+
# turn LED on
100+
strh(r2, [r1, stm.GPIO_BSRRL])
101+
102+
# delay for a bit
103+
movwt(r4, 5599900)
104+
label(delay_on)
105+
sub(r4, r4, 1)
106+
cmp(r4, 0)
107+
bgt(delay_on)
108+
109+
# turn LED off
110+
strh(r2, [r1, stm.GPIO_BSRRH])
111+
112+
# delay for a bit
113+
movwt(r4, 5599900)
114+
label(delay_off)
115+
sub(r4, r4, 1)
116+
cmp(r4, 0)
117+
bgt(delay_off)
118+
119+
# loop r0 times
120+
sub(r0, r0, 1)
121+
label(loop_entry)
122+
cmp(r0, 0)
123+
bgt(loop1)

0 commit comments

Comments
 (0)