summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rwxr-xr-xdocs/conf.py2
-rw-r--r--docs/esp8266/quickref.rst41
-rw-r--r--docs/esp8266/tutorial/intro.rst4
-rw-r--r--docs/esp8266/tutorial/onewire.rst6
-rw-r--r--docs/esp8266/tutorial/pins.rst2
-rw-r--r--docs/library/machine.WDT.rst2
-rw-r--r--docs/library/machine.rst2
-rw-r--r--docs/library/pyb.USB_HID.rst28
-rw-r--r--docs/library/pyb.rst30
-rw-r--r--docs/pyboard/quickref.rst21
-rw-r--r--docs/pyboard/tutorial/usb_mouse.rst28
-rw-r--r--docs/reference/isr_rules.rst30
12 files changed, 161 insertions, 35 deletions
diff --git a/docs/conf.py b/docs/conf.py
index fbc89afc6a..a737e43ef1 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -99,7 +99,7 @@ copyright = '2014-2016, Damien P. George and contributors'
# The short X.Y version.
version = '1.8'
# The full version, including alpha/beta/rc tags.
-release = '1.8.3'
+release = '1.8.4'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
index 48543dfab6..d06fe5a6f1 100644
--- a/docs/esp8266/quickref.rst
+++ b/docs/esp8266/quickref.rst
@@ -23,14 +23,14 @@ Tab-completion is useful to find out what methods an object has.
Paste mode (ctrl-E) is useful to paste a large slab of Python code into
the REPL.
-The ``machine`` module::
+The :mod:`machine` module::
import machine
machine.freq() # get the current frequency of the CPU
machine.freq(160000000) # set the CPU frequency to 160 MHz
-The ``esp`` module::
+The :mod:`esp` module::
import esp
@@ -40,7 +40,7 @@ The ``esp`` module::
Networking
----------
-The ``network`` module::
+The :mod:`network` module::
import network
@@ -69,13 +69,13 @@ A useful function for connecting to your local WiFi network is::
pass
print('network config:', wlan.ifconfig())
-Once the network is established the ``socket`` module can be used
+Once the network is established the :mod:`socket <usocket>` module can be used
to create and use TCP/UDP sockets as usual.
Delay and timing
----------------
-Use the ``time`` module::
+Use the :mod:`time <utime>` module::
import time
@@ -162,17 +162,18 @@ Use the ``machine.ADC`` class::
adc = ADC(0) # create ADC object on ADC pin
adc.read() # read value, 0-1024
-SPI bus
--------
+Software SPI bus
+----------------
-The SPI driver is implemented in software and works on all pins::
+There are two SPI drivers. One is implemented in software (bit-banging)
+and works on all pins::
from machine import Pin, SPI
# construct an SPI bus on the given pins
# polarity is the idle state of SCK
# phase=0 means sample on the first edge of SCK, phase=1 means the second
- spi = SPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
+ spi = SPI(-1, baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
spi.init(baudrate=200000) # set the baudrate
@@ -189,6 +190,21 @@ The SPI driver is implemented in software and works on all pins::
spi.write_readinto(b'1234', buf) # write to MOSI and read from MISO into the buffer
spi.write_readinto(buf, buf) # write buf to MOSI and read MISO back into buf
+
+Hardware SPI bus
+----------------
+
+The hardware SPI is faster (up to 80Mhz), but only works on following pins:
+``MISO`` is GPIO12, ``MOSI`` is GPIO13, and ``SCK`` is GPIO14. It has the same
+methods as the bitbanging SPI class above, except for the pin parameters for the
+constructor and init (as those are fixed)::
+
+ from machine import Pin, SPI
+
+ hspi = SPI(1, baudrate=80000000, polarity=0, phase=0)
+
+(``SPI(0)`` is used for FlashROM and not available to users.)
+
I2C bus
-------
@@ -239,15 +255,14 @@ The OneWire driver is implemented in software and works on all pins::
ow.scan() # return a list of devices on the bus
ow.reset() # reset the bus
ow.readbyte() # read a byte
- ow.read(5) # read 5 bytes
ow.writebyte(0x12) # write a byte on the bus
ow.write('123') # write bytes on the bus
ow.select_rom(b'12345678') # select a specific device by its ROM code
-There is a specific driver for DS18B20 devices::
+There is a specific driver for DS18S20 and DS18B20 devices::
- import time
- ds = onewire.DS18B20(ow)
+ import time, ds18x20
+ ds = ds18x20.DS18X20(ow)
roms = ds.scan()
ds.convert_temp()
time.sleep_ms(750)
diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst
index 8c356b913f..32e9326b37 100644
--- a/docs/esp8266/tutorial/intro.rst
+++ b/docs/esp8266/tutorial/intro.rst
@@ -135,6 +135,10 @@ after it, here are troubleshooting recommendations:
rate may be too high and lead to errors. Try a more common 115200 baud
rate instead in such cases.
+* If lower baud rate didn't help, you may want to try older version of
+ esptool.py, which had a different programming algorithm::
+ pip install esptool==1.0.1
+
* The ``--flash_size`` option in the commands above is mandatory. Omitting
it will lead to a corrupted firmware.
diff --git a/docs/esp8266/tutorial/onewire.rst b/docs/esp8266/tutorial/onewire.rst
index c90044b7a8..c2cede9e38 100644
--- a/docs/esp8266/tutorial/onewire.rst
+++ b/docs/esp8266/tutorial/onewire.rst
@@ -6,19 +6,19 @@ The 1-wire bus is a serial bus that uses just a single wire for communication
is a very popular 1-wire device, and here we show how to use the onewire module
to read from such a device.
-For the following code to work you need to have at least one DS18B20 temperature
+For the following code to work you need to have at least one DS18S20 or DS18B20 temperature
sensor with its data line connected to GPIO12. You must also power the sensors
and connect a 4.7k Ohm resistor between the data pin and the power pin. ::
import time
import machine
- import onewire
+ import onewire, ds18x20
# the device is on GPIO12
dat = machine.Pin(12)
# create the onewire object
- ds = onewire.DS18B20(onewire.OneWire(dat))
+ ds = ds18x20.DS18X20(onewire.OneWire(dat))
# scan for devices on the bus
roms = ds.scan()
diff --git a/docs/esp8266/tutorial/pins.rst b/docs/esp8266/tutorial/pins.rst
index 639267d2ee..a44f40d3a7 100644
--- a/docs/esp8266/tutorial/pins.rst
+++ b/docs/esp8266/tutorial/pins.rst
@@ -14,7 +14,7 @@ Here, the "0" is the pin that you want to access. Usually you want to
configure the pin to be input or output, and you do this when constructing
it. To make an input pin use::
- >>> pin = machine.Pin(0, machine.Pin.OUT, machine.Pin.PULL_UP)
+ >>> pin = machine.Pin(0, machine.Pin.IN, machine.Pin.PULL_UP)
You can either use PULL_UP or None for the input pull-mode. If it's
not specified then it defaults to None, which is no pull resistor.
diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst
index d7c801356e..1d79b4c4ed 100644
--- a/docs/library/machine.WDT.rst
+++ b/docs/library/machine.WDT.rst
@@ -14,6 +14,8 @@ Example usage::
wdt = WDT(timeout=2000) # enable it with a timeout of 2s
wdt.feed()
+Availability of this class: pyboard, WiPy.
+
Constructors
------------
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index 0f361a7cb7..46d8eea71f 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -125,7 +125,7 @@ Constants
irq wake values
-.. data:: machine.POWER_ON
+.. data:: machine.PWRON_RESET
.. data:: machine.HARD_RESET
.. data:: machine.WDT_RESET
.. data:: machine.DEEPSLEEP_RESET
diff --git a/docs/library/pyb.USB_HID.rst b/docs/library/pyb.USB_HID.rst
new file mode 100644
index 0000000000..65fb4014e0
--- /dev/null
+++ b/docs/library/pyb.USB_HID.rst
@@ -0,0 +1,28 @@
+.. currentmodule:: pyb
+
+class USB_HID -- USB Human Interface Device (HID)
+=================================================
+
+The USB_HID class allows creation of an object representing the USB
+Human Interface Device (HID) interface. It can be used to emulate
+a peripheral such as a mouse or keyboard.
+
+Before you can use this class, you need to use :meth:`pyb.usb_mode()` to set the USB mode to include the HID interface.
+
+Constructors
+------------
+
+.. class:: pyb.USB_HID()
+
+ Create a new USB_HID object.
+
+
+Methods
+-------
+
+.. method:: USB_HID.send(data)
+
+ Send data over the USB HID interface:
+
+ - ``data`` is the data to send (a tuple/list of integers, or a
+ bytearray).
diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
index 2f3e7d36bd..910b2f45b4 100644
--- a/docs/library/pyb.rst
+++ b/docs/library/pyb.rst
@@ -188,7 +188,7 @@ Miscellaneous functions
Takes a 4-tuple (or list) and sends it to the USB host (the PC) to
signal a HID mouse-motion event.
- .. note:: This function is deprecated. Use pyb.USB_HID().send(...) instead.
+ .. note:: This function is deprecated. Use :meth:`pyb.USB_HID.send()` instead.
.. function:: info([dump_alloc_table])
@@ -254,6 +254,33 @@ Miscellaneous functions
Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU.
+.. function:: usb_mode([modestr], vid=0xf055, pid=0x9801, hid=pyb.hid_mouse)
+
+ If called with no arguments, return the current USB mode as a string.
+
+ If called with ``modestr`` provided, attempts to set USB mode.
+ This can only be done when called from ``boot.py`` before
+ :meth:`pyb.main()` has been called. The following values of
+ ``modestr`` are understood:
+
+ - ``None``: disables USB
+ - ``'VCP'``: enable with VCP (Virtual COM Port) interface
+ - ``'VCP+MSC'``: enable with VCP and MSC (mass storage device class)
+ - ``'VCP+HID'``: enable with VCP and HID (human interface device)
+
+ For backwards compatibility, ``'CDC'`` is understood to mean
+ ``'VCP'`` (and similarly for ``'CDC+MSC'`` and ``'CDC+HID'``).
+
+ The ``vid`` and ``pid`` parameters allow you to specify the VID
+ (vendor id) and PID (product id).
+
+ If enabling HID mode, you may also specify the HID details by
+ passing the ``hid`` keyword parameter. It takes a tuple of
+ (subclass, protocol, max packet length, polling interval, report
+ descriptor). By default it will set appropriate values for a USB
+ mouse. There is also a ``pyb.hid_keyboard`` constant, which is an
+ appropriate tuple for a USB keyboard.
+
Classes
-------
@@ -277,4 +304,5 @@ Classes
pyb.Switch.rst
pyb.Timer.rst
pyb.UART.rst
+ pyb.USB_HID.rst
pyb.USB_VCP.rst
diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst
index 2a1429cb05..3d08ae9109 100644
--- a/docs/pyboard/quickref.rst
+++ b/docs/pyboard/quickref.rst
@@ -3,6 +3,12 @@
Quick reference for the pyboard
===============================
+The below pinout is for PYBv1.0. You can also view pinouts for
+other versions of the pyboard:
+`PYBv1.1 <http://micropython.org/resources/pybv11-pinout.jpg>`__
+or `PYBLITEv1.0-AC <http://micropython.org/resources/pyblitev10ac-pinout.jpg>`__
+or `PYBLITEv1.0 <http://micropython.org/resources/pyblitev10-pinout.jpg>`__.
+
.. image:: http://micropython.org/resources/pybv10-pinout.jpg
:alt: PYBv1.0 pinout
:width: 700px
@@ -14,14 +20,25 @@ See :mod:`pyb`. ::
import pyb
- pyb.delay(50) # wait 50 milliseconds
- pyb.millis() # number of milliseconds since bootup
pyb.repl_uart(pyb.UART(1, 9600)) # duplicate REPL on UART(1)
pyb.wfi() # pause CPU, waiting for interrupt
pyb.freq() # get CPU and bus frequencies
pyb.freq(60000000) # set CPU freq to 60MHz
pyb.stop() # stop CPU, waiting for external interrupt
+Delay and timing
+----------------
+
+Use the :mod:`time <utime>` module::
+
+ import time
+
+ time.sleep(1) # sleep for 1 second
+ time.sleep_ms(500) # sleep for 500 milliseconds
+ time.sleep_us(10) # sleep for 10 microseconds
+ start = time.ticks_ms() # get value of millisecond counter
+ delta = time.ticks_diff(start, time.ticks_ms()) # compute time difference
+
LEDs
----
diff --git a/docs/pyboard/tutorial/usb_mouse.rst b/docs/pyboard/tutorial/usb_mouse.rst
index ac1de6e275..6f8831edb4 100644
--- a/docs/pyboard/tutorial/usb_mouse.rst
+++ b/docs/pyboard/tutorial/usb_mouse.rst
@@ -13,23 +13,23 @@ will look something like this::
import pyb
#pyb.main('main.py') # main script to run after this one
- #pyb.usb_mode('CDC+MSC') # act as a serial and a storage device
- #pyb.usb_mode('CDC+HID') # act as a serial device and a mouse
+ #pyb.usb_mode('VCP+MSC') # act as a serial and a storage device
+ #pyb.usb_mode('VCP+HID') # act as a serial device and a mouse
To enable the mouse mode, uncomment the last line of the file, to
make it look like::
- pyb.usb_mode('CDC+HID') # act as a serial device and a mouse
+ pyb.usb_mode('VCP+HID') # act as a serial device and a mouse
If you already changed your ``boot.py`` file, then the minimum code it
needs to work is::
import pyb
- pyb.usb_mode('CDC+HID')
+ pyb.usb_mode('VCP+HID')
-This tells the pyboard to configure itself as a CDC (serial) and HID
-(human interface device, in our case a mouse) USB device when it boots
-up.
+This tells the pyboard to configure itself as a VCP (Virtual COM Port,
+ie serial port) and HID (human interface device, in our case a mouse)
+USB device when it boots up.
Eject/unmount the pyboard drive and reset it using the RST switch.
Your PC should now detect the pyboard as a mouse!
@@ -41,7 +41,8 @@ To get the py-mouse to do anything we need to send mouse events to the PC.
We will first do this manually using the REPL prompt. Connect to your
pyboard using your serial program and type the following::
- >>> pyb.hid((0, 10, 0, 0))
+ >>> hid = pyb.USB_HID()
+ >>> hid.send((0, 10, 0, 0))
Your mouse should move 10 pixels to the right! In the command above you
are sending 4 pieces of information: button status, x, y and scroll. The
@@ -52,7 +53,7 @@ Let's make the mouse oscillate left and right::
>>> import math
>>> def osc(n, d):
... for i in range(n):
- ... pyb.hid((0, int(20 * math.sin(i / 10)), 0, 0))
+ ... hid.send((0, int(20 * math.sin(i / 10)), 0, 0))
... pyb.delay(d)
...
>>> osc(100, 50)
@@ -100,9 +101,10 @@ In ``main.py`` put the following code::
switch = pyb.Switch()
accel = pyb.Accel()
+ hid = pyb.USB_HID()
while not switch():
- pyb.hid((0, accel.x(), accel.y(), 0))
+ hid.send((0, accel.x(), accel.y(), 0))
pyb.delay(20)
Save your file, eject/unmount your pyboard drive, and reset it using the RST
@@ -112,7 +114,7 @@ the mouse around. Try it out, and see if you can make the mouse stand still!
Press the USR switch to stop the mouse motion.
You'll note that the y-axis is inverted. That's easy to fix: just put a
-minus sign in front of the y-coordinate in the ``pyb.hid()`` line above.
+minus sign in front of the y-coordinate in the ``hid.send()`` line above.
Restoring your pyboard to normal
--------------------------------
@@ -121,9 +123,9 @@ If you leave your pyboard as-is, it'll behave as a mouse everytime you plug
it in. You probably want to change it back to normal. To do this you need
to first enter safe mode (see above), and then edit the ``boot.py`` file.
In the ``boot.py`` file, comment out (put a # in front of) the line with the
-``CDC+HID`` setting, so it looks like::
+``VCP+HID`` setting, so it looks like::
- #pyb.usb_mode('CDC+HID') # act as a serial device and a mouse
+ #pyb.usb_mode('VCP+HID') # act as a serial device and a mouse
Save your file, eject/unmount the drive, and reset the pyboard. It is now
back to normal operating mode.
diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst
index b33e4dd6f2..23dcfd01f4 100644
--- a/docs/reference/isr_rules.rst
+++ b/docs/reference/isr_rules.rst
@@ -110,6 +110,19 @@ the flag. The memory allocation occurs in the main program code when the object
The MicroPython library I/O methods usually provide an option to use a pre-allocated buffer. For
example ``pyb.i2c.recv()`` can accept a mutable buffer as its first argument: this enables its use in an ISR.
+A means of creating an object without employing a class or globals is as follows:
+
+.. code:: python
+
+ def set_volume(t, buf=bytearray(3)):
+ buf[0] = 0xa5
+ buf[1] = t >> 4
+ buf[2] = 0x5a
+ return buf
+
+The compiler instantiates the default ``buf`` argument when the function is
+loaded for the first time (usually when the module it's in is imported).
+
Use of Python objects
~~~~~~~~~~~~~~~~~~~~~
@@ -300,3 +313,20 @@ that access to the critical variables is denied. A simple example of a mutex may
but only for the duration of eight machine instructions: the benefit of this approach is that other interrupts are
virtually unaffected.
+Interrupts and the REPL
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Interrupt handlers, such as those associated with timers, can continue to run
+after a program terminates. This may produce unexpected results where you might
+have expected the object raising the callback to have gone out of scope. For
+example on the Pyboard:
+
+.. code:: python
+
+ def bar():
+ foo = pyb.Timer(2, freq=4, callback=lambda t: print('.', end=''))
+
+ bar()
+
+This continues to run until the timer is explicitly disabled or the board is
+reset with ``ctrl D``.