docs: Bump version to 1.9.3.

This reverts commit 3289b9b7a7.
The commit broke building on MINGW because the filename became
micropython.exe.exe.  A proper solution to support more Windows build
environments requires more thought and testing.

.gitattributes

@@ -0,0 +1,27 @@
+# Per default everything gets normalized and gets LF line endings on checkout.
+* text eol=lf
+
+# These will always have CRLF line endings on checkout.
+*.vcxproj text eol=crlf
+*.props text eol=crlf
+*.bat text eol=crlf
+
+# These are binary so should never be modified by git.
+*.png binary
+*.jpg binary
+*.dxf binary
+*.mpy binary
+
+# These should also not be modified by git.
+tests/basics/string_cr_conversion.py -text
+tests/basics/string_crlf_conversion.py -text
+ports/stm32/pybcdc.inf_template -text
+ports/stm32/usbd_* -text
+ports/stm32/usbdev/** -text
+ports/stm32/usbhost/** -text
+ports/cc3200/hal/aes.c -text
+ports/cc3200/hal/aes.h -text
+ports/cc3200/hal/des.c -text
+ports/cc3200/hal/i2s.c -text
+ports/cc3200/hal/i2s.h -text
+ports/cc3200/version.h -text

.gitignore

@@ -9,7 +9,7 @@
 *.dis
 *.exe
 
-# Packages 
+# Packages
 ############
 
 # Logs and Databases
@@ -32,3 +32,13 @@ tests/*.out
 # Python cache files
 ######################
 __pycache__/
+*.pyc
+
+# Customized Makefile/project overrides
+######################
+GNUmakefile
+user.props
+
+# Generated rst files
+######################
+genrst/

.gitmodules

@@ -0,0 +1,17 @@
+[submodule "lib/axtls"]
+	path = lib/axtls
+	url = https://github.com/pfalcon/axtls
+	branch = micropython
+[submodule "lib/libffi"]
+	path = lib/libffi
+	url = https://github.com/atgreen/libffi
+[submodule "lib/lwip"]
+	path = lib/lwip
+	url = http://git.savannah.gnu.org/r/lwip.git
+[submodule "lib/berkeley-db-1.xx"]
+	path = lib/berkeley-db-1.xx
+	url = https://github.com/pfalcon/berkeley-db-1.xx
+[submodule "lib/stm32lib"]
+	path = lib/stm32lib
+	url = https://github.com/micropython/stm32lib
+	branch = work-F4-1.13.1+F7-1.5.0+L4-1.3.0

.travis.yml

@@ -1,21 +1,66 @@
+sudo: required
+dist: trusty
 language: c
 compiler:
   - gcc
+cache:
+  directories:
+    - "${HOME}/persist"
 
 before_script:
-  - sudo add-apt-repository -y ppa:fkrull/deadsnakes
-  - sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
+# Extra CPython versions
+#  - sudo add-apt-repository -y ppa:fkrull/deadsnakes
+# Extra gcc versions
+#  - sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
   - sudo add-apt-repository -y ppa:terry.guo/gcc-arm-embedded
-  - sudo apt-get update -qq
-  - sudo apt-get install -y python3.3 python3 gcc-4.7 gcc-arm-none-eabi qemu-system
+  - sudo dpkg --add-architecture i386
+  - sudo apt-get update -qq || true
+  - sudo apt-get install -y python3 gcc-multilib pkg-config libffi-dev libffi-dev:i386 qemu-system gcc-mingw-w64
+  - sudo apt-get install -y --force-yes gcc-arm-none-eabi
+  # For teensy build
+  - sudo apt-get install realpath
+  # For coverage testing (upgrade is used to get latest urllib3 version)
+  - sudo pip install --upgrade cpp-coveralls
+  - gcc --version
+  - arm-none-eabi-gcc --version
+  - python3 --version
 
 script:
-  - make -C unix CC=gcc-4.7
-  - make -C unix-cpy CC=gcc-4.7
-  - make -C bare-arm
-  - make -C qemu-arm
-  - make -C stmhal
-  - (cd tests && MICROPY_CPYTHON3=python3.3 ./run-tests)
+  - make -C mpy-cross
+  - make -C ports/minimal CROSS=1 build/firmware.bin
+  - ls -l ports/minimal/build/firmware.bin
+  - tools/check_code_size.sh
+  - mkdir -p ${HOME}/persist
+  # Save new firmware for reference, but only if building a main branch, not a pull request
+  - 'if [ "$TRAVIS_PULL_REQUEST" = "false" ]; then cp ports/minimal/build/firmware.bin ${HOME}/persist/; fi'
+  - make -C ports/unix deplibs
+  - make -C ports/unix
+  - make -C ports/unix nanbox
+  - make -C ports/bare-arm
+  - make -C ports/qemu-arm test
+  - make -C ports/stm32
+  - make -C ports/stm32 BOARD=PYBV11 MICROPY_PY_WIZNET5K=5200 MICROPY_PY_CC3K=1
+  - make -C ports/stm32 BOARD=STM32F769DISC
+  - make -C ports/stm32 BOARD=STM32L476DISC
+  - make -C ports/teensy
+  - make -C ports/cc3200 BTARGET=application BTYPE=release
+  - make -C ports/cc3200 BTARGET=bootloader  BTYPE=release
+  - make -C ports/windows CROSS_COMPILE=i686-w64-mingw32-
+
+  # run tests without coverage info
+  #- (cd tests && MICROPY_CPYTHON3=python3.4 ./run-tests)
+  #- (cd tests && MICROPY_CPYTHON3=python3.4 ./run-tests --emit native)
+
+  # run tests with coverage info
+  - make -C ports/unix coverage
+  - (cd tests && MICROPY_CPYTHON3=python3.4 MICROPY_MICROPYTHON=../ports/unix/micropython_coverage ./run-tests)
+  - (cd tests && MICROPY_CPYTHON3=python3.4 MICROPY_MICROPYTHON=../ports/unix/micropython_coverage ./run-tests -d thread)
+  - (cd tests && MICROPY_CPYTHON3=python3.4 MICROPY_MICROPYTHON=../ports/unix/micropython_coverage ./run-tests --emit native)
+  - (cd tests && MICROPY_CPYTHON3=python3.4 MICROPY_MICROPYTHON=../ports/unix/micropython_coverage ./run-tests --via-mpy -d basics float)
+
+  # run coveralls coverage analysis (try to, even if some builds/tests failed)
+  - (cd ports/unix && coveralls --root ../.. --build-root . --gcov $(which gcov) --gcov-options '\-o build-coverage/' --include py --include extmod)
 
 after_failure:
-  - (cd tests && for exp in *.exp; do testbase=$(basename $exp .exp); echo -e "\nFAILURE $testbase"; diff $testbase.exp $testbase.out; done)
+  - (cd tests && for exp in *.exp; do testbase=$(basename $exp .exp); echo -e "\nFAILURE $testbase"; diff -u $testbase.exp $testbase.out; done)
+  - (grep "FAIL" ports/qemu-arm/build/console.out)

CODECONVENTIONS.md

@@ -1,3 +1,52 @@
+Git commit conventions
+======================
+
+Each commit message should start with a directory or full file path
+prefix, so it was clear which part of codebase a commit affects. If
+a change affects one file, it's better to use path to a file. If it
+affects few files in a subdirectory, using subdirectory as a prefix
+is ok. For longish paths, it's acceptable to drop intermediate
+components, which still should provide good context of a change.
+It's also ok to drop file extensions.
+
+Besides prefix, first line of a commit message should describe a
+change clearly and to the point, and be a grammatical sentence with
+final full stop. First line should fit within 78 characters. Examples
+of good first line of commit messages:
+
+    py/objstr: Add splitlines() method.
+    py: Rename FOO to BAR.
+    docs/machine: Fix typo in reset() description.
+    ports: Switch to use lib/foo instead of duplicated code.
+
+After the first line, add an empty line and in following lines describe
+a change in a detail, if needed. Any change beyond 5 lines would likely
+require such detailed description.
+
+To get good practical examples of good commits and their messages, browse
+the `git log` of the project.
+
+MicroPython doesn't require explicit sign-off for patches ("Signed-off-by"
+lines and similar). Instead, the commit message, and your name and email
+address on it construes your sign-off of the following:
+
+* That you wrote the change yourself, or took it from a project with
+  a compatible license (in the latter case the commit message, and possibly
+  source code should provide reference where the implementation was taken
+  from and give credit to the original author, as required by the license).
+* That you are allowed to release these changes to an open-source project
+  (for example, changes done during paid work for a third party may require
+  explicit approval from that third party).
+* That you (or your employer) agree to release the changes under
+  MicroPython's license, which is the MIT license. Note that you retain
+  copyright for your changes (for smaller changes, the commit message
+  conveys your copyright; if you make significant changes to a particular
+  source module, you're welcome to add your name to the file header).
+* Your signature for all of the above, which is the 'Author' line in
+  the commit message, and which should include your full real name and
+  a valid and active email address by which you can be contacted in the
+  foreseeable future.
+
 Python code conventions
 =======================
 
@@ -24,7 +73,7 @@ White space:
   keyword and the opening parenthesis.
 - Put 1 space after a comma, and 1 space around operators.
 
-Braces: 
+Braces:
 - Use braces for all blocks, even no-line and single-line pieces of
   code.
 - Put opening braces on the end of the line it belongs to, not on
@@ -33,26 +82,50 @@ Braces:
   closing brace.
 
 Header files:
-- Try to stick to the Plan 9 header style, where header files do not
-  include other header files.
-- Don't protect a header file from multiple inclusion with #if directives.
+- Header files should be protected from multiple inclusion with #if
+  directives. See an existing header for naming convention.
 
-Type names and declarations:
-- When defining a type, put '_t' after it.
+Names:
+- Use underscore_case, not camelCase for all names.
+- Use CAPS_WITH_UNDERSCORE for enums and macros.
+- When defining a type use underscore_case and put '_t' after it.
+
+Integer types: MicroPython runs on 16, 32, and 64 bit machines, so it's
+important to use the correctly-sized (and signed) integer types.  The
+general guidelines are:
+- For most cases use mp_int_t for signed and mp_uint_t for unsigned
+  integer values.  These are guaranteed to be machine-word sized and
+  therefore big enough to hold the value from a MicroPython small-int
+  object.
+- Use size_t for things that count bytes / sizes of objects.
+- You can use int/uint, but remember that they may be 16-bits wide.
+- If in doubt, use mp_int_t/mp_uint_t.
+
+Comments:
+- Be concise and only write comments for things that are not obvious.
+- Use `// ` prefix, NOT `/* ... */`. No extra fluff.
+
+Memory allocation:
+- Use m_new, m_renew, m_del (and friends) to allocate and free heap memory.
+  These macros are defined in py/misc.h.
 
 Examples
 --------
 
-Braces and spaces:
+Braces, spaces, names and comments:
 
-    int foo(int x, int y) {
-        if (x < y) {
-            foo(y, x);
+    #define TO_ADD (123)
+
+    // This function will always recurse indefinitely and is only used to show
+    // coding style
+    int foo_function(int x, int some_value) {
+        if (x < some_value) {
+            foo(some_value, x);
         } else {
-            foo(x + 1, y - 1);
+            foo(x + TO_ADD, some_value - 1);
         }
 
-        for (int i = 0; i < x; i++) {
+        for (int my_counter = 0; my_counter < x; my_counter++) {
         }
     }
 
@@ -62,3 +135,76 @@ Type declarations:
         int member;
         void *data;
     } my_struct_t;
+
+Documentation conventions
+=========================
+
+MicroPython generally follows CPython in documentation process and
+conventions. reStructuredText syntax is used for the documention.
+
+Specific conventions/suggestions:
+
+* Use `*` markup to refer to arguments of a function, e.g.:
+
+```
+.. method:: poll.unregister(obj)
+
+   Unregister *obj* from polling.
+```
+
+* Use following syntax for cross-references/cross-links:
+
+```
+:func:`foo` - function foo in current module
+:func:`module1.foo` - function foo in module "module1"
+    (similarly for other referent types)
+:class:`Foo` - class Foo
+:meth:`Class.method1` - method1 in Class
+:meth:`~Class.method1` - method1 in Class, but rendered just as "method1()",
+    not "Class.method1()"
+:meth:`title <method1>` - reference method1, but render as "title" (use only
+    if really needed)
+:mod:`module1` - module module1
+
+`symbol` - generic xref syntax which can replace any of the above in case
+    the xref is unambiguous. If there's ambiguity, there will be a warning
+    during docs generation, which need to be fixed using one of the syntaxes
+    above
+```
+
+* Cross-referencing arbitrary locations
+~~~
+.. _xref_target:
+
+Normal non-indented text.
+
+This is :ref:`reference <xref_target>`.
+
+(If xref target is followed by section title, can be just
+:ref:`xref_target`).
+~~~
+
+* Linking to external URL:
+```
+`link text <http://foo.com/...>`_
+```
+
+* Referencing builtin singleton objects:
+```
+``None``, ``True``, ``False``
+```
+
+* Use following syntax to create common description for more than one element:
+~~~
+.. function:: foo(x)
+              bar(y)
+
+   Description common to foo() and bar().
+~~~
+
+
+More detailed guides and quickrefs:
+
+* http://www.sphinx-doc.org/en/stable/rest.html
+* http://www.sphinx-doc.org/en/stable/markup/inline.html
+* http://docutils.sourceforge.net/docs/user/rst/quickref.html

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+When reporting an issue and especially submitting a pull request, please
+make sure that you are acquainted with Contributor Guidelines:
+
+https://github.com/micropython/micropython/wiki/ContributorGuidelines
+
+and Code Conventions:
+
+https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013 Damien P. George
+Copyright (c) 2013, 2014 Damien P. George
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,78 +1,153 @@
-[![Build Status][travis-img]][travis-repo]
-[travis-img]:  https://travis-ci.org/micropython/micropython.png?branch=master
-[travis-repo]: https://travis-ci.org/micropython/micropython
+[![Build Status](https://travis-ci.org/micropython/micropython.png?branch=master)](https://travis-ci.org/micropython/micropython) [![Coverage Status](https://coveralls.io/repos/micropython/micropython/badge.png?branch=master)](https://coveralls.io/r/micropython/micropython?branch=master)
 
-The Micro Python project
-========================
+The MicroPython project
+=======================
 <p align="center">
-  <img src="https://raw2.github.com/micropython/micropython/master/logo/upython-with-micro.jpg" alt="MicroPython Logo"/>
+  <img src="https://raw.githubusercontent.com/micropython/micropython/master/logo/upython-with-micro.jpg" alt="MicroPython Logo"/>
 </p>
 
-This is the Micro Python project, which aims to put an implementation
-of Python 3.x on a microcontroller.
+This is the MicroPython project, which aims to put an implementation
+of Python 3.x on microcontrollers and small embedded systems.
+You can find the official website at [micropython.org](http://www.micropython.org).
 
-WARNING: this project is in its early stages and is subject to large
-changes of the code-base, including project-wide name changes and API
-changes.
+WARNING: this project is in beta stage and is subject to changes of the
+code-base, including project-wide name changes and API changes.
 
-See the repository www.github.com/micropython/pyboard for the Micro
-Python board.
+MicroPython implements the entire Python 3.4 syntax (including exceptions,
+`with`, `yield from`, etc., and additionally `async`/`await` keywords from
+Python 3.5). The following core datatypes are provided: `str` (including
+basic Unicode support), `bytes`, `bytearray`, `tuple`, `list`, `dict`, `set`,
+`frozenset`, `array.array`, `collections.namedtuple`, classes and instances.
+Builtin modules include `sys`, `time`, and `struct`, etc. Select ports have
+support for `_thread` module (multithreading). Note that only a subset of
+Python 3 functionality is implemented for the data types and modules.
+
+MicroPython can execute scripts in textual source form or from precompiled
+bytecode, in both cases either from an on-device filesystem or "frozen" into
+the MicroPython executable.
+
+See the repository http://github.com/micropython/pyboard for the MicroPython
+board (PyBoard), the officially supported reference electronic circuit board.
 
 Major components in this repository:
-- py/ -- the core Python implementation, including compiler and runtime.
-- unix/ -- a version of Micro Python that runs on Unix.
-- stmhal/ -- a version of Micro Python that runs on the Micro Python board
-  with an STM32F405RG (using ST's new Cube HAL drivers).
-- teensy/ -- a version of Micro Python that runs on the Teensy 3.1
-  (preliminary but functional).
+- py/ -- the core Python implementation, including compiler, runtime, and
+  core library.
+- mpy-cross/ -- the MicroPython cross-compiler which is used to turn scripts
+  into precompiled bytecode.
+- ports/unix/ -- a version of MicroPython that runs on Unix.
+- ports/stm32/ -- a version of MicroPython that runs on the PyBoard and similar
+  STM32 boards (using ST's Cube HAL drivers).
+- ports/minimal/ -- a minimal MicroPython port. Start with this if you want
+  to port MicroPython to another microcontroller.
+- tests/ -- test framework and test scripts.
+- docs/ -- user documentation in Sphinx reStructuredText format. Rendered
+  HTML documentation is available at http://docs.micropython.org (be sure
+  to select needed board/port at the bottom left corner).
 
 Additional components:
-- bare-arm/ -- a bare minimum version of Micro Python for ARM MCUs.  Start
-  with this if you want to port Micro Python to another microcontroller.
-- stm/ -- obsolete version of Micro Python for the Micro Python board
-  that uses ST's old peripheral drivers.
-- unix-cpy/ -- a version of Micro Python that outputs bytecode (for testing).
-- tests/ -- test framework and test scripts.
+- ports/bare-arm/ -- a bare minimum version of MicroPython for ARM MCUs. Used
+  mostly to control code size.
+- ports/teensy/ -- a version of MicroPython that runs on the Teensy 3.1
+  (preliminary but functional).
+- ports/pic16bit/ -- a version of MicroPython for 16-bit PIC microcontrollers.
+- ports/cc3200/ -- a version of MicroPython that runs on the CC3200 from TI.
+- ports/esp8266/ -- an experimental port for ESP8266 WiFi modules.
+- extmod/ -- additional (non-core) modules implemented in C.
 - tools/ -- various tools, including the pyboard.py module.
 - examples/ -- a few example Python scripts.
 
+The subdirectories above may include READMEs with additional info.
+
 "make" is used to build the components, or "gmake" on BSD-based systems.
-You will also need bash and Python (at least 2.7 or 3.3).
+You will also need bash, gcc, and Python (at least 2.7 or 3.3).
 
 The Unix version
 ----------------
 
 The "unix" port requires a standard Unix environment with gcc and GNU make.
 x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
-as ARMv7. Porting to other architectures require writing some assembly code
-for the exception handling.
+as ARM and MIPS. Making full-featured port to another architecture requires
+writing some assembly code for the exception handling and garbage collection.
+Alternatively, fallback implementation based on setjmp/longjmp can be used.
 
-To build:
+To build (see section below for required dependencies):
 
-    $ cd unix
+    $ git submodule update --init
+    $ cd ports/unix
+    $ make axtls
     $ make
 
-Then to test it:
+Then to give it a try:
 
     $ ./micropython
     >>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
 
-Debian/Ubuntu/Mint derivative Linux distros will require build-essentials and
-libreadline-dev packages installed. To build FFI (Foreign Function Interface)
-module, libffi-dev package is required. If you have problems with some
-dependencies, they can be disabled in unix/mpconfigport.mk .
+Use `CTRL-D` (i.e. EOF) to exit the shell.
+Learn about command-line options (in particular, how to increase heap size
+which may be needed for larger applications):
 
-The STM version
----------------
+    $ ./micropython --help
 
-The "stmhal" port requires an ARM compiler, arm-none-eabi-gcc, and associated
-bin-utils.  For those using Arch Linux, you need arm-none-eabi-binutils and
-arm-none-eabi-gcc packages from the AUR.  Otherwise, try here:
+Run complete testsuite:
+
+    $ make test
+
+Unix version comes with a builtin package manager called upip, e.g.:
+
+    $ ./micropython -m upip install micropython-pystone
+    $ ./micropython -m pystone
+
+Browse available modules on
+[PyPI](https://pypi.python.org/pypi?%3Aaction=search&term=micropython).
+Standard library modules come from
+[micropython-lib](https://github.com/micropython/micropython-lib) project.
+
+External dependencies
+---------------------
+
+Building MicroPython ports may require some dependencies installed.
+
+For Unix port, `libffi` library and `pkg-config` tool are required. On
+Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`
+(includes toolchain and make), `libffi-dev`, and `pkg-config` packages.
+
+Other dependencies can be built together with MicroPython. This may
+be required to enable extra features or capabilities, and in recent
+versions of MicroPython, these may be enabled by default. To build
+these additional dependencies, first fetch git submodules for them:
+
+    $ git submodule update --init
+
+Use the same command to get the latest versions of dependencies, as
+they are updated from time to time. After that, in the port directory
+(e.g. `ports/unix/`), execute:
+
+    $ make deplibs
+
+This will build all available dependencies (regardless whether they
+are used or not). If you intend to build MicroPython with additional
+options (like cross-compiling), the same set of options should be passed
+to `make deplibs`. To actually enable/disable use of dependencies, edit
+`ports/unix/mpconfigport.mk` file, which has inline descriptions of the options.
+For example, to build SSL module (required for `upip` tool described above,
+and so enabled by dfeault), `MICROPY_PY_USSL` should be set to 1.
+
+For some ports, building required dependences is transparent, and happens
+automatically. They still need to be fetched with the git submodule command
+above.
+
+The STM32 version
+-----------------
+
+The "stm32" port requires an ARM compiler, arm-none-eabi-gcc, and associated
+bin-utils.  For those using Arch Linux, you need arm-none-eabi-binutils,
+arm-none-eabi-gcc and arm-none-eabi-newlib packages.  Otherwise, try here:
 https://launchpad.net/gcc-arm-embedded
 
 To build:
 
-    $ cd stmhal
+    $ git submodule update --init
+    $ cd ports/stm32
     $ make
 
 You then need to get your board into DFU mode.  On the pyboard, connect the
@@ -81,6 +156,19 @@ on the bottom left of the board, second row from the bottom).
 
 Then to flash the code via USB DFU to your device:
 
-    $ dfu-util -a 0 -D build/flash.dfu
+    $ make deploy
 
-You will need the dfu-util program, on Arch Linux it's dfu-util-git in the AUR.
+This will use the included `tools/pydfu.py` script.  If flashing the firmware
+does not work it may be because you don't have the correct permissions, and
+need to use `sudo make deploy`.
+See the README.md file in the ports/stm32/ directory for further details.
+
+Contributing
+------------
+
+MicroPython is an open-source project and welcomes contributions. To be
+productive, please be sure to follow the
+[Contributors' Guidelines](https://github.com/micropython/micropython/wiki/ContributorGuidelines)
+and the [Code Conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
+Note that MicroPython is licenced under the MIT license, and all contributions
+should follow this license.

bare-arm/Makefile

@@ -1,48 +0,0 @@
-include ../py/mkenv.mk
-
-# qstr definitions (must come before including py.mk)
-QSTR_DEFS = qstrdefsport.h
-
-# include py core make definitions
-include ../py/py.mk
-
-CROSS_COMPILE = arm-none-eabi-
-
-INC =  -I.
-INC += -I$(PY_SRC)
-INC += -I$(BUILD)
-
-CFLAGS_CORTEX_M4 = -mthumb -mtune=cortex-m4 -mabi=aapcs-linux -mcpu=cortex-m4 -mfpu=fpv4-sp-d16 -mfloat-abi=hard -fsingle-precision-constant -Wdouble-promotion
-CFLAGS = $(INC) -Wall -Werror -ansi -std=gnu99 $(CFLAGS_CORTEX_M4) $(COPT)
-
-#Debugging/Optimization
-ifeq ($(DEBUG), 1)
-CFLAGS += -O0 -ggdb
-else
-CFLAGS += -Os -DNDEBUG
-endif
-
-LDFLAGS = --nostdlib -T stm32f405.ld
-LIBS =
-
-SRC_C = \
-	main.c \
-#	printf.c \
-	string0.c \
-	malloc0.c \
-	gccollect.c \
-
-SRC_S = \
-#	startup_stm32f40xx.s \
-	gchelper.s \
-
-OBJ = $(PY_O) $(addprefix $(BUILD)/, $(SRC_C:.c=.o) $(SRC_S:.s=.o))
-
-all: $(BUILD)/flash.elf
-
-$(BUILD)/flash.elf: $(OBJ)
-	$(ECHO) "LINK $@"
-	$(Q)$(LD) $(LDFLAGS) -o $@ $(OBJ) $(LIBS)
-	$(Q)$(SIZE) $@
-
-include ../py/mkrules.mk

bare-arm/main.c

@@ -1,117 +0,0 @@
-#include <stdint.h>
-#include <stdio.h>
-#include <string.h>
-
-#include "mpconfig.h"
-#include "nlr.h"
-#include "misc.h"
-#include "qstr.h"
-#include "lexer.h"
-#include "parse.h"
-#include "obj.h"
-#include "parsehelper.h"
-#include "compile.h"
-#include "runtime0.h"
-#include "runtime.h"
-#include "repl.h"
-
-void do_str(const char *src) {
-    mp_lexer_t *lex = mp_lexer_new_from_str_len(MP_QSTR__lt_stdin_gt_, src, strlen(src), 0);
-    if (lex == NULL) {
-        return;
-    }
-
-    mp_parse_error_kind_t parse_error_kind;
-    mp_parse_node_t pn = mp_parse(lex, MP_PARSE_SINGLE_INPUT, &parse_error_kind);
-
-    if (pn == MP_PARSE_NODE_NULL) {
-        // parse error
-        mp_parse_show_exception(lex, parse_error_kind);
-        mp_lexer_free(lex);
-        return;
-    }
-
-    // parse okay
-    qstr source_name = mp_lexer_source_name(lex);
-    mp_lexer_free(lex);
-    mp_obj_t module_fun = mp_compile(pn, source_name, MP_EMIT_OPT_NONE, true);
-    mp_parse_node_free(pn);
-
-    if (module_fun == mp_const_none) {
-        // compile error
-        return;
-    }
-
-    nlr_buf_t nlr;
-    if (nlr_push(&nlr) == 0) {
-        mp_call_function_0(module_fun);
-        nlr_pop();
-    } else {
-        // uncaught exception
-        mp_obj_print_exception((mp_obj_t)nlr.ret_val);
-    }
-}
-
-int main(int argc, char **argv) {
-    qstr_init();
-    mp_init();
-    do_str("print('hello world!', list(x+1 for x in range(10)), end='eol\n')");
-    mp_deinit();
-    return 0;
-}
-
-void gc_collect(void) {
-}
-
-mp_lexer_t *mp_lexer_new_from_file(const char *filename) {
-    return NULL;
-}
-
-mp_import_stat_t mp_import_stat(const char *path) {
-    return MP_IMPORT_STAT_NO_EXIST;
-}
-
-mp_obj_t mp_builtin_open(uint n_args, const mp_obj_t *args) {
-    return mp_const_none;
-}
-MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_builtin_open_obj, 1, 2, mp_builtin_open);
-
-void nlr_jump_fail(void *val) {
-}
-
-/*
-int _lseek() {return 0;}
-int _read() {return 0;}
-int _write() {return 0;}
-int _close() {return 0;}
-void _exit(int x) {for(;;){}}
-int _sbrk() {return 0;}
-int _kill() {return 0;}
-int _getpid() {return 0;}
-int _fstat() {return 0;}
-int _isatty() {return 0;}
-*/
-
-void *malloc(size_t n) {return NULL;}
-void *calloc(size_t nmemb, size_t size) {return NULL;}
-void *realloc(void *ptr, size_t size) {return NULL;}
-void free(void *p) {}
-int printf(const char *m, ...) {return 0;}
-void *memcpy(void *dest, const void *src, size_t n) {return NULL;}
-int memcmp(const void *s1, const void *s2, size_t n) {return 0;}
-void *memmove(void *dest, const void *src, size_t n) {return NULL;}
-void *memset(void *s, int c, size_t n) {return NULL;}
-int strcmp(const char *s1, const char* s2) {return 0;}
-int strncmp(const char *s1, const char* s2, size_t n) {return 0;}
-size_t strlen(const char *s) {return 0;}
-char *strcat(char *dest, const char *src) {return NULL;}
-char *strchr(const char *dest, int c) {return NULL;}
-#include <stdarg.h>
-int vprintf(const char *format, va_list ap) {return 0;}
-int vsnprintf(char *str,  size_t  size,  const  char  *format, va_list ap) {return 0;}
-
-#undef putchar
-int putchar(int c) {return 0;}
-int puts(const char *s) {return 0;}
-
-void _start(void) {main(0, NULL);}

bare-arm/mpconfigport.h

@@ -1,42 +0,0 @@
-#include <stdint.h>
-
-// options to control how Micro Python is built
-
-#define MICROPY_EMIT_X64            (0)
-#define MICROPY_EMIT_THUMB          (0)
-#define MICROPY_EMIT_INLINE_THUMB   (0)
-#define MICROPY_MEM_STATS           (0)
-#define MICROPY_DEBUG_PRINTERS      (0)
-#define MICROPY_ENABLE_GC           (0)
-#define MICROPY_ENABLE_REPL_HELPERS (0)
-#define MICROPY_ENABLE_LEXER_UNIX   (0)
-#define MICROPY_ENABLE_SOURCE_LINE  (0)
-#define MICROPY_ENABLE_MOD_COLLECTIONS (0)
-#define MICROPY_ENABLE_MOD_MATH     (0)
-#define MICROPY_ENABLE_MOD_CMATH    (0)
-#define MICROPY_ENABLE_MOD_IO       (0)
-#define MICROPY_ENABLE_MOD_STRUCT   (0)
-#define MICROPY_ENABLE_MOD_SYS      (0)
-#define MICROPY_ENABLE_PROPERTY     (0)
-#define MICROPY_CPYTHON_COMPAT      (0)
-#define MICROPY_LONGINT_IMPL        (MICROPY_LONGINT_IMPL_NONE)
-#define MICROPY_FLOAT_IMPL          (MICROPY_FLOAT_IMPL_NONE)
-#define MICROPY_PATH_MAX            (512)
-
-// type definitions for the specific machine
-
-#define BYTES_PER_WORD (4)
-
-#define UINT_FMT "%lu"
-#define INT_FMT "%ld"
-
-typedef int32_t machine_int_t; // must be pointer size
-typedef uint32_t machine_uint_t; // must be pointer size
-typedef void *machine_ptr_t; // must be of pointer size
-typedef const void *machine_const_ptr_t; // must be of pointer size
-
-// extra built in names to add to the global namespace
-extern const struct _mp_obj_fun_native_t mp_builtin_open_obj;
-#define MICROPY_EXTRA_BUILTINS \
-    { MP_OBJ_NEW_QSTR(MP_QSTR_open), (mp_obj_t)&mp_builtin_open_obj },
-

bare-arm/stm32f405.ld

@@ -1,117 +0,0 @@
-/*
-    GNU linker script for STM32F405
-*/
-
-/* Specify the memory areas */
-MEMORY
-{
-    FLASH (rx)      : ORIGIN = 0x08000000, LENGTH = 0x100000 /* entire flash, 1 MiB */
-    FLASH_ISR (rx)  : ORIGIN = 0x08000000, LENGTH = 0x004000 /* sector 0, 16 KiB */
-    FLASH_TEXT (rx) : ORIGIN = 0x08020000, LENGTH = 0x080000 /* sectors 5,6,7,8, 4*128KiB = 512 KiB (could increase it more) */
-    CCMRAM (xrw)    : ORIGIN = 0x10000000, LENGTH = 0x010000 /* 64 KiB */
-    RAM (xrw)       : ORIGIN = 0x20000000, LENGTH = 0x020000 /* 128 KiB */
-}
- 
-/* top end of the stack */
-_estack = ORIGIN(RAM) + LENGTH(RAM);
-
-/* RAM extents for the garbage collector */
-_ram_end = ORIGIN(RAM) + LENGTH(RAM);
-_heap_end = 0x2001c000; /* tunable */
-
-/* define output sections */
-SECTIONS
-{
-    /* The startup code goes first into FLASH */
-    .isr_vector :
-    {
-        . = ALIGN(4);
-        KEEP(*(.isr_vector)) /* Startup code */
-
-        . = ALIGN(4);
-    } >FLASH_ISR
-   
-    /* The program code and other data goes into FLASH */
-    .text :
-    {
-        . = ALIGN(4);
-        *(.text)           /* .text sections (code) */
-        *(.text*)          /* .text* sections (code) */
-        *(.rodata)         /* .rodata sections (constants, strings, etc.) */
-        *(.rodata*)        /* .rodata* sections (constants, strings, etc.) */
-    /*  *(.glue_7)   */    /* glue arm to thumb code */
-    /*  *(.glue_7t)  */    /* glue thumb to arm code */
-
-        . = ALIGN(4);
-        _etext = .;        /* define a global symbol at end of code */
-        _sidata = _etext;  /* This is used by the startup in order to initialize the .data secion */
-    } >FLASH_TEXT
-     
-    /*
-    .ARM.extab :
-    {
-        *(.ARM.extab* .gnu.linkonce.armextab.*)
-    } >FLASH
-
-    .ARM :
-    {
-        __exidx_start = .;
-        *(.ARM.exidx*)
-        __exidx_end = .;
-    } >FLASH
-    */
-        
-    /* This is the initialized data section
-    The program executes knowing that the data is in the RAM
-    but the loader puts the initial values in the FLASH (inidata).
-    It is one task of the startup to copy the initial values from FLASH to RAM. */
-    .data : AT ( _sidata )
-    {
-        . = ALIGN(4);
-        _sdata = .;        /* create a global symbol at data start; used by startup code in order to initialise the .data section in RAM */
-        _ram_start = .;    /* create a global symbol at ram start for garbage collector */
-        *(.data)           /* .data sections */
-        *(.data*)          /* .data* sections */
-
-        . = ALIGN(4);
-        _edata = .;        /* define a global symbol at data end; used by startup code in order to initialise the .data section in RAM */
-    } >RAM
-            
-    /* Uninitialized data section */
-    .bss :
-    {
-        . = ALIGN(4);
-        _sbss = .;         /* define a global symbol at bss start; used by startup code */
-        *(.bss)
-        *(.bss*)
-        *(COMMON)
-
-        . = ALIGN(4);
-        _ebss = .;         /* define a global symbol at bss end; used by startup code */
-    } >RAM
-
-    /* this is to define the start of the heap, and make sure we have a minimum size */
-    .heap :
-    {
-        . = ALIGN(4);
-        _heap_start = .;    /* define a global symbol at heap start */
-    } >RAM
-
-    /* this just checks there is enough RAM for the stack */
-    .stack :
-    {
-        . = ALIGN(4);
-    } >RAM
-
-    /* Remove information from the standard libraries */
-    /*
-    /DISCARD/ :
-    {
-        libc.a ( * )
-        libm.a ( * )
-        libgcc.a ( * )
-    }
-    */
-
-    .ARM.attributes 0 : { *(.ARM.attributes) }
-}

docs/Makefile

@@ -0,0 +1,191 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+PYTHON        = python3
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build/$(MICROPY_PORT)
+CPYDIFFDIR    = ../tools
+CPYDIFF       = gen-cpydiff.py
+GENRSTDIR     = genrst
+# Run "make FORCE= ..." to avoid rebuilding from scratch (and risk
+# producing incorrect docs).
+FORCE         = -E
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  cpydiff    to generate the MicroPython differences from CPython"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -f $(GENRSTDIR)/*
+
+cpydiff:
+	@echo "Generating MicroPython Differences."
+	rm -f $(GENRSTDIR)/*
+	cd $(CPYDIFFDIR) && $(PYTHON) $(CPYDIFF)
+
+html: cpydiff
+	$(SPHINXBUILD) $(FORCE) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MicroPython.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MicroPython.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/MicroPython"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MicroPython"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex: cpydiff
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf: cpydiff
+	$(SPHINXBUILD) $(FORCE) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja: cpydiff
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/README.md

@@ -0,0 +1,40 @@
+MicroPython Documentation
+=========================
+
+The MicroPython documentation can be found at:
+http://docs.micropython.org/en/latest/
+
+The documentation you see there is generated from the files in the docs tree:
+https://github.com/micropython/micropython/tree/master/docs
+
+Building the documentation locally
+----------------------------------
+
+If you're making changes to the documentation, you may want to build the
+documentation locally so that you can preview your changes.
+
+Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme,
+preferably in a virtualenv:
+
+     pip install sphinx
+     pip install sphinx_rtd_theme
+
+In `micropython/docs`, build the docs:
+
+    make MICROPY_PORT=<port_name> html
+
+Where `<port_name>` can be `unix`, `pyboard`, `wipy` or `esp8266`.
+
+You'll find the index page at `micropython/docs/build/<port_name>/html/index.html`.
+
+PDF manual generation
+---------------------
+
+This can be achieved with:
+
+    make MICROPY_PORT=<port_name> latexpdf
+
+but require rather complete install of LaTeX with various extensions. On
+Debian/Ubuntu, try (500MB+ download):
+
+    apt-get install texlive-latex-recommended texlive-latex-extra

docs/conf.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# MicroPython documentation build configuration file, created by
+# sphinx-quickstart on Sun Sep 21 11:42:03 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('.'))
+
+# Work out the port to generate the docs for
+from collections import OrderedDict
+micropy_port = os.getenv('MICROPY_PORT') or 'pyboard'
+tags.add('port_' + micropy_port)
+ports = OrderedDict((
+    ('unix', 'unix'),
+    ('pyboard', 'the pyboard'),
+    ('wipy', 'the WiPy'),
+    ('esp8266', 'the ESP8266'),
+))
+
+# The members of the html_context dict are available inside topindex.html
+micropy_version = os.getenv('MICROPY_VERSION') or 'latest'
+micropy_all_versions = (os.getenv('MICROPY_ALL_VERSIONS') or 'latest').split(',')
+url_pattern = '%s/en/%%s/%%s' % (os.getenv('MICROPY_URL_PREFIX') or '/',)
+html_context = {
+    'port':micropy_port,
+    'port_name':ports[micropy_port],
+    'port_version':micropy_version,
+    'all_ports':[
+        (port_id, url_pattern % (micropy_version, port_id))
+            for port_id, port_name in ports.items()
+    ],
+    'all_versions':[
+        (ver, url_pattern % (ver, micropy_port))
+            for ver in micropy_all_versions
+    ],
+    'downloads':[
+        ('PDF', url_pattern % (micropy_version, 'micropython-%s.pdf' % micropy_port)),
+    ],
+}
+
+
+# Specify a custom master document based on the port name
+master_doc = micropy_port + '_' + 'index'
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx_selective_exclude.modindex_exclude',
+    'sphinx_selective_exclude.eager_only',
+    'sphinx_selective_exclude.search_auto_exclude',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+#master_doc = 'index'
+
+# General information about the project.
+project = 'MicroPython'
+copyright = '2014-2017, Damien P. George, Paul Sokolovsky, and contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
+# breakdown, so use the same version identifier for both to avoid confusion.
+version = release = '1.9.3'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['build', '.venv']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+default_role = 'any'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# Global include files. Sphinx docs suggest using rst_epilog in preference
+# of rst_prolog, so we follow. Absolute paths below mean "from the base
+# of the doctree".
+rst_epilog = """
+.. include:: /templates/replace.inc
+"""
+
+# -- Options for HTML output ----------------------------------------------
+
+# on_rtd is whether we are on readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    try:
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
+    except:
+        html_theme = 'default'
+        html_theme_path = ['.']
+else:
+    html_theme_path = ['.']
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = ['.']
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = '../../logo/trans-logo.png'
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = 'favicon.ico'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%d %b %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+html_additional_pages = {"index": "topindex.html"}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'MicroPythondoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+# Include 3 levels of headers in PDF ToC
+'preamble': '\setcounter{tocdepth}{2}',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  (master_doc, 'MicroPython.tex', 'MicroPython Documentation',
+   'Damien P. George, Paul Sokolovsky, and contributors', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'micropython', 'MicroPython Documentation',
+     ['Damien P. George, Paul Sokolovsky, and contributors'], 1),
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  (master_doc, 'MicroPython', 'MicroPython Documentation',
+   'Damien P. George, Paul Sokolovsky, and contributors', 'MicroPython', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'python': ('http://docs.python.org/3', None)}
+
+# Append the other ports' specific folders/files to the exclude pattern
+exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
+
+modules_port_specific = {
+    'pyboard': ['pyb'],
+    'wipy': ['wipy'],
+    'esp8266': ['esp'],
+}
+
+modindex_exclude = []
+
+for p, l in modules_port_specific.items():
+    if p != micropy_port:
+        modindex_exclude += l
+
+# Exclude extra modules per port
+modindex_exclude += {
+    'esp8266': ['cmath', 'select'],
+    'wipy': ['cmath'],
+}.get(micropy_port, [])

docs/differences/index_template.txt

@@ -0,0 +1,10 @@
+.. _cpython_diffs:
+
+MicroPython differences from CPython
+====================================
+
+The operations listed in this section produce conflicting results in MicroPython when compared to standard Python.
+
+.. toctree::
+    :maxdepth: 2
+

docs/esp8266/general.rst

@@ -0,0 +1,187 @@
+General information about the ESP8266 port
+==========================================
+
+ESP8266 is a popular WiFi-enabled System-on-Chip (SoC) by Espressif Systems.
+
+Multitude of boards
+-------------------
+
+There are a multitude of modules and boards from different sources which carry
+the ESP8266 chip. MicroPython tries to provide a generic port which would run on
+as many boards/modules as possible, but there may be limitations. Adafruit
+Feather HUZZAH board is taken as a reference board for the port (for example,
+testing is performed on it). If you have another board, please make sure you
+have datasheet, schematics and other reference materials for your board
+handy to look up various aspects of your board functioning.
+
+To make a generic ESP8266 port and support as many boards as possible,
+following design and implementation decision were made:
+
+* GPIO pin numbering is based on ESP8266 chip numbering, not some "logical"
+  numbering of a particular board. Please have the manual/pin diagram of your board
+  at hand to find correspondence between your board pins and actual ESP8266 pins.
+  We also encourage users of various boards to share this mapping via MicroPython
+  forum, with the idea to collect community-maintained reference materials
+  eventually.
+* All pins which make sense to support, are supported by MicroPython
+  (for example, pins which are used to connect SPI flash
+  are not exposed, as they're unlikely useful for anything else, and
+  operating on them will lead to board lock-up). However, any particular
+  board may expose only subset of pins. Consult your board reference manual.
+* Some boards may lack external pins/internal connectivity to support
+  ESP8266 deepsleep mode.
+
+
+Technical specifications and SoC datasheets
+-------------------------------------------
+
+The datasheets and other reference material for ESP8266 chip are available
+from the vendor site: http://bbs.espressif.com/viewtopic.php?f=67&t=225 .
+They are the primary reference for the chip technical specifications, capabilities,
+operating modes, internal functioning, etc.
+
+For your convenience, some of technical specifications are provided below:
+
+* Architecture: Xtensa lx106
+* CPU frequency: 80MHz overclockable to 160MHz
+* Total RAM available: 96KB (part of it reserved for system)
+* BootROM: 64KB
+* Internal FlashROM: None
+* External FlashROM: code and data, via SPI Flash. Normal sizes 512KB-4MB.
+* GPIO: 16 + 1 (GPIOs are multiplexed with other functions, including
+  external FlashROM, UART, deep sleep wake-up, etc.)
+* UART: One RX/TX UART (no hardware handshaking), one TX-only UART.
+* SPI: 2 SPI interfaces (one used for FlashROM).
+* I2C: No native external I2C (bitbang implementation available on any pins).
+* I2S: 1.
+* Programming: using BootROM bootloader from UART. Due to external FlashROM
+  and always-available BootROM bootloader, ESP8266 is not brickable.
+
+
+Scarcity of runtime resources
+-----------------------------
+
+ESP8266 has very modest resources (first of all, RAM memory). So, please
+avoid allocating too big container objects (lists, dictionaries) and
+buffers. There is also no full-fledged OS to keep track of resources
+and automatically clean them up, so that's the task of a user/user
+application: please be sure to close open files, sockets, etc. as soon
+as possible after use.
+
+
+Boot process
+------------
+
+On boot, MicroPython EPS8266 port executes ``_boot.py`` script from internal
+frozen modules. It mounts filesystem in FlashROM, or if it's not available,
+performs first-time setup of the module and creates the filesystem. This
+part of the boot process is considered fixed, and not available for customization
+for end users (even if you build from source, please refrain from changes to
+it; customization of early boot process is available only to advanced users
+and developers, who can diagnose themselves any issues arising from
+modifying the standard process).
+
+Once the filesystem is mounted, ``boot.py`` is executed from it. The standard
+version of this file is created during first-time module set up and has
+commands to start a WebREPL daemon (disabled by default, configurable
+with ``webrepl_setup`` module), etc. This
+file is customizable by end users (for example, you may want to set some
+parameters or add other services which should be run on
+a module start-up). But keep in mind that incorrect modifications to boot.py
+may still lead to boot loops or lock ups, requiring to reflash a module
+from scratch. (In particular, it's recommended that you use either
+``webrepl_setup`` module or manual editing to configure WebREPL, but not
+both).
+
+As a final step of boot procedure, ``main.py`` is executed from filesystem,
+if exists. This file is a hook to start up a user application each time
+on boot (instead of going to REPL). For small test applications, you may
+name them directly as ``main.py``, and upload to module, but instead it's
+recommended to keep your application(s) in separate files, and have just
+the following in ``main.py``::
+
+    import my_app
+    my_app.main()
+
+This will allow to keep the structure of your application clear, as well as
+allow to install multiple applications on a board, and switch among them.
+
+
+Known Issues
+------------
+
+Real-time clock
+~~~~~~~~~~~~~~~
+
+RTC in ESP8266 has very bad accuracy, drift may be seconds per minute. As
+a workaround, to measure short enough intervals you can use
+``utime.time()``, etc. functions, and for wall clock time, synchronize from
+the net using included ``ntptime.py`` module.
+
+Due to limitations of the ESP8266 chip the internal real-time clock (RTC)
+will overflow every 7:45h.  If a long-term working RTC time is required then
+``time()`` or ``localtime()`` must be called at least once within 7 hours.
+MicroPython will then handle the overflow.
+
+Sockets and WiFi buffers overflow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Socket instances remain active until they are explicitly closed. This has two
+consequences. Firstly they occupy RAM, so an application which opens sockets
+without closing them may eventually run out of memory. Secondly not properly
+closed socket can cause the low-level part of the vendor WiFi stack to emit
+``Lmac`` errors. This occurs if data comes in for a socket and is not
+processed in a timely manner. This can overflow the WiFi stack input queue
+and lead to a deadlock. The only recovery is by a hard reset.
+
+The above may also happen after an application terminates and quits to the REPL
+for any reason including an exception. Subsequent arrival of data provokes the
+failure with the above error message repeatedly issued. So, sockets should be
+closed in any case, regardless whether an application terminates successfully
+or by an exeption, for example using try/finally::
+
+    sock = socket(...)
+    try:
+        # Use sock
+    finally:
+        sock.close()
+
+
+SSL/TLS limitations
+~~~~~~~~~~~~~~~~~~~
+
+ESP8266 uses `axTLS <http://axtls.sourceforge.net/>`_ library, which is one
+of the smallest TLS libraries with the compatible licensing. However, it
+also has some known issues/limitations:
+
+1. No support for Diffie-Hellman (DH) key exchange and Elliptic-curve
+   cryptography (ECC). This means it can't work with sites which force
+   the use of these features (it works ok with classic RSA certifactes).
+2. Half-duplex communication nature. axTLS uses a single buffer for both
+   sending and receiving, which leads to considerable memory saving and
+   works well with protocols like HTTP. But there may be problems with
+   protocols which don't follow classic request-response model.
+
+Besides axTLS own limitations, the configuration used for MicroPython is
+highly optimized for code size, which leads to additional limitations
+(these may be lifted in the future):
+
+3. Optimized RSA algorithms are not enabled, which may lead to slow
+   SSL handshakes.
+4. Stored sessions are not supported (may allow faster repeated connections
+   to the same site in some circumstances).
+
+Besides axTLS specific limitations described above, there's another generic
+limitation with usage of TLS on the low-memory devices:
+
+5. The TLS standard specifies the maximum length of the TLS record (unit
+   of TLS communication, the entire record must be buffered before it can
+   be processed) as 16KB. That's almost half of the available ESP8266 memory,
+   and inside a more or less advanced application would be hard to allocate
+   due to memory fragmentation issues. As a compromise, a smaller buffer is
+   used, with the idea that the most interesting usage for SSL would be
+   accessing various REST APIs, which usually require much smaller messages.
+   The buffers size is on the order of 5KB, and is adjusted from time to
+   time, taking as a reference being able to access https://google.com .
+   The smaller buffer hower means that some sites can't be accessed using
+   it, and it's not possible to stream large amounts of data.

docs/esp8266/quickref.rst

@@ -0,0 +1,375 @@
+.. _quickref:
+
+Quick reference for the ESP8266
+===============================
+
+.. image:: img/adafruit_products_pinoutstop.jpg
+    :alt: Adafruit Feather HUZZAH board
+    :width: 640px
+
+The Adafruit Feather HUZZAH board (image attribution: Adafruit).
+
+Installing MicroPython
+----------------------
+
+See the corresponding section of tutorial: :ref:`intro`. It also includes
+a troubleshooting subsection.
+
+General board control
+---------------------
+
+The MicroPython REPL is on UART0 (GPIO1=TX, GPIO3=RX) at baudrate 115200.
+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 :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 :mod:`esp` module::
+
+    import esp
+
+    esp.osdebug(None)       # turn off vendor O/S debugging messages
+    esp.osdebug(0)          # redirect vendor O/S debugging messages to UART(0)
+
+Networking
+----------
+
+The :mod:`network` module::
+
+    import network
+
+    wlan = network.WLAN(network.STA_IF) # create station interface
+    wlan.active(True)       # activate the interface
+    wlan.scan()             # scan for access points
+    wlan.isconnected()      # check if the station is connected to an AP
+    wlan.connect('essid', 'password') # connect to an AP
+    wlan.config('mac')      # get the interface's MAC adddress
+    wlan.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
+
+    ap = network.WLAN(network.AP_IF) # create access-point interface
+    ap.active(True)         # activate the interface
+    ap.config(essid='ESP-AP') # set the ESSID of the access point
+
+A useful function for connecting to your local WiFi network is::
+
+    def do_connect():
+        import network
+        wlan = network.WLAN(network.STA_IF)
+        wlan.active(True)
+        if not wlan.isconnected():
+            print('connecting to network...')
+            wlan.connect('essid', 'password')
+            while not wlan.isconnected():
+                pass
+        print('network config:', wlan.ifconfig())
+
+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 :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 millisecond counter
+    delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference
+
+Timers
+------
+
+Virtual (RTOS-based) timers are supported. Use the :ref:`machine.Timer <machine.Timer>` class
+with timer ID of -1::
+
+    from machine import Timer
+
+    tim = Timer(-1)
+    tim.init(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(1))
+    tim.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(2))
+
+The period is in milliseconds.
+
+Pins and GPIO
+-------------
+
+Use the :ref:`machine.Pin <machine.Pin>` class::
+
+    from machine import Pin
+
+    p0 = Pin(0, Pin.OUT)    # create output pin on GPIO0
+    p0.on()                 # set pin to "on" (high) level
+    p0.off()                # set pin to "off" (low) level
+    p0.value(1)             # set pin to on/high
+
+    p2 = Pin(2, Pin.IN)     # create input pin on GPIO2
+    print(p2.value())       # get value, 0 or 1
+
+    p4 = Pin(4, Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
+    p5 = Pin(5, Pin.OUT, value=1) # set pin high on creation
+
+Available pins are: 0, 1, 2, 3, 4, 5, 12, 13, 14, 15, 16, which correspond
+to the actual GPIO pin numbers of ESP8266 chip. Note that many end-user
+boards use their own adhoc pin numbering (marked e.g. D0, D1, ...). As
+MicroPython supports different boards and modules, physical pin numbering
+was chosen as the lowest common denominator. For mapping between board
+logical pins and physical chip pins, consult your board documentation.
+
+Note that Pin(1) and Pin(3) are REPL UART TX and RX respectively.
+Also note that Pin(16) is a special pin (used for wakeup from deepsleep
+mode) and may be not available for use with higher-level classes like
+``Neopixel``.
+
+PWM (pulse width modulation)
+----------------------------
+
+PWM can be enabled on all pins except Pin(16).  There is a single frequency
+for all channels, with range between 1 and 1000 (measured in Hz).  The duty
+cycle is between 0 and 1023 inclusive.
+
+Use the ``machine.PWM`` class::
+
+    from machine import Pin, PWM
+
+    pwm0 = PWM(Pin(0))      # create PWM object from a pin
+    pwm0.freq()             # get current frequency
+    pwm0.freq(1000)         # set frequency
+    pwm0.duty()             # get current duty cycle
+    pwm0.duty(200)          # set duty cycle
+    pwm0.deinit()           # turn off PWM on the pin
+
+    pwm2 = PWM(Pin(2), freq=500, duty=512) # create and configure in one go
+
+ADC (analog to digital conversion)
+----------------------------------
+
+ADC is available on a dedicated pin.
+Note that input voltages on the ADC pin must be between 0v and 1.0v.
+
+Use the :ref:`machine.ADC <machine.ADC>` class::
+
+    from machine import ADC
+
+    adc = ADC(0)            # create ADC object on ADC pin
+    adc.read()              # read value, 0-1024
+
+Software SPI bus
+----------------
+
+There are two SPI drivers. One is implemented in software (bit-banging)
+and works on all pins, and is accessed via the :ref:`machine.SPI <machine.SPI>`
+class::
+
+    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(-1, baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
+
+    spi.init(baudrate=200000) # set the baudrate
+
+    spi.read(10)            # read 10 bytes on MISO
+    spi.read(10, 0xff)      # read 10 bytes while outputing 0xff on MOSI
+
+    buf = bytearray(50)     # create a buffer
+    spi.readinto(buf)       # read into the given buffer (reads 50 bytes in this case)
+    spi.readinto(buf, 0xff) # read into the given buffer and output 0xff on MOSI
+
+    spi.write(b'12345')     # write 5 bytes on MOSI
+
+    buf = bytearray(4)      # create a buffer
+    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
+-------
+
+The I2C driver is implemented in software and works on all pins,
+and is accessed via the :ref:`machine.I2C <machine.I2C>` class::
+
+    from machine import Pin, I2C
+
+    # construct an I2C bus
+    i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
+
+    i2c.readfrom(0x3a, 4)   # read 4 bytes from slave device with address 0x3a
+    i2c.writeto(0x3a, '12') # write '12' to slave device with address 0x3a
+
+    buf = bytearray(10)     # create a buffer with 10 bytes
+    i2c.writeto(0x3a, buf)  # write the given buffer to the slave
+
+Real time clock (RTC)
+---------------------
+
+See :ref:`machine.RTC <machine.RTC>` ::
+
+    from machine import RTC
+
+    rtc = RTC()
+    rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time
+    rtc.datetime() # get date and time
+
+Deep-sleep mode
+---------------
+
+Connect GPIO16 to the reset pin (RST on HUZZAH).  Then the following code
+can be used to sleep, wake and check the reset cause::
+
+    import machine
+
+    # configure RTC.ALARM0 to be able to wake the device
+    rtc = machine.RTC()
+    rtc.irq(trigger=rtc.ALARM0, wake=machine.DEEPSLEEP)
+
+    # check if the device woke from a deep sleep
+    if machine.reset_cause() == machine.DEEPSLEEP_RESET:
+        print('woke from a deep sleep')
+
+    # set RTC.ALARM0 to fire after 10 seconds (waking the device)
+    rtc.alarm(rtc.ALARM0, 10000)
+
+    # put the device to sleep
+    machine.deepsleep()
+
+OneWire driver
+--------------
+
+The OneWire driver is implemented in software and works on all pins::
+
+    from machine import Pin
+    import onewire
+
+    ow = onewire.OneWire(Pin(12)) # create a OneWire bus on GPIO12
+    ow.scan()               # return a list of devices on the bus
+    ow.reset()              # reset the bus
+    ow.readbyte()           # read a byte
+    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 DS18S20 and DS18B20 devices::
+
+    import time, ds18x20
+    ds = ds18x20.DS18X20(ow)
+    roms = ds.scan()
+    ds.convert_temp()
+    time.sleep_ms(750)
+    for rom in roms:
+        print(ds.read_temp(rom))
+
+Be sure to put a 4.7k pull-up resistor on the data line.  Note that
+the ``convert_temp()`` method must be called each time you want to
+sample the temperature.
+
+NeoPixel driver
+---------------
+
+Use the ``neopixel`` module::
+
+    from machine import Pin
+    from neopixel import NeoPixel
+
+    pin = Pin(0, Pin.OUT)   # set GPIO0 to output to drive NeoPixels
+    np = NeoPixel(pin, 8)   # create NeoPixel driver on GPIO0 for 8 pixels
+    np[0] = (255, 255, 255) # set the first pixel to white
+    np.write()              # write data to all pixels
+    r, g, b = np[0]         # get first pixel colour
+
+For low-level driving of a NeoPixel::
+
+    import esp
+    esp.neopixel_write(pin, grb_buf, is800khz)
+
+APA102 driver
+-------------
+
+Use the ``apa102`` module::
+
+    from machine import Pin
+    from apa102 import APA102
+
+    clock = Pin(14, Pin.OUT)     # set GPIO14 to output to drive the clock
+    data = Pin(13, Pin.OUT)      # set GPIO13 to output to drive the data
+    apa = APA102(clock, data, 8) # create APA102 driver on the clock and the data pin for 8 pixels
+    apa[0] = (255, 255, 255, 31) # set the first pixel to white with a maximum brightness of 31
+    apa.write()                  # write data to all pixels
+    r, g, b, brightness = apa[0] # get first pixel colour
+
+For low-level driving of an APA102::
+
+    import esp
+    esp.apa102_write(clock_pin, data_pin, rgbi_buf)
+
+DHT driver
+----------
+
+The DHT driver is implemented in software and works on all pins::
+
+    import dht
+    import machine
+
+    d = dht.DHT11(machine.Pin(4))
+    d.measure()
+    d.temperature() # eg. 23 (°C)
+    d.humidity()    # eg. 41 (% RH)
+
+    d = dht.DHT22(machine.Pin(4))
+    d.measure()
+    d.temperature() # eg. 23.6 (°C)
+    d.humidity()    # eg. 41.3 (% RH)
+
+WebREPL (web browser interactive prompt)
+----------------------------------------
+
+WebREPL (REPL over WebSockets, accessible via a web browser) is an
+experimental feature available in ESP8266 port. Download web client
+from https://github.com/micropython/webrepl (hosted version available
+at http://micropython.org/webrepl), and configure it by executing::
+
+    import webrepl_setup
+
+and following on-screen instructions. After reboot, it will be available
+for connection. If you disabled automatic start-up on boot, you may
+run configured daemon on demand using::
+
+    import webrepl
+    webrepl.start()
+
+The supported way to use WebREPL is by connecting to ESP8266 access point,
+but the daemon is also started on STA interface if it is active, so if your
+router is set up and works correctly, you may also use WebREPL while connected
+to your normal Internet access point (use the ESP8266 AP connection method
+if you face any issues).
+
+Besides terminal/command prompt access, WebREPL also has provision for file
+transfer (both upload and download). Web client has buttons for the
+corresponding functions, or you can use command-line client ``webrepl_cli.py``
+from the repository above.
+
+See the MicroPython forum for other community-supported alternatives
+to transfer files to ESP8266.

docs/esp8266/tutorial/adc.rst

@@ -0,0 +1,19 @@
+Analog to Digital Conversion
+============================
+
+The ESP8266 has a single pin (separate to the GPIO pins) which can be used to
+read analog voltages and convert them to a digital value.  You can construct
+such an ADC pin object using::
+
+    >>> import machine
+    >>> adc = machine.ADC(0)
+
+Then read its value with::
+
+    >>> adc.read()
+    58
+
+The values returned from the ``read()`` function are between 0 (for 0.0 volts)
+and 1024 (for 1.0 volts).  Please note that this input can only tolerate a
+maximum of 1.0 volts and you must use a voltage divider circuit to measure
+larger voltages.

docs/esp8266/tutorial/dht.rst

@@ -0,0 +1,65 @@
+Temperature and Humidity
+========================
+
+DHT (Digital Humidity & Temperature) sensors are low cost digital sensors with
+capacitive humidity sensors and thermistors to measure the surrounding air.
+They feature a chip that handles analog to digital conversion and provide a
+1-wire interface. Newer sensors additionally provide an I2C interface.
+
+The DHT11 (blue) and DHT22 (white) sensors provide the same 1-wire interface,
+however, the DHT22 requires a separate object as it has more complex
+calculation. DHT22 have 1 decimal place resolution for both humidity and
+temperature readings. DHT11 have whole number for both.
+
+A custom 1-wire protocol, which is different to Dallas 1-wire, is used to get
+the measurements from the sensor. The payload consists of a humidity value,
+a temperature value and a checksum.
+
+To use the 1-wire interface, construct the objects referring to their data pin::
+
+    >>> import dht
+    >>> import machine
+    >>> d = dht.DHT11(machine.Pin(4))
+
+    >>> import dht
+    >>> import machine
+    >>> d = dht.DHT22(machine.Pin(4))
+
+Then measure and read their values with::
+
+    >>> d.measure()
+    >>> d.temperature()
+    >>> d.humidity()
+
+Values returned from ``temperature()`` are in degrees Celsius and values
+returned from ``humidity()`` are a percentage of relative humidity.
+
+The DHT11 can be called no more than once per second and the DHT22 once every
+two seconds for most accurate results. Sensor accuracy will degrade over time.
+Each sensor supports a different operating range. Refer to the product
+datasheets for specifics.
+
+In 1-wire mode, only three of the four pins are used and in I2C mode, all four
+pins are used. Older sensors may still have 4 pins even though they do not
+support I2C. The 3rd pin is simply not connected.
+
+Pin configurations:
+
+Sensor without I2C in 1-wire mode (eg. DHT11, DHT22, AM2301, AM2302):
+
+    1=VDD, 2=Data, 3=NC, 4=GND
+
+Sensor with I2C in 1-wire mode (eg. DHT12, AM2320, AM2321, AM2322):
+
+    1=VDD, 2=Data, 3=GND, 4=GND
+
+Sensor with I2C in I2C mode (eg. DHT12, AM2320, AM2321, AM2322):
+
+    1=VDD, 2=SDA, 3=GND, 4=SCL
+
+You should use pull-up resistors for the Data, SDA and SCL pins.
+
+To make newer I2C sensors work in backwards compatible 1-wire mode, you must
+connect both pins 3 and 4 to GND. This disables the I2C interface.
+
+DHT22 sensors are now sold under the name AM2302 and are otherwise identical.

docs/esp8266/tutorial/filesystem.rst

@@ -0,0 +1,69 @@
+The internal filesystem
+=======================
+
+If your devices has 1Mbyte or more of storage then it will be set up (upon first
+boot) to contain a filesystem.  This filesystem uses the FAT format and is
+stored in the flash after the MicroPython firmware.
+
+Creating and reading files
+--------------------------
+
+MicroPython on the ESP8266 supports the standard way of accessing files in
+Python, using the built-in ``open()`` function.
+
+To create a file try::
+
+    >>> f = open('data.txt', 'w')
+    >>> f.write('some data')
+    9
+    >>> f.close()
+
+The "9" is the number of bytes that were written with the ``write()`` method.
+Then you can read back the contents of this new file using::
+
+    >>> f = open('data.txt')
+    >>> f.read()
+    'some data'
+    >>> f.close()
+
+Note that the default mode when opening a file is to open it in read-only mode,
+and as a text file.  Specify ``'wb'`` as the second argument to ``open()`` to
+open for writing in binary mode, and ``'rb'`` to open for reading in binary
+mode.
+
+Listing file and more
+---------------------
+
+The os module can be used for further control over the filesystem.  First
+import the module::
+
+    >>> import os
+
+Then try listing the contents of the filesystem::
+
+    >>> os.listdir()
+    ['boot.py', 'port_config.py', 'data.txt']
+
+You can make directories::
+
+    >>> os.mkdir('dir')
+
+And remove entries::
+
+    >>> os.remove('data.txt')
+
+Start up scripts
+----------------
+
+There are two files that are treated specially by the ESP8266 when it starts up:
+boot.py and main.py.  The boot.py script is executed first (if it exists) and
+then once it completes the main.py script is executed.  You can create these
+files yourself and populate them with the code that you want to run when the
+device starts up.
+
+Accessing the filesystem via WebREPL
+------------------------------------
+
+You can access the filesystem over WebREPL using the web client in a browser
+or via the command-line tool. Please refer to Quick Reference and Tutorial
+sections for more information about WebREPL.

docs/esp8266/tutorial/index.rst

@@ -0,0 +1,33 @@
+.. _tutorial-index:
+
+MicroPython tutorial for ESP8266
+================================
+
+This tutorial is intended to get you started using MicroPython on the ESP8266
+system-on-a-chip.  If it is your first time it is recommended to follow the
+tutorial through in the order below.  Otherwise the sections are mostly self
+contained, so feel free to skip to those that interest you.
+
+The tutorial does not assume that you know Python, but it also does not attempt
+to explain any of the details of the Python language.  Instead it provides you
+with commands that are ready to run, and hopes that you will gain a bit of
+Python knowledge along the way.  To learn more about Python itself please refer
+to `<https://www.python.org>`__.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   repl.rst
+   filesystem.rst
+   network_basics.rst
+   network_tcp.rst
+   pins.rst
+   pwm.rst
+   adc.rst
+   powerctrl.rst
+   onewire.rst
+   neopixel.rst
+   dht.rst
+   nextsteps.rst

docs/esp8266/tutorial/intro.rst

@@ -0,0 +1,202 @@
+.. _intro:
+
+Getting started with MicroPython on the ESP8266
+===============================================
+
+Using MicroPython is a great way to get the most of your ESP8266 board.  And
+vice versa, the ESP8266 chip is a great platform for using MicroPython.  This
+tutorial will guide you through setting up MicroPython, getting a prompt, using
+WebREPL, connecting to the network and communicating with the Internet, using
+the hardware peripherals, and controlling some external components.
+
+Let's get started!
+
+Requirements
+------------
+
+The first thing you need is a board with an ESP8266 chip.  The MicroPython
+software supports the ESP8266 chip itself and any board should work.  The main
+characteristic of a board is how much flash it has, how the GPIO pins are
+connected to the outside world, and whether it includes a built-in USB-serial
+convertor to make the UART available to your PC.
+
+The minimum requirement for flash size is 1Mbyte. There is also a special
+build for boards with 512KB, but it is highly limited comparing to the
+normal build: there is no support for filesystem, and thus features which
+depend on it won't work (WebREPL, upip, etc.). As such, 512KB build will
+be more interesting for users who build from source and fine-tune parameters
+for their particular application.
+
+Names of pins will be given in this tutorial using the chip names (eg GPIO0)
+and it should be straightforward to find which pin this corresponds to on your
+particular board.
+
+Powering the board
+------------------
+
+If your board has a USB connector on it then most likely it is powered through
+this when connected to your PC.  Otherwise you will need to power it directly.
+Please refer to the documentation for your board for further details.
+
+Getting the firmware
+--------------------
+
+The first thing you need to do is download the most recent MicroPython firmware 
+.bin file to load onto your ESP8266 device. You can download it from the  
+`MicroPython downloads page <http://micropython.org/download#esp8266>`_.
+From here, you have 3 main choices
+
+* Stable firmware builds for 1024kb modules and above.
+* Daily firmware builds for 1024kb modules and above.
+* Daily firmware builds for 512kb modules.
+
+If you are just starting with MicroPython, the best bet is to go for the Stable
+firmware builds. If you are an advanced, experienced MicroPython ESP8266 user
+who would like to follow development closely and help with testing new
+features, there are daily builds (note: you actually may need some
+development experience, e.g. being ready to follow git history to know
+what new changes and features were introduced).
+
+Support for 512kb modules is provided on a feature preview basis. For end
+users, it's recommended to use modules with flash of 1024kb or more. As
+such, only daily builds for 512kb modules are provided.
+
+Deploying the firmware
+----------------------
+
+Once you have the MicroPython firmware (compiled code), you need to load it onto 
+your ESP8266 device.  There are two main steps to do this: first you
+need to put your device in boot-loader mode, and second you need to copy across
+the firmware.  The exact procedure for these steps is highly dependent on the
+particular board and you will need to refer to its documentation for details.
+
+If you have a board that has a USB connector, a USB-serial convertor, and has
+the DTR and RTS pins wired in a special way then deploying the firmware should
+be easy as all steps can be done automatically.  Boards that have such features
+include the Adafruit Feather HUZZAH and NodeMCU boards.
+
+For best results it is recommended to first erase the entire flash of your
+device before putting on new MicroPython firmware.
+
+Currently we only support esptool.py to copy across the firmware.  You can find
+this tool here: `<https://github.com/espressif/esptool/>`__, or install it
+using pip::
+
+    pip install esptool
+
+Versions starting with 1.3 support both Python 2.7 and Python 3.4 (or newer).
+An older version (at least 1.2.1 is needed) works fine but will require Python
+2.7.
+
+Any other flashing program should work, so feel free to try them out or refer
+to the documentation for your board to see its recommendations.
+
+Using esptool.py you can erase the flash with the command::
+
+    esptool.py --port /dev/ttyUSB0 erase_flash
+
+And then deploy the new firmware using::
+
+    esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20170108-v1.8.7.bin
+
+You might need to change the "port" setting to something else relevant for your
+PC.  You may also need to reduce the baudrate if you get errors when flashing
+(eg down to 115200).  The filename of the firmware should also match the file
+that you have.
+
+For some boards with a particular FlashROM configuration (e.g. some variants of
+a NodeMCU board) you may need to use the following command to deploy
+the firmware (note the ``-fm dio`` option)::
+
+    esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dio 0 esp8266-20170108-v1.8.7.bin
+
+If the above commands run without error then MicroPython should be installed on
+your board!
+
+Serial prompt
+-------------
+
+Once you have the firmware on the device you can access the REPL (Python prompt)
+over UART0 (GPIO1=TX, GPIO3=RX), which might be connected to a USB-serial
+convertor, depending on your board.  The baudrate is 115200.  The next part of
+the tutorial will discuss the prompt in more detail.
+
+WiFi
+----
+
+After a fresh install and boot the device configures itself as a WiFi access
+point (AP) that you can connect to.  The ESSID is of the form MicroPython-xxxxxx
+where the x's are replaced with part of the MAC address of your device (so will
+be the same everytime, and most likely different for all ESP8266 chips).  The
+password for the WiFi is micropythoN (note the upper-case N).  Its IP address
+will be 192.168.4.1 once you connect to its network.  WiFi configuration will
+be discussed in more detail later in the tutorial.
+
+Troubleshooting installation problems
+-------------------------------------
+
+If you experience problems during flashing or with running firmware immediately
+after it, here are troubleshooting recommendations:
+
+* Be aware of and try to exclude hardware problems. There are 2 common problems:
+  bad power source quality and worn-out/defective FlashROM. Speaking of power
+  source, not just raw amperage is important, but also low ripple and noise/EMI
+  in general. If you experience issues with self-made or wall-wart style power
+  supply, try USB power from a computer. Unearthed power supplies are also known
+  to cause problems as they source of increased EMI (electromagnetic interference)
+  - at the very least, and may lead to electrical devices breakdown. So, you are
+  advised to avoid using unearthed power connections when working with ESP8266
+  and other boards. In regard to FlashROM hardware problems, there are independent
+  (not related to MicroPython in any way) reports
+  `(e.g.) <http://internetofhomethings.com/homethings/?p=538>`_
+  that on some ESP8266 modules, FlashROM can be programmed as little as 20 times
+  before programming errors occur. This is *much* less than 100,000 programming
+  cycles cited for FlashROM chips of a type used with ESP8266 by reputable
+  vendors, which points to either production rejects, or second-hand worn-out
+  flash chips to be used on some (apparently cheap) modules/boards. You may want
+  to use your best judgement about source, price, documentation, warranty,
+  post-sales support for the modules/boards you purchase.
+
+* The flashing instructions above use flashing speed of 460800 baud, which is
+  good compromise between speed and stability. However, depending on your
+  module/board, USB-UART convertor, cables, host OS, etc., the above baud
+  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
+
+  This version doesn't support ``--flash_size=detect`` option, so you will
+  need to specify FlashROM size explicitly (in megabits). It also requires
+  Python 2.7, so you may need to use ``pip2`` instead of ``pip`` in the
+  command above.
+
+* The ``--flash_size`` option in the commands above is mandatory. Omitting
+  it will lead to a corrupted firmware.
+
+* To catch incorrect flash content (e.g. from a defective sector on a chip),
+  add ``--verify`` switch to the commands above.
+
+* Additionally, you can check the firmware integrity from a MicroPython REPL
+  prompt (assuming you were able to flash it and ``--verify`` option doesn't
+  report errors)::
+
+    import esp
+    esp.check_fw()
+
+  If the last output value is True, the firmware is OK. Otherwise, it's
+  corrupted and need to be reflashed correctly.
+
+* If you experience any issues with another flashing application (not
+  esptool.py), try esptool.py, it is a generally accepted flashing
+  application in the ESP8266 community.
+
+* If you still experience problems with even flashing the firmware, please
+  refer to esptool.py project page, https://github.com/espressif/esptool
+  for additional documentation and bug tracker where you can report problems.
+
+* If you are able to flash firmware, but ``--verify`` option or
+  ``esp.check_fw()`` return errors even after multiple retries, you
+  may have a defective FlashROM chip, as explained above.

docs/esp8266/tutorial/neopixel.rst

@@ -0,0 +1,84 @@
+Controlling NeoPixels
+=====================
+
+NeoPixels, also known as WS2812 LEDs, are full-colour LEDs that are connected in
+serial, are individually addressable, and can have their red, green and blue
+components set between 0 and 255.  They require precise timing to control them
+and there is a special neopixel module to do just this.
+
+To create a NeoPixel object do the following::
+
+    >>> import machine, neopixel
+    >>> np = neopixel.NeoPixel(machine.Pin(4), 8)
+
+This configures a NeoPixel strip on GPIO4 with 8 pixels.  You can adjust the
+"4" (pin number) and the "8" (number of pixel) to suit your set up.
+
+To set the colour of pixels use::
+
+    >>> np[0] = (255, 0, 0) # set to red, full brightness
+    >>> np[1] = (0, 128, 0) # set to green, half brightness
+    >>> np[2] = (0, 0, 64)  # set to blue, quarter brightness
+
+For LEDs with more than 3 colours, such as RGBW pixels or RGBY pixels, the
+NeoPixel class takes a ``bpp`` parameter. To setup a NeoPixel object for an
+RGBW Pixel, do the following::
+
+    >>> import machine, neopixel
+    >>> np = neopixel.NeoPixel(machine.Pin(4), 8, bpp=4)
+
+In a 4-bpp mode, remember to use 4-tuples instead of 3-tuples to set the colour.
+For example to set the first three pixels use::
+
+    >>> np[0] = (255, 0, 0, 128) # Orange in an RGBY Setup
+    >>> np[1] = (0, 255, 0, 128) # Yellow-green in an RGBY Setup
+    >>> np[2] = (0, 0, 255, 128) # Green-blue in an RGBY Setup
+
+Then use the ``write()`` method to output the colours to the LEDs::
+
+    >>> np.write()
+
+The following demo function makes a fancy show on the LEDs::
+
+    import time
+
+    def demo(np):
+        n = np.n
+
+        # cycle
+        for i in range(4 * n):
+            for j in range(n):
+                np[j] = (0, 0, 0)
+            np[i % n] = (255, 255, 255)
+            np.write()
+            time.sleep_ms(25)
+
+        # bounce
+        for i in range(4 * n):
+            for j in range(n):
+                np[j] = (0, 0, 128)
+            if (i // n) % 2 == 0:
+                np[i % n] = (0, 0, 0)
+            else:
+                np[n - 1 - (i % n)] = (0, 0, 0)
+            np.write()
+            time.sleep_ms(60)
+
+        # fade in/out
+        for i in range(0, 4 * 256, 8):
+            for j in range(n):
+                if (i // 256) % 2 == 0:
+                    val = i & 0xff
+                else:
+                    val = 255 - (i & 0xff)
+                np[j] = (val, 0, 0)
+            np.write()
+
+        # clear
+        for i in range(n):
+            np[i] = (0, 0, 0)
+        np.write()
+
+Execute it using::
+
+    >>> demo(np)

docs/esp8266/tutorial/network_basics.rst

@@ -0,0 +1,81 @@
+Network basics
+==============
+
+The network module is used to configure the WiFi connection.  There are two WiFi
+interfaces, one for the station (when the ESP8266 connects to a router) and one
+for the access point (for other devices to connect to the ESP8266).  Create
+instances of these objects using::
+
+    >>> import network
+    >>> sta_if = network.WLAN(network.STA_IF)
+    >>> ap_if = network.WLAN(network.AP_IF)
+
+You can check if the interfaces are active by::
+
+    >>> sta_if.active()
+    False
+    >>> ap_if.active()
+    True
+
+You can also check the network settings of the interface by::
+
+    >>> ap_if.ifconfig()
+    ('192.168.4.1', '255.255.255.0', '192.168.4.1', '8.8.8.8')
+
+The returned values are: IP address, netmask, gateway, DNS.
+
+Configuration of the WiFi
+-------------------------
+
+Upon a fresh install the ESP8266 is configured in access point mode, so the
+AP_IF interface is active and the STA_IF interface is inactive.  You can
+configure the module to connect to your own network using the STA_IF interface.
+
+First activate the station interface::
+
+    >>> sta_if.active(True)
+
+Then connect to your WiFi network::
+
+    >>> sta_if.connect('<your ESSID>', '<your password>')
+
+To check if the connection is established use::
+
+    >>> sta_if.isconnected()
+
+Once established you can check the IP address::
+
+    >>> sta_if.ifconfig()
+    ('192.168.0.2', '255.255.255.0', '192.168.0.1', '8.8.8.8')
+
+You can then disable the access-point interface if you no longer need it::
+
+    >>> ap_if.active(False)
+
+Here is a function you can run (or put in your boot.py file) to automatically
+connect to your WiFi network::
+
+    def do_connect():
+        import network
+        sta_if = network.WLAN(network.STA_IF)
+        if not sta_if.isconnected():
+            print('connecting to network...')
+            sta_if.active(True)
+            sta_if.connect('<essid>', '<password>')
+            while not sta_if.isconnected():
+                pass
+        print('network config:', sta_if.ifconfig())
+
+Sockets
+-------
+
+Once the WiFi is set up the way to access the network is by using sockets.
+A socket represents an endpoint on a network device, and when two sockets are
+connected together communication can proceed.
+Internet protocols are built on top of sockets, such as email (SMTP), the web
+(HTTP), telnet, ssh, among many others.  Each of these protocols is assigned
+a specific port, which is just an integer.  Given an IP address and a port
+number you can connect to a remote device and start talking with it.
+
+The next part of the tutorial discusses how to use sockets to do some common
+and useful network tasks.

docs/esp8266/tutorial/network_tcp.rst

@@ -0,0 +1,122 @@
+Network - TCP sockets
+=====================
+
+The building block of most of the internet is the TCP socket.  These sockets
+provide a reliable stream of bytes between the connected network devices.
+This part of the tutorial will show how to use TCP sockets in a few different
+cases.
+
+Star Wars Asciimation
+---------------------
+
+The simplest thing to do is to download data from the internet.  In this case
+we will use the Star Wars Asciimation service provided by the blinkenlights.nl
+website.  It uses the telnet protocol on port 23 to stream data to anyone that
+connects.  It's very simple to use because it doesn't require you to
+authenticate (give a username or password), you can just start downloading data
+straight away.
+
+The first thing to do is make sure we have the socket module available::
+
+    >>> import socket
+
+Then get the IP address of the server::
+
+    >>> addr_info = socket.getaddrinfo("towel.blinkenlights.nl", 23)
+
+The ``getaddrinfo`` function actually returns a list of addresses, and each
+address has more information than we need.  We want to get just the first valid
+address, and then just the IP address and port of the server.  To do this use::
+
+    >>> addr = addr_info[0][-1]
+
+If you type ``addr_info`` and ``addr`` at the prompt you will see exactly what
+information they hold.
+
+Using the IP address we can make a socket and connect to the server::
+
+    >>> s = socket.socket()
+    >>> s.connect(addr)
+
+Now that we are connected we can download and display the data::
+
+    >>> while True:
+    ...     data = s.recv(500)
+    ...     print(str(data, 'utf8'), end='')
+    ...
+ 
+When this loop executes it should start showing the animation (use ctrl-C to
+interrupt it).
+
+You should also be able to run this same code on your PC using normal Python if
+you want to try it out there.
+
+HTTP GET request
+----------------
+
+The next example shows how to download a webpage.  HTTP uses port 80 and you
+first need to send a "GET" request before you can download anything.  As part
+of the request you need to specify the page to retrieve.
+
+Let's define a function that can download and print a URL::
+
+    def http_get(url):
+        _, _, host, path = url.split('/', 3)
+        addr = socket.getaddrinfo(host, 80)[0][-1]
+        s = socket.socket()
+        s.connect(addr)
+        s.send(bytes('GET /%s HTTP/1.0\r\nHost: %s\r\n\r\n' % (path, host), 'utf8'))
+        while True:
+            data = s.recv(100)
+            if data:
+                print(str(data, 'utf8'), end='')
+            else:
+                break
+        s.close()
+
+Make sure that you import the socket module before running this function.  Then
+you can try::
+
+    >>> http_get('http://micropython.org/ks/test.html')
+
+This should retrieve the webpage and print the HTML to the console.
+
+Simple HTTP server
+------------------
+
+The following code creates an simple HTTP server which serves a single webpage
+that contains a table with the state of all the GPIO pins::
+
+    import machine
+    pins = [machine.Pin(i, machine.Pin.IN) for i in (0, 2, 4, 5, 12, 13, 14, 15)]
+
+    html = """<!DOCTYPE html>
+    <html>
+        <head> <title>ESP8266 Pins</title> </head>
+        <body> <h1>ESP8266 Pins</h1>
+            <table border="1"> <tr><th>Pin</th><th>Value</th></tr> %s </table>
+        </body>
+    </html>
+    """
+
+    import socket
+    addr = socket.getaddrinfo('0.0.0.0', 80)[0][-1]
+
+    s = socket.socket()
+    s.bind(addr)
+    s.listen(1)
+
+    print('listening on', addr)
+
+    while True:
+        cl, addr = s.accept()
+        print('client connected from', addr)
+        cl_file = cl.makefile('rwb', 0)
+        while True:
+            line = cl_file.readline()
+            if not line or line == b'\r\n':
+                break
+        rows = ['<tr><td>%s</td><td>%d</td></tr>' % (str(p), p.value()) for p in pins]
+        response = html % '\n'.join(rows)
+        cl.send(response)
+        cl.close()

docs/esp8266/tutorial/nextsteps.rst

@@ -0,0 +1,12 @@
+Next steps
+==========
+
+That brings us to the end of the tutorial!  Hopefully by now you have a good
+feel for the capabilities of MicroPython on the ESP8266 and understand how to
+control both the WiFi and IO aspects of the chip.
+
+There are many features that were not covered in this tutorial.  The best way
+to learn about them is to read the full documentation of the modules, and to
+experiment!
+
+Good luck creating your Internet of Things devices!

docs/esp8266/tutorial/onewire.rst

@@ -0,0 +1,37 @@
+Controlling 1-wire devices
+==========================
+
+The 1-wire bus is a serial bus that uses just a single wire for communication
+(in addition to wires for ground and power).  The DS18B20 temperature sensor
+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 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, ds18x20
+
+    # the device is on GPIO12
+    dat = machine.Pin(12)
+
+    # create the onewire object
+    ds = ds18x20.DS18X20(onewire.OneWire(dat))
+
+    # scan for devices on the bus
+    roms = ds.scan()
+    print('found devices:', roms)
+
+    # loop 10 times and print all temperatures
+    for i in range(10):
+        print('temperatures:', end=' ')
+        ds.convert_temp()
+        time.sleep_ms(750)
+        for rom in roms:
+            print(ds.read_temp(rom), end=' ')
+        print()
+
+Note that you must execute the ``convert_temp()`` function to initiate a
+temperature reading, then wait at least 750ms before reading the value.

docs/esp8266/tutorial/pins.rst

@@ -0,0 +1,75 @@
+GPIO Pins
+=========
+
+The way to connect your board to the external world, and control other
+components, is through the GPIO pins.  Not all pins are available to use,
+in most cases only pins 0, 2, 4, 5, 12, 13, 14, 15, and 16 can be used.
+
+The pins are available in the machine module, so make sure you import that
+first.  Then you can create a pin using::
+
+    >>> pin = machine.Pin(0)
+
+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.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.
+You can read the value on the pin using::
+
+    >>> pin.value()
+    0
+
+The pin on your board may return 0 or 1 here, depending on what it's connected
+to.  To make an output pin use::
+
+    >>> pin = machine.Pin(0, machine.Pin.OUT)
+
+Then set its value using::
+
+    >>> pin.value(0)
+    >>> pin.value(1)
+
+Or::
+
+    >>> pin.off()
+    >>> pin.on()
+
+External interrupts
+-------------------
+
+All pins except number 16 can be configured to trigger a hard interrupt if their
+input changes.  You can set code (a callback function) to be executed on the
+trigger.
+
+Let's first define a callback function, which must take a single argument,
+being the pin that triggered the function.  We will make the function just print
+the pin::
+
+    >>> def callback(p):
+    ...     print('pin change', p)
+
+Next we will create two pins and configure them as inputs::
+
+    >>> from machine import Pin
+    >>> p0 = Pin(0, Pin.IN)
+    >>> p2 = Pin(2, Pin.IN)
+
+An finally we need to tell the pins when to trigger, and the function to call
+when they detect an event::
+
+    >>> p0.irq(trigger=Pin.IRQ_FALLING, handler=callback)
+    >>> p2.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=callback)
+
+We set pin 0 to trigger only on a falling edge of the input (when it goes from
+high to low), and set pin 2 to trigger on both a rising and falling edge.  After
+entering this code you can apply high and low voltages to pins 0 and 2 to see
+the interrupt being executed.
+
+A hard interrupt will trigger as soon as the event occurs and will interrupt any
+running code, including Python code.  As such your callback functions are
+limited in what they can do (they cannot allocate memory, for example) and
+should be as short and simple as possible.

docs/esp8266/tutorial/powerctrl.rst

@@ -0,0 +1,61 @@
+Power control
+=============
+
+The ESP8266 provides the ability to change the CPU frequency on the fly, and
+enter a deep-sleep state.  Both can be used to manage power consumption.
+
+Changing the CPU frequency
+--------------------------
+
+The machine module has a function to get and set the CPU frequency.  To get the
+current frequency use::
+
+    >>> import machine
+    >>> machine.freq()
+    80000000
+
+By default the CPU runs at 80MHz.  It can be change to 160MHz if you need more
+processing power, at the expense of current consumption::
+
+    >>> machine.freq(160000000)
+    >>> machine.freq()
+    160000000
+
+You can change to the higher frequency just while your code does the heavy
+processing and then change back when it's finished.
+
+Deep-sleep mode
+---------------
+
+The deep-sleep mode will shut down the ESP8266 and all its peripherals,
+including the WiFi (but not including the real-time-clock, which is used to wake
+the chip).  This drastically reduces current consumption and is a good way to
+make devices that can run for a while on a battery.
+
+To be able to use the deep-sleep feature you must connect GPIO16 to the reset
+pin (RST on the Adafruit Feather HUZZAH board).  Then the following code can be
+used to sleep and wake the device::
+
+    import machine
+
+    # configure RTC.ALARM0 to be able to wake the device
+    rtc = machine.RTC()
+    rtc.irq(trigger=rtc.ALARM0, wake=machine.DEEPSLEEP)
+
+    # set RTC.ALARM0 to fire after 10 seconds (waking the device)
+    rtc.alarm(rtc.ALARM0, 10000)
+
+    # put the device to sleep
+    machine.deepsleep()
+
+Note that when the chip wakes from a deep-sleep it is completely reset,
+including all of the memory.  The boot scripts will run as usual and you can
+put code in them to check the reset cause to perhaps do something different if
+the device just woke from a deep-sleep.  For example, to print the reset cause
+you can use::
+
+    if machine.reset_cause() == machine.DEEPSLEEP_RESET:
+        print('woke from a deep sleep')
+    else:
+        print('power on or hard reset')
+

docs/esp8266/tutorial/pwm.rst

@@ -0,0 +1,87 @@
+Pulse Width Modulation
+======================
+
+Pulse width modulation (PWM) is a way to get an artificial analog output on a
+digital pin.  It achieves this by rapidly toggling the pin from low to high.
+There are two parameters associated with this: the frequency of the toggling,
+and the duty cycle.  The duty cycle is defined to be how long the pin is high
+compared with the length of a single period (low plus high time).  Maximum
+duty cycle is when the pin is high all of the time, and minimum is when it is
+low all of the time.
+
+On the ESP8266 the pins 0, 2, 4, 5, 12, 13, 14 and 15 all support PWM.  The
+limitation is that they must all be at the same frequency, and the frequency
+must be between 1Hz and 1kHz.
+
+To use PWM on a pin you must first create the pin object, for example::
+
+    >>> import machine
+    >>> p12 = machine.Pin(12)
+
+Then create the PWM object using::
+
+    >>> pwm12 = machine.PWM(p12)
+
+You can set the frequency and duty cycle using::
+
+    >>> pwm12.freq(500)
+    >>> pwm12.duty(512)
+
+Note that the duty cycle is between 0 (all off) and 1023 (all on), with 512
+being a 50% duty.  If you print the PWM object then it will tell you its current
+configuration::
+
+    >>> pwm12
+    PWM(12, freq=500, duty=512)
+
+You can also call the ``freq()`` and ``duty()`` methods with no arguments to
+get their current values.
+
+The pin will continue to be in PWM mode until you deinitialise it using::
+
+    >>> pwm12.deinit()
+
+Fading an LED
+-------------
+
+Let's use the PWM feature to fade an LED.  Assuming your board has an LED
+connected to pin 2 (ESP-12 modules do) we can create an LED-PWM object using::
+
+    >>> led = machine.PWM(machine.Pin(2), freq=1000)
+
+Notice that we can set the frequency in the PWM constructor.
+
+For the next part we will use timing and some math, so import these modules::
+
+    >>> import time, math
+
+Then create a function to pulse the LED::
+
+    >>> def pulse(l, t):
+    ...     for i in range(20):
+    ...         l.duty(int(math.sin(i / 10 * math.pi) * 500 + 500))
+    ...         time.sleep_ms(t)
+
+You can try this function out using::
+
+    >>> pulse(led, 50)
+
+For a nice effect you can pulse many times in a row::
+
+    >>> for i in range(10):
+    ...     pulse(led, 20)
+
+Remember you can use ctrl-C to interrupt the code.
+
+Control a hobby servo
+---------------------
+
+Hobby servo motors can be controlled using PWM.  They require a frequency of
+50Hz and then a duty between about 40 and 115, with 77 being the centre value.
+If you connect a servo to the power and ground pins, and then the signal line
+to pin 12 (other pins will work just as well), you can control the motor using::
+
+    >>> servo = machine.PWM(machine.Pin(12), freq=50)
+    >>> servo.duty(40)
+    >>> servo.duty(115)
+    >>> servo.duty(77)

docs/esp8266/tutorial/repl.rst

@@ -0,0 +1,212 @@
+Getting a MicroPython REPL prompt
+=================================
+
+REPL stands for Read Evaluate Print Loop, and is the name given to the
+interactive MicroPython prompt that you can access on the ESP8266.  Using the
+REPL is by far the easiest way to test out your code and run commands.
+
+There are two ways to access the REPL: either via a wired connection through the
+UART serial port, or via WiFi.
+
+REPL over the serial port
+-------------------------
+
+The REPL is always available on the UART0 serial peripheral, which is connected
+to the pins GPIO1 for TX and GPIO3 for RX.  The baudrate of the REPL is 115200.
+If your board has a USB-serial convertor on it then you should be able to access
+the REPL directly from your PC.  Otherwise you will need to have a way of
+communicating with the UART.
+
+To access the prompt over USB-serial you need to use a terminal emulator program.
+On Windows TeraTerm is a good choice, on Mac you can use the built-in screen
+program, and Linux has picocom and minicom.  Of course, there are many other
+terminal programs that will work, so pick your favourite!
+
+For example, on Linux you can try running::
+
+    picocom /dev/ttyUSB0 -b115200
+
+Once you have made the connection over the serial port you can test if it is
+working by hitting enter a few times.  You should see the Python REPL prompt,
+indicated by ``>>>``.
+
+WebREPL - a prompt over WiFi
+----------------------------
+
+WebREPL allows you to use the Python prompt over WiFi, connecting through a
+browser. The latest versions of Firefox and Chrome are supported.
+
+For your convenience, WebREPL client is hosted at
+`<http://micropython.org/webrepl>`__ . Alternatively, you can install it
+locally from the the GitHub repository
+`<https://github.com/micropython/webrepl>`__ .
+
+Before connecting to WebREPL, you should set a password and enable it via
+a normal serial connection. Initial versions of MicroPython for ESP8266
+came with WebREPL automatically enabled on the boot and with the
+ability to set a password via WiFi on the first connection, but as WebREPL
+was becoming more widely known and popular, the initial setup has switched
+to a wired connection for improved security::
+
+    import webrepl_setup
+
+Follow the on-screen instructions and prompts. To make any changes active,
+you will need to reboot your device.
+
+To use WebREPL connect your computer to the ESP8266's access point
+(MicroPython-xxxxxx, see the previous section about this).  If you have
+already reconfigured your ESP8266 to connect to a router then you can
+skip this part.
+
+Once you are on the same network as the ESP8266 you click the "Connect" button
+(if you are connecting via a router then you may need to change the IP address,
+by default the IP address is correct when connected to the ESP8266's access
+point).  If the connection succeeds then you should see a password prompt.
+
+Once you type the password configured at the setup step above, press Enter once
+more and you should get a prompt looking like ``>>>``.  You can now start
+typing Python commands!
+
+Using the REPL
+--------------
+
+Once you have a prompt you can start experimenting!  Anything you type at the
+prompt will be executed after you press the Enter key.  MicroPython will run
+the code that you enter and print the result (if there is one).  If there is an
+error with the text that you enter then an error message is printed.
+
+Try typing the following at the prompt::
+
+    >>> print('hello esp8266!')
+    hello esp8266!
+
+Note that you shouldn't type the ``>>>`` arrows, they are there to indicate that
+you should type the text after it at the prompt.  And then the line following is
+what the device should respond with.  In the end, once you have entered the text
+``print("hello esp8266!")`` and pressed the Enter key, the output on your screen
+should look exactly like it does above.
+
+If you already know some python you can now try some basic commands here.   For
+example::
+
+    >>> 1 + 2
+    3
+    >>> 1 / 2
+    0.5
+    >>> 12**34
+    4922235242952026704037113243122008064
+
+If your board has an LED attached to GPIO2 (the ESP-12 modules do) then you can
+turn it on and off using the following code::
+
+    >>> import machine
+    >>> pin = machine.Pin(2, machine.Pin.OUT)
+    >>> pin.on()
+    >>> pin.off()
+
+Note that ``on`` method of a Pin might turn the LED off and ``off`` might
+turn it on (or vice versa), depending on how the LED is wired on your board.
+To resolve this, machine.Signal class is provided.
+
+Line editing
+~~~~~~~~~~~~
+
+You can edit the current line that you are entering using the left and right
+arrow keys to move the cursor, as well as the delete and backspace keys.  Also,
+pressing Home or ctrl-A moves the cursor to the start of the line, and pressing
+End or ctrl-E moves to the end of the line.
+
+Input history
+~~~~~~~~~~~~~
+
+The REPL remembers a certain number of previous lines of text that you entered
+(up to 8 on the ESP8266).  To recall previous lines use the up and down arrow
+keys.
+
+Tab completion
+~~~~~~~~~~~~~~
+
+Pressing the Tab key will do an auto-completion of the current word that you are
+entering.  This can be very useful to find out functions and methods that a
+module or object has.  Try it out by typing "ma" and then pressing Tab.  It
+should complete to "machine" (assuming you imported machine in the above
+example).  Then type "." and press Tab again to see a list of all the functions
+that the machine module has.
+
+Line continuation and auto-indent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Certain things that you type will need "continuing", that is, will need more
+lines of text to make a proper Python statement.  In this case the prompt will
+change to ``...`` and the cursor will auto-indent the correct amount so you can
+start typing the next line straight away.  Try this by defining the following
+function::
+
+    >>> def toggle(p):
+    ...    p.value(not p.value())
+    ...    
+    ...    
+    ...    
+    >>>
+
+In the above, you needed to press the Enter key three times in a row to finish
+the compound statement (that's the three lines with just dots on them).  The
+other way to finish a compound statement is to press backspace to get to the
+start of the line, then press the Enter key.  (If you did something wrong and
+want to escape the continuation mode then press ctrl-C; all lines will be
+ignored.)
+
+The function you just defined allows you to toggle a pin.  The pin object you
+created earlier should still exist (recreate it if it doesn't) and you can
+toggle the LED using::
+
+    >>> toggle(pin)
+
+Let's now toggle the LED in a loop (if you don't have an LED then you can just
+print some text instead of calling toggle, to see the effect)::
+
+    >>> import time
+    >>> while True:
+    ...     toggle(pin)
+    ...     time.sleep_ms(500)
+    ...    
+    ...    
+    ...    
+    >>>
+
+This will toggle the LED at 1Hz (half a second on, half a second off).  To stop
+the toggling press ctrl-C, which will raise a KeyboardInterrupt exception and
+break out of the loop.
+
+The time module provides some useful functions for making delays and doing
+timing.  Use tab completion to find out what they are and play around with them!
+
+Paste mode
+~~~~~~~~~~
+
+Pressing ctrl-E will enter a special paste mode.  This allows you to copy and
+paste a chunk of text into the REPL.  If you press ctrl-E you will see the
+paste-mode prompt::
+
+    paste mode; Ctrl-C to cancel, Ctrl-D to finish
+    === 
+
+You can then paste (or type) your text in.  Note that none of the special keys
+or commands work in paste mode (eg Tab or backspace), they are just accepted
+as-is.  Press ctrl-D to finish entering the text and execute it.
+
+Other control commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+There are four other control commands:
+
+* Ctrl-A on a blank line will enter raw REPL mode.  This is like a permanent
+  paste mode, except that characters are not echoed back.
+
+* Ctrl-B on a blank like goes to normal REPL mode.
+
+* Ctrl-C cancels any input, or interrupts the currently running code.
+
+* Ctrl-D on a blank line will do a soft reset.
+
+Note that ctrl-A and ctrl-D do not work with WebREPL.

docs/esp8266_index.rst

@@ -0,0 +1,12 @@
+MicroPython documentation and references
+========================================
+
+.. toctree::
+
+    esp8266/quickref.rst
+    esp8266/general.rst
+    esp8266/tutorial/index.rst
+    library/index.rst
+    reference/index.rst
+    genrst/index.rst
+    license.rst

docs/library/array.rst

@@ -0,0 +1,29 @@
+:mod:`array` -- arrays of numeric data
+======================================
+
+.. module:: array
+   :synopsis: efficient arrays of numeric data
+
+|see_cpython_module| :mod:`python:array`.
+
+Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
+``L``, ``q``, ``Q``, ``f``, ``d`` (the latter 2 depending on the
+floating-point support).
+
+Classes
+-------
+
+.. class:: array.array(typecode, [iterable])
+
+    Create array with elements of given type. Initial contents of the
+    array are given by an `iterable`. If it is not provided, an empty
+    array is created.
+
+    .. method:: append(val)
+
+        Append new element to the end of array, growing it.
+
+    .. method:: extend(iterable)
+
+        Append new elements as contained in an iterable to the end of
+        array, growing it.

docs/library/btree.rst

@@ -0,0 +1,159 @@
+:mod:`btree` -- simple BTree database
+=====================================
+
+.. module:: btree
+   :synopsis: simple BTree database
+
+The ``btree`` module implements a simple key-value database using external
+storage (disk files, or in general case, a random-access stream). Keys are
+stored sorted in the database, and besides efficient retrieval by a key
+value, a database also supports efficient ordered range scans (retrieval
+of values with the keys in a given range). On the application interface
+side, BTree database work as close a possible to a way standard `dict`
+type works, one notable difference is that both keys and values must
+be `bytes` objects (so, if you want to store objects of other types, you
+need to serialize them to `bytes` first).
+
+The module is based on the well-known BerkelyDB library, version 1.xx.
+
+Example::
+
+    import btree
+
+    # First, we need to open a stream which holds a database
+    # This is usually a file, but can be in-memory database
+    # using uio.BytesIO, a raw flash partition, etc.
+    # Oftentimes, you want to create a database file if it doesn't
+    # exist and open if it exists. Idiom below takes care of this.
+    # DO NOT open database with "a+b" access mode.
+    try:
+        f = open("mydb", "r+b")
+    except OSError:
+        f = open("mydb", "w+b")
+
+    # Now open a database itself
+    db = btree.open(f)
+
+    # The keys you add will be sorted internally in the database
+    db[b"3"] = b"three"
+    db[b"1"] = b"one"
+    db[b"2"] = b"two"
+
+    # Assume that any changes are cached in memory unless
+    # explicitly flushed (or database closed). Flush database
+    # at the end of each "transaction".
+    db.flush()
+
+    # Prints b'two'
+    print(db[b"2"])
+
+    # Iterate over sorted keys in the database, starting from b"2"
+    # until the end of the database, returning only values.
+    # Mind that arguments passed to values() method are *key* values.
+    # Prints:
+    #   b'two'
+    #   b'three'
+    for word in db.values(b"2"):
+        print(word)
+
+    del db[b"2"]
+
+    # No longer true, prints False
+    print(b"2" in db)
+
+    # Prints:
+    #  b"1"
+    #  b"3"
+    for key in db:
+        print(key)
+
+    db.close()
+
+    # Don't forget to close the underlying stream!
+    f.close()
+
+
+Functions
+---------
+
+.. function:: open(stream, \*, flags=0, pagesize=0, cachesize=0, minkeypage=0)
+
+   Open a database from a random-access `stream` (like an open file). All
+   other parameters are optional and keyword-only, and allow to tweak advanced
+   parameters of the database operation (most users will not need them):
+
+   * *flags* - Currently unused.
+   * *pagesize* - Page size used for the nodes in BTree. Acceptable range
+     is 512-65536. If 0, a port-specific default will be used, optimized for
+     port's memory usage and/or performance.
+   * *cachesize* - Suggested memory cache size in bytes. For a
+     board with enough memory using larger values may improve performance.
+     Cache policy is as follows: entire cache is not allocated at once;
+     instead, accessing a new page in database will allocate a memory buffer
+     for it, until value specified by *cachesize* is reached. Then, these
+     buffers will be managed using LRU (least recently used) policy. More
+     buffers may still be allocated if needed (e.g., if a database contains
+     big keys and/or values). Allocated cache buffers aren't reclaimed.
+   * *minkeypage* - Minimum number of keys to store per page. Default value
+     of 0 equivalent to 2.
+
+   Returns a BTree object, which implements a dictionary protocol (set
+   of methods), and some additional methods described below.
+
+Methods
+-------
+
+.. method:: btree.close()
+
+   Close the database. It's mandatory to close the database at the end of
+   processing, as some unwritten data may be still in the cache. Note that
+   this does not close underlying stream with which the database was opened,
+   it should be closed separately (which is also mandatory to make sure that
+   data flushed from buffer to the underlying storage).
+
+.. method:: btree.flush()
+
+   Flush any data in cache to the underlying stream.
+
+.. method:: btree.__getitem__(key)
+            btree.get(key, default=None)
+            btree.__setitem__(key, val)
+            btree.__detitem__(key)
+            btree.__contains__(key)
+
+   Standard dictionary methods.
+
+.. method:: btree.__iter__()
+
+   A BTree object can be iterated over directly (similar to a dictionary)
+   to get access to all keys in order.
+
+.. method:: btree.keys([start_key, [end_key, [flags]]])
+            btree.values([start_key, [end_key, [flags]]])
+            btree.items([start_key, [end_key, [flags]]])
+
+   These methods are similar to standard dictionary methods, but also can
+   take optional parameters to iterate over a key sub-range, instead of
+   the entire database. Note that for all 3 methods, *start_key* and
+   *end_key* arguments represent key values. For example, `values()`
+   method will iterate over values corresponding to they key range
+   given. None values for *start_key* means "from the first key", no
+   *end_key* or its value of None means "until the end of database".
+   By default, range is inclusive of *start_key* and exclusive of
+   *end_key*, you can include *end_key* in iteration by passing *flags*
+   of `btree.INCL`. You can iterate in descending key direction
+   by passing *flags* of `btree.DESC`. The flags values can be ORed
+   together.
+
+Constants
+---------
+
+.. data:: INCL
+
+   A flag for `keys()`, `values()`, `items()` methods to specify that
+   scanning should be inclusive of the end key.
+
+.. data:: DESC
+
+   A flag for `keys()`, `values()`, `items()` methods to specify that
+   scanning should be in descending direction of keys.

docs/library/builtins.rst

@@ -0,0 +1,199 @@
+Builtin functions and exceptions
+================================
+
+All builtin functions and exceptions are described here. They are also
+available via ``builtins`` module.
+
+Functions and types
+-------------------
+
+.. function:: abs()
+
+.. function:: all()
+
+.. function:: any()
+
+.. function:: bin()
+
+.. class:: bool()
+
+.. class:: bytearray()
+
+.. class:: bytes()
+
+    |see_cpython| `python:bytes`.
+
+.. function:: callable()
+
+.. function:: chr()
+
+.. function:: classmethod()
+
+.. function:: compile()
+
+.. class:: complex()
+
+.. function:: delattr(obj, name)
+
+   The argument *name* should be a string, and this function deletes the named
+   attribute from the object given by *obj*.
+
+.. class:: dict()
+
+.. function:: dir()
+
+.. function:: divmod()
+
+.. function:: enumerate()
+
+.. function:: eval()
+
+.. function:: exec()
+
+.. function:: filter()
+
+.. class:: float()
+
+.. class:: frozenset()
+
+.. function:: getattr()
+
+.. function:: globals()
+
+.. function:: hasattr()
+
+.. function:: hash()
+
+.. function:: hex()
+
+.. function:: id()
+
+.. function:: input()
+
+.. class:: int()
+
+   .. classmethod:: from_bytes(bytes, byteorder)
+
+      In MicroPython, `byteorder` parameter must be positional (this is
+      compatible with CPython).
+
+   .. method:: to_bytes(size, byteorder)
+
+      In MicroPython, `byteorder` parameter must be positional (this is
+      compatible with CPython).
+
+.. function:: isinstance()
+
+.. function:: issubclass()
+
+.. function:: iter()
+
+.. function:: len()
+
+.. class:: list()
+
+.. function:: locals()
+
+.. function:: map()
+
+.. function:: max()
+
+.. class:: memoryview()
+
+.. function:: min()
+
+.. function:: next()
+
+.. class:: object()
+
+.. function:: oct()
+
+.. function:: open()
+
+.. function:: ord()
+
+.. function:: pow()
+
+.. function:: print()
+
+.. function:: property()
+
+.. function:: range()
+
+.. function:: repr()
+
+.. function:: reversed()
+
+.. function:: round()
+
+.. class:: set()
+
+.. function:: setattr()
+
+.. class:: slice()
+
+   The *slice* builtin is the type that slice objects have.
+
+.. function:: sorted()
+
+.. function:: staticmethod()
+
+.. class:: str()
+
+.. function:: sum()
+
+.. function:: super()
+
+.. class:: tuple()
+
+.. function:: type()
+
+.. function:: zip()
+
+
+Exceptions
+----------
+
+.. exception:: AssertionError
+
+.. exception:: AttributeError
+
+.. exception:: Exception
+
+.. exception:: ImportError
+
+.. exception:: IndexError
+
+.. exception:: KeyboardInterrupt
+
+.. exception:: KeyError
+
+.. exception:: MemoryError
+
+.. exception:: NameError
+
+.. exception:: NotImplementedError
+
+.. exception:: OSError
+
+    |see_cpython| `python:OSError`. MicroPython doesn't implement ``errno``
+    attribute, instead use the standard way to access exception arguments:
+    ``exc.args[0]``.
+
+.. exception:: RuntimeError
+
+.. exception:: StopIteration
+
+.. exception:: SyntaxError
+
+.. exception:: SystemExit
+
+    |see_cpython| `python:SystemExit`.
+
+.. exception:: TypeError
+
+    |see_cpython| `python:TypeError`.
+
+.. exception:: ValueError
+
+.. exception:: ZeroDivisionError

docs/library/cmath.rst

@@ -0,0 +1,63 @@
+:mod:`cmath` -- mathematical functions for complex numbers
+==========================================================
+
+.. module:: cmath
+   :synopsis: mathematical functions for complex numbers
+
+|see_cpython_module| :mod:`python:cmath`.
+
+The ``cmath`` module provides some basic mathematical functions for
+working with complex numbers.
+
+Availability: not available on WiPy and ESP8266. Floating point support
+required for this module.
+
+Functions
+---------
+
+.. function:: cos(z)
+
+   Return the cosine of ``z``.
+
+.. function:: exp(z)
+
+   Return the exponential of ``z``.
+
+.. function:: log(z)
+
+   Return the natural logarithm of ``z``.  The branch cut is along the negative real axis.
+
+.. function:: log10(z)
+
+   Return the base-10 logarithm of ``z``.  The branch cut is along the negative real axis.
+
+.. function:: phase(z)
+
+   Returns the phase of the number ``z``, in the range (-pi, +pi].
+
+.. function:: polar(z)
+
+   Returns, as a tuple, the polar form of ``z``.
+
+.. function:: rect(r, phi)
+
+   Returns the complex number with modulus ``r`` and phase ``phi``.
+
+.. function:: sin(z)
+
+   Return the sine of ``z``.
+
+.. function:: sqrt(z)
+
+   Return the square-root of ``z``.
+
+Constants
+---------
+
+.. data:: e
+
+   base of the natural logarithm
+
+.. data:: pi
+
+   the ratio of a circle's circumference to its diameter

docs/library/esp.rst

@@ -0,0 +1,83 @@
+:mod:`esp` --- functions related to the ESP8266
+===============================================
+
+.. module:: esp
+    :synopsis: functions related to the ESP8266
+
+The ``esp`` module contains specific functions related to the ESP8266 module.
+
+
+Functions
+---------
+
+.. function:: sleep_type([sleep_type])
+
+    Get or set the sleep type.
+
+    If the *sleep_type* parameter is provided, sets the sleep type to its
+    value. If the function is called without parameters, returns the current
+    sleep type.
+
+    The possible sleep types are defined as constants:
+
+        * ``SLEEP_NONE`` -- all functions enabled,
+        * ``SLEEP_MODEM`` -- modem sleep, shuts down the WiFi Modem circuit.
+        * ``SLEEP_LIGHT`` -- light sleep, shuts down the WiFi Modem circuit
+          and suspends the processor periodically.
+
+    The system enters the set sleep mode automatically when possible.
+
+.. function:: deepsleep(time=0)
+
+    Enter deep sleep.
+
+    The whole module powers down, except for the RTC clock circuit, which can
+    be used to restart the module after the specified time if the pin 16 is
+    connected to the reset pin. Otherwise the module will sleep until manually
+    reset.
+
+.. function:: flash_id()
+
+    Read the device ID of the flash memory.
+
+.. function:: flash_read(byte_offset, length_or_buffer)
+
+.. function:: flash_write(byte_offset, bytes)
+
+.. function:: flash_erase(sector_no)
+
+.. function:: set_native_code_location(start, length)
+
+    Set the location that native code will be placed for execution after it is
+    compiled.  Native code is emitted when the ``@micropython.native``,
+    ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied
+    to a function.  The ESP8266 must execute code from either iRAM or the lower
+    1MByte of flash (which is memory mapped), and this function controls the
+    location.
+
+    If *start* and *length* are both ``None`` then the native code location is
+    set to the unused portion of memory at the end of the iRAM1 region.  The
+    size of this unused portion depends on the firmware and is typically quite
+    small (around 500 bytes), and is enough to store a few very small
+    functions.  The advantage of using this iRAM1 region is that it does not
+    get worn out by writing to it.
+
+    If neither *start* nor *length* are ``None`` then they should be integers.
+    *start* should specify the byte offset from the beginning of the flash at
+    which native code should be stored.  *length* specifies how many bytes of
+    flash from *start* can be used to store native code.  *start* and *length*
+    should be multiples of the sector size (being 4096 bytes).  The flash will
+    be automatically erased before writing to it so be sure to use a region of
+    flash that is not otherwise used, for example by the firmware or the
+    filesystem.
+
+    When using the flash to store native code *start+length* must be less
+    than or equal to 1MByte.  Note that the flash can be worn out if repeated
+    erasures (and writes) are made so use this feature sparingly.
+    In particular, native code needs to be recompiled and rewritten to flash
+    on each boot (including wake from deepsleep).
+
+    In both cases above, using iRAM1 or flash, if there is no more room left
+    in the specified region then the use of a native decorator on a function
+    will lead to `MemoryError` exception being raised during compilation of
+    that function.

docs/library/framebuf.rst

@@ -0,0 +1,153 @@
+:mod:`framebuf` --- Frame buffer manipulation
+=============================================
+
+.. module:: framebuf
+   :synopsis: Frame buffer manipulation
+
+This module provides a general frame buffer which can be used to create
+bitmap images, which can then be sent to a display.
+
+class FrameBuffer
+-----------------
+
+The FrameBuffer class provides a pixel buffer which can be drawn upon with
+pixels, lines, rectangles, text and even other FrameBuffer's. It is useful
+when generating output for displays.
+
+For example::
+
+    import framebuf
+
+    # FrameBuffer needs 2 bytes for every RGB565 pixel
+    fbuf = FrameBuffer(bytearray(10 * 100 * 2), 10, 100, framebuf.RGB565)
+
+    fbuf.fill(0)
+    fbuf.text('MicroPython!', 0, 0, 0xffff)
+    fbuf.hline(0, 10, 96, 0xffff)
+
+Constructors
+------------
+
+.. class:: FrameBuffer(buffer, width, height, format, stride=width)
+
+    Construct a FrameBuffer object.  The parameters are:
+
+        - *buffer* is an object with a buffer protocol which must be large
+          enough to contain every pixel defined by the width, height and
+          format of the FrameBuffer.
+        - *width* is the width of the FrameBuffer in pixels
+        - *height* is the height of the FrameBuffer in pixels
+        - *format* specifies the type of pixel used in the FrameBuffer;
+          permissible values are listed under Constants below. These set the
+          number of bits used to encode a color value and the layout of these
+          bits in *buffer*.
+          Where a color value c is passed to a method, c is a small integer
+          with an encoding that is dependent on the format of the FrameBuffer.
+        - *stride* is the number of pixels between each horizontal line
+          of pixels in the FrameBuffer. This defaults to *width* but may
+          need adjustments when implementing a FrameBuffer within another
+          larger FrameBuffer or screen. The *buffer* size must accommodate
+          an increased step size.
+
+    One must specify valid *buffer*, *width*, *height*, *format* and
+    optionally *stride*.  Invalid *buffer* size or dimensions may lead to
+    unexpected errors.
+
+Drawing primitive shapes
+------------------------
+
+The following methods draw shapes onto the FrameBuffer.
+
+.. method:: FrameBuffer.fill(c)
+
+    Fill the entire FrameBuffer with the specified color.
+
+.. method:: FrameBuffer.pixel(x, y[, c])
+
+    If *c* is not given, get the color value of the specified pixel.
+    If *c* is given, set the specified pixel to the given color.
+
+.. method:: FrameBuffer.hline(x, y, w, c)
+.. method:: FrameBuffer.vline(x, y, h, c)
+.. method:: FrameBuffer.line(x1, y1, x2, y2, c)
+
+    Draw a line from a set of coordinates using the given color and
+    a thickness of 1 pixel. The `line` method draws the line up to
+    a second set of coordinates whereas the `hline` and `vline`
+    methods draw horizontal and vertical lines respectively up to
+    a given length.
+
+.. method:: FrameBuffer.rect(x, y, w, h, c)
+.. method:: FrameBuffer.fill_rect(x, y, w, h, c)
+
+    Draw a rectangle at the given location, size and color. The `rect`
+    method draws only a 1 pixel outline whereas the `fill_rect` method
+    draws both the outline and interior.
+
+Drawing text
+------------
+
+.. method:: FrameBuffer.text(s, x, y[, c])
+
+    Write text to the FrameBuffer using the the coordinates as the upper-left
+    corner of the text. The color of the text can be defined by the optional
+    argument but is otherwise a default value of 1. All characters have
+    dimensions of 8x8 pixels and there is currently no way to change the font.
+
+
+Other methods
+-------------
+
+.. method:: FrameBuffer.scroll(xstep, ystep)
+
+    Shift the contents of the FrameBuffer by the given vector. This may
+    leave a footprint of the previous colors in the FrameBuffer.
+
+.. method:: FrameBuffer.blit(fbuf, x, y[, key])
+
+    Draw another FrameBuffer on top of the current one at the given coordinates.
+    If *key* is specified then it should be a color integer and the
+    corresponding color will be considered transparent: all pixels with that
+    color value will not be drawn.
+
+    This method works between FrameBuffer instances utilising different formats,
+    but the resulting colors may be unexpected due to the mismatch in color
+    formats.
+
+Constants
+---------
+
+.. data:: framebuf.MONO_VLSB
+
+    Monochrome (1-bit) color format
+    This defines a mapping where the bits in a byte are vertically mapped with
+    bit 0 being nearest the top of the screen. Consequently each byte occupies
+    8 vertical pixels. Subsequent bytes appear at successive horizontal
+    locations until the rightmost edge is reached. Further bytes are rendered
+    at locations starting at the leftmost edge, 8 pixels lower.
+
+.. data:: framebuf.MONO_HLSB
+
+    Monochrome (1-bit) color format
+    This defines a mapping where the bits in a byte are horizontally mapped.
+    Each byte occupies 8 horizontal pixels with bit 0 being the leftmost.
+    Subsequent bytes appear at successive horizontal locations until the
+    rightmost edge is reached. Further bytes are rendered on the next row, one
+    pixel lower.
+
+.. data:: framebuf.MONO_HMSB
+
+    Monochrome (1-bit) color format
+    This defines a mapping where the bits in a byte are horizontally mapped.
+    Each byte occupies 8 horizontal pixels with bit 7 being the leftmost.
+    Subsequent bytes appear at successive horizontal locations until the
+    rightmost edge is reached. Further bytes are rendered on the next row, one
+    pixel lower.
+
+.. data:: framebuf.RGB565
+
+    Red Green Blue (16-bit, 5+6+5) color format
+
+.. data:: framebuf.GS4_HMSB
+
+    Grayscale (4-bit) color format

docs/library/gc.rst

@@ -0,0 +1,66 @@
+:mod:`gc` -- control the garbage collector
+==========================================
+
+.. module:: gc
+   :synopsis: control the garbage collector
+
+|see_cpython_module| :mod:`python:gc`.
+
+Functions
+---------
+
+.. function:: enable()
+
+   Enable automatic garbage collection.
+
+.. function:: disable()
+
+   Disable automatic garbage collection.  Heap memory can still be allocated,
+   and garbage collection can still be initiated manually using :meth:`gc.collect`.
+
+.. function:: collect()
+
+   Run a garbage collection.
+
+.. function:: mem_alloc()
+
+   Return the number of bytes of heap RAM that are allocated.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      This function is MicroPython extension.
+
+.. function:: mem_free()
+
+   Return the number of bytes of available heap RAM, or -1 if this amount
+   is not known.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      This function is MicroPython extension.
+
+.. function:: threshold([amount])
+
+   Set or query the additional GC allocation threshold. Normally, a collection
+   is triggered only when a new allocation cannot be satisfied, i.e. on an
+   out-of-memory (OOM) condition. If this function is called, in addition to
+   OOM, a collection will be triggered each time after *amount* bytes have been
+   allocated (in total, since the previous time such an amount of bytes
+   have been allocated). *amount* is usually specified as less than the
+   full heap size, with the intention to trigger a collection earlier than when the
+   heap becomes exhausted, and in the hope that an early collection will prevent
+   excessive memory fragmentation. This is a heuristic measure, the effect
+   of which will vary from application to application, as well as
+   the optimal value of the *amount* parameter.
+
+   Calling the function without argument will return the current value of
+   the threshold. A value of -1 means a disabled allocation threshold.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      This function is a MicroPython extension. CPython has a similar
+      function - ``set_threshold()``, but due to different GC
+      implementations, its signature and semantics are different.

docs/library/index.rst

@@ -0,0 +1,216 @@
+.. _micropython_lib:
+
+MicroPython libraries
+=====================
+
+.. warning::
+
+   Important summary of this section
+
+   * MicroPython implements a subset of Python functionality for each module.
+   * To ease extensibility, MicroPython versions of standard Python modules
+     usually have ``u`` (micro) prefix.
+   * Any particular MicroPython variant or port may miss any feature/function
+     described in this general documentation, due to resource constraints.
+
+
+This chapter describes modules (function and class libraries) which are built
+into MicroPython. There are a few categories of modules:
+
+* Modules which implement a subset of standard Python functionality and are not
+  intended to be extended by the user.
+* Modules which implement a subset of Python functionality, with a provision
+  for extension by the user (via Python code).
+* Modules which implement MicroPython extensions to the Python standard libraries.
+* Modules specific to a particular port and thus not portable.
+
+Note about the availability of modules and their contents: This documentation
+in general aspires to describe all modules and functions/classes which are
+implemented in MicroPython. However, MicroPython is highly configurable, and
+each port to a particular board/embedded system makes available only a subset
+of MicroPython libraries. For officially supported ports, there is an effort
+to either filter out non-applicable items, or mark individual descriptions
+with "Availability:" clauses describing which ports provide a given feature.
+With that in mind, please still be warned that some functions/classes
+in a module (or even the entire module) described in this documentation may be
+unavailable in a particular build of MicroPython on a particular board. The
+best place to find general information of the availability/non-availability
+of a particular feature is the "General Information" section which contains
+information pertaining to a specific port.
+
+Beyond the built-in libraries described in this documentation, many more
+modules from the Python standard library, as well as further MicroPython
+extensions to it, can be found in `micropython-lib`.
+
+Python standard libraries and micro-libraries
+---------------------------------------------
+
+The following standard Python libraries have been "micro-ified" to fit in with
+the philosophy of MicroPython.  They provide the core functionality of that
+module and are intended to be a drop-in replacement for the standard Python
+library.  Some modules below use a standard Python name, but prefixed with "u",
+e.g. ``ujson`` instead of ``json``. This is to signify that such a module is
+micro-library, i.e. implements only a subset of CPython module functionality.
+By naming them differently, a user has a choice to write a Python-level module
+to extend functionality for better compatibility with CPython (indeed, this is
+what done by the `micropython-lib` project mentioned above).
+
+On some embedded platforms, where it may be cumbersome to add Python-level
+wrapper modules to achieve naming compatibility with CPython, micro-modules
+are available both by their u-name, and also by their non-u-name.  The
+non-u-name can be overridden by a file of that name in your package path.
+For example, ``import json`` will first search for a file ``json.py`` or
+directory ``json`` and load that package if it is found.  If nothing is found,
+it will fallback to loading the built-in ``ujson`` module.
+
+.. only:: port_unix
+
+    .. toctree::
+       :maxdepth: 1
+
+       builtins.rst
+       array.rst
+       cmath.rst
+       gc.rst
+       math.rst
+       sys.rst
+       ubinascii.rst
+       ucollections.rst
+       uerrno.rst
+       uhashlib.rst
+       uheapq.rst
+       uio.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       uselect.rst
+       usocket.rst
+       ustruct.rst
+       utime.rst
+       uzlib.rst
+
+.. only:: port_pyboard
+
+    .. toctree::
+       :maxdepth: 1
+
+       builtins.rst
+       array.rst
+       cmath.rst
+       gc.rst
+       math.rst
+       sys.rst
+       ubinascii.rst
+       ucollections.rst
+       uerrno.rst
+       uhashlib.rst
+       uheapq.rst
+       uio.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       uselect.rst
+       usocket.rst
+       ustruct.rst
+       utime.rst
+       uzlib.rst
+
+.. only:: port_wipy
+
+    .. toctree::
+       :maxdepth: 1
+
+       builtins.rst
+       array.rst
+       gc.rst
+       sys.rst
+       ubinascii.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       uselect.rst
+       usocket.rst
+       ussl.rst
+       utime.rst
+
+.. only:: port_esp8266
+
+    .. toctree::
+       :maxdepth: 1
+
+       builtins.rst
+       array.rst
+       gc.rst
+       math.rst
+       sys.rst
+       ubinascii.rst
+       ucollections.rst
+       uerrno.rst
+       uhashlib.rst
+       uheapq.rst
+       uio.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       uselect.rst
+       usocket.rst
+       ussl.rst
+       ustruct.rst
+       utime.rst
+       uzlib.rst
+
+
+MicroPython-specific libraries
+------------------------------
+
+Functionality specific to the MicroPython implementation is available in
+the following libraries.
+
+.. toctree::
+   :maxdepth: 1
+
+   btree.rst
+   framebuf.rst
+   machine.rst
+   micropython.rst
+   network.rst
+   uctypes.rst
+
+
+.. only:: port_pyboard
+
+   Libraries specific to the pyboard
+   ---------------------------------
+
+   The following libraries are specific to the pyboard.
+
+   .. toctree::
+      :maxdepth: 2
+
+      pyb.rst
+      lcd160cr.rst
+
+.. only:: port_wipy
+
+   Libraries specific to the WiPy
+   ---------------------------------
+
+   The following libraries are specific to the WiPy.
+
+   .. toctree::
+      :maxdepth: 2
+
+      wipy.rst
+
+
+.. only:: port_esp8266
+
+   Libraries specific to the ESP8266
+   ---------------------------------
+
+   The following libraries are specific to the ESP8266.
+
+   .. toctree::
+      :maxdepth: 2
+
+      esp.rst

docs/library/lcd160cr.rst

@@ -0,0 +1,394 @@
+:mod:`lcd160cr` --- control of LCD160CR display
+===============================================
+
+.. module:: lcd160cr
+   :synopsis: control of LCD160CR display
+
+This module provides control of the MicroPython LCD160CR display.
+
+.. image:: http://micropython.org/resources/LCD160CRv10-persp.jpg
+    :alt: LCD160CRv1.0 picture
+    :width: 640px
+
+Further resources are available via the following links:
+
+* `LCD160CRv1.0 reference manual <http://micropython.org/resources/LCD160CRv10-refmanual.pdf>`_ (100KiB PDF)
+* `LCD160CRv1.0 schematics <http://micropython.org/resources/LCD160CRv10-schematics.pdf>`_ (1.6MiB PDF)
+
+class LCD160CR
+--------------
+
+The LCD160CR class provides an interface to the display.  Create an
+instance of this class and use its methods to draw to the LCD and get
+the status of the touch panel.
+
+For example::
+
+    import lcd160cr
+
+    lcd = lcd160cr.LCD160CR('X')
+    lcd.set_orient(lcd160cr.PORTRAIT)
+    lcd.set_pos(0, 0)
+    lcd.set_text_color(lcd.rgb(255, 0, 0), lcd.rgb(0, 0, 0))
+    lcd.set_font(1)
+    lcd.write('Hello MicroPython!')
+    print('touch:', lcd.get_touch())
+
+Constructors
+------------
+
+.. class:: LCD160CR(connect=None, \*, pwr=None, i2c=None, spi=None, i2c_addr=98)
+
+    Construct an LCD160CR object.  The parameters are:
+
+        - *connect* is a string specifying the physical connection of the LCD
+          display to the board; valid values are "X", "Y", "XY", "YX".
+          Use "X" when the display is connected to a pyboard in the X-skin
+          position, and "Y" when connected in the Y-skin position.  "XY"
+          and "YX" are used when the display is connected to the right or
+          left side of the pyboard, respectively.
+        - *pwr* is a Pin object connected to the LCD's power/enabled pin.
+        - *i2c* is an I2C object connected to the LCD's I2C interface.
+        - *spi* is an SPI object connected to the LCD's SPI interface.
+        - *i2c_addr* is the I2C address of the display.
+
+    One must specify either a valid *connect* or all of *pwr*, *i2c* and *spi*.
+    If a valid *connect* is given then any of *pwr*, *i2c* or *spi* which are
+    not passed as parameters (i.e. they are ``None``) will be created based on the
+    value of *connect*.  This allows to override the default interface to the
+    display if needed.
+
+    The default values are:
+
+        - "X" is for the X-skin and uses:
+          ``pwr=Pin("X4")``, ``i2c=I2C("X")``, ``spi=SPI("X")``
+        - "Y" is for the Y-skin and uses:
+          ``pwr=Pin("Y4")``, ``i2c=I2C("Y")``, ``spi=SPI("Y")``
+        - "XY" is for the right-side and uses:
+          ``pwr=Pin("X4")``, ``i2c=I2C("Y")``, ``spi=SPI("X")``
+        - "YX" is for the left-side and uses:
+          ``pwr=Pin("Y4")``, ``i2c=I2C("X")``, ``spi=SPI("Y")``
+
+    See `this image <http://micropython.org/resources/LCD160CRv10-positions.jpg>`_
+    for how the display can be connected to the pyboard.
+
+Static methods
+--------------
+
+.. staticmethod:: LCD160CR.rgb(r, g, b)
+
+    Return a 16-bit integer representing the given rgb color values.  The
+    16-bit value can be used to set the font color (see
+    :meth:`LCD160CR.set_text_color`) pen color (see :meth:`LCD160CR.set_pen`)
+    and draw individual pixels.
+
+.. staticmethod:: LCD160CR.clip_line(data, w, h):
+
+    Clip the given line data.  This is for internal use.
+
+Instance members
+----------------
+
+The following instance members are publicly accessible.
+
+.. data:: LCD160CR.w
+.. data:: LCD160CR.h
+
+    The width and height of the display, respectively, in pixels.  These
+    members are updated when calling :meth:`LCD160CR.set_orient` and should
+    be considered read-only.
+
+Setup commands
+--------------
+
+.. method:: LCD160CR.set_power(on)
+
+    Turn the display on or off, depending on the given value of *on*: 0 or ``False``
+    will turn the display off, and 1 or ``True`` will turn it on.
+
+.. method:: LCD160CR.set_orient(orient)
+
+    Set the orientation of the display.  The *orient* parameter can be one
+    of `PORTRAIT`, `LANDSCAPE`, `PORTRAIT_UPSIDEDOWN`, `LANDSCAPE_UPSIDEDOWN`.
+
+.. method:: LCD160CR.set_brightness(value)
+
+    Set the brightness of the display, between 0 and 31.
+
+.. method:: LCD160CR.set_i2c_addr(addr)
+
+    Set the I2C address of the display.  The *addr* value must have the
+    lower 2 bits cleared.
+
+.. method:: LCD160CR.set_uart_baudrate(baudrate)
+
+    Set the baudrate of the UART interface.
+
+.. method:: LCD160CR.set_startup_deco(value)
+
+    Set the start-up decoration of the display.  The *value* parameter can be a
+    logical or of `STARTUP_DECO_NONE`, `STARTUP_DECO_MLOGO`, `STARTUP_DECO_INFO`.
+
+.. method:: LCD160CR.save_to_flash()
+
+    Save the following parameters to flash so they persist on restart and power up:
+    initial decoration, orientation, brightness, UART baud rate, I2C address.
+
+Pixel access methods
+--------------------
+
+The following methods manipulate individual pixels on the display.
+
+.. method:: LCD160CR.set_pixel(x, y, c)
+
+    Set the specified pixel to the given color.  The color should be a 16-bit
+    integer and can be created by :meth:`LCD160CR.rgb`.
+
+.. method:: LCD160CR.get_pixel(x, y)
+
+    Get the 16-bit value of the specified pixel.
+
+.. method:: LCD160CR.get_line(x, y, buf)
+
+    Low-level method to get a line of pixels into the given buffer.
+    To read *n* pixels *buf* should be *2*n+1* bytes in length.  The first byte
+    is a dummy byte and should be ignored, and subsequent bytes represent the
+    pixels in the line starting at coordinate *(x, y)*.
+
+.. method:: LCD160CR.screen_dump(buf, x=0, y=0, w=None, h=None)
+
+    Dump the contents of the screen to the given buffer.  The parameters *x* and *y*
+    specify the starting coordinate, and *w* and *h* the size of the region.  If *w*
+    or *h* are ``None`` then they will take on their maximum values, set by the size
+    of the screen minus the given *x* and *y* values.  *buf* should be large enough
+    to hold ``2*w*h`` bytes.  If it's smaller then only the initial horizontal lines
+    will be stored.
+
+.. method:: LCD160CR.screen_load(buf)
+
+    Load the entire screen from the given buffer.
+
+Drawing text
+------------
+
+To draw text one sets the position, color and font, and then uses
+`write` to draw the text.
+
+.. method:: LCD160CR.set_pos(x, y)
+
+    Set the position for text output using :meth:`LCD160CR.write`.  The position
+    is the upper-left corner of the text.
+
+.. method:: LCD160CR.set_text_color(fg, bg)
+
+    Set the foreground and background color of the text.
+
+.. method:: LCD160CR.set_font(font, scale=0, bold=0, trans=0, scroll=0)
+
+    Set the font for the text.  Subsequent calls to `write` will use the newly
+    configured font.  The parameters are:
+
+        - *font* is the font family to use, valid values are 0, 1, 2, 3.
+        - *scale* is a scaling value for each character pixel, where the pixels
+          are drawn as a square with side length equal to *scale + 1*.  The value
+          can be between 0 and 63.
+        - *bold* controls the number of pixels to overdraw each character pixel,
+          making a bold effect.  The lower 2 bits of *bold* are the number of
+          pixels to overdraw in the horizontal direction, and the next 2 bits are
+          for the vertical direction.  For example, a *bold* value of 5 will
+          overdraw 1 pixel in both the horizontal and vertical directions.
+        - *trans* can be either 0 or 1 and if set to 1 the characters will be
+          drawn with a transparent background.
+        - *scroll* can be either 0 or 1 and if set to 1 the display will do a
+          soft scroll if the text moves to the next line.
+
+.. method:: LCD160CR.write(s)
+
+    Write text to the display, using the current position, color and font.
+    As text is written the position is automatically incremented.  The
+    display supports basic VT100 control codes such as newline and backspace.
+
+Drawing primitive shapes
+------------------------
+
+Primitive drawing commands use a foreground and background color set by the
+`set_pen` method.
+
+.. method:: LCD160CR.set_pen(line, fill)
+
+    Set the line and fill color for primitive shapes.
+
+.. method:: LCD160CR.erase()
+
+    Erase the entire display to the pen fill color.
+
+.. method:: LCD160CR.dot(x, y)
+
+    Draw a single pixel at the given location using the pen line color.
+
+.. method:: LCD160CR.rect(x, y, w, h)
+.. method:: LCD160CR.rect_outline(x, y, w, h)
+.. method:: LCD160CR.rect_interior(x, y, w, h)
+
+    Draw a rectangle at the given location and size using the pen line
+    color for the outline, and the pen fill color for the interior.
+    The `rect` method draws the outline and interior, while the other methods
+    just draw one or the other.
+
+.. method:: LCD160CR.line(x1, y1, x2, y2)
+
+    Draw a line between the given coordinates using the pen line color.
+
+.. method:: LCD160CR.dot_no_clip(x, y)
+.. method:: LCD160CR.rect_no_clip(x, y, w, h)
+.. method:: LCD160CR.rect_outline_no_clip(x, y, w, h)
+.. method:: LCD160CR.rect_interior_no_clip(x, y, w, h)
+.. method:: LCD160CR.line_no_clip(x1, y1, x2, y2)
+
+    These methods are as above but don't do any clipping on the input
+    coordinates.  They are faster than the clipping versions and can be
+    used when you know that the coordinates are within the display.
+
+.. method:: LCD160CR.poly_dot(data)
+
+    Draw a sequence of dots using the pen line color.
+    The *data* should be a buffer of bytes, with each successive pair of
+    bytes corresponding to coordinate pairs (x, y).
+
+.. method:: LCD160CR.poly_line(data)
+
+    Similar to :meth:`LCD160CR.poly_dot` but draws lines between the dots.
+
+Touch screen methods
+--------------------
+
+.. method:: LCD160CR.touch_config(calib=False, save=False, irq=None)
+
+    Configure the touch panel:
+
+        - If *calib* is ``True`` then the call will trigger a touch calibration of
+          the resistive touch sensor.  This requires the user to touch various
+          parts of the screen.
+        - If *save* is ``True`` then the touch parameters will be saved to NVRAM
+          to persist across reset/power up.
+        - If *irq* is ``True`` then the display will be configured to pull the IRQ
+          line low when a touch force is detected.  If *irq* is ``False`` then this
+          feature is disabled.  If *irq* is ``None`` (the default value) then no
+          change is made to this setting.
+
+.. method:: LCD160CR.is_touched()
+
+    Returns a boolean: ``True`` if there is currently a touch force on the screen,
+    `False` otherwise.
+
+.. method:: LCD160CR.get_touch()
+
+    Returns a 3-tuple of: *(active, x, y)*.  If there is currently a touch force
+    on the screen then *active* is 1, otherwise it is 0.  The *x* and *y* values
+    indicate the position of the current or most recent touch.
+
+Advanced commands
+-----------------
+
+.. method:: LCD160CR.set_spi_win(x, y, w, h)
+
+    Set the window that SPI data is written to.
+
+.. method:: LCD160CR.fast_spi(flush=True)
+
+    Ready the display to accept RGB pixel data on the SPI bus, resetting the location
+    of the first byte to go to the top-left corner of the window set by
+    :meth:`LCD160CR.set_spi_win`.
+    The method returns an SPI object which can be used to write the pixel data.
+
+    Pixels should be sent as 16-bit RGB values in the 5-6-5 format.  The destination
+    counter will increase as data is sent, and data can be sent in arbitrary sized
+    chunks.  Once the destination counter reaches the end of the window specified by
+    :meth:`LCD160CR.set_spi_win` it will wrap around to the top-left corner of that window.
+
+.. method:: LCD160CR.show_framebuf(buf)
+
+    Show the given buffer on the display.  *buf* should be an array of bytes containing
+    the 16-bit RGB values for the pixels, and they will be written to the area
+    specified by :meth:`LCD160CR.set_spi_win`, starting from the top-left corner.
+
+    The `framebuf <framebuf.html>`_ module can be used to construct frame buffers
+    and provides drawing primitives. Using a frame buffer will improve 
+    performance of animations when compared to drawing directly to the screen.
+
+.. method:: LCD160CR.set_scroll(on)
+
+    Turn scrolling on or off.  This controls globally whether any window regions will
+    scroll.
+
+.. method:: LCD160CR.set_scroll_win(win, x=-1, y=0, w=0, h=0, vec=0, pat=0, fill=0x07e0, color=0)
+
+    Configure a window region for scrolling:
+
+        - *win* is the window id to configure.  There are 0..7 standard windows for
+          general purpose use.  Window 8 is the text scroll window (the ticker).
+        - *x*, *y*, *w*, *h* specify the location of the window in the display.
+        - *vec* specifies the direction and speed of scroll: it is a 16-bit value
+          of the form ``0bF.ddSSSSSSSSSSSS``.  *dd* is 0, 1, 2, 3 for +x, +y, -x,
+          -y scrolling. *F* sets the speed format, with 0 meaning that the window
+          is shifted *S % 256* pixel every frame, and 1 meaning that the window
+          is shifted 1 pixel every *S* frames.
+        - *pat* is a 16-bit pattern mask for the background.
+        - *fill* is the fill color.
+        - *color* is the extra color, either of the text or pattern foreground.
+
+.. method:: LCD160CR.set_scroll_win_param(win, param, value)
+
+    Set a single parameter of a scrolling window region:
+    
+        - *win* is the window id, 0..8.
+        - *param* is the parameter number to configure, 0..7, and corresponds
+          to the parameters in the `set_scroll_win` method.
+        - *value* is the value to set.
+
+.. method:: LCD160CR.set_scroll_buf(s)
+
+    Set the string for scrolling in window 8.  The parameter *s* must be a string
+    with length 32 or less.
+
+.. method:: LCD160CR.jpeg(buf)
+
+    Display a JPEG.  *buf* should contain the entire JPEG data. JPEG data should
+    not include EXIF information. The following encodings are supported: Baseline
+    DCT, Huffman coding, 8 bits per sample, 3 color components, YCbCr4:2:2.
+    The origin of the JPEG is set by :meth:`LCD160CR.set_pos`.
+
+.. method:: LCD160CR.jpeg_start(total_len)
+.. method:: LCD160CR.jpeg_data(buf)
+
+    Display a JPEG with the data split across multiple buffers.  There must be
+    a single call to `jpeg_start` to begin with, specifying the total number of
+    bytes in the JPEG.  Then this number of bytes must be transferred to the
+    display using one or more calls to the `jpeg_data` command.
+
+.. method:: LCD160CR.feed_wdt()
+
+    The first call to this method will start the display's internal watchdog
+    timer.  Subsequent calls will feed the watchdog.  The timeout is roughly 30
+    seconds.
+
+.. method:: LCD160CR.reset()
+
+    Reset the display.
+
+Constants
+---------
+
+.. data:: lcd160cr.PORTRAIT
+          lcd160cr.LANDSCAPE
+          lcd160cr.PORTRAIT_UPSIDEDOWN
+          lcd160cr.LANDSCAPE_UPSIDEDOWN
+
+   Orientations of the display, used by :meth:`LCD160CR.set_orient`.
+
+.. data:: lcd160cr.STARTUP_DECO_NONE
+          lcd160cr.STARTUP_DECO_MLOGO
+          lcd160cr.STARTUP_DECO_INFO
+
+   Types of start-up decoration, can be OR'ed together, used by
+   :meth:`LCD160CR.set_startup_deco`.

docs/library/machine.ADC.rst

@@ -0,0 +1,74 @@
+.. currentmodule:: machine
+.. _machine.ADC:
+
+class ADC -- analog to digital conversion
+=========================================
+
+Usage::
+
+   import machine
+
+   adc = machine.ADC()             # create an ADC object
+   apin = adc.channel(pin='GP3')   # create an analog pin on GP3
+   val = apin()                    # read an analog value
+
+Constructors
+------------
+
+.. class:: ADC(id=0, \*, bits=12)
+
+   Create an ADC object associated with the given pin.
+   This allows you to then read analog values on that pin.
+   For more info check the `pinout and alternate functions
+   table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ 
+
+   .. warning:: 
+
+      ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it 
+      can withstand). When GP2, GP3, GP4 or GP5 are remapped to the 
+      ADC block, 1.8 V is the maximum. If these pins are used in digital mode, 
+      then the maximum allowed input is 3.6V.
+
+Methods
+-------
+
+.. method:: ADC.channel(id, \*, pin)
+
+   Create an analog pin. If only channel ID is given, the correct pin will
+   be selected. Alternatively, only the pin can be passed and the correct
+   channel will be selected. Examples::
+
+      # all of these are equivalent and enable ADC channel 1 on GP3
+      apin = adc.channel(1)
+      apin = adc.channel(pin='GP3')
+      apin = adc.channel(id=1, pin='GP3')
+
+.. method:: ADC.init()
+
+   Enable the ADC block.
+
+.. method:: ADC.deinit()
+
+   Disable the ADC block.
+
+class ADCChannel --- read analog values from internal or external sources
+=========================================================================
+
+ADC channels can be connected to internal points of the MCU or to GPIO pins.
+ADC channels are created using the ADC.channel method.
+
+.. method:: adcchannel()
+
+   Fast method to read the channel value.
+
+.. method:: adcchannel.value()
+
+   Read the channel value.
+
+.. method:: adcchannel.init()
+
+   Re-init (and effectively enable) the ADC channel.
+
+.. method:: adcchannel.deinit()
+
+   Disable the ADC channel.

docs/library/machine.I2C.rst

@@ -0,0 +1,172 @@
+.. currentmodule:: machine
+.. _machine.I2C:
+
+class I2C -- a two-wire serial protocol
+=======================================
+
+I2C is a two-wire protocol for communicating between devices.  At the physical
+level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
+
+I2C objects are created attached to a specific bus.  They can be initialised
+when created, or initialised later on.
+
+Printing the I2C object gives you information about its configuration.
+
+Example usage::
+
+    from machine import I2C
+
+    i2c = I2C(freq=400000)          # create I2C peripheral at frequency of 400kHz
+                                    # depending on the port, extra parameters may be required
+                                    # to select the peripheral and/or pins to use
+
+    i2c.scan()                      # scan for slaves, returning a list of 7-bit addresses
+
+    i2c.writeto(42, b'123')         # write 3 bytes to slave with 7-bit address 42
+    i2c.readfrom(42, 4)             # read 4 bytes from slave with 7-bit address 42
+
+    i2c.readfrom_mem(42, 8, 3)      # read 3 bytes from memory of slave 42,
+                                    #   starting at memory-address 8 in the slave
+    i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of slave 42
+                                    #   starting at address 2 in the slave
+
+Constructors
+------------
+
+.. class:: I2C(id=-1, \*, scl, sda, freq=400000)
+
+   Construct and return a new I2C object using the following parameters:
+
+      - *id* identifies a particular I2C peripheral.  The default
+        value of -1 selects a software implementation of I2C which can
+        work (in most cases) with arbitrary pins for SCL and SDA.
+        If *id* is -1 then *scl* and *sda* must be specified.  Other
+        allowed values for *id* depend on the particular port/board,
+        and specifying *scl* and *sda* may or may not be required or
+        allowed in this case.
+      - *scl* should be a pin object specifying the pin to use for SCL.
+      - *sda* should be a pin object specifying the pin to use for SDA.
+      - *freq* should be an integer which sets the maximum frequency
+        for SCL.
+
+General Methods
+---------------
+
+.. method:: I2C.init(scl, sda, \*, freq=400000)
+
+  Initialise the I2C bus with the given arguments:
+
+     - *scl* is a pin object for the SCL line
+     - *sda* is a pin object for the SDA line
+     - *freq* is the SCL clock rate
+
+.. method:: I2C.deinit()
+
+   Turn off the I2C bus.
+
+   Availability: WiPy.
+
+.. method:: I2C.scan()
+
+   Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of
+   those that respond.  A device responds if it pulls the SDA line low after
+   its address (including a write bit) is sent on the bus.
+
+Primitive I2C operations
+------------------------
+
+The following methods implement the primitive I2C master bus operations and can
+be combined to make any I2C transaction.  They are provided if you need more
+control over the bus, otherwise the standard methods (see below) can be used.
+
+.. method:: I2C.start()
+
+   Generate a START condition on the bus (SDA transitions to low while SCL is high).
+
+   Availability: ESP8266.
+
+.. method:: I2C.stop()
+
+   Generate a STOP condition on the bus (SDA transitions to high while SCL is high).
+
+   Availability: ESP8266.
+
+.. method:: I2C.readinto(buf, nack=True)
+
+   Reads bytes from the bus and stores them into *buf*.  The number of bytes
+   read is the length of *buf*.  An ACK will be sent on the bus after
+   receiving all but the last byte.  After the last byte is received, if *nack*
+   is true then a NACK will be sent, otherwise an ACK will be sent (and in this
+   case the slave assumes more bytes are going to be read in a later call).
+
+   Availability: ESP8266.
+
+.. method:: I2C.write(buf)
+
+   Write the bytes from *buf* to the bus.  Checks that an ACK is received
+   after each byte and stops transmitting the remaining bytes if a NACK is
+   received.  The function returns the number of ACKs that were received.
+
+   Availability: ESP8266.
+
+Standard bus operations
+-----------------------
+
+The following methods implement the standard I2C master read and write
+operations that target a given slave device.
+
+.. method:: I2C.readfrom(addr, nbytes, stop=True)
+
+   Read *nbytes* from the slave specified by *addr*.
+   If *stop* is true then a STOP condition is generated at the end of the transfer.
+   Returns a `bytes` object with the data read.
+
+.. method:: I2C.readfrom_into(addr, buf, stop=True)
+
+   Read into *buf* from the slave specified by *addr*.
+   The number of bytes read will be the length of *buf*.
+   If *stop* is true then a STOP condition is generated at the end of the transfer.
+
+   The method returns ``None``.
+
+.. method:: I2C.writeto(addr, buf, stop=True)
+
+   Write the bytes from *buf* to the slave specified by *addr*.  If a
+   NACK is received following the write of a byte from *buf* then the
+   remaining bytes are not sent.  If *stop* is true then a STOP condition is
+   generated at the end of the transfer, even if a NACK is received.
+   The function returns the number of ACKs that were received.
+
+Memory operations
+-----------------
+
+Some I2C devices act as a memory device (or set of registers) that can be read
+from and written to.  In this case there are two addresses associated with an
+I2C transaction: the slave address and the memory address.  The following
+methods are convenience functions to communicate with such devices.
+
+.. method:: I2C.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
+
+   Read *nbytes* from the slave specified by *addr* starting from the memory
+   address specified by *memaddr*.
+   The argument *addrsize* specifies the address size in bits.
+   Returns a `bytes` object with the data read.
+
+.. method:: I2C.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
+
+   Read into *buf* from the slave specified by *addr* starting from the
+   memory address specified by *memaddr*.  The number of bytes read is the
+   length of *buf*.
+   The argument *addrsize* specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+
+   The method returns ``None``.
+
+.. method:: I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
+
+   Write *buf* to the slave specified by *addr* starting from the
+   memory address specified by *memaddr*.
+   The argument *addrsize* specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+
+   The method returns ``None``.

docs/library/machine.Pin.rst

@@ -0,0 +1,248 @@
+.. currentmodule:: machine
+.. _machine.Pin:
+
+class Pin -- control I/O pins
+=============================
+
+A pin object is used to control I/O pins (also known as GPIO - general-purpose
+input/output).  Pin objects are commonly associated with a physical pin that can
+drive an output voltage and read input voltages.  The pin class has methods to set the mode of
+the pin (IN, OUT, etc) and methods to get and set the digital logic level.
+For analog control of a pin, see the :class:`ADC` class.
+
+A pin object is constructed by using an identifier which unambiguously
+specifies a certain I/O pin.  The allowed forms of the identifier and the
+physical pin that the identifier maps to are port-specific.  Possibilities
+for the identifier are an integer, a string or a tuple with port and pin
+number.
+
+Usage Model::
+
+    from machine import Pin
+
+    # create an output pin on pin #0
+    p0 = Pin(0, Pin.OUT)
+
+    # set the value low then high
+    p0.value(0)
+    p0.value(1)
+
+    # create an input pin on pin #2, with a pull up resistor
+    p2 = Pin(2, Pin.IN, Pin.PULL_UP)
+
+    # read and print the pin value
+    print(p2.value())
+
+    # reconfigure pin #0 in input mode
+    p0.mode(p0.IN)
+
+    # configure an irq callback
+    p0.irq(lambda p:print(p))
+
+Constructors
+------------
+
+.. class:: Pin(id, mode=-1, pull=-1, \*, value, drive, alt)
+
+   Access the pin peripheral (GPIO pin) associated with the given ``id``.  If
+   additional arguments are given in the constructor then they are used to initialise
+   the pin.  Any settings that are not specified will remain in their previous state.
+
+   The arguments are:
+
+     - ``id`` is mandatory and can be an arbitrary object.  Among possible value
+       types are: int (an internal Pin identifier), str (a Pin name), and tuple
+       (pair of [port, pin]).
+
+     - ``mode`` specifies the pin mode, which can be one of:
+
+       - ``Pin.IN`` - Pin is configured for input.  If viewed as an output the pin
+         is in high-impedance state.
+
+       - ``Pin.OUT`` - Pin is configured for (normal) output.
+
+       - ``Pin.OPEN_DRAIN`` - Pin is configured for open-drain output. Open-drain
+         output works in the following way: if the output value is set to 0 the pin
+         is active at a low level; if the output value is 1 the pin is in a high-impedance
+         state.  Not all ports implement this mode, or some might only on certain pins.
+
+       - ``Pin.ALT`` - Pin is configured to perform an alternative function, which is
+         port specific.  For a pin configured in such a way any other Pin methods
+         (except :meth:`Pin.init`) are not applicable (calling them will lead to undefined,
+         or a hardware-specific, result).  Not all ports implement this mode.
+
+       - ``Pin.ALT_OPEN_DRAIN`` - The Same as ``Pin.ALT``, but the pin is configured as
+         open-drain.  Not all ports implement this mode.
+
+     - ``pull`` specifies if the pin has a (weak) pull resistor attached, and can be
+       one of:
+
+       - ``None`` - No pull up or down resistor.
+       - ``Pin.PULL_UP`` - Pull up resistor enabled.
+       - ``Pin.PULL_DOWN`` - Pull down resistor enabled.
+
+     - ``value`` is valid only for Pin.OUT and Pin.OPEN_DRAIN modes and specifies initial
+       output pin value if given, otherwise the state of the pin peripheral remains
+       unchanged.
+
+     - ``drive`` specifies the output power of the pin and can be one of: ``Pin.LOW_POWER``,
+       ``Pin.MED_POWER`` or ``Pin.HIGH_POWER``.  The actual current driving capabilities
+       are port dependent.  Not all ports implement this argument.
+
+     - ``alt`` specifies an alternate function for the pin and the values it can take are
+       port dependent.  This argument is valid only for ``Pin.ALT`` and ``Pin.ALT_OPEN_DRAIN``
+       modes.  It may be used when a pin supports more than one alternate function.  If only
+       one pin alternate function is supported the this argument is not required.  Not all
+       ports implement this argument.
+
+   As specified above, the Pin class allows to set an alternate function for a particular
+   pin, but it does not specify any further operations on such a pin.  Pins configured in
+   alternate-function mode are usually not used as GPIO but are instead driven by other
+   hardware peripherals.  The only operation supported on such a pin is re-initialising,
+   by calling the constructor or :meth:`Pin.init` method.  If a pin that is configured in
+   alternate-function mode is re-initialised with ``Pin.IN``, ``Pin.OUT``, or
+   ``Pin.OPEN_DRAIN``, the alternate function will be removed from the pin.
+
+Methods
+-------
+
+.. method:: Pin.init(mode=-1, pull=-1, \*, value, drive, alt)
+
+   Re-initialise the pin using the given parameters.  Only those arguments that
+   are specified will be set.  The rest of the pin peripheral state will remain
+   unchanged.  See the constructor documentation for details of the arguments.
+
+   Returns ``None``.
+
+.. method:: Pin.value([x])
+
+   This method allows to set and get the value of the pin, depending on whether
+   the argument ``x`` is supplied or not.
+
+   If the argument is omitted then this method gets the digital logic level of
+   the pin, returning 0 or 1 corresponding to low and high voltage signals
+   respectively.  The behaviour of this method depends on the mode of the pin:
+
+     - ``Pin.IN`` - The method returns the actual input value currently present
+       on the pin.
+     - ``Pin.OUT`` - The behaviour and return value of the method is undefined.
+     - ``Pin.OPEN_DRAIN`` - If the pin is in state '0' then the behaviour and
+       return value of the method is undefined.  Otherwise, if the pin is in
+       state '1', the method returns the actual input value currently present
+       on the pin.
+
+   If the argument is supplied then this method sets the digital logic level of
+   the pin.  The argument ``x`` can be anything that converts to a boolean.
+   If it converts to ``True``, the pin is set to state '1', otherwise it is set
+   to state '0'.  The behaviour of this method depends on the mode of the pin:
+
+     - ``Pin.IN`` - The value is stored in the output buffer for the pin.  The
+       pin state does not change, it remains in the high-impedance state.  The
+       stored value will become active on the pin as soon as it is changed to
+       ``Pin.OUT`` or ``Pin.OPEN_DRAIN`` mode.
+     - ``Pin.OUT`` - The output buffer is set to the given value immediately.
+     - ``Pin.OPEN_DRAIN`` - If the value is '0' the pin is set to a low voltage
+       state.  Otherwise the pin is set to high-impedance state.
+
+   When setting the value this method returns ``None``.
+
+.. method:: Pin.__call__([x])
+
+   Pin objects are callable.  The call method provides a (fast) shortcut to set
+   and get the value of the pin.  It is equivalent to Pin.value([x]).
+   See :meth:`Pin.value` for more details.
+
+.. method:: Pin.on()
+
+   Set pin to "1" output level.
+
+.. method:: Pin.off()
+
+   Set pin to "0" output level.
+
+.. method:: Pin.mode([mode])
+
+   Get or set the pin mode.
+   See the constructor documentation for details of the ``mode`` argument.
+
+.. method:: Pin.pull([pull])
+
+   Get or set the pin pull state.
+   See the constructor documentation for details of the ``pull`` argument.
+
+.. method:: Pin.drive([drive])
+
+   Get or set the pin drive strength.
+   See the constructor documentation for details of the ``drive`` argument.
+
+   Not all ports implement this method.
+
+   Availability: WiPy.
+
+.. method:: Pin.irq(handler=None, trigger=(Pin.IRQ_FALLING | Pin.IRQ_RISING), \*, priority=1, wake=None)
+
+   Configure an interrupt handler to be called when the trigger source of the
+   pin is active.  If the pin mode is ``Pin.IN`` then the trigger source is
+   the external value on the pin.  If the pin mode is ``Pin.OUT`` then the
+   trigger source is the output buffer of the pin.  Otherwise, if the pin mode
+   is ``Pin.OPEN_DRAIN`` then the trigger source is the output buffer for
+   state '0' and the external pin value for state '1'.
+
+   The arguments are:
+
+     - ``handler`` is an optional function to be called when the interrupt
+       triggers.
+
+     - ``trigger`` configures the event which can generate an interrupt.
+       Possible values are:
+
+       - ``Pin.IRQ_FALLING`` interrupt on falling edge.
+       - ``Pin.IRQ_RISING`` interrupt on rising edge.
+       - ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
+       - ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
+
+       These values can be OR'ed together to trigger on multiple events.
+
+     - ``priority`` sets the priority level of the interrupt.  The values it
+       can take are port-specific, but higher values always represent higher
+       priorities.
+
+     - ``wake`` selects the power mode in which this interrupt can wake up the
+       system.  It can be ``machine.IDLE``, ``machine.SLEEP`` or ``machine.DEEPSLEEP``.
+       These values can also be OR'ed together to make a pin generate interrupts in
+       more than one power mode.
+
+   This method returns a callback object.
+
+Constants
+---------
+
+The following constants are used to configure the pin objects.  Note that
+not all constants are available on all ports.
+
+.. data:: Pin.IN
+          Pin.OUT
+          Pin.OPEN_DRAIN
+          Pin.ALT
+          Pin.ALT_OPEN_DRAIN
+
+   Selects the pin mode.
+
+.. data:: Pin.PULL_UP
+          Pin.PULL_DOWN
+
+   Selects whether there is a pull up/down resistor.  Use the value
+   ``None`` for no pull.
+
+.. data:: Pin.LOW_POWER
+          Pin.MED_POWER
+          Pin.HIGH_POWER
+
+   Selects the pin drive strength.
+
+.. data:: Pin.IRQ_FALLING
+          Pin.IRQ_RISING
+          Pin.IRQ_LOW_LEVEL
+          Pin.IRQ_HIGH_LEVEL
+
+   Selects the IRQ trigger type.

docs/library/machine.RTC.rst

@@ -0,0 +1,69 @@
+.. currentmodule:: machine
+.. _machine.RTC:
+
+class RTC -- real time clock
+============================
+
+The RTC is and independent clock that keeps track of the date
+and time.
+
+Example usage::
+
+    rtc = machine.RTC()
+    rtc.init((2014, 5, 1, 4, 13, 0, 0, 0))
+    print(rtc.now())
+
+
+Constructors
+------------
+
+.. class:: RTC(id=0, ...)
+
+   Create an RTC object. See init for parameters of initialization.
+
+Methods
+-------
+
+.. method:: RTC.init(datetime)
+
+   Initialise the RTC. Datetime is a tuple of the form:
+   
+      ``(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])``
+
+.. method:: RTC.now()
+
+   Get get the current datetime tuple.
+
+.. method:: RTC.deinit()
+
+   Resets the RTC to the time of January 1, 2015 and starts running it again.
+
+.. method:: RTC.alarm(id, time, \*, repeat=False)
+
+   Set the RTC alarm. Time might be either a millisecond value to program the alarm to
+   current time + time_in_ms in the future, or a datetimetuple. If the time passed is in
+   milliseconds, repeat can be set to ``True`` to make the alarm periodic.
+
+.. method:: RTC.alarm_left(alarm_id=0)
+
+   Get the number of milliseconds left before the alarm expires.
+
+.. method:: RTC.cancel(alarm_id=0)
+
+   Cancel a running alarm.
+
+.. method:: RTC.irq(\*, trigger, handler=None, wake=machine.IDLE)
+
+   Create an irq object triggered by a real time clock alarm.
+
+      - ``trigger`` must be ``RTC.ALARM0``
+      - ``handler`` is the function to be called when the callback is triggered.
+      - ``wake`` specifies the sleep mode from where this interrupt can wake
+        up the system.
+
+Constants
+---------
+
+.. data:: RTC.ALARM0
+
+    irq trigger source

docs/library/machine.SD.rst

@@ -0,0 +1,42 @@
+.. currentmodule:: machine
+.. _machine.SD:
+
+class SD -- secure digital memory card
+======================================
+
+The SD card class allows to configure and enable the memory card
+module of the WiPy and automatically mount it as ``/sd`` as part
+of the file system. There are several pin combinations that can be
+used to wire the SD card socket to the WiPy and the pins used can
+be specified in the constructor. Please check the `pinout and alternate functions
+table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ for
+more info regarding the pins which can be remapped to be used with a SD card.
+
+Example usage::
+
+    from machine import SD
+    import os
+    # clk cmd and dat0 pins must be passed along with
+    # their respective alternate functions
+    sd = machine.SD(pins=('GP10', 'GP11', 'GP15'))
+    os.mount(sd, '/sd')
+    # do normal file operations
+
+Constructors
+------------
+
+.. class:: SD(id,... )
+
+   Create a SD card object. See ``init()`` for parameters if initialization. 
+
+Methods
+-------
+
+.. method:: SD.init(id=0, pins=('GP10', 'GP11', 'GP15'))
+
+   Enable the SD card. In order to initialize the card, give it a 3-tuple:
+   ``(clk_pin, cmd_pin, dat0_pin)``.
+
+.. method:: SD.deinit()
+
+   Disable the SD card.

docs/library/machine.SPI.rst

@@ -0,0 +1,97 @@
+.. currentmodule:: machine
+.. _machine.SPI:
+
+class SPI -- a Serial Peripheral Interface bus protocol (master side)
+=====================================================================
+
+SPI is a synchronous serial protocol that is driven by a master. At the
+physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices
+can share the same bus. Each device should have a separate, 4th signal,
+SS (Slave Select), to select a particular device on a bus with which
+communication takes place. Management of an SS signal should happen in
+user code (via machine.Pin class).
+
+Constructors
+------------
+
+.. class:: SPI(id, ...)
+
+   Construct an SPI object on the given bus, ``id``. Values of ``id`` depend
+   on a particular port and its hardware. Values 0, 1, etc. are commonly used
+   to select hardware SPI block #0, #1, etc. Value -1 can be used for
+   bitbanging (software) implementation of SPI (if supported by a port).
+
+   With no additional parameters, the SPI object is created but not
+   initialised (it has the settings from the last initialisation of
+   the bus, if any).  If extra arguments are given, the bus is initialised.
+   See ``init`` for parameters of initialisation.
+
+Methods
+-------
+
+.. method:: SPI.init(baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, sck=None, mosi=None, miso=None, pins=(SCK, MOSI, MISO))
+
+   Initialise the SPI bus with the given parameters:
+
+     - ``baudrate`` is the SCK clock rate.
+     - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
+     - ``phase`` can be 0 or 1 to sample data on the first or second clock edge
+       respectively.
+     - ``bits`` is the width in bits of each transfer. Only 8 is guaranteed to be supported by all hardware.
+     - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
+     - ``sck``, ``mosi``, ``miso`` are pins (machine.Pin) objects to use for bus signals. For most
+       hardware SPI blocks (as selected by ``id`` parameter to the constructor), pins are fixed
+       and cannot be changed. In some cases, hardware blocks allow 2-3 alternative pin sets for
+       a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver
+       (``id`` = -1).
+     - ``pins`` - WiPy port doesn't ``sck``, ``mosi``, ``miso`` arguments, and instead allows to
+       specify them as a tuple of ``pins`` parameter.
+
+.. method:: SPI.deinit()
+
+   Turn off the SPI bus.
+
+.. method:: SPI.read(nbytes, write=0x00)
+
+    Read a number of bytes specified by ``nbytes`` while continuously writing
+    the single byte given by ``write``.
+    Returns a ``bytes`` object with the data that was read.
+
+.. method:: SPI.readinto(buf, write=0x00)
+
+    Read into the buffer specified by ``buf`` while continuously writing the
+    single byte given by ``write``.
+    Returns ``None``.
+
+    Note: on WiPy this function returns the number of bytes read.
+
+.. method:: SPI.write(buf)
+
+    Write the bytes contained in ``buf``.
+    Returns ``None``.
+
+    Note: on WiPy this function returns the number of bytes written.
+
+.. method:: SPI.write_readinto(write_buf, read_buf)
+
+    Write the bytes from ``write_buf`` while reading into ``read_buf``.  The
+    buffers can be the same or different, but both buffers must have the
+    same length.
+    Returns ``None``.
+
+    Note: on WiPy this function returns the number of bytes written.
+
+Constants
+---------
+
+.. data:: SPI.MASTER
+
+   for initialising the SPI bus to master; this is only used for the WiPy
+
+.. data:: SPI.MSB
+
+   set the first bit to be the most significant bit
+
+.. data:: SPI.LSB
+
+   set the first bit to be the least significant bit

docs/library/machine.Signal.rst

@@ -0,0 +1,123 @@
+.. currentmodule:: machine
+.. _machine.Signal:
+
+class Signal -- control and sense external I/O devices
+======================================================
+
+The Signal class is a simple extension of the `Pin` class. Unlike Pin, which
+can be only in "absolute" 0 and 1 states, a Signal can be in "asserted"
+(on) or "deasserted" (off) states, while being inverted (active-low) or
+not. In other words, it adds logical inversion support to Pin functionality.
+While this may seem a simple addition, it is exactly what is needed to
+support wide array of simple digital devices in a way portable across
+different boards, which is one of the major MicroPython goals. Regardless
+of whether different users have an active-high or active-low LED, a normally
+open or normally closed relay - you can develop a single, nicely looking
+application which works with each of them, and capture hardware
+configuration differences in few lines in the config file of your app.
+
+Example::
+
+    from machine import Pin, Signal
+
+    # Suppose you have an active-high LED on pin 0
+    led1_pin = Pin(0, Pin.OUT)
+    # ... and active-low LED on pin 1
+    led2_pin = Pin(1, Pin.OUT)
+
+    # Now to light up both of them using Pin class, you'll need to set
+    # them to different values
+    led1_pin.value(1)
+    led2_pin.value(0)
+
+    # Signal class allows to abstract away active-high/active-low
+    # difference
+    led1 = Signal(led1_pin, invert=False)
+    led2 = Signal(led2_pin, invert=True)
+
+    # Now lighting up them looks the same
+    led1.value(1)
+    led2.value(1)
+
+    # Even better:
+    led1.on()
+    led2.on()
+
+Following is the guide when Signal vs Pin should be used:
+
+* Use Signal: If you want to control a simple on/off (including software
+  PWM!) devices like LEDs, multi-segment indicators, relays, buzzers, or
+  read simple binary sensors, like normally open or normally closed buttons,
+  pulled high or low, Reed switches, moisture/flame detectors, etc. etc.
+  Summing up, if you have a real physical device/sensor requiring GPIO
+  access, you likely should use a Signal.
+
+* Use Pin: If you implement a higher-level protocol or bus to communicate
+  with more complex devices.
+
+The split between Pin and Signal come from the usecases above and the
+architecture of MicroPython: Pin offers the lowest overhead, which may
+be important when bit-banging protocols. But Signal adds additional
+flexibility on top of Pin, at the cost of minor overhead (much smaller
+than if you implemented active-high vs active-low device differences in
+Python manually!). Also, Pin is a low-level object which needs to be
+implemented for each support board, while Signal is a high-level object
+which comes for free once Pin is implemented.
+
+If in doubt, give the Signal a try! Once again, it is offered to save
+developers from the need to handle unexciting differences like active-low
+vs active-high signals, and allow other users to share and enjoy your
+application, instead of being frustrated by the fact that it doesn't
+work for them simply because their LEDs or relays are wired in a slightly
+different way.
+
+Constructors
+------------
+
+.. class:: Signal(pin_obj, invert=False)
+           Signal(pin_arguments..., \*, invert=False)
+
+   Create a Signal object. There're two ways to create it:
+
+   * By wrapping existing Pin object - universal method which works for
+     any board.
+   * By passing required Pin parameters directly to Signal constructor,
+     skipping the need to create intermediate Pin object. Available on
+     many, but not all boards.
+
+   The arguments are:
+
+     - ``pin_obj`` is existing Pin object.
+
+     - ``pin_arguments`` are the same arguments as can be passed to Pin constructor.
+
+     - ``invert`` - if True, the signal will be inverted (active low).
+
+Methods
+-------
+
+.. method:: Signal.value([x])
+
+   This method allows to set and get the value of the signal, depending on whether
+   the argument ``x`` is supplied or not.
+
+   If the argument is omitted then this method gets the signal level, 1 meaning
+   signal is asserted (active) and 0 - signal inactive.
+
+   If the argument is supplied then this method sets the signal level. The
+   argument ``x`` can be anything that converts to a boolean. If it converts
+   to ``True``, the signal is active, otherwise it is inactive.
+
+   Correspondence between signal being active and actual logic level on the
+   underlying pin depends on whether signal is inverted (active-low) or not.
+   For non-inverted signal, active status corresponds to logical 1, inactive -
+   to logical 0. For inverted/active-low signal, active status corresponds
+   to logical 0, while inactive - to logical 1.
+
+.. method:: Signal.on()
+
+   Activate signal.
+
+.. method:: Signal.off()
+
+   Deactivate signal.

docs/library/machine.Timer.rst

@@ -0,0 +1,160 @@
+.. currentmodule:: machine
+.. _machine.Timer:
+
+class Timer -- control hardware timers
+======================================
+
+Hardware timers deal with timing of periods and events. Timers are perhaps
+the most flexible and heterogeneous kind of hardware in MCUs and SoCs,
+differently greatly from a model to a model. MicroPython's Timer class
+defines a baseline operation of executing a callback with a given period
+(or once after some delay), and allow specific boards to define more
+non-standard behavior (which thus won't be portable to other boards).
+
+See discussion of :ref:`important constraints <machine_callbacks>` on
+Timer callbacks.
+
+.. note::
+
+    Memory can't be allocated inside irq handlers (an interrupt) and so
+    exceptions raised within a handler don't give much information.  See
+    :func:`micropython.alloc_emergency_exception_buf` for how to get around this
+    limitation.
+
+Constructors
+------------
+
+.. class:: Timer(id, ...)
+
+   Construct a new timer object of the given id. Id of -1 constructs a
+   virtual timer (if supported by a board).
+
+Methods
+-------
+
+.. only:: port_wipy
+
+    .. method:: Timer.init(mode, \*, width=16)
+
+       Initialise the timer. Example::
+
+           tim.init(Timer.PERIODIC)             # periodic 16-bit timer
+           tim.init(Timer.ONE_SHOT, width=32)   # one shot 32-bit timer
+
+       Keyword arguments:
+       
+         - ``mode`` can be one of:
+         
+           - ``Timer.ONE_SHOT`` - The timer runs once until the configured 
+             period of the channel expires.
+           - ``Timer.PERIODIC`` - The timer runs periodically at the configured 
+             frequency of the channel.
+           - ``Timer.PWM``      - Output a PWM signal on a pin.
+
+         - ``width`` must be either 16 or 32 (bits). For really low frequencies < 5Hz
+           (or large periods), 32-bit timers should be used. 32-bit mode is only available
+           for ``ONE_SHOT`` AND ``PERIODIC`` modes.
+
+.. method:: Timer.deinit()
+
+   Deinitialises the timer. Stops the timer, and disables the timer peripheral.
+
+.. only:: port_wipy
+
+    .. method:: Timer.channel(channel, \**, freq, period, polarity=Timer.POSITIVE, duty_cycle=0)
+    
+       If only a channel identifier passed, then a previously initialized channel
+       object is returned (or ``None`` if there is no previous channel).
+
+       Otherwise, a TimerChannel object is initialized and returned.
+       
+       The operating mode is is the one configured to the Timer object that was used to
+       create the channel.
+
+       - ``channel`` if the width of the timer is 16-bit, then must be either ``TIMER.A``, ``TIMER.B``. 
+         If the width is 32-bit then it **must be** ``TIMER.A | TIMER.B``.
+
+       Keyword only arguments:
+
+         - ``freq`` sets the frequency in Hz.
+         - ``period`` sets the period in microseconds.
+
+         .. note::
+
+            Either ``freq`` or ``period`` must be given, never both.
+
+         - ``polarity`` this is applicable for ``PWM``, and defines the polarity of the duty cycle
+         - ``duty_cycle`` only applicable to ``PWM``. It's a percentage (0.00-100.00). Since the WiPy
+           doesn't support floating point numbers the duty cycle must be specified in the range 0-10000,
+           where 10000 would represent 100.00, 5050 represents 50.50, and so on.
+
+       .. note::
+
+          When the channel is in PWM mode, the corresponding pin is assigned automatically, therefore
+          there's no need to assign the alternate function of the pin via the ``Pin`` class. The pins which
+          support PWM functionality are the following:
+
+          - ``GP24`` on Timer 0 channel A.
+          - ``GP25`` on Timer 1 channel A.
+          - ``GP9``  on Timer 2 channel B.
+          - ``GP10`` on Timer 3 channel A.
+          - ``GP11`` on Timer 3 channel B.
+
+.. only:: port_wipy
+
+    class TimerChannel --- setup a channel for a timer
+    ==================================================
+
+    Timer channels are used to generate/capture a signal using a timer.
+
+    TimerChannel objects are created using the Timer.channel() method.
+
+    Methods
+    -------
+
+    .. method:: timerchannel.irq(\*, trigger, priority=1, handler=None)
+
+        The behavior of this callback is heavily dependent on the operating
+        mode of the timer channel:
+
+            - If mode is ``Timer.PERIODIC`` the callback is executed periodically
+              with the configured frequency or period.
+            - If mode is ``Timer.ONE_SHOT`` the callback is executed once when
+              the configured timer expires.
+            - If mode is ``Timer.PWM`` the callback is executed when reaching the duty
+              cycle value.
+
+        The accepted params are:
+
+            - ``priority`` level of the interrupt. Can take values in the range 1-7.
+              Higher values represent higher priorities.
+            - ``handler`` is an optional function to be called when the interrupt is triggered.
+            - ``trigger`` must be ``Timer.TIMEOUT`` when the operating mode is either ``Timer.PERIODIC`` or
+              ``Timer.ONE_SHOT``. In the case that mode is ``Timer.PWM`` then trigger must be equal to
+              ``Timer.MATCH``.
+
+        Returns a callback object.
+
+.. only:: port_wipy
+
+    .. method:: timerchannel.freq([value])
+
+       Get or set the timer channel frequency (in Hz).
+
+    .. method:: timerchannel.period([value])
+
+       Get or set the timer channel period (in microseconds).
+
+    .. method:: timerchannel.duty_cycle([value])
+
+       Get or set the duty cycle of the PWM signal. It's a percentage (0.00-100.00). Since the WiPy
+       doesn't support floating point numbers the duty cycle must be specified in the range 0-10000,
+       where 10000 would represent 100.00, 5050 represents 50.50, and so on.
+
+Constants
+---------
+
+.. data:: Timer.ONE_SHOT
+.. data:: Timer.PERIODIC
+
+   Timer operating mode.

docs/library/machine.UART.rst

@@ -0,0 +1,142 @@
+.. currentmodule:: machine
+.. _machine.UART:
+
+class UART -- duplex serial communication bus
+=============================================
+
+UART implements the standard UART/USART duplex serial communications protocol.  At
+the physical level it consists of 2 lines: RX and TX.  The unit of communication
+is a character (not to be confused with a string character) which can be 8 or 9
+bits wide.
+
+UART objects can be created and initialised using::
+
+    from machine import UART
+
+    uart = UART(1, 9600)                         # init with given baudrate
+    uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters
+
+Supported parameters differ on a board:
+
+Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With *parity=None*,
+only 8 and 9 bits are supported.  With parity enabled, only 7 and 8 bits
+are supported.
+
+WiPy/CC3200: Bits can be 5, 6, 7, 8. Stop can be 1 or 2.
+
+A UART object acts like a stream object and reading and writing is done
+using the standard stream methods::
+
+    uart.read(10)       # read 10 characters, returns a bytes object
+    uart.read()         # read all available characters
+    uart.readline()     # read a line
+    uart.readinto(buf)  # read and store into the given buffer
+    uart.write('abc')   # write the 3 characters
+
+Constructors
+------------
+
+.. class:: UART(id, ...)
+
+   Construct a UART object of the given id.
+
+Methods
+-------
+
+.. only:: port_wipy
+
+    .. method:: UART.init(baudrate=9600, bits=8, parity=None, stop=1, \*, pins=(TX, RX, RTS, CTS))
+    
+       Initialise the UART bus with the given parameters:
+    
+         - ``baudrate`` is the clock rate.
+         - ``bits`` is the number of bits per character, 7, 8 or 9.
+         - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd).
+         - ``stop`` is the number of stop bits, 1 or 2.
+         - ``pins`` is a 4 or 2 item list indicating the TX, RX, RTS and CTS pins (in that order).
+           Any of the pins can be None if one wants the UART to operate with limited functionality.
+           If the RTS pin is given the the RX pin must be given as well. The same applies to CTS. 
+           When no pins are given, then the default set of TX and RX pins is taken, and hardware 
+           flow control will be disabled. If pins=None, no pin assignment will be made.
+
+.. method:: UART.deinit()
+
+   Turn off the UART bus.
+
+.. method:: UART.any()
+
+   Returns an integer counting the number of characters that can be read without
+   blocking.  It will return 0 if there are no characters available and a positive
+   number if there are characters.  The method may return 1 even if there is more
+   than one character available for reading.
+
+   For more sophisticated querying of available characters use select.poll::
+
+    poll = select.poll()
+    poll.register(uart, select.POLLIN)
+    poll.poll(timeout)
+
+.. method:: UART.read([nbytes])
+
+   Read characters.  If ``nbytes`` is specified then read at most that many bytes,
+   otherwise read as much data as possible.
+
+   Return value: a bytes object containing the bytes read in.  Returns ``None``
+   on timeout.
+
+.. method:: UART.readinto(buf[, nbytes])
+
+   Read bytes into the ``buf``.  If ``nbytes`` is specified then read at most
+   that many bytes.  Otherwise, read at most ``len(buf)`` bytes.
+
+   Return value: number of bytes read and stored into ``buf`` or ``None`` on
+   timeout.
+
+.. method:: UART.readline()
+
+   Read a line, ending in a newline character.
+
+   Return value: the line read or ``None`` on timeout.
+
+.. method:: UART.write(buf)
+
+   Write the buffer of bytes to the bus.
+
+   Return value: number of bytes written or ``None`` on timeout.
+
+.. method:: UART.sendbreak()
+
+   Send a break condition on the bus. This drives the bus low for a duration
+   longer than required for a normal transmission of a character.
+
+.. only:: port_wipy
+
+    .. method:: UART.irq(trigger, priority=1, handler=None, wake=machine.IDLE)
+
+       Create a callback to be triggered when data is received on the UART.
+
+           - ``trigger`` can only be ``UART.RX_ANY``
+           - ``priority`` level of the interrupt. Can take values in the range 1-7.
+             Higher values represent higher priorities.
+           - ``handler`` an optional function to be called when new characters arrive.
+           - ``wake`` can only be ``machine.IDLE``.
+
+       .. note::
+
+          The handler will be called whenever any of the following two conditions are met:
+
+              - 8 new characters have been received.
+              - At least 1 new character is waiting in the Rx buffer and the Rx line has been
+                silent for the duration of 1 complete frame.
+
+          This means that when the handler function is called there will be between 1 to 8 
+          characters waiting.
+
+       Returns an irq object.
+
+    Constants
+    ---------
+
+    .. data:: UART.RX_ANY
+
+        IRQ trigger sources

docs/library/machine.WDT.rst

@@ -0,0 +1,36 @@
+.. currentmodule:: machine
+.. _machine.WDT:
+
+class WDT -- watchdog timer
+===========================
+
+The WDT is used to restart the system when the application crashes and ends
+up into a non recoverable state. Once started it cannot be stopped or
+reconfigured in any way. After enabling, the application must "feed" the
+watchdog periodically to prevent it from expiring and resetting the system.
+
+Example usage::
+
+    from machine import WDT
+    wdt = WDT(timeout=2000)  # enable it with a timeout of 2s
+    wdt.feed()
+
+Availability of this class: pyboard, WiPy.
+
+Constructors
+------------
+
+.. class:: WDT(id=0, timeout=5000)
+
+   Create a WDT object and start it. The timeout must be given in seconds and
+   the minimum value that is accepted is 1 second. Once it is running the timeout
+   cannot be changed and the WDT cannot be stopped either.
+
+Methods
+-------
+
+.. method:: wdt.feed()
+
+   Feed the WDT to prevent it from resetting the system. The application
+   should place this call in a sensible place ensuring that the WDT is
+   only fed after verifying that everything is functioning correctly.

docs/library/machine.rst

@@ -0,0 +1,170 @@
+:mod:`machine` --- functions related to the hardware
+====================================================
+
+.. module:: machine
+   :synopsis: functions related to the hardware
+
+The ``machine`` module contains specific functions related to the hardware
+on a particular board. Most functions in this module allow to achieve direct
+and unrestricted access to and control of hardware blocks on a system
+(like CPU, timers, buses, etc.). Used incorrectly, this can lead to
+malfunction, lockups, crashes of your board, and in extreme cases, hardware
+damage.
+
+.. _machine_callbacks:
+
+A note of callbacks used by functions and class methods of :mod:`machine` module:
+all these callbacks should be considered as executing in an interrupt context.
+This is true for both physical devices with IDs >= 0 and "virtual" devices
+with negative IDs like -1 (these "virtual" devices are still thin shims on
+top of real hardware and real hardware interrupts). See :ref:`isr_rules`.
+
+Reset related functions
+-----------------------
+
+.. function:: reset()
+
+   Resets the device in a manner similar to pushing the external RESET
+   button.
+
+.. function:: reset_cause()
+
+   Get the reset cause. See :ref:`constants <machine_constants>` for the possible return values.
+
+Interrupt related functions
+---------------------------
+
+.. function:: disable_irq()
+
+   Disable interrupt requests.
+   Returns the previous IRQ state which should be considered an opaque value.
+   This return value should be passed to the `enable_irq()` function to restore
+   interrupts to their original state, before `disable_irq()` was called.
+
+.. function:: enable_irq(state)
+
+   Re-enable interrupt requests.
+   The *state* parameter should be the value that was returned from the most
+   recent call to the `disable_irq()` function.
+
+Power related functions
+-----------------------
+
+.. function:: freq()
+
+    Returns CPU frequency in hertz.
+
+.. function:: idle()
+
+   Gates the clock to the CPU, useful to reduce power consumption at any time during
+   short or long periods. Peripherals continue working and execution resumes as soon
+   as any interrupt is triggered (on many ports this includes system timer
+   interrupt occurring at regular intervals on the order of millisecond).
+
+.. function:: sleep()
+
+   Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from
+   the point where the sleep was requested. For wake up to actually happen, wake sources
+   should be configured first.
+
+.. function:: deepsleep()
+
+   Stops the CPU and all peripherals (including networking interfaces, if any). Execution
+   is resumed from the main script, just as with a reset. The reset cause can be checked
+   to know that we are coming from `machine.DEEPSLEEP`. For wake up to actually happen,
+   wake sources should be configured first, like `Pin` change or `RTC` timeout.
+
+.. only:: port_wipy
+
+    .. function:: wake_reason()
+
+        Get the wake reason. See :ref:`constants <machine_constants>` for the possible return values.
+
+Miscellaneous functions
+-----------------------
+
+.. only:: port_wipy
+
+    .. function:: rng()
+
+        Return a 24-bit software generated random number.
+
+.. function:: unique_id()
+
+   Returns a byte string with a unique identifier of a board/SoC. It will vary
+   from a board/SoC instance to another, if underlying hardware allows. Length
+   varies by hardware (so use substring of a full value if you expect a short
+   ID). In some MicroPython ports, ID corresponds to the network MAC address.
+
+.. function:: time_pulse_us(pin, pulse_level, timeout_us=1000000)
+
+   Time a pulse on the given *pin*, and return the duration of the pulse in
+   microseconds.  The *pulse_level* argument should be 0 to time a low pulse
+   or 1 to time a high pulse.
+
+   If the current input value of the pin is different to *pulse_level*,
+   the function first (*) waits until the pin input becomes equal to *pulse_level*,
+   then (**) times the duration that the pin is equal to *pulse_level*.
+   If the pin is already equal to *pulse_level* then timing starts straight away.
+
+   The function will return -2 if there was timeout waiting for condition marked
+   (*) above, and -1 if there was timeout during the main measurement, marked (**)
+   above. The timeout is the same for both cases and given by *timeout_us* (which
+   is in microseconds).
+
+.. _machine_constants:
+
+Constants
+---------
+
+.. data:: machine.IDLE
+          machine.SLEEP
+          machine.DEEPSLEEP
+
+    IRQ wake values.
+
+.. data:: machine.PWRON_RESET
+          machine.HARD_RESET
+          machine.WDT_RESET
+          machine.DEEPSLEEP_RESET
+          machine.SOFT_RESET
+
+    Reset causes.
+
+.. data:: machine.WLAN_WAKE
+          machine.PIN_WAKE
+          machine.RTC_WAKE
+
+    Wake-up reasons.
+
+Classes
+-------
+
+.. only:: not port_wipy
+
+ .. toctree::
+   :maxdepth: 1
+
+   machine.Pin.rst
+   machine.Signal.rst
+   machine.UART.rst
+   machine.SPI.rst
+   machine.I2C.rst
+   machine.RTC.rst
+   machine.Timer.rst
+   machine.WDT.rst
+
+.. only:: port_wipy
+
+ .. toctree::
+   :maxdepth: 1
+
+   machine.Pin.rst
+   machine.UART.rst
+   machine.SPI.rst
+   machine.I2C.rst
+   machine.RTC.rst
+   machine.Timer.rst
+   machine.WDT.rst
+   machine.ADC.rst
+   machine.SD.rst

docs/library/math.rst

@@ -0,0 +1,185 @@
+:mod:`math` -- mathematical functions
+=====================================
+
+.. module:: math
+   :synopsis: mathematical functions
+
+|see_cpython_module| :mod:`python:math`.
+
+The ``math`` module provides some basic mathematical functions for
+working with floating-point numbers.
+
+*Note:* On the pyboard, floating-point numbers have 32-bit precision.
+
+Availability: not available on WiPy. Floating point support required
+for this module.
+
+Functions
+---------
+
+.. function:: acos(x)
+
+   Return the inverse cosine of ``x``.
+
+.. function:: acosh(x)
+
+   Return the inverse hyperbolic cosine of ``x``.
+
+.. function:: asin(x)
+
+   Return the inverse sine of ``x``.
+
+.. function:: asinh(x)
+
+   Return the inverse hyperbolic sine of ``x``.
+
+.. function:: atan(x)
+
+   Return the inverse tangent of ``x``.
+
+.. function:: atan2(y, x)
+
+   Return the principal value of the inverse tangent of ``y/x``.
+
+.. function:: atanh(x)
+
+   Return the inverse hyperbolic tangent of ``x``.
+
+.. function:: ceil(x)
+
+   Return an integer, being ``x`` rounded towards positive infinity.
+
+.. function:: copysign(x, y)
+
+   Return ``x`` with the sign of ``y``.
+
+.. function:: cos(x)
+
+   Return the cosine of ``x``.
+
+.. function:: cosh(x)
+
+   Return the hyperbolic cosine of ``x``.
+
+.. function:: degrees(x)
+
+   Return radians ``x`` converted to degrees.
+
+.. function:: erf(x)
+
+   Return the error function of ``x``.
+
+.. function:: erfc(x)
+
+   Return the complementary error function of ``x``.
+
+.. function:: exp(x)
+
+   Return the exponential of ``x``.
+
+.. function:: expm1(x)
+
+   Return ``exp(x) - 1``.
+
+.. function:: fabs(x)
+
+   Return the absolute value of ``x``.
+
+.. function:: floor(x)
+
+   Return an integer, being ``x`` rounded towards negative infinity.
+
+.. function:: fmod(x, y)
+
+   Return the remainder of ``x/y``.
+
+.. function:: frexp(x)
+
+   Decomposes a floating-point number into its mantissa and exponent.
+   The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e``
+   exactly.  If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise
+   the relation ``0.5 <= abs(m) < 1`` holds.
+
+.. function:: gamma(x)
+
+   Return the gamma function of ``x``.
+
+.. function:: isfinite(x)
+
+   Return ``True`` if ``x`` is finite.
+
+.. function:: isinf(x)
+
+   Return ``True`` if ``x`` is infinite.
+
+.. function:: isnan(x)
+
+   Return ``True`` if ``x`` is not-a-number
+
+.. function:: ldexp(x, exp)
+
+   Return ``x * (2**exp)``.
+
+.. function:: lgamma(x)
+
+   Return the natural logarithm of the gamma function of ``x``.
+
+.. function:: log(x)
+
+   Return the natural logarithm of ``x``.
+
+.. function:: log10(x)
+
+   Return the base-10 logarithm of ``x``.
+
+.. function:: log2(x)
+
+   Return the base-2 logarithm of ``x``.
+
+.. function:: modf(x)
+
+   Return a tuple of two floats, being the fractional and integral parts of
+   ``x``.  Both return values have the same sign as ``x``.
+
+.. function:: pow(x, y)
+
+   Returns ``x`` to the power of ``y``.
+
+.. function:: radians(x)
+
+   Return degrees ``x`` converted to radians.
+
+.. function:: sin(x)
+
+   Return the sine of ``x``.
+
+.. function:: sinh(x)
+
+   Return the hyperbolic sine of ``x``.
+
+.. function:: sqrt(x)
+
+   Return the square root of ``x``.
+
+.. function:: tan(x)
+
+   Return the tangent of ``x``.
+
+.. function:: tanh(x)
+
+   Return the hyperbolic tangent of ``x``.
+
+.. function:: trunc(x)
+
+   Return an integer, being ``x`` rounded towards 0.
+
+Constants
+---------
+
+.. data:: e
+
+   base of the natural logarithm
+
+.. data:: pi
+
+   the ratio of a circle's circumference to its diameter

docs/library/micropython.rst

@@ -0,0 +1,116 @@
+:mod:`micropython` -- access and control MicroPython internals
+==============================================================
+
+.. module:: micropython
+   :synopsis: access and control MicroPython internals
+
+Functions
+---------
+
+.. function:: const(expr)
+
+   Used to declare that the expression is a constant so that the compile can
+   optimise it.  The use of this function should be as follows::
+
+    from micropython import const
+
+    CONST_X = const(123)
+    CONST_Y = const(2 * CONST_X + 1)
+
+   Constants declared this way are still accessible as global variables from
+   outside the module they are declared in.  On the other hand, if a constant
+   begins with an underscore then it is hidden, it is not available as a global
+   variable, and does not take up any memory during execution.
+
+   This `const` function is recognised directly by the MicroPython parser and is
+   provided as part of the :mod:`micropython` module mainly so that scripts can be
+   written which run under both CPython and MicroPython, by following the above
+   pattern.
+
+.. function:: opt_level([level])
+
+   If *level* is given then this function sets the optimisation level for subsequent
+   compilation of scripts, and returns ``None``.  Otherwise it returns the current
+   optimisation level.
+
+.. function:: alloc_emergency_exception_buf(size)
+
+   Allocate *size* bytes of RAM for the emergency exception buffer (a good
+   size is around 100 bytes).  The buffer is used to create exceptions in cases
+   when normal RAM allocation would fail (eg within an interrupt handler) and
+   therefore give useful traceback information in these situations.
+
+   A good way to use this function is to put it at the start of your main script
+   (eg ``boot.py`` or ``main.py``) and then the emergency exception buffer will be active
+   for all the code following it.
+
+.. function:: mem_info([verbose])
+
+   Print information about currently used memory.  If the *verbose* argument
+   is given then extra information is printed.
+
+   The information that is printed is implementation dependent, but currently
+   includes the amount of stack and heap used.  In verbose mode it prints out
+   the entire heap indicating which blocks are used and which are free.
+
+.. function:: qstr_info([verbose])
+
+   Print information about currently interned strings.  If the *verbose*
+   argument is given then extra information is printed.
+
+   The information that is printed is implementation dependent, but currently
+   includes the number of interned strings and the amount of RAM they use.  In
+   verbose mode it prints out the names of all RAM-interned strings.
+
+.. function:: stack_use()
+
+   Return an integer representing the current amount of stack that is being
+   used.  The absolute value of this is not particularly useful, rather it
+   should be used to compute differences in stack usage at different points.
+
+.. function:: heap_lock()
+.. function:: heap_unlock()
+
+   Lock or unlock the heap.  When locked no memory allocation can occur and a
+   `MemoryError` will be raised if any heap allocation is attempted.
+
+   These functions can be nested, ie `heap_lock()` can be called multiple times
+   in a row and the lock-depth will increase, and then `heap_unlock()` must be
+   called the same number of times to make the heap available again.
+
+.. function:: kbd_intr(chr)
+
+   Set the character that will raise a `KeyboardInterrupt` exception.  By
+   default this is set to 3 during script execution, corresponding to Ctrl-C.
+   Passing -1 to this function will disable capture of Ctrl-C, and passing 3
+   will restore it.
+
+   This function can be used to prevent the capturing of Ctrl-C on the
+   incoming stream of characters that is usually used for the REPL, in case
+   that stream is used for other purposes.
+
+.. function:: schedule(func, arg)
+
+   Schedule the function *func* to be executed "very soon".  The function
+   is passed the value *arg* as its single argument.  "Very soon" means that
+   the MicroPython runtime will do its best to execute the function at the
+   earliest possible time, given that it is also trying to be efficient, and
+   that the following conditions hold:
+
+   - A scheduled function will never preempt another scheduled function.
+   - Scheduled functions are always executed "between opcodes" which means
+     that all fundamental Python operations (such as appending to a list)
+     are guaranteed to be atomic.
+   - A given port may define "critical regions" within which scheduled
+     functions will never be executed.  Functions may be scheduled within
+     a critical region but they will not be executed until that region
+     is exited.  An example of a critical region is a preempting interrupt
+     handler (an IRQ).
+
+   A use for this function is to schedule a callback from a preempting IRQ.
+   Such an IRQ puts restrictions on the code that runs in the IRQ (for example
+   the heap may be locked) and scheduling a function to call later will lift
+   those restrictions.
+
+   There is a finite stack to hold the scheduled functions and `schedule`
+   will raise a `RuntimeError` if the stack is full.

docs/library/network.rst

@@ -0,0 +1,591 @@
+****************************************
+:mod:`network` --- network configuration
+****************************************
+
+.. module:: network
+   :synopsis: network configuration
+
+This module provides network drivers and routing configuration. To use this
+module, a MicroPython variant/build with network capabilities must be installed.
+Network drivers for specific hardware are available within this module and are
+used to configure hardware network interface(s). Network services provided
+by configured interfaces are then available for use via the :mod:`usocket`
+module.
+
+For example::
+
+    # connect/ show IP config a specific network interface
+    # see below for examples of specific drivers
+    import network
+    import utime
+    nic = network.Driver(...)
+    if not nic.isconnected():
+        nic.connect()
+        print("Waiting for connection...")
+        while not nic.isconnected():
+            utime.sleep(1)
+    print(nic.ifconfig())
+
+    # now use usocket as usual
+    import usocket as socket
+    addr = socket.getaddrinfo('micropython.org', 80)[0][-1]
+    s = socket.socket()
+    s.connect(addr)
+    s.send(b'GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n')
+    data = s.recv(1000)
+    s.close()
+
+Common network adapter interface
+================================
+
+This section describes an (implied) abstract base class for all network
+interface classes implemented by `MicroPython ports <MicroPython port>`
+for different hardware. This means that MicroPython does not actually
+provide ``AbstractNIC`` class, but any actual NIC class, as described
+in the following sections, implements methods as described here.
+
+.. class:: AbstractNIC(id=None, ...)
+
+Instantiate a network interface object. Parameters are network interface
+dependent. If there are more than one interface of the same type, the first
+parameter should be `id`.
+
+    .. method:: active([is_active])
+
+        Activate ("up") or deactivate ("down") the network interface, if
+        a boolean argument is passed. Otherwise, query current state if
+        no argument is provided. Most other methods require an active
+        interface (behavior of calling them on inactive interface is
+        undefined).
+
+    .. method:: connect([service_id, key=None, \*, ...])
+
+       Connect the interface to a network. This method is optional, and
+       available only for interfaces which are not "always connected".
+       If no parameters are given, connect to the default (or the only)
+       service. If a single parameter is given, it is the primary identifier
+       of a service to connect to. It may be accompanied by a key
+       (password) required to access said service. There can be further
+       arbitrary keyword-only parameters, depending on the networking medium
+       type and/or particular device. Parameters can be used to: a)
+       specify alternative service identifer types; b) provide additional
+       connection parameters. For various medium types, there are different
+       sets of predefined/recommended parameters, among them:
+
+       * WiFi: *bssid* keyword to connect to a specific BSSID (MAC address)
+
+    .. method:: disconnect()
+
+       Disconnect from network.
+
+    .. method:: isconnected()
+
+       Returns ``True`` if connected to network, otherwise returns ``False``.
+
+    .. method:: scan(\*, ...)
+
+       Scan for the available network services/connections. Returns a
+       list of tuples with discovered service parameters. For various
+       network media, there are different variants of predefined/
+       recommended tuple formats, among them:
+
+       * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There
+         may be further fields, specific to a particular device.
+
+       The function may accept additional keyword arguments to filter scan
+       results (e.g. scan for a particular service, on a particular channel,
+       for services of a particular set, etc.), and to affect scan
+       duration and other parameters. Where possible, parameter names
+       should match those in connect().
+
+    .. method:: status()
+
+       Return detailed status of the interface, values are dependent
+       on the network medium/technology.
+
+    .. method:: ifconfig([(ip, subnet, gateway, dns)])
+
+       Get/set IP-level network interface parameters: IP address, subnet mask,
+       gateway and DNS server. When called with no arguments, this method returns
+       a 4-tuple with the above information. To set the above values, pass a
+       4-tuple with the required information.  For example::
+
+        nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+
+    .. method:: config('param')
+                config(param=value, ...)
+
+       Get or set general network interface parameters. These methods allow to work
+       with additional parameters beyond standard IP configuration (as dealt with by
+       `ifconfig()`). These include network-specific and hardware-specific
+       parameters and status values. For setting parameters, the keyword argument
+       syntax should be used, and multiple parameters can be set at once. For
+       querying, a parameter name should be quoted as a string, and only one
+       parameter can be queried at a time::
+
+        # Set WiFi access point name (formally known as ESSID) and WiFi channel
+        ap.config(essid='My AP', channel=11)
+        # Query params one by one
+        print(ap.config('essid'))
+        print(ap.config('channel'))
+        # Extended status information also available this way
+        print(sta.config('rssi'))
+
+.. only:: port_pyboard
+
+    class CC3K
+    ==========
+    
+    This class provides a driver for CC3000 WiFi modules.  Example usage::
+    
+        import network
+        nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
+        nic.connect('your-ssid', 'your-password')
+        while not nic.isconnected():
+            pyb.delay(50)
+        print(nic.ifconfig())
+    
+        # now use socket as usual
+        ...
+    
+    For this example to work the CC3000 module must have the following connections:
+    
+        - MOSI connected to Y8
+        - MISO connected to Y7
+        - CLK connected to Y6
+        - CS connected to Y5
+        - VBEN connected to Y4
+        - IRQ connected to Y3
+    
+    It is possible to use other SPI busses and other pins for CS, VBEN and IRQ.
+    
+    Constructors
+    ------------
+    
+    .. class:: CC3K(spi, pin_cs, pin_en, pin_irq)
+    
+       Create a CC3K driver object, initialise the CC3000 module using the given SPI bus
+       and pins, and return the CC3K object.
+    
+       Arguments are:
+    
+         - *spi* is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the CC3000 is
+           connected to (the MOSI, MISO and CLK pins).
+         - *pin_cs* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin.
+         - *pin_en* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin.
+         - *pin_irq* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 IRQ pin.
+    
+       All of these objects will be initialised by the driver, so there is no need to
+       initialise them yourself.  For example, you can use::
+    
+         nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
+    
+    Methods
+    -------
+    
+    .. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None)
+    
+       Connect to a WiFi access point using the given SSID, and other security
+       parameters.
+    
+    .. method:: cc3k.disconnect()
+    
+       Disconnect from the WiFi access point.
+    
+    .. method:: cc3k.isconnected()
+    
+       Returns True if connected to a WiFi access point and has a valid IP address,
+       False otherwise.
+    
+    .. method:: cc3k.ifconfig()
+    
+       Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server,
+       MAC address, SSID).
+    
+    .. method:: cc3k.patch_version()
+    
+       Return the version of the patch program (firmware) on the CC3000.
+    
+    .. method:: cc3k.patch_program('pgm')
+    
+       Upload the current firmware to the CC3000.  You must pass 'pgm' as the first
+       argument in order for the upload to proceed.
+    
+    Constants
+    ---------
+    
+    .. data:: CC3K.WEP
+    .. data:: CC3K.WPA
+    .. data:: CC3K.WPA2
+    
+       security type to use
+    
+    class WIZNET5K
+    ==============
+    
+    This class allows you to control WIZnet5x00 Ethernet adaptors based on
+    the W5200 and W5500 chipsets.  The particular chipset that is supported
+    by the firmware is selected at compile-time via the MICROPY_PY_WIZNET5K
+    option.
+    
+    Example usage::
+    
+        import network
+        nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4)
+        print(nic.ifconfig())
+    
+        # now use socket as usual
+        ...
+    
+    For this example to work the WIZnet5x00 module must have the following connections:
+    
+        - MOSI connected to X8
+        - MISO connected to X7
+        - SCLK connected to X6
+        - nSS connected to X5
+        - nRESET connected to X4
+    
+    It is possible to use other SPI busses and other pins for nSS and nRESET.
+    
+    Constructors
+    ------------
+    
+    .. class:: WIZNET5K(spi, pin_cs, pin_rst)
+    
+       Create a WIZNET5K driver object, initialise the WIZnet5x00 module using the given
+       SPI bus and pins, and return the WIZNET5K object.
+    
+       Arguments are:
+    
+         - *spi* is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the WIZnet5x00 is
+           connected to (the MOSI, MISO and SCLK pins).
+         - *pin_cs* is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nSS pin.
+         - *pin_rst* is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nRESET pin.
+    
+       All of these objects will be initialised by the driver, so there is no need to
+       initialise them yourself.  For example, you can use::
+    
+         nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4)
+    
+    Methods
+    -------
+    
+    .. method:: wiznet5k.isconnected()
+
+       Returns ``True`` if the physical Ethernet link is connected and up.
+       Returns ``False`` otherwise.
+
+    .. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)])
+    
+       Get/set IP address, subnet mask, gateway and DNS.
+    
+       When called with no arguments, this method returns a 4-tuple with the above information.
+    
+       To set the above values, pass a 4-tuple with the required information.  For example::
+    
+        nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+    
+    .. method:: wiznet5k.regs()
+    
+       Dump the WIZnet5x00 registers.  Useful for debugging.
+
+.. _network.WLAN:
+
+.. only:: port_esp8266
+
+    Functions
+    =========
+
+    .. function:: phy_mode([mode])
+
+        Get or set the PHY mode.
+
+        If the *mode* parameter is provided, sets the mode to its value. If
+        the function is called without parameters, returns the current mode.
+
+        The possible modes are defined as constants:
+            * ``MODE_11B`` -- IEEE 802.11b,
+            * ``MODE_11G`` -- IEEE 802.11g,
+            * ``MODE_11N`` -- IEEE 802.11n.
+
+    class WLAN
+    ==========
+
+    This class provides a driver for WiFi network processor in the ESP8266.  Example usage::
+
+        import network
+        # enable station interface and connect to WiFi access point
+        nic = network.WLAN(network.STA_IF)
+        nic.active(True)
+        nic.connect('your-ssid', 'your-password')
+        # now use sockets as usual
+
+    Constructors
+    ------------
+    .. class:: WLAN(interface_id)
+
+    Create a WLAN network interface object. Supported interfaces are
+    ``network.STA_IF`` (station aka client, connects to upstream WiFi access
+    points) and ``network.AP_IF`` (access point, allows other WiFi clients to
+    connect). Availability of the methods below depends on interface type.
+    For example, only STA interface may `connect()` to an access point.
+
+    Methods
+    -------
+
+    .. method:: wlan.active([is_active])
+
+        Activate ("up") or deactivate ("down") network interface, if boolean
+        argument is passed. Otherwise, query current state if no argument is
+        provided. Most other methods require active interface.
+
+    .. method:: wlan.connect(ssid=None, password=None, \*, bssid=None)
+
+        Connect to the specified wireless network, using the specified password.
+        If *bssid* is given then the connection will be restricted to the
+        access-point with that MAC address (the *ssid* must also be specified
+        in this case).
+
+    .. method:: wlan.disconnect()
+
+        Disconnect from the currently connected wireless network.
+
+    .. method:: wlan.scan()
+
+        Scan for the available wireless networks.
+
+        Scanning is only possible on STA interface. Returns list of tuples with
+        the information about WiFi access points:
+
+            (ssid, bssid, channel, RSSI, authmode, hidden)
+
+        *bssid* is hardware address of an access point, in binary form, returned as
+        bytes object. You can use `ubinascii.hexlify()` to convert it to ASCII form.
+
+        There are five values for authmode:
+
+            * 0 -- open
+            * 1 -- WEP
+            * 2 -- WPA-PSK
+            * 3 -- WPA2-PSK
+            * 4 -- WPA/WPA2-PSK
+
+        and two for hidden:
+
+            * 0 -- visible
+            * 1 -- hidden
+
+    .. method:: wlan.status()
+
+        Return the current status of the wireless connection.
+
+        The possible statuses are defined as constants:
+
+            * ``STAT_IDLE`` -- no connection and no activity,
+            * ``STAT_CONNECTING`` -- connecting in progress,
+            * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password,
+            * ``STAT_NO_AP_FOUND`` -- failed because no access point replied,
+            * ``STAT_CONNECT_FAIL`` -- failed due to other problems,
+            * ``STAT_GOT_IP`` -- connection successful.
+
+    .. method:: wlan.isconnected()
+
+        In case of STA mode, returns ``True`` if connected to a WiFi access
+        point and has a valid IP address.  In AP mode returns ``True`` when a
+        station is connected. Returns ``False`` otherwise.
+
+    .. method:: wlan.ifconfig([(ip, subnet, gateway, dns)])
+
+       Get/set IP-level network interface parameters: IP address, subnet mask,
+       gateway and DNS server. When called with no arguments, this method returns
+       a 4-tuple with the above information. To set the above values, pass a
+       4-tuple with the required information.  For example::
+
+        nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+
+    .. method:: wlan.config('param')
+    .. method:: wlan.config(param=value, ...)
+
+       Get or set general network interface parameters. These methods allow to work
+       with additional parameters beyond standard IP configuration (as dealt with by
+       `wlan.ifconfig()`). These include network-specific and hardware-specific
+       parameters. For setting parameters, keyword argument syntax should be used,
+       multiple parameters can be set at once. For querying, parameters name should
+       be quoted as a string, and only one parameter can be queries at time::
+
+        # Set WiFi access point name (formally known as ESSID) and WiFi channel
+        ap.config(essid='My AP', channel=11)
+        # Query params one by one
+        print(ap.config('essid'))
+        print(ap.config('channel'))
+
+       Following are commonly supported parameters (availability of a specific parameter
+       depends on network technology type, driver, and `MicroPython port`).
+
+       =============  ===========
+       Parameter      Description
+       =============  ===========
+       mac            MAC address (bytes)
+       essid          WiFi access point name (string)
+       channel        WiFi channel (integer)
+       hidden         Whether ESSID is hidden (boolean)
+       authmode       Authentication mode supported (enumeration, see module constants)
+       password       Access password (string)
+       dhcp_hostname  The DHCP hostname to use
+       =============  ===========
+
+
+
+.. only:: port_wipy
+
+    class WLAN
+    ==========
+
+    This class provides a driver for the WiFi network processor in the WiPy. Example usage::
+
+        import network
+        import time
+        # setup as a station
+        wlan = network.WLAN(mode=WLAN.STA)
+        wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key'))
+        while not wlan.isconnected():
+            time.sleep_ms(50)
+        print(wlan.ifconfig())
+
+        # now use socket as usual
+        ...
+
+    Constructors
+    ------------
+    
+    .. class:: WLAN(id=0, ...)
+
+       Create a WLAN object, and optionally configure it. See `init()` for params of configuration.
+
+    .. note::
+
+       The ``WLAN`` constructor is special in the sense that if no arguments besides the id are given,
+       it will return the already existing ``WLAN`` instance without re-configuring it. This is
+       because ``WLAN`` is a system feature of the WiPy. If the already existing instance is not
+       initialized it will do the same as the other constructors an will initialize it with default
+       values.
+
+    Methods
+    -------
+
+    .. method:: wlan.init(mode, \*, ssid, auth, channel, antenna)
+    
+       Set or get the WiFi network processor configuration.
+    
+       Arguments are:
+    
+         - *mode* can be either ``WLAN.STA`` or ``WLAN.AP``.
+         - *ssid* is a string with the ssid name. Only needed when mode is ``WLAN.AP``.
+         - *auth* is a tuple with (sec, key). Security can be ``None``, ``WLAN.WEP``,
+           ``WLAN.WPA`` or ``WLAN.WPA2``. The key is a string with the network password.
+           If ``sec`` is ``WLAN.WEP`` the key must be a string representing hexadecimal
+           values (e.g. 'ABC1DE45BF'). Only needed when mode is ``WLAN.AP``.
+         - *channel* a number in the range 1-11. Only needed when mode is ``WLAN.AP``.
+         - *antenna* selects between the internal and the external antenna. Can be either
+           ``WLAN.INT_ANT`` or ``WLAN.EXT_ANT``.
+    
+       For example, you can do::
+
+          # create and configure as an access point
+          wlan.init(mode=WLAN.AP, ssid='wipy-wlan', auth=(WLAN.WPA2,'www.wipy.io'), channel=7, antenna=WLAN.INT_ANT)
+
+       or::
+
+          # configure as an station
+          wlan.init(mode=WLAN.STA)
+
+    .. method:: wlan.connect(ssid, \*, auth=None, bssid=None, timeout=None)
+
+       Connect to a WiFi access point using the given SSID, and other security
+       parameters.
+
+          - *auth* is a tuple with (sec, key). Security can be ``None``, ``WLAN.WEP``,
+            ``WLAN.WPA`` or ``WLAN.WPA2``. The key is a string with the network password.
+            If ``sec`` is ``WLAN.WEP`` the key must be a string representing hexadecimal
+            values (e.g. 'ABC1DE45BF').
+          - *bssid* is the MAC address of the AP to connect to. Useful when there are several
+            APs with the same ssid.
+          - *timeout* is the maximum time in milliseconds to wait for the connection to succeed.
+
+    .. method:: wlan.scan()
+
+       Performs a network scan and returns a list of named tuples with (ssid, bssid, sec, channel, rssi).
+       Note that channel is always ``None`` since this info is not provided by the WiPy.
+
+    .. method:: wlan.disconnect()
+
+       Disconnect from the WiFi access point.
+
+    .. method:: wlan.isconnected()
+
+       In case of STA mode, returns ``True`` if connected to a WiFi access point and has a valid IP address.
+       In AP mode returns ``True`` when a station is connected, ``False`` otherwise.
+
+    .. method:: wlan.ifconfig(if_id=0, config=['dhcp' or configtuple])
+
+       With no parameters given returns a 4-tuple of *(ip, subnet_mask, gateway, DNS_server)*.
+
+       if ``'dhcp'`` is passed as a parameter then the DHCP client is enabled and the IP params
+       are negotiated with the AP.
+
+       If the 4-tuple config is given then a static IP is configured. For instance::
+
+          wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+
+    .. method:: wlan.mode([mode])
+
+       Get or set the WLAN mode.
+
+    .. method:: wlan.ssid([ssid])
+
+       Get or set the SSID when in AP mode.
+
+    .. method:: wlan.auth([auth])
+
+       Get or set the authentication type when in AP mode.
+
+    .. method:: wlan.channel([channel])
+
+       Get or set the channel (only applicable in AP mode).
+
+    .. method:: wlan.antenna([antenna])
+
+       Get or set the antenna type (external or internal).
+
+    .. method:: wlan.mac([mac_addr])
+
+       Get or set a 6-byte long bytes object with the MAC address.
+
+    .. method:: wlan.irq(\*, handler, wake)
+
+        Create a callback to be triggered when a WLAN event occurs during ``machine.SLEEP``
+        mode. Events are triggered by socket activity or by WLAN connection/disconnection.
+
+            - *handler* is the function that gets called when the IRQ is triggered.
+            - *wake* must be ``machine.SLEEP``.
+
+        Returns an IRQ object.
+
+    Constants
+    ---------
+
+    .. data:: WLAN.STA
+    .. data:: WLAN.AP
+
+       selects the WLAN mode
+
+    .. data:: WLAN.WEP
+    .. data:: WLAN.WPA
+    .. data:: WLAN.WPA2
+
+       selects the network security
+
+    .. data:: WLAN.INT_ANT
+    .. data:: WLAN.EXT_ANT
+
+       selects the antenna type

docs/library/pyb.ADC.rst

@@ -0,0 +1,143 @@
+.. currentmodule:: pyb
+.. _pyb.ADC:
+
+class ADC -- analog to digital conversion
+=========================================
+
+.. only:: port_pyboard
+
+    Usage::
+
+        import pyb
+    
+        adc = pyb.ADC(pin)              # create an analog object from a pin
+        val = adc.read()                # read an analog value
+    
+        adc = pyb.ADCAll(resolution)    # create an ADCAll object
+        val = adc.read_channel(channel) # read the given channel
+        val = adc.read_core_temp()      # read MCU temperature
+        val = adc.read_core_vbat()      # read MCU VBAT
+        val = adc.read_core_vref()      # read MCU VREF
+
+ 
+Constructors
+------------
+
+
+.. only:: port_pyboard
+
+    .. class:: pyb.ADC(pin)
+
+       Create an ADC object associated with the given pin.
+       This allows you to then read analog values on that pin.
+
+Methods
+-------
+
+.. only:: port_pyboard
+
+    .. method:: ADC.read()
+
+       Read the value on the analog pin and return it.  The returned value
+       will be between 0 and 4095.
+
+    .. method:: ADC.read_timed(buf, timer)
+    
+       Read analog values into ``buf`` at a rate set by the ``timer`` object.
+
+       ``buf`` can be bytearray or array.array for example.  The ADC values have
+       12-bit resolution and are stored directly into ``buf`` if its element size is
+       16 bits or greater.  If ``buf`` has only 8-bit elements (eg a bytearray) then
+       the sample resolution will be reduced to 8 bits.
+
+       ``timer`` should be a Timer object, and a sample is read each time the timer
+       triggers.  The timer must already be initialised and running at the desired
+       sampling frequency.
+
+       To support previous behaviour of this function, ``timer`` can also be an
+       integer which specifies the frequency (in Hz) to sample at.  In this case
+       Timer(6) will be automatically configured to run at the given frequency.
+
+       Example using a Timer object (preferred way)::
+
+           adc = pyb.ADC(pyb.Pin.board.X19)    # create an ADC on pin X19
+           tim = pyb.Timer(6, freq=10)         # create a timer running at 10Hz
+           buf = bytearray(100)                # creat a buffer to store the samples
+           adc.read_timed(buf, tim)            # sample 100 values, taking 10s
+
+       Example using an integer for the frequency::
+
+           adc = pyb.ADC(pyb.Pin.board.X19)    # create an ADC on pin X19
+           buf = bytearray(100)                # create a buffer of 100 bytes
+           adc.read_timed(buf, 10)             # read analog values into buf at 10Hz
+                                               #   this will take 10 seconds to finish
+           for val in buf:                     # loop over all values
+               print(val)                      # print the value out
+
+       This function does not allocate any memory.
+
+The ADCAll Object
+-----------------
+
+.. only:: port_pyboard
+
+    Instantiating this changes all ADC pins to analog inputs. The raw MCU temperature,
+    VREF and VBAT data can be accessed on ADC channels 16, 17 and 18 respectively.
+    Appropriate scaling will need to be applied. The temperature sensor on the chip
+    has poor absolute accuracy and is suitable only for detecting temperature changes.
+
+    The ``ADCAll`` ``read_core_vbat()`` and ``read_core_vref()`` methods read
+    the backup battery voltage and the (1.21V nominal) reference voltage using the
+    3.3V supply as a reference. Assuming the ``ADCAll`` object has been Instantiated with
+    ``adc = pyb.ADCAll(12)`` the 3.3V supply voltage may be calculated:
+    
+    ``v33 = 3.3 * 1.21 / adc.read_core_vref()``
+
+    If the 3.3V supply is correct the value of ``adc.read_core_vbat()`` will be
+    valid. If the supply voltage can drop below 3.3V, for example in in battery
+    powered systems with a discharging battery, the regulator will fail to preserve
+    the 3.3V supply resulting in an incorrect reading. To produce a value which will
+    remain valid under these circumstances use the following:
+
+    ``vback = adc.read_core_vbat() * 1.21 / adc.read_core_vref()``
+
+    It is possible to access these values without incurring the side effects of ``ADCAll``::
+    
+        def adcread(chan):                              # 16 temp 17 vbat 18 vref
+            assert chan >= 16 and chan <= 18, 'Invalid ADC channel'
+            start = pyb.millis()
+            timeout = 100
+            stm.mem32[stm.RCC + stm.RCC_APB2ENR] |= 0x100 # enable ADC1 clock.0x4100
+            stm.mem32[stm.ADC1 + stm.ADC_CR2] = 1       # Turn on ADC
+            stm.mem32[stm.ADC1 + stm.ADC_CR1] = 0       # 12 bit
+            if chan == 17:
+                stm.mem32[stm.ADC1 + stm.ADC_SMPR1] = 0x200000 # 15 cycles
+                stm.mem32[stm.ADC + 4] = 1 << 23
+            elif chan == 18:
+                stm.mem32[stm.ADC1 + stm.ADC_SMPR1] = 0x1000000
+                stm.mem32[stm.ADC + 4] = 0xc00000
+            else:
+                stm.mem32[stm.ADC1 + stm.ADC_SMPR1] = 0x40000
+                stm.mem32[stm.ADC + 4] = 1 << 23
+            stm.mem32[stm.ADC1 + stm.ADC_SQR3] = chan
+            stm.mem32[stm.ADC1 + stm.ADC_CR2] = 1 | (1 << 30) | (1 << 10) # start conversion
+            while not stm.mem32[stm.ADC1 + stm.ADC_SR] & 2: # wait for EOC
+                if pyb.elapsed_millis(start) > timeout:
+                    raise OSError('ADC timout')
+            data = stm.mem32[stm.ADC1 + stm.ADC_DR]     # clear down EOC
+            stm.mem32[stm.ADC1 + stm.ADC_CR2] = 0       # Turn off ADC
+            return data
+
+        def v33():
+            return 4096 * 1.21 / adcread(17)
+
+        def vbat():
+            return  1.21 * 2 * adcread(18) / adcread(17)  # 2:1 divider on Vbat channel
+
+        def vref():
+            return 3.3 * adcread(17) / 4096
+
+        def temperature():
+            return 25 + 400 * (3.3 * adcread(16) / 4096 - 0.76)
+
+    

docs/library/pyb.Accel.rst

@@ -0,0 +1,57 @@
+.. currentmodule:: pyb
+.. _pyb.Accel:
+
+class Accel -- accelerometer control
+====================================
+
+Accel is an object that controls the accelerometer.  Example usage::
+
+    accel = pyb.Accel()
+    for i in range(10):
+        print(accel.x(), accel.y(), accel.z())
+
+Raw values are between -32 and 31.
+
+
+Constructors
+------------
+
+.. class:: pyb.Accel()
+
+   Create and return an accelerometer object.
+   
+Methods
+-------
+
+.. method:: Accel.filtered_xyz()
+
+   Get a 3-tuple of filtered x, y and z values.
+
+   Implementation note: this method is currently implemented as taking the
+   sum of 4 samples, sampled from the 3 previous calls to this function along
+   with the sample from the current call.  Returned values are therefore 4
+   times the size of what they would be from the raw x(), y() and z() calls.
+
+.. method:: Accel.tilt()
+
+   Get the tilt register.
+
+.. method:: Accel.x()
+
+   Get the x-axis value.
+
+.. method:: Accel.y()
+
+   Get the y-axis value.
+
+.. method:: Accel.z()
+
+   Get the z-axis value.
+
+Hardware Note
+-------------
+
+The accelerometer uses I2C bus 1 to communicate with the processor. Consequently
+when readings are being taken pins X9 and X10 should be unused (other than for
+I2C). Other devices using those pins, and which therefore cannot be used
+concurrently, are UART 1 and Timer 4 channels 1 and 2.

docs/library/pyb.CAN.rst

@@ -0,0 +1,223 @@
+.. currentmodule:: pyb
+.. _pyb.CAN:
+
+class CAN -- controller area network communication bus
+======================================================
+
+CAN implements the standard CAN communications protocol.  At
+the physical level it consists of 2 lines: RX and TX.  Note that
+to connect the pyboard to a CAN bus you must use a CAN transceiver
+to convert the CAN logic signals from the pyboard to the correct
+voltage levels on the bus.
+
+Example usage (works without anything connected)::
+
+    from pyb import CAN
+    can = CAN(1, CAN.LOOPBACK)
+    can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126))  # set a filter to receive messages with id=123, 124, 125 and 126
+    can.send('message!', 123)   # send a message with id 123
+    can.recv(0)                 # receive message on FIFO 0
+
+
+Constructors
+------------
+
+.. class:: pyb.CAN(bus, ...)
+
+   Construct a CAN object on the given bus.  ``bus`` can be 1-2, or 'YA' or 'YB'.
+   With no additional parameters, the CAN object is created but not
+   initialised (it has the settings from the last initialisation of
+   the bus, if any).  If extra arguments are given, the bus is initialised.
+   See ``init`` for parameters of initialisation.
+
+   The physical pins of the CAN busses are:
+
+     - ``CAN(1)`` is on ``YA``: ``(RX, TX) = (Y3, Y4) = (PB8, PB9)``
+     - ``CAN(2)`` is on ``YB``: ``(RX, TX) = (Y5, Y6) = (PB12, PB13)``
+
+Class Methods
+-------------
+.. classmethod:: CAN.initfilterbanks(nr)
+
+   Reset and disable all filter banks and assign how many banks should be available for CAN(1).
+
+   STM32F405 has 28 filter banks that are shared between the two available CAN bus controllers.
+   This function configures how many filter banks should be assigned to each. ``nr`` is the number of banks
+   that will be assigned to CAN(1), the rest of the 28 are assigned to CAN(2).
+   At boot, 14 banks are assigned to each controller.
+
+Methods
+-------
+
+.. method:: CAN.init(mode, extframe=False, prescaler=100, \*, sjw=1, bs1=6, bs2=8)
+
+   Initialise the CAN bus with the given parameters:
+
+     - ``mode`` is one of:  NORMAL, LOOPBACK, SILENT, SILENT_LOOPBACK
+     - if ``extframe`` is True then the bus uses extended identifiers in the frames
+       (29 bits); otherwise it uses standard 11 bit identifiers
+     - ``prescaler`` is used to set the duration of 1 time quanta; the time quanta
+       will be the input clock (PCLK1, see :meth:`pyb.freq()`) divided by the prescaler
+     - ``sjw`` is the resynchronisation jump width in units of the time quanta;
+       it can be 1, 2, 3, 4
+     - ``bs1`` defines the location of the sample point in units of the time quanta;
+       it can be between 1 and 1024 inclusive
+     - ``bs2`` defines the location of the transmit point in units of the time quanta;
+       it can be between 1 and 16 inclusive
+
+   The time quanta tq is the basic unit of time for the CAN bus.  tq is the CAN
+   prescaler value divided by PCLK1 (the frequency of internal peripheral bus 1);
+   see :meth:`pyb.freq()` to determine PCLK1.
+
+   A single bit is made up of the synchronisation segment, which is always 1 tq.
+   Then follows bit segment 1, then bit segment 2.  The sample point is after bit
+   segment 1 finishes.  The transmit point is after bit segment 2 finishes.
+   The baud rate will be 1/bittime, where the bittime is 1 + BS1 + BS2 multiplied
+   by the time quanta tq.
+
+   For example, with PCLK1=42MHz, prescaler=100, sjw=1, bs1=6, bs2=8, the value of
+   tq is 2.38 microseconds.  The bittime is 35.7 microseconds, and the baudrate
+   is 28kHz.
+
+   See page 680 of the STM32F405 datasheet for more details.
+
+.. method:: CAN.deinit()
+
+   Turn off the CAN bus.
+
+.. method:: CAN.setfilter(bank, mode, fifo, params, \*, rtr)
+
+   Configure a filter bank:
+
+   - ``bank`` is the filter bank that is to be configured.
+   - ``mode`` is the mode the filter should operate in.
+   - ``fifo`` is which fifo (0 or 1) a message should be stored in, if it is accepted by this filter.
+   - ``params`` is an array of values the defines the filter. The contents of the array depends on the ``mode`` argument.
+
+   +-----------+---------------------------------------------------------+
+   |``mode``   |contents of parameter array                              |
+   +===========+=========================================================+
+   |CAN.LIST16 |Four 16 bit ids that will be accepted                    |
+   +-----------+---------------------------------------------------------+
+   |CAN.LIST32 |Two 32 bit ids that will be accepted                     |
+   +-----------+---------------------------------------------------------+
+   |CAN.MASK16 |Two 16 bit id/mask pairs. E.g. (1, 3, 4, 4)              |
+   |           | | The first pair, 1 and 3 will accept all ids           |
+   |           | | that have bit 0 = 1 and bit 1 = 0.                    |
+   |           | | The second pair, 4 and 4, will accept all ids         |
+   |           | | that have bit 2 = 1.                                  |
+   +-----------+---------------------------------------------------------+
+   |CAN.MASK32 |As with CAN.MASK16 but with only one 32 bit id/mask pair.|
+   +-----------+---------------------------------------------------------+
+
+   - ``rtr`` is an array of booleans that states if a filter should accept a
+     remote transmission request message.  If this argument is not given
+     then it defaults to False for all entries.  The length of the array
+     depends on the ``mode`` argument.
+
+   +-----------+----------------------+
+   |``mode``   |length of rtr array   |
+   +===========+======================+
+   |CAN.LIST16 |4                     |
+   +-----------+----------------------+
+   |CAN.LIST32 |2                     |
+   +-----------+----------------------+
+   |CAN.MASK16 |2                     |
+   +-----------+----------------------+
+   |CAN.MASK32 |1                     |
+   +-----------+----------------------+
+
+.. method:: CAN.clearfilter(bank)
+
+   Clear and disables a filter bank:
+
+   - ``bank`` is the filter bank that is to be cleared.
+
+.. method:: CAN.any(fifo)
+
+   Return ``True`` if any message waiting on the FIFO, else ``False``.
+
+.. method:: CAN.recv(fifo, \*, timeout=5000)
+
+   Receive data on the bus:
+
+     - ``fifo`` is an integer, which is the FIFO to receive on
+     - ``timeout`` is the timeout in milliseconds to wait for the receive.
+
+   Return value: A tuple containing four values.
+
+     - The id of the message.
+     - A boolean that indicates if the message is an RTR message.
+     - The FMI (Filter Match Index) value.
+     - An array containing the data.
+
+.. method:: CAN.send(data, id, \*, timeout=0, rtr=False)
+
+   Send a message on the bus:
+
+     - ``data`` is the data to send (an integer to send, or a buffer object).
+     - ``id`` is the id of the message to be sent.
+     - ``timeout`` is the timeout in milliseconds to wait for the send.
+     - ``rtr`` is a boolean that specifies if the message shall be sent as
+       a remote transmission request.  If ``rtr`` is True then only the length
+       of ``data`` is used to fill in the DLC slot of the frame; the actual
+       bytes in ``data`` are unused.
+
+     If timeout is 0 the message is placed in a buffer in one of three hardware
+     buffers and the method returns immediately. If all three buffers are in use
+     an exception is thrown. If timeout is not 0, the method waits until the
+     message is transmitted. If the message can't be transmitted within the
+     specified time an exception is thrown.
+
+   Return value: ``None``.
+
+.. method:: CAN.rxcallback(fifo, fun)
+
+   Register a function to be called when a message is accepted into a empty fifo:
+
+   - ``fifo`` is the receiving fifo.
+   - ``fun`` is the function to be called when the fifo becomes non empty.
+
+   The callback function takes two arguments the first is the can object it self the second is
+   a integer that indicates the reason for the callback.
+
+   +--------+------------------------------------------------+
+   | Reason |                                                |
+   +========+================================================+
+   | 0      | A message has been accepted into a empty FIFO. |
+   +--------+------------------------------------------------+
+   | 1      | The FIFO is full                               |
+   +--------+------------------------------------------------+
+   | 2      | A message has been lost due to a full FIFO     |
+   +--------+------------------------------------------------+
+
+   Example use of rxcallback::
+
+     def cb0(bus, reason):
+       print('cb0')
+       if reason == 0:
+           print('pending')
+       if reason == 1:
+           print('full')
+       if reason == 2:
+           print('overflow')
+
+     can = CAN(1, CAN.LOOPBACK)
+     can.rxcallback(0, cb0)
+
+Constants
+---------
+
+.. data:: CAN.NORMAL
+.. data:: CAN.LOOPBACK
+.. data:: CAN.SILENT
+.. data:: CAN.SILENT_LOOPBACK
+
+   the mode of the CAN bus
+
+.. data:: CAN.LIST16
+.. data:: CAN.MASK16
+.. data:: CAN.LIST32
+.. data:: CAN.MASK32
+
+   the operation mode of a filter

docs/library/pyb.DAC.rst

@@ -0,0 +1,109 @@
+.. currentmodule:: pyb
+.. _pyb.DAC:
+
+class DAC -- digital to analog conversion
+=========================================
+
+The DAC is used to output analog values (a specific voltage) on pin X5 or pin X6.
+The voltage will be between 0 and 3.3V.
+
+*This module will undergo changes to the API.*
+
+Example usage::
+
+    from pyb import DAC
+
+    dac = DAC(1)            # create DAC 1 on pin X5
+    dac.write(128)          # write a value to the DAC (makes X5 1.65V)
+
+    dac = DAC(1, bits=12)   # use 12 bit resolution
+    dac.write(4095)         # output maximum value, 3.3V
+
+To output a continuous sine-wave::
+
+    import math
+    from pyb import DAC
+
+    # create a buffer containing a sine-wave
+    buf = bytearray(100)
+    for i in range(len(buf)):
+        buf[i] = 128 + int(127 * math.sin(2 * math.pi * i / len(buf)))
+
+    # output the sine-wave at 400Hz
+    dac = DAC(1)
+    dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
+
+To output a continuous sine-wave at 12-bit resolution::
+
+    import math
+    from array import array
+    from pyb import DAC
+
+    # create a buffer containing a sine-wave, using half-word samples
+    buf = array('H', 2048 + int(2047 * math.sin(2 * math.pi * i / 128)) for i in range(128))
+
+    # output the sine-wave at 400Hz
+    dac = DAC(1, bits=12)
+    dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR)
+
+Constructors
+------------
+
+.. class:: pyb.DAC(port, bits=8)
+
+   Construct a new DAC object.
+
+   ``port`` can be a pin object, or an integer (1 or 2).
+   DAC(1) is on pin X5 and DAC(2) is on pin X6.
+
+   ``bits`` is an integer specifying the resolution, and can be 8 or 12.
+   The maximum value for the write and write_timed methods will be
+   2\*\*``bits``-1.
+
+Methods
+-------
+
+.. method:: DAC.init(bits=8)
+
+   Reinitialise the DAC.  ``bits`` can be 8 or 12.
+
+.. method:: DAC.deinit()
+
+   De-initialise the DAC making its pin available for other uses.
+
+.. method:: DAC.noise(freq)
+
+   Generate a pseudo-random noise signal.  A new random sample is written
+   to the DAC output at the given frequency.
+
+.. method:: DAC.triangle(freq)
+
+   Generate a triangle wave.  The value on the DAC output changes at
+   the given frequency, and the frequency of the repeating triangle wave
+   itself is 2048 times smaller.
+
+.. method:: DAC.write(value)
+
+   Direct access to the DAC output.  The minimum value is 0.  The maximum
+   value is 2\*\*``bits``-1, where ``bits`` is set when creating the DAC
+   object or by using the ``init`` method.
+
+.. method:: DAC.write_timed(data, freq, \*, mode=DAC.NORMAL)
+
+   Initiates a burst of RAM to DAC using a DMA transfer.
+   The input data is treated as an array of bytes in 8-bit mode, and
+   an array of unsigned half-words (array typecode 'H') in 12-bit mode.
+
+   ``freq`` can be an integer specifying the frequency to write the DAC
+   samples at, using Timer(6).  Or it can be an already-initialised
+   Timer object which is used to trigger the DAC sample.  Valid timers
+   are 2, 4, 5, 6, 7 and 8.
+
+   ``mode`` can be ``DAC.NORMAL`` or ``DAC.CIRCULAR``.
+
+   Example using both DACs at the same time::
+
+     dac1 = DAC(1)
+     dac2 = DAC(2)
+     dac1.write_timed(buf1, pyb.Timer(6, freq=100), mode=DAC.CIRCULAR)
+     dac2.write_timed(buf2, pyb.Timer(7, freq=200), mode=DAC.CIRCULAR)

docs/library/pyb.ExtInt.rst

@@ -0,0 +1,114 @@
+.. currentmodule:: pyb
+.. _pyb.ExtInt:
+
+class ExtInt -- configure I/O pins to interrupt on external events
+==================================================================
+
+There are a total of 22 interrupt lines. 16 of these can come from GPIO pins
+and the remaining 6 are from internal sources.
+
+For lines 0 through 15, a given line can map to the corresponding line from an
+arbitrary port. So line 0 can map to Px0 where x is A, B, C, ... and
+line 1 can map to Px1 where x is A, B, C, ... ::
+
+    def callback(line):
+        print("line =", line)
+
+Note: ExtInt will automatically configure the gpio line as an input. ::
+
+    extint = pyb.ExtInt(pin, pyb.ExtInt.IRQ_FALLING, pyb.Pin.PULL_UP, callback)
+
+Now every time a falling edge is seen on the X1 pin, the callback will be
+called. Caution: mechanical pushbuttons have "bounce" and pushing or
+releasing a switch will often generate multiple edges.
+See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed
+explanation, along with various techniques for debouncing.
+
+Trying to register 2 callbacks onto the same pin will throw an exception.
+
+If pin is passed as an integer, then it is assumed to map to one of the
+internal interrupt sources, and must be in the range 16 through 22.
+
+All other pin objects go through the pin mapper to come up with one of the
+gpio pins. ::
+
+    extint = pyb.ExtInt(pin, mode, pull, callback)
+
+Valid modes are pyb.ExtInt.IRQ_RISING, pyb.ExtInt.IRQ_FALLING,
+pyb.ExtInt.IRQ_RISING_FALLING, pyb.ExtInt.EVT_RISING,
+pyb.ExtInt.EVT_FALLING, and pyb.ExtInt.EVT_RISING_FALLING.
+
+Only the IRQ_xxx modes have been tested. The EVT_xxx modes have
+something to do with sleep mode and the WFE instruction.
+
+Valid pull values are pyb.Pin.PULL_UP, pyb.Pin.PULL_DOWN, pyb.Pin.PULL_NONE.
+
+There is also a C API, so that drivers which require EXTI interrupt lines
+can also use this code. See extint.h for the available functions and
+usrsw.h for an example of using this.
+
+
+Constructors
+------------
+
+.. class:: pyb.ExtInt(pin, mode, pull, callback)
+
+   Create an ExtInt object:
+   
+     - ``pin`` is the pin on which to enable the interrupt (can be a pin object or any valid pin name).
+     - ``mode`` can be one of:
+       - ``ExtInt.IRQ_RISING`` - trigger on a rising edge;
+       - ``ExtInt.IRQ_FALLING`` - trigger on a falling edge;
+       - ``ExtInt.IRQ_RISING_FALLING`` - trigger on a rising or falling edge.
+     - ``pull`` can be one of:
+       - ``pyb.Pin.PULL_NONE`` - no pull up or down resistors;
+       - ``pyb.Pin.PULL_UP`` - enable the pull-up resistor;
+       - ``pyb.Pin.PULL_DOWN`` - enable the pull-down resistor.
+     - ``callback`` is the function to call when the interrupt triggers.  The
+       callback function must accept exactly 1 argument, which is the line that
+       triggered the interrupt.
+
+
+Class methods
+-------------
+
+.. classmethod:: ExtInt.regs()
+
+   Dump the values of the EXTI registers.
+
+
+Methods
+-------
+
+.. method:: ExtInt.disable()
+
+   Disable the interrupt associated with the ExtInt object.
+   This could be useful for debouncing.
+
+.. method:: ExtInt.enable()
+
+   Enable a disabled interrupt.
+
+.. method:: ExtInt.line()
+
+   Return the line number that the pin is mapped to.
+
+.. method:: ExtInt.swint()
+
+   Trigger the callback from software.
+
+
+Constants
+---------
+
+.. data:: ExtInt.IRQ_FALLING
+
+   interrupt on a falling edge
+
+.. data:: ExtInt.IRQ_RISING
+
+   interrupt on a rising edge
+
+.. data:: ExtInt.IRQ_RISING_FALLING
+
+   interrupt on a rising or falling edge

docs/library/pyb.I2C.rst

@@ -0,0 +1,175 @@
+.. currentmodule:: pyb
+.. _pyb.I2C:
+
+class I2C -- a two-wire serial protocol
+=======================================
+
+I2C is a two-wire protocol for communicating between devices.  At the physical
+level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
+
+I2C objects are created attached to a specific bus.  They can be initialised
+when created, or initialised later on.
+
+.. only:: port_pyboard
+
+    Example::
+
+        from pyb import I2C
+
+        i2c = I2C(1)                         # create on bus 1
+        i2c = I2C(1, I2C.MASTER)             # create and init as a master
+        i2c.init(I2C.MASTER, baudrate=20000) # init as a master
+        i2c.init(I2C.SLAVE, addr=0x42)       # init as a slave with given address
+        i2c.deinit()                         # turn off the peripheral
+
+Printing the i2c object gives you information about its configuration.
+
+.. only:: port_pyboard
+
+    The basic methods are send and recv::
+
+        i2c.send('abc')      # send 3 bytes
+        i2c.send(0x42)       # send a single byte, given by the number
+        data = i2c.recv(3)   # receive 3 bytes
+    
+    To receive inplace, first create a bytearray::
+
+        data = bytearray(3)  # create a buffer
+        i2c.recv(data)       # receive 3 bytes, writing them into data
+
+    You can specify a timeout (in ms)::
+
+        i2c.send(b'123', timeout=2000)   # timeout after 2 seconds
+
+    A master must specify the recipient's address::
+
+        i2c.init(I2C.MASTER)
+        i2c.send('123', 0x42)        # send 3 bytes to slave with address 0x42
+        i2c.send(b'456', addr=0x42)  # keyword for address
+
+    Master also has other methods::
+
+        i2c.is_ready(0x42)           # check if slave 0x42 is ready
+        i2c.scan()                   # scan for slaves on the bus, returning
+                                     #   a list of valid addresses
+        i2c.mem_read(3, 0x42, 2)     # read 3 bytes from memory of slave 0x42,
+                                     #   starting at address 2 in the slave
+        i2c.mem_write('abc', 0x42, 2, timeout=1000) # write 'abc' (3 bytes) to memory of slave 0x42
+                                                    # starting at address 2 in the slave, timeout after 1 second
+
+Constructors
+------------
+
+.. only:: port_pyboard
+
+    .. class:: pyb.I2C(bus, ...)
+
+       Construct an I2C object on the given bus.  ``bus`` can be 1 or 2, 'X' or
+       'Y'. With no additional parameters, the I2C object is created but not
+       initialised (it has the settings from the last initialisation of
+       the bus, if any).  If extra arguments are given, the bus is initialised.
+       See ``init`` for parameters of initialisation.
+
+       The physical pins of the I2C busses on Pyboards V1.0 and V1.1 are:
+
+         - ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)``
+         - ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)``
+       
+       On the Pyboard Lite:
+       
+         - ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)``
+         - ``I2C(3)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PA8, PB8)``
+         
+       Calling the constructor with 'X' or 'Y' enables portability between Pyboard
+       types.
+
+Methods
+-------
+
+.. method:: I2C.deinit()
+
+   Turn off the I2C bus.
+
+.. only:: port_pyboard
+
+    .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False, dma=False)
+
+      Initialise the I2C bus with the given parameters:
+
+         - ``mode`` must be either ``I2C.MASTER`` or ``I2C.SLAVE``
+         - ``addr`` is the 7-bit address (only sensible for a slave)
+         - ``baudrate`` is the SCL clock rate (only sensible for a master)
+         - ``gencall`` is whether to support general call mode
+         - ``dma`` is whether to allow the use of DMA for the I2C transfers (note
+           that DMA transfers have more precise timing but currently do not handle bus
+           errors properly)
+
+    .. method:: I2C.is_ready(addr)
+
+       Check if an I2C device responds to the given address.  Only valid when in master mode.
+
+    .. method:: I2C.mem_read(data, addr, memaddr, \*, timeout=5000, addr_size=8)
+
+       Read from the memory of an I2C device:
+
+         - ``data`` can be an integer (number of bytes to read) or a buffer to read into
+         - ``addr`` is the I2C device address
+         - ``memaddr`` is the memory location within the I2C device
+         - ``timeout`` is the timeout in milliseconds to wait for the read
+         - ``addr_size`` selects width of memaddr: 8 or 16 bits
+
+       Returns the read data.
+       This is only valid in master mode.
+
+    .. method:: I2C.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8)
+
+       Write to the memory of an I2C device:
+
+         - ``data`` can be an integer or a buffer to write from
+         - ``addr`` is the I2C device address
+         - ``memaddr`` is the memory location within the I2C device
+         - ``timeout`` is the timeout in milliseconds to wait for the write
+         - ``addr_size`` selects width of memaddr: 8 or 16 bits
+
+       Returns ``None``.
+       This is only valid in master mode.
+
+    .. method:: I2C.recv(recv, addr=0x00, \*, timeout=5000)
+
+       Receive data on the bus:
+
+         - ``recv`` can be an integer, which is the number of bytes to receive,
+           or a mutable buffer, which will be filled with received bytes
+         - ``addr`` is the address to receive from (only required in master mode)
+         - ``timeout`` is the timeout in milliseconds to wait for the receive
+    
+       Return value: if ``recv`` is an integer then a new buffer of the bytes received,
+       otherwise the same buffer that was passed in to ``recv``.
+
+    .. method:: I2C.send(send, addr=0x00, \*, timeout=5000)
+
+       Send data on the bus:
+
+         - ``send`` is the data to send (an integer to send, or a buffer object)
+         - ``addr`` is the address to send to (only required in master mode)
+         - ``timeout`` is the timeout in milliseconds to wait for the send
+
+       Return value: ``None``.
+
+.. method:: I2C.scan()
+
+   Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond.
+   Only valid when in master mode.
+
+Constants
+---------
+
+.. data:: I2C.MASTER
+
+   for initialising the bus to master mode
+
+.. only:: port_pyboard
+
+    .. data:: I2C.SLAVE
+    
+       for initialising the bus to slave mode

docs/library/pyb.LCD.rst

@@ -0,0 +1,97 @@
+.. currentmodule:: pyb
+.. _pyb.LCD:
+
+class LCD -- LCD control for the LCD touch-sensor pyskin
+========================================================
+
+The LCD class is used to control the LCD on the LCD touch-sensor pyskin,
+LCD32MKv1.0.  The LCD is a 128x32 pixel monochrome screen, part NHD-C12832A1Z.
+
+The pyskin must be connected in either the X or Y positions, and then
+an LCD object is made using::
+
+    lcd = pyb.LCD('X')      # if pyskin is in the X position
+    lcd = pyb.LCD('Y')      # if pyskin is in the Y position
+
+Then you can use::
+
+    lcd.light(True)                 # turn the backlight on
+    lcd.write('Hello world!\n')     # print text to the screen
+
+This driver implements a double buffer for setting/getting pixels.
+For example, to make a bouncing dot, try::
+
+    x = y = 0
+    dx = dy = 1
+    while True:
+        # update the dot's position
+        x += dx
+        y += dy
+
+        # make the dot bounce of the edges of the screen
+        if x <= 0 or x >= 127: dx = -dx
+        if y <= 0 or y >= 31: dy = -dy
+
+        lcd.fill(0)                 # clear the buffer
+        lcd.pixel(x, y, 1)          # draw the dot
+        lcd.show()                  # show the buffer
+        pyb.delay(50)               # pause for 50ms
+
+
+Constructors
+------------
+
+.. class:: pyb.LCD(skin_position)
+
+   Construct an LCD object in the given skin position.  ``skin_position`` can be 'X' or 'Y', and
+   should match the position where the LCD pyskin is plugged in.
+
+
+Methods
+-------
+
+.. method:: LCD.command(instr_data, buf)
+
+   Send an arbitrary command to the LCD.  Pass 0 for ``instr_data`` to send an
+   instruction, otherwise pass 1 to send data.  ``buf`` is a buffer with the
+   instructions/data to send.
+
+.. method:: LCD.contrast(value)
+
+   Set the contrast of the LCD.  Valid values are between 0 and 47.
+
+.. method:: LCD.fill(colour)
+
+   Fill the screen with the given colour (0 or 1 for white or black).
+   
+   This method writes to the hidden buffer.  Use ``show()`` to show the buffer.
+
+.. method:: LCD.get(x, y)
+
+   Get the pixel at the position ``(x, y)``.  Returns 0 or 1.
+   
+   This method reads from the visible buffer.
+
+.. method:: LCD.light(value)
+
+   Turn the backlight on/off.  True or 1 turns it on, False or 0 turns it off.
+
+.. method:: LCD.pixel(x, y, colour)
+
+   Set the pixel at ``(x, y)`` to the given colour (0 or 1).
+   
+   This method writes to the hidden buffer.  Use ``show()`` to show the buffer.
+
+.. method:: LCD.show()
+
+   Show the hidden buffer on the screen.
+
+.. method:: LCD.text(str, x, y, colour)
+
+   Draw the given text to the position ``(x, y)`` using the given colour (0 or 1).
+   
+   This method writes to the hidden buffer.  Use ``show()`` to show the buffer.
+
+.. method:: LCD.write(str)
+
+   Write the string ``str`` to the screen.  It will appear immediately.

docs/library/pyb.LED.rst

@@ -0,0 +1,46 @@
+.. currentmodule:: pyb
+.. _pyb.LED:
+
+class LED -- LED object
+=======================
+
+The LED object controls an individual LED (Light Emitting Diode).
+
+
+Constructors
+------------
+
+.. class:: pyb.LED(id)
+
+   Create an LED object associated with the given LED:
+   
+     - ``id`` is the LED number, 1-4.
+
+
+Methods
+-------
+
+.. method:: LED.intensity([value])
+
+   Get or set the LED intensity.  Intensity ranges between 0 (off) and 255 (full on).
+   If no argument is given, return the LED intensity.
+   If an argument is given, set the LED intensity and return ``None``.
+
+   *Note:* Only LED(3) and LED(4) can have a smoothly varying intensity, and
+   they use timer PWM to implement it.  LED(3) uses Timer(2) and LED(4) uses
+   Timer(3).  These timers are only configured for PWM if the intensity of the
+   relevant LED is set to a value between 1 and 254.  Otherwise the timers are
+   free for general purpose use.
+
+.. method:: LED.off()
+
+   Turn the LED off.
+
+.. method:: LED.on()
+
+   Turn the LED on, to maximum intensity.
+
+.. method:: LED.toggle()
+
+   Toggle the LED between on (maximum intensity) and off.  If the LED is at
+   non-zero intensity then it is considered "on" and toggle will turn it off.

docs/library/pyb.Pin.rst

@@ -0,0 +1,280 @@
+.. currentmodule:: pyb
+.. _pyb.Pin:
+
+class Pin -- control I/O pins
+=============================
+
+A pin is the basic object to control I/O pins.  It has methods to set
+the mode of the pin (input, output, etc) and methods to get and set the
+digital logic level. For analog control of a pin, see the ADC class.
+
+Usage Model:
+
+.. only:: port_pyboard
+
+    All Board Pins are predefined as pyb.Pin.board.Name::
+    
+        x1_pin = pyb.Pin.board.X1
+    
+        g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN)
+    
+    CPU pins which correspond to the board pins are available
+    as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter
+    followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and
+    ``pyb.Pin.cpu.A0`` are the same pin.
+    
+    You can also use strings::
+    
+        g = pyb.Pin('X1', pyb.Pin.OUT_PP)
+    
+    Users can add their own names::
+    
+        MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 }
+        pyb.Pin.dict(MyMapperDict)
+        g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD)
+    
+    and can query mappings::
+    
+        pin = pyb.Pin("LeftMotorDir")
+    
+    Users can also add their own mapping function::
+    
+        def MyMapper(pin_name):
+           if pin_name == "LeftMotorDir":
+               return pyb.Pin.cpu.A0
+    
+        pyb.Pin.mapper(MyMapper)
+    
+    So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)``
+    then ``"LeftMotorDir"`` is passed directly to the mapper function.
+    
+    To summarise, the following order determines how things get mapped into
+    an ordinal pin number:
+    
+    1. Directly specify a pin object
+    2. User supplied mapping function
+    3. User supplied mapping (object must be usable as a dictionary key)
+    4. Supply a string which matches a board pin
+    5. Supply a string which matches a CPU port/pin
+    
+    You can set ``pyb.Pin.debug(True)`` to get some debug information about
+    how a particular object gets mapped to a pin.
+    
+    When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
+    that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
+    respectively (except pin Y5 which has 11k Ohm resistors).
+
+    Now every time a falling edge is seen on the gpio pin, the callback will be
+    executed. Caution: mechanical push buttons have "bounce" and pushing or
+    releasing a switch will often generate multiple edges.
+    See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed
+    explanation, along with various techniques for debouncing.
+
+    All pin objects go through the pin mapper to come up with one of the
+    gpio pins.
+
+Constructors
+------------
+
+.. class:: pyb.Pin(id, ...)
+
+   Create a new Pin object associated with the id.  If additional arguments are given,
+   they are used to initialise the pin.  See :meth:`pin.init`.
+
+.. only:: port_pyboard
+
+    Class methods
+    -------------
+
+    .. classmethod:: Pin.debug([state])
+    
+       Get or set the debugging state (``True`` or ``False`` for on or off).
+    
+    .. classmethod:: Pin.dict([dict])
+    
+       Get or set the pin mapper dictionary.
+    
+    .. classmethod:: Pin.mapper([fun])
+    
+       Get or set the pin mapper function.
+
+
+Methods
+-------
+
+.. only:: port_pyboard
+
+    .. method:: Pin.init(mode, pull=Pin.PULL_NONE, af=-1)
+    
+       Initialise the pin:
+       
+         - ``mode`` can be one of:
+
+            - ``Pin.IN`` - configure the pin for input;
+            - ``Pin.OUT_PP`` - configure the pin for output, with push-pull control;
+            - ``Pin.OUT_OD`` - configure the pin for output, with open-drain control;
+            - ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull;
+            - ``Pin.AF_OD`` - configure the pin for alternate function, open-drain;
+            - ``Pin.ANALOG`` - configure the pin for analog.
+
+         - ``pull`` can be one of:
+
+            - ``Pin.PULL_NONE`` - no pull up or down resistors;
+            - ``Pin.PULL_UP`` - enable the pull-up resistor;
+            - ``Pin.PULL_DOWN`` - enable the pull-down resistor.
+
+         - when mode is ``Pin.AF_PP`` or ``Pin.AF_OD``, then af can be the index or name
+           of one of the alternate functions associated with a pin.
+       
+       Returns: ``None``.
+
+.. method:: Pin.value([value])
+
+   Get or set the digital logic level of the pin:
+
+     - With no argument, return 0 or 1 depending on the logic level of the pin.
+     - With ``value`` given, set the logic level of the pin.  ``value`` can be
+       anything that converts to a boolean.  If it converts to ``True``, the pin
+       is set high, otherwise it is set low.
+
+.. only:: port_pyboard
+
+    .. method:: Pin.__str__()
+    
+       Return a string describing the pin object.
+    
+    .. method:: Pin.af()
+    
+       Returns the currently configured alternate-function of the pin. The
+       integer returned will match one of the allowed constants for the af
+       argument to the init function.
+
+    .. method:: Pin.af_list()
+
+       Returns an array of alternate functions available for this pin.
+    
+    .. method:: Pin.gpio()
+    
+       Returns the base address of the GPIO block associated with this pin.
+    
+    .. method:: Pin.mode()
+    
+       Returns the currently configured mode of the pin. The integer returned
+       will match one of the allowed constants for the mode argument to the init
+       function.
+    
+    .. method:: Pin.name()
+
+       Get the pin name.
+
+    .. method:: Pin.names()
+    
+       Returns the cpu and board names for this pin.
+    
+    .. method:: Pin.pin()
+    
+       Get the pin number.
+    
+    .. method:: Pin.port()
+    
+       Get the pin port.
+
+.. method:: Pin.pull()
+
+    Returns the currently configured pull of the pin. The integer returned
+    will match one of the allowed constants for the pull argument to the init
+    function.
+
+Constants
+---------
+
+.. only:: port_pyboard
+
+    .. data:: Pin.AF_OD
+    
+       initialise the pin to alternate-function mode with an open-drain drive
+    
+    .. data:: Pin.AF_PP
+    
+       initialise the pin to alternate-function mode with a push-pull drive
+    
+    .. data:: Pin.ANALOG
+    
+       initialise the pin to analog mode
+    
+    .. data:: Pin.IN
+    
+       initialise the pin to input mode
+    
+    .. data:: Pin.OUT_OD
+    
+       initialise the pin to output mode with an open-drain drive
+    
+    .. data:: Pin.OUT_PP
+    
+       initialise the pin to output mode with a push-pull drive
+    
+    .. data:: Pin.PULL_DOWN
+    
+       enable the pull-down resistor on the pin
+    
+    .. data:: Pin.PULL_NONE
+    
+       don't enable any pull up or down resistors on the pin
+    
+    .. data:: Pin.PULL_UP
+    
+       enable the pull-up resistor on the pin
+
+.. only:: port_pyboard
+
+    class PinAF -- Pin Alternate Functions
+    ======================================
+    
+    A Pin represents a physical pin on the microprocessor. Each pin
+    can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF
+    object represents a particular function for a pin.
+    
+    Usage Model::
+    
+        x3 = pyb.Pin.board.X3
+        x3_af = x3.af_list()
+    
+    x3_af will now contain an array of PinAF objects which are available on
+    pin X3.
+    
+    For the pyboard, x3_af would contain:
+        [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2]
+    
+    Normally, each peripheral would configure the af automatically, but sometimes
+    the same function is available on multiple pins, and having more control
+    is desired.
+    
+    To configure X3 to expose TIM2_CH3, you could use::
+    
+       pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2)
+    
+    or::
+    
+       pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1)
+
+    Methods
+    -------
+    
+    .. method:: pinaf.__str__()
+    
+       Return a string describing the alternate function.
+    
+    .. method:: pinaf.index()
+    
+       Return the alternate function index.
+    
+    .. method:: pinaf.name()
+    
+       Return the name of the alternate function.
+    
+    .. method:: pinaf.reg()
+    
+       Return the base register associated with the peripheral assigned to this
+       alternate function. For example, if the alternate function were TIM2_CH3
+       this would return stm.TIM2

docs/library/pyb.RTC.rst

@@ -0,0 +1,83 @@
+.. currentmodule:: pyb
+.. _pyb.RTC:
+
+class RTC -- real time clock
+============================
+
+The RTC is and independent clock that keeps track of the date
+and time.
+
+Example usage::
+
+    rtc = pyb.RTC()
+    rtc.datetime((2014, 5, 1, 4, 13, 0, 0, 0))
+    print(rtc.datetime())
+
+
+Constructors
+------------
+
+.. class:: pyb.RTC()
+
+   Create an RTC object.
+
+
+Methods
+-------
+
+.. method:: RTC.datetime([datetimetuple])
+
+   Get or set the date and time of the RTC.
+   
+   With no arguments, this method returns an 8-tuple with the current
+   date and time.  With 1 argument (being an 8-tuple) it sets the date
+   and time.
+   
+   .. only:: port_pyboard
+   
+       The 8-tuple has the following format:
+       
+           (year, month, day, weekday, hours, minutes, seconds, subseconds)
+       
+       ``weekday`` is 1-7 for Monday through Sunday.
+       
+       ``subseconds`` counts down from 255 to 0
+
+.. only:: port_pyboard
+
+    .. method:: RTC.wakeup(timeout, callback=None)
+    
+       Set the RTC wakeup timer to trigger repeatedly at every ``timeout``
+       milliseconds.  This trigger can wake the pyboard from both the sleep
+       states: :meth:`pyb.stop` and :meth:`pyb.standby`.
+    
+       If ``timeout`` is ``None`` then the wakeup timer is disabled.
+    
+       If ``callback`` is given then it is executed at every trigger of the
+       wakeup timer.  ``callback`` must take exactly one argument.
+    
+    .. method:: RTC.info()
+    
+       Get information about the startup time and reset source.
+       
+        - The lower 0xffff are the number of milliseconds the RTC took to
+          start up.
+        - Bit 0x10000 is set if a power-on reset occurred.
+        - Bit 0x20000 is set if an external reset occurred
+    
+    .. method:: RTC.calibration(cal)
+    
+       Get or set RTC calibration.
+    
+       With no arguments, ``calibration()`` returns the current calibration
+       value, which is an integer in the range [-511 : 512].  With one
+       argument it sets the RTC calibration.
+    
+       The RTC Smooth Calibration mechanism adjusts the RTC clock rate by
+       adding or subtracting the given number of ticks from the 32768 Hz
+       clock over a 32 second period (corresponding to 2^20 clock ticks.)
+       Each tick added will speed up the clock by 1 part in 2^20, or 0.954
+       ppm; likewise the RTC clock it slowed by negative values. The
+       usable calibration range is:
+       (-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm
+

docs/library/pyb.SPI.rst

@@ -0,0 +1,132 @@
+.. currentmodule:: pyb
+.. _pyb.SPI:
+
+class SPI -- a master-driven serial protocol
+============================================
+
+SPI is a serial protocol that is driven by a master.  At the physical level
+there are 3 lines: SCK, MOSI, MISO.
+
+.. only:: port_pyboard
+
+    See usage model of I2C; SPI is very similar.  Main difference is
+    parameters to init the SPI bus::
+
+        from pyb import SPI
+        spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7)
+
+    Only required parameter is mode, SPI.MASTER or SPI.SLAVE.  Polarity can be
+    0 or 1, and is the level the idle clock line sits at.  Phase can be 0 or 1
+    to sample data on the first or second clock edge respectively.  Crc can be
+    None for no CRC, or a polynomial specifier.
+
+    Additional methods for SPI::
+
+        data = spi.send_recv(b'1234')        # send 4 bytes and receive 4 bytes
+        buf = bytearray(4)
+        spi.send_recv(b'1234', buf)          # send 4 bytes and receive 4 into buf
+        spi.send_recv(buf, buf)              # send/recv 4 bytes from/to buf
+
+Constructors
+------------
+
+.. only:: port_pyboard
+
+    .. class:: pyb.SPI(bus, ...)
+
+       Construct an SPI object on the given bus.  ``bus`` can be 1 or 2, or
+       'X' or 'Y'. With no additional parameters, the SPI object is created but
+       not initialised (it has the settings from the last initialisation of
+       the bus, if any).  If extra arguments are given, the bus is initialised.
+       See ``init`` for parameters of initialisation.
+
+       The physical pins of the SPI busses are:
+
+         - ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)``
+         - ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)``
+
+       At the moment, the NSS pin is not used by the SPI driver and is free
+       for other use.
+
+Methods
+-------
+
+.. method:: SPI.deinit()
+
+   Turn off the SPI bus.
+
+.. only:: port_pyboard
+
+    .. method:: SPI.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None)
+
+       Initialise the SPI bus with the given parameters:
+
+         - ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``.
+         - ``baudrate`` is the SCK clock rate (only sensible for a master).
+         - ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency;
+           use of ``prescaler`` overrides ``baudrate``.
+         - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
+         - ``phase`` can be 0 or 1 to sample data on the first or second clock edge
+           respectively.
+         - ``bits`` can be 8 or 16, and is the number of bits in each transferred word.
+         - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
+         - ``crc`` can be None for no CRC, or a polynomial specifier.
+
+       Note that the SPI clock frequency will not always be the requested baudrate.
+       The hardware only supports baudrates that are the APB bus frequency
+       (see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32,
+       64, 128 or 256.  SPI(1) is on AHB2, and SPI(2) is on AHB1.  For precise
+       control over the SPI clock frequency, specify ``prescaler`` instead of
+       ``baudrate``.
+
+       Printing the SPI object will show you the computed baudrate and the chosen
+       prescaler.
+
+.. only:: port_pyboard
+
+    .. method:: SPI.recv(recv, \*, timeout=5000)
+    
+       Receive data on the bus:
+
+         - ``recv`` can be an integer, which is the number of bytes to receive,
+           or a mutable buffer, which will be filled with received bytes.
+         - ``timeout`` is the timeout in milliseconds to wait for the receive.
+
+       Return value: if ``recv`` is an integer then a new buffer of the bytes received,
+       otherwise the same buffer that was passed in to ``recv``.
+    
+    .. method:: SPI.send(send, \*, timeout=5000)
+
+       Send data on the bus:
+
+         - ``send`` is the data to send (an integer to send, or a buffer object).
+         - ``timeout`` is the timeout in milliseconds to wait for the send.
+
+       Return value: ``None``.
+
+    .. method:: SPI.send_recv(send, recv=None, \*, timeout=5000)
+    
+       Send and receive data on the bus at the same time:
+
+         - ``send`` is the data to send (an integer to send, or a buffer object).
+         - ``recv`` is a mutable buffer which will be filled with received bytes.
+           It can be the same as ``send``, or omitted.  If omitted, a new buffer will
+           be created.
+         - ``timeout`` is the timeout in milliseconds to wait for the receive.
+
+       Return value: the buffer with the received bytes.
+
+Constants
+---------
+
+.. only:: port_pyboard
+
+    .. data:: SPI.MASTER
+    .. data:: SPI.SLAVE
+    
+       for initialising the SPI bus to master or slave mode
+    
+    .. data:: SPI.LSB
+    .. data:: SPI.MSB
+    
+       set the first bit to be the least or most significant bit

docs/library/pyb.Servo.rst

@@ -0,0 +1,80 @@
+.. currentmodule:: pyb
+.. _pyb.Servo:
+
+class Servo -- 3-wire hobby servo driver
+========================================
+
+Servo objects control standard hobby servo motors with 3-wires (ground, power,
+signal).  There are 4 positions on the pyboard where these motors can be plugged
+in: pins X1 through X4 are the signal pins, and next to them are 4 sets of power
+and ground pins.
+
+Example usage::
+
+    import pyb
+
+    s1 = pyb.Servo(1)   # create a servo object on position X1
+    s2 = pyb.Servo(2)   # create a servo object on position X2
+
+    s1.angle(45)        # move servo 1 to 45 degrees
+    s2.angle(0)         # move servo 2 to 0 degrees
+
+    # move servo1 and servo2 synchronously, taking 1500ms
+    s1.angle(-60, 1500)
+    s2.angle(30, 1500)
+
+.. note:: The Servo objects use Timer(5) to produce the PWM output.  You can
+   use Timer(5) for Servo control, or your own purposes, but not both at the
+   same time.
+
+Constructors
+------------
+
+.. class:: pyb.Servo(id)
+
+   Create a servo object.  ``id`` is 1-4, and corresponds to pins X1 through X4.
+
+
+Methods
+-------
+
+.. method:: Servo.angle([angle, time=0])
+
+   If no arguments are given, this function returns the current angle.
+
+   If arguments are given, this function sets the angle of the servo:
+
+     - ``angle`` is the angle to move to in degrees.
+     - ``time`` is the number of milliseconds to take to get to the specified
+       angle.  If omitted, then the servo moves as quickly as possible to its
+       new position.
+
+.. method:: Servo.speed([speed, time=0])
+
+   If no arguments are given, this function returns the current speed.
+
+   If arguments are given, this function sets the speed of the servo:
+
+     - ``speed`` is the speed to change to, between -100 and 100.
+     - ``time`` is the number of milliseconds to take to get to the specified
+       speed.  If omitted, then the servo accelerates as quickly as possible.
+
+.. method:: Servo.pulse_width([value])
+
+   If no arguments are given, this function returns the current raw pulse-width
+   value.
+
+   If an argument is given, this function sets the raw pulse-width value.
+
+.. method:: Servo.calibration([pulse_min, pulse_max, pulse_centre, [pulse_angle_90, pulse_speed_100]])
+
+   If no arguments are given, this function returns the current calibration
+   data, as a 5-tuple.
+
+   If arguments are given, this function sets the timing calibration:
+
+     - ``pulse_min`` is the minimum allowed pulse width.
+     - ``pulse_max`` is the maximum allowed pulse width.
+     - ``pulse_centre`` is the pulse width corresponding to the centre/zero position.
+     - ``pulse_angle_90`` is the pulse width corresponding to 90 degrees.
+     - ``pulse_speed_100`` is the pulse width corresponding to a speed of 100.

docs/library/pyb.Switch.rst

@@ -0,0 +1,46 @@
+.. currentmodule:: pyb
+.. _pyb.Switch:
+
+class Switch -- switch object
+=============================
+
+A Switch object is used to control a push-button switch.
+
+Usage::
+
+     sw = pyb.Switch()       # create a switch object
+     sw.value()              # get state (True if pressed, False otherwise)
+     sw()                    # shorthand notation to get the switch state
+     sw.callback(f)          # register a callback to be called when the
+                             #   switch is pressed down
+     sw.callback(None)       # remove the callback
+
+Example::
+
+     pyb.Switch().callback(lambda: pyb.LED(1).toggle())
+
+
+Constructors
+------------
+
+.. class:: pyb.Switch()
+
+   Create and return a switch object.
+
+
+Methods
+-------
+
+.. method:: Switch.__call__()
+
+   Call switch object directly to get its state: ``True`` if pressed down,
+   ``False`` otherwise.
+
+.. method:: Switch.value()
+
+   Get the switch state.  Returns `True` if pressed down, otherwise `False`.
+
+.. method:: Switch.callback(fun)
+
+   Register the given function to be called when the switch is pressed down.
+   If ``fun`` is ``None``, then it disables the callback.

docs/library/pyb.Timer.rst

@@ -0,0 +1,286 @@
+.. currentmodule:: pyb
+.. _pyb.Timer:
+
+class Timer -- control internal timers
+======================================
+
+.. only:: port_pyboard
+
+    Timers can be used for a great variety of tasks.  At the moment, only
+    the simplest case is implemented: that of calling a function periodically.
+    
+    Each timer consists of a counter that counts up at a certain rate.  The rate
+    at which it counts is the peripheral clock frequency (in Hz) divided by the
+    timer prescaler.  When the counter reaches the timer period it triggers an
+    event, and the counter resets back to zero.  By using the callback method,
+    the timer event can call a Python function.
+    
+    Example usage to toggle an LED at a fixed frequency::
+    
+        tim = pyb.Timer(4)              # create a timer object using timer 4
+        tim.init(freq=2)                # trigger at 2Hz
+        tim.callback(lambda t:pyb.LED(1).toggle())
+    
+    Example using named function for the callback::
+    
+        def tick(timer):                # we will receive the timer object when being called
+            print(timer.counter())      # show current timer's counter value
+        tim = pyb.Timer(4, freq=1)      # create a timer object using timer 4 - trigger at 1Hz
+        tim.callback(tick)              # set the callback to our tick function
+    
+    Further examples::
+    
+        tim = pyb.Timer(4, freq=100)    # freq in Hz
+        tim = pyb.Timer(4, prescaler=0, period=99)
+        tim.counter()                   # get counter (can also set)
+        tim.prescaler(2)                # set prescaler (can also get)
+        tim.period(199)                 # set period (can also get)
+        tim.callback(lambda t: ...)     # set callback for update interrupt (t=tim instance)
+        tim.callback(None)              # clear callback
+    
+    *Note:* Timer(2) and Timer(3) are used for PWM to set the intensity of LED(3)
+    and LED(4) respectively.  But these timers are only configured for PWM if
+    the intensity of the relevant LED is set to a value between 1 and 254.  If
+    the intensity feature of the LEDs is not used then these timers are free for
+    general purpose use.  Similarly, Timer(5) controls the servo driver, and
+    Timer(6) is used for timed ADC/DAC reading/writing.  It is recommended to
+    use the other timers in your programs.
+
+*Note:* Memory can't be allocated during a callback (an interrupt) and so
+exceptions raised within a callback don't give much information.  See
+:func:`micropython.alloc_emergency_exception_buf` for how to get around this
+limitation.
+
+
+Constructors
+------------
+
+.. class:: pyb.Timer(id, ...)
+
+    .. only:: port_pyboard
+    
+       Construct a new timer object of the given id.  If additional
+       arguments are given, then the timer is initialised by ``init(...)``.
+       ``id`` can be 1 to 14.
+
+Methods
+-------
+
+.. only:: port_pyboard
+
+    .. method:: Timer.init(\*, freq, prescaler, period)
+    
+       Initialise the timer.  Initialisation must be either by frequency (in Hz)
+       or by prescaler and period::
+       
+           tim.init(freq=100)                  # set the timer to trigger at 100Hz
+           tim.init(prescaler=83, period=999)  # set the prescaler and period directly
+       
+       Keyword arguments:
+       
+         - ``freq`` --- specifies the periodic frequency of the timer. You might also
+           view this as the frequency with which the timer goes through one complete cycle.
+       
+         - ``prescaler`` [0-0xffff] - specifies the value to be loaded into the
+           timer's Prescaler Register (PSC). The timer clock source is divided by
+           (``prescaler + 1``) to arrive at the timer clock. Timers 2-7 and 12-14
+           have a clock source of 84 MHz (pyb.freq()[2] \* 2), and Timers 1, and 8-11
+           have a clock source of 168 MHz (pyb.freq()[3] \* 2).
+       
+         - ``period`` [0-0xffff] for timers 1, 3, 4, and 6-15. [0-0x3fffffff] for timers 2 & 5.
+           Specifies the value to be loaded into the timer's AutoReload
+           Register (ARR). This determines the period of the timer (i.e. when the
+           counter cycles). The timer counter will roll-over after ``period + 1``
+           timer clock cycles.
+       
+         - ``mode`` can be one of:
+    
+           - ``Timer.UP`` - configures the timer to count from 0 to ARR (default)
+           - ``Timer.DOWN`` - configures the timer to count from ARR down to 0.
+           - ``Timer.CENTER`` - configures the timer to count from 0 to ARR and
+             then back down to 0.
+       
+         - ``div`` can be one of 1, 2, or 4. Divides the timer clock to determine
+           the sampling clock used by the digital filters.
+       
+         - ``callback`` - as per Timer.callback()
+       
+         - ``deadtime`` - specifies the amount of "dead" or inactive time between
+           transitions on complimentary channels (both channels will be inactive)
+           for this time). ``deadtime`` may be an integer between 0 and 1008, with
+           the following restrictions: 0-128 in steps of 1. 128-256 in steps of
+           2, 256-512 in steps of 8, and 512-1008 in steps of 16. ``deadtime``
+           measures ticks of ``source_freq`` divided by ``div`` clock ticks.
+           ``deadtime`` is only available on timers 1 and 8.
+       
+        You must either specify freq or both of period and prescaler.
+
+.. method:: Timer.deinit()
+
+   Deinitialises the timer.
+   
+   .. only:: port_pyboard
+
+      Disables the callback (and the associated irq).
+
+   Disables any channel callbacks (and the associated irq).
+   Stops the timer, and disables the timer peripheral.
+
+.. only:: port_pyboard
+
+    .. method:: Timer.callback(fun)
+    
+       Set the function to be called when the timer triggers.
+       ``fun`` is passed 1 argument, the timer object.
+       If ``fun`` is ``None`` then the callback will be disabled.
+
+.. only:: port_pyboard
+
+    .. method:: Timer.channel(channel, mode, ...)
+    
+       If only a channel number is passed, then a previously initialized channel
+       object is returned (or ``None`` if there is no previous channel).
+       
+       Otherwise, a TimerChannel object is initialized and returned.
+       
+       Each channel can be configured to perform pwm, output compare, or
+       input capture. All channels share the same underlying timer, which means
+       that they share the same timer clock.
+       
+       Keyword arguments:
+       
+         - ``mode`` can be one of:
+    
+           - ``Timer.PWM`` --- configure the timer in PWM mode (active high).
+           - ``Timer.PWM_INVERTED`` --- configure the timer in PWM mode (active low).
+           - ``Timer.OC_TIMING`` --- indicates that no pin is driven.
+           - ``Timer.OC_ACTIVE`` --- the pin will be made active when a compare match occurs (active is determined by polarity)
+           - ``Timer.OC_INACTIVE`` --- the pin will be made inactive when a compare match occurs.
+           - ``Timer.OC_TOGGLE`` --- the pin will be toggled when an compare match occurs.
+           - ``Timer.OC_FORCED_ACTIVE`` --- the pin is forced active (compare match is ignored).
+           - ``Timer.OC_FORCED_INACTIVE`` --- the pin is forced inactive (compare match is ignored).
+           - ``Timer.IC`` --- configure the timer in Input Capture mode.
+           - ``Timer.ENC_A`` --- configure the timer in Encoder mode. The counter only changes when CH1 changes.
+           - ``Timer.ENC_B`` --- configure the timer in Encoder mode. The counter only changes when CH2 changes.
+           - ``Timer.ENC_AB`` --- configure the timer in Encoder mode. The counter changes when CH1 or CH2 changes.
+    
+         - ``callback`` - as per TimerChannel.callback()
+       
+         - ``pin`` None (the default) or a Pin object. If specified (and not None)
+           this will cause the alternate function of the the indicated pin
+           to be configured for this timer channel. An error will be raised if
+           the pin doesn't support any alternate functions for this timer channel.
+    
+       Keyword arguments for Timer.PWM modes:
+       
+         - ``pulse_width`` - determines the initial pulse width value to use.
+         - ``pulse_width_percent`` - determines the initial pulse width percentage to use.
+       
+       Keyword arguments for Timer.OC modes:
+       
+         - ``compare`` - determines the initial value of the compare register.
+       
+         - ``polarity`` can be one of:
+    
+           - ``Timer.HIGH`` - output is active high
+           - ``Timer.LOW`` - output is active low
+       
+       Optional keyword arguments for Timer.IC modes:
+       
+         - ``polarity`` can be one of:
+    
+           - ``Timer.RISING`` - captures on rising edge.
+           - ``Timer.FALLING`` - captures on falling edge.
+           - ``Timer.BOTH`` - captures on both edges.
+       
+         Note that capture only works on the primary channel, and not on the
+         complimentary channels.
+       
+       Notes for Timer.ENC modes:
+    
+         - Requires 2 pins, so one or both pins will need to be configured to use
+           the appropriate timer AF using the Pin API.
+         - Read the encoder value using the timer.counter() method.
+         - Only works on CH1 and CH2 (and not on CH1N or CH2N)
+         - The channel number is ignored when setting the encoder mode.
+           
+       PWM Example::
+       
+           timer = pyb.Timer(2, freq=1000)
+           ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000)
+           ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000)
+
+.. only:: port_pyboard
+
+    .. method:: Timer.counter([value])
+
+       Get or set the timer counter.
+
+.. only:: port_pyboard
+
+    .. method:: Timer.freq([value])
+    
+       Get or set the frequency for the timer (changes prescaler and period if set).
+
+.. only:: port_pyboard
+
+    .. method:: Timer.period([value])
+    
+       Get or set the period of the timer.
+    
+    .. method:: Timer.prescaler([value])
+    
+       Get or set the prescaler for the timer.
+    
+    .. method:: Timer.source_freq()
+    
+       Get the frequency of the source of the timer.
+
+class TimerChannel --- setup a channel for a timer
+==================================================
+
+Timer channels are used to generate/capture a signal using a timer.
+
+TimerChannel objects are created using the Timer.channel() method.
+
+Methods
+-------
+
+.. only:: port_pyboard
+
+    .. method:: timerchannel.callback(fun)
+
+       Set the function to be called when the timer channel triggers.
+       ``fun`` is passed 1 argument, the timer object.
+       If ``fun`` is ``None`` then the callback will be disabled.
+
+.. only:: port_pyboard
+
+    .. method:: timerchannel.capture([value])
+    
+       Get or set the capture value associated with a channel.
+       capture, compare, and pulse_width are all aliases for the same function.
+       capture is the logical name to use when the channel is in input capture mode.
+    
+    .. method:: timerchannel.compare([value])
+    
+       Get or set the compare value associated with a channel.
+       capture, compare, and pulse_width are all aliases for the same function.
+       compare is the logical name to use when the channel is in output compare mode.
+    
+    .. method:: timerchannel.pulse_width([value])
+    
+       Get or set the pulse width value associated with a channel.
+       capture, compare, and pulse_width are all aliases for the same function.
+       pulse_width is the logical name to use when the channel is in PWM mode.
+       
+       In edge aligned mode, a pulse_width of ``period + 1`` corresponds to a duty cycle of 100%
+       In center aligned mode, a pulse width of ``period`` corresponds to a duty cycle of 100%
+    
+    .. method:: timerchannel.pulse_width_percent([value])
+    
+       Get or set the pulse width percentage associated with a channel.  The value
+       is a number between 0 and 100 and sets the percentage of the timer period
+       for which the pulse is active.  The value can be an integer or
+       floating-point number for more accuracy.  For example, a value of 25 gives
+       a duty cycle of 25%.

docs/library/pyb.UART.rst

@@ -0,0 +1,245 @@
+.. currentmodule:: pyb
+.. _pyb.UART:
+
+class UART -- duplex serial communication bus
+=============================================
+
+UART implements the standard UART/USART duplex serial communications protocol.  At
+the physical level it consists of 2 lines: RX and TX.  The unit of communication
+is a character (not to be confused with a string character) which can be 8 or 9
+bits wide.
+
+UART objects can be created and initialised using::
+
+    from pyb import UART
+
+    uart = UART(1, 9600)                         # init with given baudrate
+    uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters
+
+.. only:: port_pyboard
+
+    Bits can be 7, 8 or 9.  Parity can be None, 0 (even) or 1 (odd).  Stop can be 1 or 2.
+    
+    *Note:* with parity=None, only 8 and 9 bits are supported.  With parity enabled,
+    only 7 and 8 bits are supported.
+
+A UART object acts like a stream object and reading and writing is done
+using the standard stream methods::
+
+    uart.read(10)       # read 10 characters, returns a bytes object
+    uart.read()         # read all available characters
+    uart.readline()     # read a line
+    uart.readinto(buf)  # read and store into the given buffer
+    uart.write('abc')   # write the 3 characters
+
+.. only:: port_pyboard
+
+    Individual characters can be read/written using::
+
+        uart.readchar()     # read 1 character and returns it as an integer
+        uart.writechar(42)  # write 1 character
+
+    To check if there is anything to be read, use::
+
+        uart.any()          # returns the number of characters waiting
+
+
+    *Note:* The stream functions ``read``, ``write``, etc. are new in MicroPython v1.3.4.
+    Earlier versions use ``uart.send`` and ``uart.recv``.
+
+Constructors
+------------
+
+.. only:: port_pyboard
+
+    .. class:: pyb.UART(bus, ...)
+    
+       Construct a UART object on the given bus.  ``bus`` can be 1-6, or 'XA', 'XB', 'YA', or 'YB'.
+       With no additional parameters, the UART object is created but not
+       initialised (it has the settings from the last initialisation of
+       the bus, if any).  If extra arguments are given, the bus is initialised.
+       See ``init`` for parameters of initialisation.
+
+       The physical pins of the UART busses are:
+    
+         - ``UART(4)`` is on ``XA``: ``(TX, RX) = (X1, X2) = (PA0, PA1)``
+         - ``UART(1)`` is on ``XB``: ``(TX, RX) = (X9, X10) = (PB6, PB7)``
+         - ``UART(6)`` is on ``YA``: ``(TX, RX) = (Y1, Y2) = (PC6, PC7)``
+         - ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)``
+         - ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)``
+
+       The Pyboard Lite supports UART(1), UART(2) and UART(6) only. Pins are as above except:
+
+         - ``UART(2)`` is on: ``(TX, RX) = (X1, X2) = (PA2, PA3)``
+
+Methods
+-------
+
+.. only:: port_pyboard
+
+    .. method:: UART.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=0, timeout_char=0, read_buf_len=64)
+    
+       Initialise the UART bus with the given parameters:
+    
+         - ``baudrate`` is the clock rate.
+         - ``bits`` is the number of bits per character, 7, 8 or 9.
+         - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd).
+         - ``stop`` is the number of stop bits, 1 or 2.
+         - ``flow`` sets the flow control type. Can be 0, ``UART.RTS``, ``UART.CTS``
+           or ``UART.RTS | UART.CTS``.
+         - ``timeout`` is the timeout in milliseconds to wait for writing/reading the first character.
+         - ``timeout_char`` is the timeout in milliseconds to wait between characters while writing or reading.
+         - ``read_buf_len`` is the character length of the read buffer (0 to disable).
+    
+       This method will raise an exception if the baudrate could not be set within
+       5% of the desired value.  The minimum baudrate is dictated by the frequency
+       of the bus that the UART is on; UART(1) and UART(6) are APB2, the rest are on
+       APB1.  The default bus frequencies give a minimum baudrate of 1300 for
+       UART(1) and UART(6) and 650 for the others.  Use :func:`pyb.freq <pyb.freq>`
+       to reduce the bus frequencies to get lower baudrates.
+    
+       *Note:* with parity=None, only 8 and 9 bits are supported.  With parity enabled,
+       only 7 and 8 bits are supported.
+
+.. method:: UART.deinit()
+
+   Turn off the UART bus.
+
+.. only:: port_pyboard
+
+    .. method:: UART.any()
+
+       Returns the number of bytes waiting (may be 0).
+
+.. method:: UART.read([nbytes])
+
+   Read characters.  If ``nbytes`` is specified then read at most that many bytes.
+   If ``nbytes`` are available in the buffer, returns immediately, otherwise returns
+   when sufficient characters arrive or the timeout elapses.
+
+   If ``nbytes`` is not given then the method reads as much data as possible.  It
+   returns after the timeout has elapsed.
+
+   .. only:: port_pyboard
+
+      *Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must
+      be even, and the number of characters is ``nbytes/2``.
+
+      Return value: a bytes object containing the bytes read in.  Returns ``None``
+      on timeout.
+
+.. method:: UART.readchar()
+
+   Receive a single character on the bus.
+
+   Return value: The character read, as an integer.  Returns -1 on timeout.
+
+.. method:: UART.readinto(buf[, nbytes])
+
+   Read bytes into the ``buf``.  If ``nbytes`` is specified then read at most
+   that many bytes.  Otherwise, read at most ``len(buf)`` bytes.
+
+   Return value: number of bytes read and stored into ``buf`` or ``None`` on
+   timeout.
+
+.. method:: UART.readline()
+
+   Read a line, ending in a newline character. If such a line exists, return is
+   immediate. If the timeout elapses, all available data is returned regardless
+   of whether a newline exists.
+
+   Return value: the line read or ``None`` on timeout if no data is available.
+
+.. method:: UART.write(buf)
+
+   .. only:: port_pyboard
+
+      Write the buffer of bytes to the bus.  If characters are 7 or 8 bits wide
+      then each byte is one character.  If characters are 9 bits wide then two
+      bytes are used for each character (little endian), and ``buf`` must contain
+      an even number of bytes.
+
+      Return value: number of bytes written. If a timeout occurs and no bytes
+      were written returns ``None``.
+
+.. only:: port_pyboard
+
+    .. method:: UART.writechar(char)
+
+      Write a single character on the bus.  ``char`` is an integer to write.
+      Return value: ``None``. See note below if CTS flow control is used.
+
+.. method:: UART.sendbreak()
+
+   Send a break condition on the bus.  This drives the bus low for a duration
+   of 13 bits.
+   Return value: ``None``.
+
+Constants
+---------
+
+.. only:: port_pyboard
+
+    .. data:: UART.RTS
+    .. data:: UART.CTS
+
+       to select the flow control type.
+
+Flow Control
+------------
+
+.. only:: port_pyboard
+
+    On Pyboards V1 and V1.1 ``UART(2)`` and ``UART(3)`` support RTS/CTS hardware flow control
+    using the following pins:
+
+        - ``UART(2)`` is on: ``(TX, RX, nRTS, nCTS) = (X3, X4, X2, X1) = (PA2, PA3, PA1, PA0)``
+        - ``UART(3)`` is on :``(TX, RX, nRTS, nCTS) = (Y9, Y10, Y7, Y6) = (PB10, PB11, PB14, PB13)``
+
+    On the Pyboard Lite only ``UART(2)`` supports flow control on these pins:
+
+        ``(TX, RX, nRTS, nCTS) = (X1, X2, X4, X3) = (PA2, PA3, PA1, PA0)``
+
+    In the following paragraphs the term "target" refers to the device connected to
+    the UART.
+
+    When the UART's ``init()`` method is called with ``flow`` set to one or both of
+    ``UART.RTS`` and ``UART.CTS`` the relevant flow control pins are configured.
+    ``nRTS`` is an active low output, ``nCTS`` is an active low input with pullup
+    enabled. To achieve flow control the Pyboard's ``nCTS`` signal should be connected
+    to the target's ``nRTS`` and the Pyboard's ``nRTS`` to the target's ``nCTS``.
+
+    CTS: target controls Pyboard transmitter
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    If CTS flow control is enabled the write behaviour is as follows:
+
+    If the Pyboard's ``UART.write(buf)`` method is called, transmission will stall for
+    any periods when ``nCTS`` is ``False``. This will result in a timeout if the entire
+    buffer was not transmitted in the timeout period. The method returns the number of
+    bytes written, enabling the user to write the remainder of the data if required. In
+    the event of a timeout, a character will remain in the UART pending ``nCTS``. The
+    number of bytes composing this character will be included in the return value.
+    
+    If ``UART.writechar()`` is called when ``nCTS`` is ``False`` the method will time
+    out unless the target asserts ``nCTS`` in time. If it times out ``OSError 116``
+    will be raised. The character will be transmitted as soon as the target asserts ``nCTS``.
+
+    RTS: Pyboard controls target's transmitter
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    If RTS flow control is enabled, behaviour is as follows:
+    
+    If buffered input is used (``read_buf_len`` > 0), incoming characters are buffered.
+    If the buffer becomes full, the next character to arrive will cause ``nRTS`` to go
+    ``False``: the target should cease transmission. ``nRTS`` will go ``True`` when
+    characters are read from the buffer.
+    
+    Note that the ``any()`` method returns the number of bytes in the buffer. Assume a
+    buffer length of ``N`` bytes. If the buffer becomes full, and another character arrives,
+    ``nRTS`` will be set False, and ``any()`` will return the count ``N``. When
+    characters are read the additional character will be placed in the buffer and will
+    be included in the result of a subsequent ``any()`` call.
+    
+    If buffered input is not used (``read_buf_len`` == 0) the arrival of a character will
+    cause ``nRTS`` to go ``False`` until the character is read.

docs/library/pyb.USB_HID.rst

@@ -0,0 +1,40 @@
+.. currentmodule:: pyb
+.. _pyb.USB_HID:
+
+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.recv(data, \*, timeout=5000)
+
+   Receive data on the bus:
+   
+     - ``data`` can be an integer, which is the number of bytes to receive,
+       or a mutable buffer, which will be filled with received bytes.
+     - ``timeout`` is the timeout in milliseconds to wait for the receive.
+   
+   Return value: if ``data`` is an integer then a new buffer of the bytes received,
+   otherwise the number of bytes read into ``data`` is returned.
+
+.. 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).

docs/library/pyb.USB_VCP.rst

@@ -0,0 +1,103 @@
+.. currentmodule:: pyb
+.. _pyb.USB_VCP:
+
+class USB_VCP -- USB virtual comm port
+======================================
+
+The USB_VCP class allows creation of an object representing the USB
+virtual comm port.  It can be used to read and write data over USB to
+the connected host.
+
+
+Constructors
+------------
+
+.. class:: pyb.USB_VCP()
+
+   Create a new USB_VCP object.
+
+
+Methods
+-------
+
+.. method:: USB_VCP.setinterrupt(chr)
+
+   Set the character which interrupts running Python code.  This is set
+   to 3 (CTRL-C) by default, and when a CTRL-C character is received over
+   the USB VCP port, a KeyboardInterrupt exception is raised.
+
+   Set to -1 to disable this interrupt feature.  This is useful when you
+   want to send raw bytes over the USB VCP port.
+
+.. method:: USB_VCP.isconnected()
+
+   Return ``True`` if USB is connected as a serial device, else ``False``.
+
+.. method:: USB_VCP.any()
+
+   Return ``True`` if any characters waiting, else ``False``.
+
+.. method:: USB_VCP.close()
+
+   This method does nothing.  It exists so the USB_VCP object can act as
+   a file.
+
+.. method:: USB_VCP.read([nbytes])
+
+   Read at most ``nbytes`` from the serial device and return them as a
+   bytes object.  If ``nbytes`` is not specified then the method reads
+   all available bytes from the serial device.
+   USB_VCP stream implicitly works in non-blocking mode,
+   so if no pending data available, this method will return immediately
+   with ``None`` value.
+
+.. method:: USB_VCP.readinto(buf, [maxlen])
+
+   Read bytes from the serial device and store them into ``buf``, which
+   should be a buffer-like object.  At most ``len(buf)`` bytes are read.
+   If ``maxlen`` is given and then at most ``min(maxlen, len(buf))`` bytes
+   are read.
+
+   Returns the number of bytes read and stored into ``buf`` or ``None``
+   if no pending data available.
+
+.. method:: USB_VCP.readline()
+
+   Read a whole line from the serial device.
+
+   Returns a bytes object containing the data, including the trailing
+   newline character or ``None`` if no pending data available.
+
+.. method:: USB_VCP.readlines()
+
+   Read as much data as possible from the serial device, breaking it into
+   lines.
+
+   Returns a list of bytes objects, each object being one of the lines.
+   Each line will include the newline character.
+
+.. method:: USB_VCP.write(buf)
+
+   Write the bytes from ``buf`` to the serial device.
+
+   Returns the number of bytes written.
+
+.. method:: USB_VCP.recv(data, \*, timeout=5000)
+
+   Receive data on the bus:
+   
+     - ``data`` can be an integer, which is the number of bytes to receive,
+       or a mutable buffer, which will be filled with received bytes.
+     - ``timeout`` is the timeout in milliseconds to wait for the receive.
+   
+   Return value: if ``data`` is an integer then a new buffer of the bytes received,
+   otherwise the number of bytes read into ``data`` is returned.
+
+.. method:: USB_VCP.send(data, \*, timeout=5000)
+
+   Send data over the USB VCP:
+   
+     - ``data`` is the data to send (an integer to send, or a buffer object).
+     - ``timeout`` is the timeout in milliseconds to wait for the send.
+   
+   Return value: number of bytes sent.

docs/library/pyb.rst

@@ -0,0 +1,321 @@
+:mod:`pyb` --- functions related to the board
+=============================================
+
+.. module:: pyb
+   :synopsis: functions related to the board
+
+The ``pyb`` module contains specific functions related to the board.
+
+Time related functions
+----------------------
+
+.. function:: delay(ms)
+
+   Delay for the given number of milliseconds.
+
+.. function:: udelay(us)
+
+   Delay for the given number of microseconds.
+
+.. function:: millis()
+
+   Returns the number of milliseconds since the board was last reset.
+   
+   The result is always a MicroPython smallint (31-bit signed number), so
+   after 2^30 milliseconds (about 12.4 days) this will start to return
+   negative numbers.
+
+   Note that if :meth:`pyb.stop()` is issued the hardware counter supporting this
+   function will pause for the duration of the "sleeping" state. This
+   will affect the outcome of :meth:`pyb.elapsed_millis()`.
+
+.. function:: micros()
+
+   Returns the number of microseconds since the board was last reset.
+   
+   The result is always a MicroPython smallint (31-bit signed number), so
+   after 2^30 microseconds (about 17.8 minutes) this will start to return
+   negative numbers.
+
+   Note that if :meth:`pyb.stop()` is issued the hardware counter supporting this
+   function will pause for the duration of the "sleeping" state. This
+   will affect the outcome of :meth:`pyb.elapsed_micros()`.
+
+.. function:: elapsed_millis(start)
+
+   Returns the number of milliseconds which have elapsed since ``start``.
+   
+   This function takes care of counter wrap, and always returns a positive
+   number. This means it can be used to measure periods up to about 12.4 days.
+   
+   Example::
+
+       start = pyb.millis()
+       while pyb.elapsed_millis(start) < 1000:
+           # Perform some operation
+
+.. function:: elapsed_micros(start)
+
+   Returns the number of microseconds which have elapsed since ``start``.
+   
+   This function takes care of counter wrap, and always returns a positive
+   number. This means it can be used to measure periods up to about 17.8 minutes.
+   
+   Example::
+
+       start = pyb.micros()
+       while pyb.elapsed_micros(start) < 1000:
+           # Perform some operation
+           pass
+
+Reset related functions
+-----------------------
+
+.. function:: hard_reset()
+
+   Resets the pyboard in a manner similar to pushing the external RESET
+   button.
+
+.. function:: bootloader()
+
+   Activate the bootloader without BOOT\* pins.
+
+.. function:: fault_debug(value)
+
+   Enable or disable hard-fault debugging.  A hard-fault is when there is a fatal
+   error in the underlying system, like an invalid memory access.
+
+   If the *value* argument is ``False`` then the board will automatically reset if
+   there is a hard fault.
+
+   If *value* is ``True`` then, when the board has a hard fault, it will print the
+   registers and the stack trace, and then cycle the LEDs indefinitely.
+
+   The default value is disabled, i.e. to automatically reset.
+
+Interrupt related functions
+---------------------------
+
+.. function:: disable_irq()
+
+   Disable interrupt requests.
+   Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs
+   respectively.  This return value can be passed to enable_irq to restore
+   the IRQ to its original state.
+
+.. function:: enable_irq(state=True)
+
+   Enable interrupt requests.
+   If ``state`` is ``True`` (the default value) then IRQs are enabled.
+   If ``state`` is ``False`` then IRQs are disabled.  The most common use of
+   this function is to pass it the value returned by ``disable_irq`` to
+   exit a critical section.
+
+Power related functions
+-----------------------
+
+.. only:: port_pyboard
+
+    .. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]])
+    
+       If given no arguments, returns a tuple of clock frequencies:
+       (sysclk, hclk, pclk1, pclk2).
+       These correspond to:
+    
+        - sysclk: frequency of the CPU
+        - hclk: frequency of the AHB bus, core memory and DMA
+        - pclk1: frequency of the APB1 bus
+        - pclk2: frequency of the APB2 bus
+    
+       If given any arguments then the function sets the frequency of the CPU,
+       and the busses if additional arguments are given.  Frequencies are given in
+       Hz.  Eg freq(120000000) sets sysclk (the CPU frequency) to 120MHz.  Note that
+       not all values are supported and the largest supported frequency not greater
+       than the given value will be selected.
+    
+       Supported sysclk frequencies are (in MHz): 8, 16, 24, 30, 32, 36, 40, 42, 48,
+       54, 56, 60, 64, 72, 84, 96, 108, 120, 144, 168.
+    
+       The maximum frequency of hclk is 168MHz, of pclk1 is 42MHz, and of pclk2 is
+       84MHz.  Be sure not to set frequencies above these values.
+    
+       The hclk, pclk1 and pclk2 frequencies are derived from the sysclk frequency
+       using a prescaler (divider).  Supported prescalers for hclk are: 1, 2, 4, 8,
+       16, 64, 128, 256, 512.  Supported prescalers for pclk1 and pclk2 are: 1, 2,
+       4, 8.  A prescaler will be chosen to best match the requested frequency.
+    
+       A sysclk frequency of
+       8MHz uses the HSE (external crystal) directly and 16MHz uses the HSI
+       (internal oscillator) directly.  The higher frequencies use the HSE to
+       drive the PLL (phase locked loop), and then use the output of the PLL.
+    
+       Note that if you change the frequency while the USB is enabled then
+       the USB may become unreliable.  It is best to change the frequency
+       in boot.py, before the USB peripheral is started.  Also note that sysclk
+       frequencies below 36MHz do not allow the USB to function correctly.
+    
+    .. function:: wfi()
+    
+       Wait for an internal or external interrupt.
+    
+       This executes a ``wfi`` instruction which reduces power consumption
+       of the MCU until any interrupt occurs (be it internal or external),
+       at which point execution continues.  Note that the system-tick interrupt
+       occurs once every millisecond (1000Hz) so this function will block for
+       at most 1ms.
+    
+    .. function:: stop()
+    
+       Put the pyboard in a "sleeping" state.
+    
+       This reduces power consumption to less than 500 uA.  To wake from this
+       sleep state requires an external interrupt or a real-time-clock event.
+       Upon waking execution continues where it left off.
+    
+       See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
+    
+    .. function:: standby()
+    
+       Put the pyboard into a "deep sleep" state.
+    
+       This reduces power consumption to less than 50 uA.  To wake from this
+       sleep state requires a real-time-clock event, or an external interrupt
+       on X1 (PA0=WKUP) or X18 (PC13=TAMP1).
+       Upon waking the system undergoes a hard reset.
+    
+       See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
+
+Miscellaneous functions
+-----------------------
+
+.. only:: port_pyboard
+
+    .. function:: have_cdc()
+    
+       Return True if USB is connected as a serial device, False otherwise.
+    
+       .. note:: This function is deprecated.  Use pyb.USB_VCP().isconnected() instead.
+    
+    .. function:: hid((buttons, x, y, z))
+    
+       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 :meth:`pyb.USB_HID.send()` instead.
+    
+    .. function:: info([dump_alloc_table])
+    
+       Print out lots of information about the board.
+
+.. function:: main(filename)
+
+   Set the filename of the main script to run after boot.py is finished.  If
+   this function is not called then the default file main.py will be executed.
+
+   It only makes sense to call this function from within boot.py.
+
+.. only:: port_pyboard
+
+    .. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False)
+    
+       Mount a block device and make it available as part of the filesystem.
+       ``device`` must be an object that provides the block protocol:
+    
+        - ``readblocks(self, blocknum, buf)``
+        - ``writeblocks(self, blocknum, buf)`` (optional)
+        - ``count(self)``
+        - ``sync(self)`` (optional)
+    
+       ``readblocks`` and ``writeblocks`` should copy data between ``buf`` and
+       the block device, starting from block number ``blocknum`` on the device.
+       ``buf`` will be a bytearray with length a multiple of 512.  If
+       ``writeblocks`` is not defined then the device is mounted read-only.
+       The return value of these two functions is ignored.
+    
+       ``count`` should return the number of blocks available on the device.
+       ``sync``, if implemented, should sync the data on the device.
+    
+       The parameter ``mountpoint`` is the location in the root of the filesystem
+       to mount the device.  It must begin with a forward-slash.
+    
+       If ``readonly`` is ``True``, then the device is mounted read-only,
+       otherwise it is mounted read-write.
+    
+       If ``mkfs`` is ``True``, then a new filesystem is created if one does not
+       already exist.
+    
+       To unmount a device, pass ``None`` as the device and the mount location
+       as ``mountpoint``.
+
+.. function:: repl_uart(uart)
+
+   Get or set the UART object where the REPL is repeated on.
+
+.. only:: port_pyboard
+
+    .. function:: rng()
+    
+       Return a 30-bit hardware generated random number.
+
+.. function:: sync()
+
+   Sync all file systems.
+
+.. only:: port_pyboard
+
+    .. function:: unique_id()
+    
+       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
+-------
+
+.. only:: port_pyboard
+
+    .. toctree::
+       :maxdepth: 1
+    
+       pyb.Accel.rst
+       pyb.ADC.rst
+       pyb.CAN.rst
+       pyb.DAC.rst
+       pyb.ExtInt.rst
+       pyb.I2C.rst
+       pyb.LCD.rst
+       pyb.LED.rst
+       pyb.Pin.rst
+       pyb.RTC.rst
+       pyb.Servo.rst
+       pyb.SPI.rst
+       pyb.Switch.rst
+       pyb.Timer.rst
+       pyb.UART.rst
+       pyb.USB_HID.rst
+       pyb.USB_VCP.rst

docs/library/sys.rst

@@ -0,0 +1,123 @@
+:mod:`sys` -- system specific functions
+=======================================
+
+.. module:: sys
+   :synopsis: system specific functions
+
+|see_cpython_module| :mod:`python:sys`.
+
+Functions
+---------
+
+.. function:: exit(retval=0)
+
+   Terminate current program with a given exit code. Underlyingly, this
+   function raise as `SystemExit` exception. If an argument is given, its
+   value given as an argument to `SystemExit`.
+
+.. function:: print_exception(exc, file=sys.stdout)
+
+   Print exception with a traceback to a file-like object *file* (or
+   `sys.stdout` by default).
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      This is simplified version of a function which appears in the
+      ``traceback`` module in CPython. Unlike ``traceback.print_exception()``,
+      this function takes just exception value instead of exception type,
+      exception value, and traceback object; *file* argument should be
+      positional; further arguments are not supported. CPython-compatible
+      ``traceback`` module can be found in `micropython-lib`.
+
+Constants
+---------
+
+.. data:: argv
+
+   A mutable list of arguments the current program was started with.
+
+.. data:: byteorder
+
+   The byte order of the system (``"little"`` or ``"big"``).
+
+.. data:: implementation
+
+   Object with information about the current Python implementation. For
+   MicroPython, it has following attributes:
+
+   * *name* - string "micropython"
+   * *version* - tuple (major, minor, micro), e.g. (1, 7, 0)
+
+   This object is the recommended way to distinguish MicroPython from other
+   Python implementations (note that it still may not exist in the very
+   minimal ports).
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      CPython mandates more attributes for this object, but the actual useful
+      bare minimum is implemented in MicroPython.
+
+.. data:: maxsize
+
+   Maximum value which a native integer type can hold on the current platform,
+   or maximum value representable by MicroPython integer type, if it's smaller
+   than platform max value (that is the case for MicroPython ports without
+   long int support).
+
+   This attribute is useful for detecting "bitness" of a platform (32-bit vs
+   64-bit, etc.). It's recommended to not compare this attribute to some
+   value directly, but instead count number of bits in it::
+
+    bits = 0
+    v = sys.maxsize
+    while v:
+        bits += 1
+        v >>= 1
+    if bits > 32:
+        # 64-bit (or more) platform
+        ...
+    else:
+        # 32-bit (or less) platform
+        # Note that on 32-bit platform, value of bits may be less than 32
+        # (e.g. 31) due to peculiarities described above, so use "> 16",
+        # "> 32", "> 64" style of comparisons.
+
+.. data:: modules
+
+   Dictionary of loaded modules. On some ports, it may not include builtin
+   modules.
+
+.. data:: path
+
+   A mutable list of directories to search for imported modules.
+
+.. data:: platform
+
+   The platform that MicroPython is running on. For OS/RTOS ports, this is
+   usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it
+   is an identifier of a board, e.g. ``"pyboard"`` for the original MicroPython
+   reference board. It thus can be used to distinguish one board from another.
+   If you need to check whether your program runs on MicroPython (vs other
+   Python implementation), use `sys.implementation` instead.
+
+.. data:: stderr
+
+   Standard error stream.
+
+.. data:: stdin
+
+   Standard input stream.
+
+.. data:: stdout
+
+   Standard output stream.
+
+.. data:: version
+
+   Python language version that this implementation conforms to, as a string.
+
+.. data:: version_info
+
+   Python language version that this implementation conforms to, as a tuple of ints.

docs/library/ubinascii.rst

@@ -0,0 +1,40 @@
+:mod:`ubinascii` -- binary/ASCII conversions
+============================================
+
+.. module:: ubinascii
+   :synopsis: binary/ASCII conversions
+
+|see_cpython_module| :mod:`python:binascii`.
+
+This module implements conversions between binary data and various
+encodings of it in ASCII form (in both directions).
+
+Functions
+---------
+
+.. function:: hexlify(data, [sep])
+
+   Convert binary data to hexadecimal representation. Returns bytes string.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      If additional argument, *sep* is supplied, it is used as a separator
+      between hexadecimal values.
+
+.. function:: unhexlify(data)
+
+   Convert hexadecimal data to binary representation. Returns bytes string.
+   (i.e. inverse of hexlify)
+
+.. function:: a2b_base64(data)
+
+   Decode base64-encoded data, ignoring invalid characters in the input.
+   Conforms to `RFC 2045 s.6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_.
+   Returns a bytes object.
+
+.. function:: b2a_base64(data)
+
+   Encode binary data in base64 format, as in `RFC 3548
+   <https://tools.ietf.org/html/rfc3548.html>`_. Returns the encoded data
+   followed by a newline character, as a bytes object.

docs/library/ucollections.rst

@@ -0,0 +1,55 @@
+:mod:`ucollections` -- collection and container types
+=====================================================
+
+.. module:: ucollections
+   :synopsis: collection and container types
+
+|see_cpython_module| :mod:`python:collections`.
+
+This module implements advanced collection and container types to
+hold/accumulate various objects.
+
+Classes
+-------
+
+.. function:: namedtuple(name, fields)
+
+    This is factory function to create a new namedtuple type with a specific
+    name and set of fields. A namedtuple is a subclass of tuple which allows
+    to access its fields not just by numeric index, but also with an attribute
+    access syntax using symbolic field names. Fields is a sequence of strings
+    specifying field names. For compatibility with CPython it can also be a
+    a string with space-separated field named (but this is less efficient).
+    Example of use::
+
+        from ucollections import namedtuple
+
+        MyTuple = namedtuple("MyTuple", ("id", "name"))
+        t1 = MyTuple(1, "foo")
+        t2 = MyTuple(2, "bar")
+        print(t1.name)
+        assert t2.name == t2[1]
+
+.. function:: OrderedDict(...)
+
+    ``dict`` type subclass which remembers and preserves the order of keys
+    added. When ordered dict is iterated over, keys/items are returned in
+    the order they were added::
+
+        from ucollections import OrderedDict
+
+        # To make benefit of ordered keys, OrderedDict should be initialized
+        # from sequence of (key, value) pairs.
+        d = OrderedDict([("z", 1), ("a", 2)])
+        # More items can be added as usual
+        d["w"] = 5
+        d["b"] = 3
+        for k, v in d.items():
+            print(k, v)
+
+    Output::
+
+        z 1
+        a 2
+        w 5
+        b 3

docs/library/uctypes.rst

@@ -0,0 +1,209 @@
+:mod:`uctypes` -- access binary data in a structured way
+========================================================
+
+.. module:: uctypes
+   :synopsis: access binary data in a structured way
+
+This module implements "foreign data interface" for MicroPython. The idea
+behind it is similar to CPython's ``ctypes`` modules, but the actual API is
+different, streamlined and optimized for small size. The basic idea of the
+module is to define data structure layout with about the same power as the
+C language allows, and the access it using familiar dot-syntax to reference
+sub-fields.
+
+.. seealso::
+
+    Module :mod:`ustruct`
+        Standard Python way to access binary data structures (doesn't scale
+        well to large and complex structures).
+
+Defining structure layout
+-------------------------
+
+Structure layout is defined by a "descriptor" - a Python dictionary which
+encodes field names as keys and other properties required to access them as
+associated values. Currently, uctypes requires explicit specification of
+offsets for each field. Offset are given in bytes from a structure start.
+
+Following are encoding examples for various field types:
+
+* Scalar types::
+
+    "field_name": uctypes.UINT32 | 0
+
+  in other words, value is scalar type identifier ORed with field offset
+  (in bytes) from the start of the structure.
+
+* Recursive structures::
+
+    "sub": (2, {
+        "b0": uctypes.UINT8 | 0,
+        "b1": uctypes.UINT8 | 1,
+    })
+
+  i.e. value is a 2-tuple, first element of which is offset, and second is
+  a structure descriptor dictionary (note: offsets in recursive descriptors
+  are relative to a structure it defines).
+
+* Arrays of primitive types::
+
+      "arr": (uctypes.ARRAY | 0, uctypes.UINT8 | 2),
+
+  i.e. value is a 2-tuple, first element of which is ARRAY flag ORed
+  with offset, and second is scalar element type ORed number of elements
+  in array.
+
+* Arrays of aggregate types::
+
+    "arr2": (uctypes.ARRAY | 0, 2, {"b": uctypes.UINT8 | 0}),
+
+  i.e. value is a 3-tuple, first element of which is ARRAY flag ORed
+  with offset, second is a number of elements in array, and third is
+  descriptor of element type.
+
+* Pointer to a primitive type::
+
+    "ptr": (uctypes.PTR | 0, uctypes.UINT8),
+
+  i.e. value is a 2-tuple, first element of which is PTR flag ORed
+  with offset, and second is scalar element type.
+
+* Pointer to an aggregate type::
+
+    "ptr2": (uctypes.PTR | 0, {"b": uctypes.UINT8 | 0}),
+
+  i.e. value is a 2-tuple, first element of which is PTR flag ORed
+  with offset, second is descriptor of type pointed to.
+
+* Bitfields::
+
+    "bitf0": uctypes.BFUINT16 | 0 | 0 << uctypes.BF_POS | 8 << uctypes.BF_LEN,
+
+  i.e. value is type of scalar value containing given bitfield (typenames are
+  similar to scalar types, but prefixes with "BF"), ORed with offset for
+  scalar value containing the bitfield, and further ORed with values for
+  bit offset and bit length of the bitfield within scalar value, shifted by
+  BF_POS and BF_LEN positions, respectively. Bitfield position is counted
+  from the least significant bit, and is the number of right-most bit of a
+  field (in other words, it's a number of bits a scalar needs to be shifted
+  right to extra the bitfield).
+
+  In the example above, first UINT16 value will be extracted at offset 0
+  (this detail may be important when accessing hardware registers, where
+  particular access size and alignment are required), and then bitfield
+  whose rightmost bit is least-significant bit of this UINT16, and length
+  is 8 bits, will be extracted - effectively, this will access
+  least-significant byte of UINT16.
+
+  Note that bitfield operations are independent of target byte endianness,
+  in particular, example above will access least-significant byte of UINT16
+  in both little- and big-endian structures. But it depends on the least
+  significant bit being numbered 0. Some targets may use different
+  numbering in their native ABI, but ``uctypes`` always uses normalized
+  numbering described above.
+
+Module contents
+---------------
+
+.. class:: struct(addr, descriptor, layout_type=NATIVE)
+
+   Instantiate a "foreign data structure" object based on structure address in
+   memory, descriptor (encoded as a dictionary), and layout type (see below).
+
+.. data:: LITTLE_ENDIAN
+
+   Layout type for a little-endian packed structure. (Packed means that every
+   field occupies exactly as many bytes as defined in the descriptor, i.e.
+   the alignment is 1).
+
+.. data:: BIG_ENDIAN
+
+   Layout type for a big-endian packed structure.
+
+.. data:: NATIVE
+
+   Layout type for a native structure - with data endianness and alignment
+   conforming to the ABI of the system on which MicroPython runs.
+
+.. function:: sizeof(struct)
+
+   Return size of data structure in bytes. Argument can be either structure
+   class or specific instantiated structure object (or its aggregate field).
+
+.. function:: addressof(obj)
+
+   Return address of an object. Argument should be bytes, bytearray or
+   other object supporting buffer protocol (and address of this buffer
+   is what actually returned).
+
+.. function:: bytes_at(addr, size)
+
+   Capture memory at the given address and size as bytes object. As bytes
+   object is immutable, memory is actually duplicated and copied into
+   bytes object, so if memory contents change later, created object
+   retains original value.
+
+.. function:: bytearray_at(addr, size)
+
+   Capture memory at the given address and size as bytearray object.
+   Unlike bytes_at() function above, memory is captured by reference,
+   so it can be both written too, and you will access current value
+   at the given memory address.
+
+Structure descriptors and instantiating structure objects
+---------------------------------------------------------
+
+Given a structure descriptor dictionary and its layout type, you can
+instantiate a specific structure instance at a given memory address
+using :class:`uctypes.struct()` constructor. Memory address usually comes from
+following sources:
+
+* Predefined address, when accessing hardware registers on a baremetal
+  system. Lookup these addresses in datasheet for a particular MCU/SoC.
+* As a return value from a call to some FFI (Foreign Function Interface)
+  function.
+* From uctypes.addressof(), when you want to pass arguments to an FFI
+  function, or alternatively, to access some data for I/O (for example,
+  data read from a file or network socket).
+
+Structure objects
+-----------------
+
+Structure objects allow accessing individual fields using standard dot
+notation: ``my_struct.substruct1.field1``. If a field is of scalar type,
+getting it will produce a primitive value (Python integer or float)
+corresponding to the value contained in a field. A scalar field can also
+be assigned to.
+
+If a field is an array, its individual elements can be accessed with
+the standard subscript operator ``[]`` - both read and assigned to.
+
+If a field is a pointer, it can be dereferenced using ``[0]`` syntax
+(corresponding to C ``*`` operator, though ``[0]`` works in C too).
+Subscripting a pointer with other integer values but 0 are supported too,
+with the same semantics as in C.
+
+Summing up, accessing structure fields generally follows C syntax,
+except for pointer dereference, when you need to use ``[0]`` operator
+instead of ``*``.
+
+Limitations
+-----------
+
+Accessing non-scalar fields leads to allocation of intermediate objects
+to represent them. This means that special care should be taken to
+layout a structure which needs to be accessed when memory allocation
+is disabled (e.g. from an interrupt). The recommendations are:
+
+* Avoid nested structures. For example, instead of
+  ``mcu_registers.peripheral_a.register1``, define separate layout
+  descriptors for each peripheral, to be accessed as
+  ``peripheral_a.register1``.
+* Avoid other non-scalar data, like array. For example, instead of
+  ``peripheral_a.register[0]`` use ``peripheral_a.register0``.
+
+Note that these recommendations will lead to decreased readability
+and conciseness of layouts, so they should be used only if the need
+to access structure fields without allocation is anticipated (it's
+even possible to define 2 parallel layouts - one for normal usage,
+and a restricted one to use when memory allocation is prohibited).

docs/library/uerrno.rst

@@ -0,0 +1,34 @@
+:mod:`uerrno` -- system error codes
+===================================
+
+.. module:: uerrno
+   :synopsis: system error codes
+
+|see_cpython_module| :mod:`python:errno`.
+
+This module provides access to symbolic error codes for `OSError` exception.
+A particular inventory of codes depends on `MicroPython port`.
+
+Constants
+---------
+
+.. data:: EEXIST, EAGAIN, etc.
+
+    Error codes, based on ANSI C/POSIX standard. All error codes start with
+    "E". As mentioned above, inventory of the codes depends on
+    `MicroPython port`. Errors are usually accessible as ``exc.args[0]``
+    where `exc` is an instance of `OSError`. Usage example::
+
+        try:
+            uos.mkdir("my_dir")
+        except OSError as exc:
+            if exc.args[0] == uerrno.EEXIST:
+                print("Directory already exists")
+
+.. data:: errorcode
+
+    Dictionary mapping numeric error codes to strings with symbolic error
+    code (see above)::
+
+        >>> print(uerrno.errorcode[uerrno.EEXIST])
+        EEXIST

docs/library/uhashlib.rst

@@ -0,0 +1,57 @@
+:mod:`uhashlib` -- hashing algorithms
+=====================================
+
+.. module:: uhashlib
+   :synopsis: hashing algorithms
+
+|see_cpython_module| :mod:`python:hashlib`.
+
+This module implements binary data hashing algorithms. The exact inventory
+of available algorithms depends on a board. Among the algorithms which may
+be implemented:
+
+* SHA256 - The current generation, modern hashing algorithm (of SHA2 series).
+  It is suitable for cryptographically-secure purposes. Included in the
+  MicroPython core and any board is recommended to provide this, unless
+  it has particular code size constraints.
+
+* SHA1 - A previous generation algorithm. Not recommended for new usages,
+  but SHA1 is a part of number of Internet standards and existing
+  applications, so boards targeting network connectivity and
+  interoperatiability will try to provide this.
+
+* MD5 - A legacy algorithm, not considered cryptographically secure. Only
+  selected boards, targeting interoperatibility with legacy applications,
+  will offer this.
+
+Constructors
+------------
+
+.. class:: uhashlib.sha256([data])
+
+    Create an SHA256 hasher object and optionally feed ``data`` into it.
+
+.. class:: uhashlib.sha1([data])
+
+    Create an SHA1 hasher object and optionally feed ``data`` into it.
+
+.. class:: uhashlib.md5([data])
+
+    Create an MD5 hasher object and optionally feed ``data`` into it.
+
+Methods
+-------
+
+.. method:: hash.update(data)
+
+   Feed more binary data into hash.
+
+.. method:: hash.digest()
+
+   Return hash for all data passed through hash, as a bytes object. After this
+   method is called, more data cannot be fed into the hash any longer.
+
+.. method:: hash.hexdigest()
+
+   This method is NOT implemented. Use ``ubinascii.hexlify(hash.digest())``
+   to achieve a similar effect.

docs/library/uheapq.rst

@@ -0,0 +1,27 @@
+:mod:`uheapq` -- heap queue algorithm
+=====================================
+
+.. module:: uheapq
+   :synopsis: heap queue algorithm
+
+|see_cpython_module| :mod:`python:heapq`.
+
+This module implements the heap queue algorithm.
+
+A heap queue is simply a list that has its elements stored in a certain way.
+
+Functions
+---------
+
+.. function:: heappush(heap, item)
+
+   Push the ``item`` onto the ``heap``.
+
+.. function:: heappop(heap)
+
+   Pop the first item from the ``heap``, and return it.  Raises IndexError if
+   heap is empty.
+
+.. function:: heapify(x)
+
+   Convert the list ``x`` into a heap.  This is an in-place operation.

docs/library/uio.rst

@@ -0,0 +1,114 @@
+:mod:`uio` -- input/output streams
+==================================
+
+.. module:: uio
+   :synopsis: input/output streams
+
+|see_cpython_module| :mod:`python:io`.
+
+This module contains additional types of stream (file-like) objects
+and helper functions.
+
+Conceptual hierarchy
+--------------------
+
+.. admonition:: Difference to CPython
+   :class: attention
+
+   Conceptual hierarchy of stream base classes is simplified in MicroPython,
+   as described in this section.
+
+(Abstract) base stream classes, which serve as a foundation for behavior
+of all the concrete classes, adhere to few dichotomies (pair-wise
+classifications) in CPython. In MicroPython, they are somewhat simplified
+and made implicit to achieve higher efficiencies and save resources.
+
+An important dichotomy in CPython is unbuffered vs buffered streams. In
+MicroPython, all streams are currently unbuffered. This is because all
+modern OSes, and even many RTOSes and filesystem drivers already perform
+buffering on their side. Adding another layer of buffering is counter-
+productive (an issue known as "bufferbloat") and takes precious memory.
+Note that there still cases where buffering may be useful, so we may
+introduce optional buffering support at a later time.
+
+But in CPython, another important dichotomy is tied with "bufferedness" -
+it's whether a stream may incur short read/writes or not. A short read
+is when a user asks e.g. 10 bytes from a stream, but gets less, similarly
+for writes. In CPython, unbuffered streams are automatically short
+operation susceptible, while buffered are guarantee against them. The
+no short read/writes is an important trait, as it allows to develop
+more concise and efficient programs - something which is highly desirable
+for MicroPython. So, while MicroPython doesn't support buffered streams,
+it still provides for no-short-operations streams. Whether there will
+be short operations or not depends on each particular class' needs, but
+developers are strongly advised to favor no-short-operations behavior
+for the reasons stated above. For example, MicroPython sockets are
+guaranteed to avoid short read/writes. Actually, at this time, there is
+no example of a short-operations stream class in the core, and one would
+be a port-specific class, where such a need is governed by hardware
+peculiarities.
+
+The no-short-operations behavior gets tricky in case of non-blocking
+streams, blocking vs non-blocking behavior being another CPython dichotomy,
+fully supported by MicroPython. Non-blocking streams never wait for
+data either to arrive or be written - they read/write whatever possible,
+or signal lack of data (or ability to write data). Clearly, this conflicts
+with "no-short-operations" policy, and indeed, a case of non-blocking
+buffered (and this no-short-ops) streams is convoluted in CPython - in
+some places, such combination is prohibited, in some it's undefined or
+just not documented, in some cases it raises verbose exceptions. The
+matter is much simpler in MicroPython: non-blocking stream are important
+for efficient asynchronous operations, so this property prevails on
+the "no-short-ops" one. So, while blocking streams will avoid short
+reads/writes whenever possible (the only case to get a short read is
+if end of file is reached, or in case of error (but errors don't
+return short data, but raise exceptions)), non-blocking streams may
+produce short data to avoid blocking the operation.
+
+The final dichotomy is binary vs text streams. MicroPython of course
+supports these, but while in CPython text streams are inherently
+buffered, they aren't in MicroPython. (Indeed, that's one of the cases
+for which we may introduce buffering support.)
+
+Note that for efficiency, MicroPython doesn't provide abstract base
+classes corresponding to the hierarchy above, and it's not possible
+to implement, or subclass, a stream class in pure Python.
+
+Functions
+---------
+
+.. function:: open(name, mode='r', **kwargs)
+
+    Open a file. Builtin ``open()`` function is aliased to this function.
+    All ports (which provide access to file system) are required to support
+    `mode` parameter, but support for other arguments vary by port.
+
+Classes
+-------
+
+.. class:: FileIO(...)
+
+    This is type of a file open in binary mode, e.g. using ``open(name, "rb")``.
+    You should not instantiate this class directly.
+
+.. class:: TextIOWrapper(...)
+
+    This is type of a file open in text mode, e.g. using ``open(name, "rt")``.
+    You should not instantiate this class directly.
+
+.. class:: StringIO([string])
+.. class:: BytesIO([string])
+
+    In-memory file-like objects for input/output. `StringIO` is used for
+    text-mode I/O (similar to a normal file opened with "t" modifier).
+    `BytesIO` is used for binary-mode I/O (similar to a normal file
+    opened with "b" modifier). Initial contents of file-like objects
+    can be specified with `string` parameter (should be normal string
+    for `StringIO` or bytes object for `BytesIO`). All the usual file
+    methods like ``read()``, ``write()``, ``seek()``, ``flush()``,
+    ``close()`` are available on these objects, and additionally, a
+    following method:
+
+    .. method:: getvalue()
+
+        Get the current contents of the underlying buffer which holds data.

docs/library/ujson.rst

@@ -0,0 +1,22 @@
+:mod:`ujson` -- JSON encoding and decoding
+==========================================
+
+.. module:: ujson
+   :synopsis: JSON encoding and decoding
+
+|see_cpython_module| :mod:`python:json`.
+
+This modules allows to convert between Python objects and the JSON
+data format.
+
+Functions
+---------
+
+.. function:: dumps(obj)
+
+   Return ``obj`` represented as a JSON string.
+
+.. function:: loads(str)
+
+   Parse the JSON ``str`` and return an object.  Raises ValueError if the
+   string is not correctly formed.

docs/library/uos.rst

@@ -0,0 +1,110 @@
+:mod:`uos` -- basic "operating system" services
+===============================================
+
+.. module:: uos
+   :synopsis: basic "operating system" services
+
+|see_cpython_module| :mod:`python:os`.
+
+The ``uos`` module contains functions for filesystem access and ``urandom``
+function.
+
+Functions
+---------
+
+.. function:: chdir(path)
+
+   Change current directory.
+
+.. function:: getcwd()
+
+   Get the current directory.
+
+.. function:: ilistdir([dir])
+
+   This function returns an iterator which then yields 3-tuples corresponding to
+   the entries in the directory that it is listing.  With no argument it lists the
+   current directory, otherwise it lists the directory given by *dir*.
+
+   The 3-tuples have the form *(name, type, inode)*:
+
+    - *name* is a string (or bytes if *dir* is a bytes object) and is the name of
+      the entry;
+    - *type* is an integer that specifies the type of the entry, with 0x4000 for
+      directories and 0x8000 for regular files;
+    - *inode* is an integer corresponding to the inode of the file, and may be 0
+      for filesystems that don't have such a notion.
+
+.. function:: listdir([dir])
+
+   With no argument, list the current directory.  Otherwise list the given directory.
+
+.. function:: mkdir(path)
+
+   Create a new directory.
+
+.. function:: remove(path)
+
+   Remove a file.
+
+.. function:: rmdir(path)
+
+   Remove a directory.
+
+.. function:: rename(old_path, new_path)
+
+   Rename a file.
+
+.. function:: stat(path)
+
+   Get the status of a file or directory.
+
+.. function:: statvfs(path)
+
+   Get the status of a fileystem.
+
+   Returns a tuple with the filesystem information in the following order:
+
+        * ``f_bsize`` -- file system block size
+        * ``f_frsize`` -- fragment size
+        * ``f_blocks`` -- size of fs in f_frsize units
+        * ``f_bfree`` -- number of free blocks
+        * ``f_bavail`` -- number of free blocks for unpriviliged users
+        * ``f_files`` -- number of inodes
+        * ``f_ffree`` -- number of free inodes
+        * ``f_favail`` -- number of free inodes for unpriviliged users
+        * ``f_flag`` -- mount flags
+        * ``f_namemax`` -- maximum filename length
+
+   Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail``
+   and the ``f_flags`` parameter may return ``0`` as they can be unavailable
+   in a port-specific implementation.
+
+.. function:: sync()
+
+   Sync all filesystems.
+
+.. function:: urandom(n)
+
+   Return a bytes object with n random bytes. Whenever possible, it is
+   generated by the hardware random number generator.
+
+.. function:: dupterm(stream_object, index=0)
+
+   Duplicate or switch the MicroPython terminal (the REPL) on the given stream-like
+   object. The *stream_object* argument must implement the ``readinto()`` and
+   ``write()`` methods.  The stream should be in non-blocking mode and
+   ``readinto()`` should return ``None`` if there is no data available for reading.
+
+   After calling this function all terminal output is repeated on this stream,
+   and any input that is available on the stream is passed on to the terminal input.
+
+   The *index* parameter should be a non-negative integer and specifies which
+   duplication slot is set.  A given port may implement more than one slot (slot 0
+   will always be available) and in that case terminal input and output is
+   duplicated on all the slots that are set.
+
+   If ``None`` is passed as the *stream_object* then duplication is cancelled on
+   the slot given by *index*.
+
+   The function returns the previous stream-like object in the given slot.

docs/library/ure.rst

@@ -0,0 +1,99 @@
+:mod:`ure` -- simple regular expressions
+========================================
+
+.. module:: ure
+   :synopsis: regular expressions
+
+|see_cpython_module| :mod:`python:re`.
+
+This module implements regular expression operations. Regular expression
+syntax supported is a subset of CPython ``re`` module (and actually is
+a subset of POSIX extended regular expressions).
+
+Supported operators are:
+
+``'.'``
+   Match any character.
+
+``'[]'``
+   Match set of characters. Individual characters and ranges are supported.
+
+``'^'``
+
+``'$'``
+
+``'?'``
+
+``'*'``
+
+``'+'``
+
+``'??'``
+
+``'*?'``
+
+``'+?'``
+
+``'|'``
+
+``'()'``
+   Grouping. Each group is capturing (a substring it captures can be accessed
+   with `match.group()` method).
+
+Counted repetitions (``{m,n}``), more advanced assertions, named groups,
+etc. are not supported.
+
+
+Functions
+---------
+
+.. function:: compile(regex_str)
+
+   Compile regular expression, return `regex <regex>` object.
+
+.. function:: match(regex_str, string)
+
+   Compile *regex_str* and match against *string*. Match always happens
+   from starting position in a string.
+
+.. function:: search(regex_str, string)
+
+   Compile *regex_str* and search it in a *string*. Unlike `match`, this will search
+   string for first position which matches regex (which still may be
+   0 if regex is anchored).
+
+.. data:: DEBUG
+
+   Flag value, display debug information about compiled expression.
+
+
+.. _regex:
+
+Regex objects
+-------------
+
+Compiled regular expression. Instances of this class are created using
+`ure.compile()`.
+
+.. method:: regex.match(string)
+            regex.search(string)
+
+   Similar to the module-level functions :meth:`match` and :meth:`search`.
+   Using methods is (much) more efficient if the same regex is applied to
+   multiple strings.
+
+.. method:: regex.split(string, max_split=-1)
+
+   Split a *string* using regex. If *max_split* is given, it specifies
+   maximum number of splits to perform. Returns list of strings (there
+   may be up to *max_split+1* elements if it's specified).
+
+Match objects
+-------------
+
+Match objects as returned by `match()` and `search()` methods.
+
+.. method:: match.group([index])
+
+   Return matching (sub)string. *index* is 0 for entire match,
+   1 and above for each capturing group. Only numeric groups are supported.

docs/library/uselect.rst

@@ -0,0 +1,84 @@
+:mod:`uselect` -- wait for events on a set of streams
+========================================================================
+
+.. module:: uselect
+   :synopsis: wait for events on a set of streams
+
+|see_cpython_module| :mod:`python:select`.
+
+This module provides functions to efficiently wait for events on multiple
+streams (select streams which are ready for operations).
+
+Functions
+---------
+
+.. function:: poll()
+
+   Create an instance of the Poll class.
+
+.. function:: select(rlist, wlist, xlist[, timeout])
+
+   Wait for activity on a set of objects.
+
+   This function is provided by some MicroPython ports for compatibility
+   and is not efficient. Usage of :class:`Poll` is recommended instead.
+
+.. _class: Poll
+
+class ``Poll``
+--------------
+
+Methods
+~~~~~~~
+
+.. method:: poll.register(obj[, eventmask])
+
+   Register *obj* for polling. *eventmask* is logical OR of:
+
+   * ``select.POLLIN``  - data available for reading
+   * ``select.POLLOUT`` - more data can be written
+   * ``select.POLLERR`` - error occurred
+   * ``select.POLLHUP`` - end of stream/connection termination detected
+
+   *eventmask* defaults to ``select.POLLIN | select.POLLOUT``.
+
+.. method:: poll.unregister(obj)
+
+   Unregister *obj* from polling.
+
+.. method:: poll.modify(obj, eventmask)
+
+   Modify the *eventmask* for *obj*.
+
+.. method:: poll.poll([timeout])
+
+   Wait for at least one of the registered objects to become ready. Returns
+   list of (``obj``, ``event``, ...) tuples, ``event`` element specifies
+   which events happened with a stream and is a combination of ``select.POLL*``
+   constants described above. There may be other elements in tuple, depending
+   on a platform and version, so don't assume that its size is 2. In case of
+   timeout, an empty list is returned.
+
+   Timeout is in milliseconds.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      Tuples returned may contain more than 2 elements as described above.
+
+.. method:: poll.ipoll(timeout=-1, flags=0)
+
+   Like :meth:`poll.poll`, but instead returns an iterator which yields
+   `callee-owned tuples`. This function provides efficient, allocation-free
+   way to poll on streams.
+
+   If *flags* is 1, one-shot behavior for events is employed: streams for
+   which events happened, event mask will be automatically reset (equivalent
+   to ``poll.modify(obj, 0)``), so new events for such a stream won't be
+   processed until new mask is set with `poll.modify()`. This behavior is
+   useful for asynchronous I/O schedulers.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      This function is a MicroPython extension.

docs/library/usocket.rst

@@ -0,0 +1,339 @@
+*******************************
+:mod:`usocket` -- socket module
+*******************************
+
+.. module:: usocket
+   :synopsis: socket module
+
+|see_cpython_module| :mod:`python:socket`.
+
+This module provides access to the BSD socket interface.
+
+.. admonition:: Difference to CPython
+   :class: attention
+
+   For efficiency and consistency, socket objects in MicroPython implement a stream
+   (file-like) interface directly. In CPython, you need to convert a socket to
+   a file-like object using `makefile()` method. This method is still supported
+   by MicroPython (but is a no-op), so where compatibility with CPython matters,
+   be sure to use it.
+
+Socket address format(s)
+------------------------
+
+The native socket address format of the ``usocket`` module is an opaque data type
+returned by `getaddrinfo` function, which must be used to resolve textual address
+(including numeric addresses)::
+
+    sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1]
+    # You must use getaddrinfo() even for numeric addresses
+    sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1]
+    # Now you can use that address
+    sock.connect(addr)
+
+Using `getaddrinfo` is the most efficient (both in terms of memory and processing
+power) and portable way to work with addresses.
+
+However, ``socket`` module (note the difference with native MicroPython
+``usocket`` module described here) provides CPython-compatible way to specify
+addresses using tuples, as described below. Note that depending on a
+`MicroPython port`, ``socket`` module can be builtin or need to be
+installed from `micropython-lib` (as in the case of `MicroPython Unix port`),
+and some ports still accept only numeric addresses in the tuple format,
+and require to use `getaddrinfo` function to resolve domain names.
+
+Summing up:
+
+* Always use `getaddrinfo` when writing portable applications.
+* Tuple addresses described below can be used as a shortcut for
+  quick hacks and interactive use, if your port supports them.
+
+Tuple address format for ``socket`` module:
+
+* IPv4: *(ipv4_address, port)*, where *ipv4_address* is a string with
+  dot-notation numeric IPv4 address, e.g. ``"8.8.8.8"``, and *port* is and
+  integer port number in the range 1-65535. Note the domain names are not
+  accepted as *ipv4_address*, they should be resolved first using
+  `usocket.getaddrinfo()`.
+* IPv6: *(ipv6_address, port, flowinfo, scopeid)*, where *ipv6_address*
+  is a string with colon-notation numeric IPv6 address, e.g. ``"2001:db8::1"``,
+  and *port* is an integer port number in the range 1-65535. *flowinfo*
+  must be 0. *scopeid* is the interface scope identifier for link-local
+  addresses. Note the domain names are not accepted as *ipv6_address*,
+  they should be resolved first using `usocket.getaddrinfo()`. Availability
+  of IPv6 support depends on a `MicroPython port`.
+
+Functions
+---------
+
+.. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP)
+
+   Create a new socket using the given address family, socket type and
+   protocol number. Note that specifying *proto* in most cases is not
+   required (and not recommended, as some MicroPython ports may omit
+   ``IPPROTO_*`` constants). Instead, *type* argument will select needed
+   protocol automatically::
+
+        # Create STREAM TCP socket
+        socket(AF_INET, SOCK_STREAM)
+        # Create DGRAM UDP socket
+        socket(AF_INET, SOCK_DGRAM)
+
+.. function:: getaddrinfo(host, port)
+
+   Translate the host/port argument into a sequence of 5-tuples that contain all the 
+   necessary arguments for creating a socket connected to that service. The list of 
+   5-tuples has following structure::
+
+      (family, type, proto, canonname, sockaddr)
+
+   The following example shows how to connect to a given url::
+
+      s = usocket.socket()
+      s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1])
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      CPython raises a ``socket.gaierror`` exception (`OSError` subclass) in case
+      of error in this function. MicroPython doesn't have ``socket.gaierror``
+      and raises OSError directly. Note that error numbers of `getaddrinfo()`
+      form a separate namespace and may not match error numbers from
+      `uerrno` module. To distinguish `getaddrinfo()` errors, they are
+      represented by negative numbers, whereas standard system errors are
+      positive numbers (error numbers are accessible using ``e.args[0]`` property
+      from an exception object). The use of negative values is a provisional
+      detail which may change in the future.
+
+.. function:: inet_ntop(af, bin_addr)
+
+   Convert a binary network address *bin_addr* of the given address family *af*
+   to a textual representation::
+
+        >>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1")
+        '127.0.0.1'
+
+.. function:: inet_pton(af, txt_addr)
+
+   Convert a textual network address *txt_addr* of the given address family *af*
+   to a binary representation::
+
+        >>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4")
+        b'\x01\x02\x03\x04'
+
+Constants
+---------
+
+.. data:: AF_INET
+          AF_INET6
+
+   Address family types. Availability depends on a particular `MicroPython port`.
+
+.. data:: SOCK_STREAM
+          SOCK_DGRAM
+
+   Socket types.
+
+.. data:: IPPROTO_UDP
+          IPPROTO_TCP
+
+   IP protocol numbers. Availability depends on a particular `MicroPython port`.
+   Note that you don't need to specify these in a call to `usocket.socket()`,
+   because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and
+   `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants
+   is as an argument to `setsockopt()`.
+
+.. data:: usocket.SOL_*
+
+   Socket option levels (an argument to `setsockopt()`). The exact
+   inventory depends on a `MicroPython port`.
+
+.. data:: usocket.SO_*
+
+   Socket options (an argument to `setsockopt()`). The exact
+   inventory depends on a `MicroPython port`.
+
+Constants specific to WiPy:
+
+.. data:: IPPROTO_SEC
+
+    Special protocol value to create SSL-compatible socket.
+
+class socket
+============
+
+Methods
+-------
+
+.. method:: socket.close()
+
+   Mark the socket closed and release all resources. Once that happens, all future operations
+   on the socket object will fail. The remote end will receive EOF indication if
+   supported by protocol.
+
+   Sockets are automatically closed when they are garbage-collected, but it is recommended 
+   to `close()` them explicitly as soon you finished working with them.
+
+.. method:: socket.bind(address)
+
+   Bind the socket to *address*. The socket must not already be bound.
+
+.. method:: socket.listen([backlog])
+
+   Enable a server to accept connections. If *backlog* is specified, it must be at least 0
+   (if it's lower, it will be set to 0); and specifies the number of unaccepted connections
+   that the system will allow before refusing new connections. If not specified, a default
+   reasonable value is chosen.
+
+.. method:: socket.accept()
+
+   Accept a connection. The socket must be bound to an address and listening for connections.
+   The return value is a pair (conn, address) where conn is a new socket object usable to send
+   and receive data on the connection, and address is the address bound to the socket on the
+   other end of the connection.
+
+.. method:: socket.connect(address)
+
+   Connect to a remote socket at *address*.
+
+.. method:: socket.send(bytes)
+
+   Send data to the socket. The socket must be connected to a remote socket.
+   Returns number of bytes sent, which may be smaller than the length of data
+   ("short write").
+
+.. method:: socket.sendall(bytes)
+
+   Send all data to the socket. The socket must be connected to a remote socket.
+   Unlike `send()`, this method will try to send all of data, by sending data
+   chunk by chunk consecutively.
+
+   The behavior of this method on non-blocking sockets is undefined. Due to this,
+   on MicroPython, it's recommended to use `write()` method instead, which
+   has the same "no short writes" policy for blocking sockets, and will return
+   number of bytes sent on non-blocking sockets.
+
+.. method:: socket.recv(bufsize)
+
+   Receive data from the socket. The return value is a bytes object representing the data
+   received. The maximum amount of data to be received at once is specified by bufsize.
+
+.. method:: socket.sendto(bytes, address)
+
+   Send data to the socket. The socket should not be connected to a remote socket, since the
+   destination socket is specified by *address*.
+
+.. method:: socket.recvfrom(bufsize)
+
+  Receive data from the socket. The return value is a pair *(bytes, address)* where *bytes* is a
+  bytes object representing the data received and *address* is the address of the socket sending
+  the data.
+
+.. method:: socket.setsockopt(level, optname, value)
+
+   Set the value of the given socket option. The needed symbolic constants are defined in the
+   socket module (SO_* etc.). The *value* can be an integer or a bytes-like object representing
+   a buffer.
+
+.. method:: socket.settimeout(value)
+
+   **Note**: Not every port supports this method, see below.
+
+   Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
+   point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
+   will raise an `OSError` exception if the timeout period value has elapsed before the operation has
+   completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
+   is put in blocking mode.
+
+   Not every `MicroPython port` supports this method. A more portable and
+   generic solution is to use `uselect.poll` object. This allows to wait on
+   multiple objects at the same time (and not just on sockets, but on generic
+   stream objects which support polling). Example::
+
+        # Instead of:
+        s.settimeout(1.0)  # time in seconds
+        s.read(10)  # may timeout
+
+        # Use:
+        poller = uselect.poll()
+        poller.register(s, uselect.POLLIN)
+        res = poller.poll(1000)  # time in milliseconds
+        if not res:
+            # s is still not ready for input, i.e. operation timed out
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      CPython raises a ``socket.timeout`` exception in case of timeout,
+      which is an `OSError` subclass. MicroPython raises an OSError directly
+      instead. If you use ``except OSError:`` to catch the exception,
+      your code will work both in MicroPython and CPython.
+
+.. method:: socket.setblocking(flag)
+
+   Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
+   else to blocking mode.
+
+   This method is a shorthand for certain `settimeout()` calls:
+
+   * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
+   * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)``
+
+.. method:: socket.makefile(mode='rb', buffering=0)
+
+   Return a file object associated with the socket. The exact returned type depends on the arguments
+   given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb').
+   CPython's arguments: *encoding*, *errors* and *newline* are not supported.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      As MicroPython doesn't support buffered streams, values of *buffering*
+      parameter is ignored and treated as if it was 0 (unbuffered).
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      Closing the file object returned by makefile() WILL close the
+      original socket as well.
+
+.. method:: socket.read([size])
+
+   Read up to size bytes from the socket. Return a bytes object. If *size* is not given, it
+   reads all data available from the socket until EOF; as such the method will not return until
+   the socket is closed. This function tries to read as much data as
+   requested (no "short reads"). This may be not possible with
+   non-blocking socket though, and then less data will be returned.
+
+.. method:: socket.readinto(buf[, nbytes])
+
+   Read bytes into the *buf*.  If *nbytes* is specified then read at most
+   that many bytes.  Otherwise, read at most *len(buf)* bytes. Just as
+   `read()`, this method follows "no short reads" policy.
+
+   Return value: number of bytes read and stored into *buf*.
+
+.. method:: socket.readline()
+
+   Read a line, ending in a newline character.
+
+   Return value: the line read.
+
+.. method:: socket.write(buf)
+
+   Write the buffer of bytes to the socket. This function will try to
+   write all data to a socket (no "short writes"). This may be not possible
+   with a non-blocking socket though, and returned value will be less than
+   the length of *buf*.
+
+   Return value: number of bytes written.
+
+.. exception:: usocket.error
+
+   MicroPython does NOT have this exception.
+
+   .. admonition:: Difference to CPython
+        :class: attention
+
+        CPython used to have a ``socket.error`` exception which is now deprecated,
+        and is an alias of `OSError`. In MicroPython, use `OSError` directly.

docs/library/ussl.rst

@@ -0,0 +1,48 @@
+:mod:`ussl` -- SSL/TLS module
+=============================
+
+.. module:: ussl
+   :synopsis: TLS/SSL wrapper for socket objects
+
+|see_cpython_module| :mod:`python:ssl`.
+
+This module provides access to Transport Layer Security (previously and
+widely known as “Secure Sockets Layer”) encryption and peer authentication
+facilities for network sockets, both client-side and server-side.
+
+Functions
+---------
+
+.. function:: ussl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None)
+
+   Takes a stream *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type),
+   and returns an instance of ssl.SSLSocket, which wraps the underlying stream in
+   an SSL context. Returned object has the usual stream interface methods like
+   `read()`, `write()`, etc. In MicroPython, the returned object does not expose
+   socket interface and methods like `recv()`, `send()`. In particular, a
+   server-side SSL socket should be created from a normal socket returned from
+   `accept()` on a non-SSL listening server socket.
+
+   Depending on the underlying module implementation in a particular
+   `MicroPython port`, some or all keyword arguments above may be not supported.
+
+.. warning::
+
+   Some implementations of ``ussl`` module do NOT validate server certificates,
+   which makes an SSL connection established prone to man-in-the-middle attacks.
+
+Exceptions
+----------
+
+.. data:: ssl.SSLError
+
+   This exception does NOT exist. Instead its base class, OSError, is used.
+
+Constants
+---------
+
+.. data:: ussl.CERT_NONE
+          ussl.CERT_OPTIONAL
+          ussl.CERT_REQUIRED
+
+    Supported values for *cert_reqs* parameter.

docs/library/ustruct.rst

@@ -0,0 +1,42 @@
+:mod:`ustruct` -- pack and unpack primitive data types
+======================================================
+
+.. module:: ustruct
+   :synopsis: pack and unpack primitive data types
+
+|see_cpython_module| :mod:`python:struct`.
+
+Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``.
+
+Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
+``L``, ``q``, ``Q``, ``s``, ``P``, ``f``, ``d`` (the latter 2 depending
+on the floating-point support).
+
+Functions
+---------
+
+.. function:: calcsize(fmt)
+
+   Return the number of bytes needed to store the given *fmt*.
+
+.. function:: pack(fmt, v1, v2, ...)
+
+   Pack the values *v1*, *v2*, ... according to the format string *fmt*.
+   The return value is a bytes object encoding the values.
+
+.. function:: pack_into(fmt, buffer, offset, v1, v2, ...)
+
+   Pack the values *v1*, *v2*, ... according to the format string *fmt*
+   into a *buffer* starting at *offset*. *offset* may be negative to count
+   from the end of *buffer*.
+
+.. function:: unpack(fmt, data)
+
+   Unpack from the *data* according to the format string *fmt*.
+   The return value is a tuple of the unpacked values.
+
+.. function:: unpack_from(fmt, data, offset=0)
+
+   Unpack from the *data* starting at *offset* according to the format string
+   *fmt*. *offset* may be negative to count from the end of *buffer*. The return
+   value is a tuple of the unpacked values.

docs/library/utime.rst

@@ -0,0 +1,229 @@
+:mod:`utime` -- time related functions
+======================================
+
+.. module:: utime
+   :synopsis: time related functions
+
+|see_cpython_module| :mod:`python:time`.
+
+The ``utime`` module provides functions for getting the current time and date,
+measuring time intervals, and for delays.
+
+**Time Epoch**: Unix port uses standard for POSIX systems epoch of
+1970-01-01 00:00:00 UTC. However, embedded ports use epoch of
+2000-01-01 00:00:00 UTC.
+
+**Maintaining actual calendar date/time**: This requires a
+Real Time Clock (RTC). On systems with underlying OS (including some
+RTOS), an RTC may be implicit. Setting and maintaining actual calendar
+time is responsibility of OS/RTOS and is done outside of MicroPython,
+it just uses OS API to query date/time. On baremetal ports however
+system time depends on ``machine.RTC()`` object. The current calendar time
+may be set using ``machine.RTC().datetime(tuple)`` function, and maintained
+by following means:
+
+* By a backup battery (which may be an additional, optional component for
+  a particular board).
+* Using networked time protocol (requires setup by a port/user).
+* Set manually by a user on each power-up (many boards then maintain
+  RTC time across hard resets, though some may require setting it again
+  in such case).
+
+If actual calendar time is not maintained with a system/MicroPython RTC,
+functions below which require reference to current absolute time may
+behave not as expected.
+
+Functions
+---------
+
+.. function:: localtime([secs])
+
+   Convert a time expressed in seconds since the Epoch (see above) into an 8-tuple which
+   contains: (year, month, mday, hour, minute, second, weekday, yearday)
+   If secs is not provided or None, then the current time from the RTC is used.
+
+   * year includes the century (for example 2014).
+   * month   is 1-12
+   * mday    is 1-31
+   * hour    is 0-23
+   * minute  is 0-59
+   * second  is 0-59
+   * weekday is 0-6 for Mon-Sun
+   * yearday is 1-366
+
+.. function:: mktime()
+
+   This is inverse function of localtime. It's argument is a full 8-tuple
+   which expresses a time as per localtime. It returns an integer which is
+   the number of seconds since Jan 1, 2000.
+
+.. function:: sleep(seconds)
+
+   Sleep for the given number of seconds. Some boards may accept *seconds* as a
+   floating-point number to sleep for a fractional number of seconds. Note that
+   other boards may not accept a floating-point argument, for compatibility with
+   them use `sleep_ms()` and `sleep_us()` functions.
+
+.. function:: sleep_ms(ms)
+
+   Delay for given number of milliseconds, should be positive or 0.
+
+.. function:: sleep_us(us)
+
+   Delay for given number of microseconds, should be positive or 0.
+
+.. function:: ticks_ms()
+
+    Returns an increasing millisecond counter with an arbitrary reference point, that
+    wraps around after some value.
+
+    The wrap-around value is not explicitly exposed, but we will
+    refer to it as *TICKS_MAX* to simplify discussion. Period of the values is
+    *TICKS_PERIOD = TICKS_MAX + 1*. *TICKS_PERIOD* is guaranteed to be a power of
+    two, but otherwise may differ from port to port. The same period value is used
+    for all of `ticks_ms()`, `ticks_us()`, `ticks_cpu()` functions (for
+    simplicity). Thus, these functions will return a value in range [*0* ..
+    *TICKS_MAX*], inclusive, total *TICKS_PERIOD* values. Note that only
+    non-negative values are used. For the most part, you should treat values returned
+    by these functions as opaque. The only operations available for them are
+    `ticks_diff()` and `ticks_add()` functions described below.
+
+    Note: Performing standard mathematical operations (+, -) or relational
+    operators (<, <=, >, >=) directly on these value will lead to invalid
+    result. Performing mathematical operations and then passing their results
+    as arguments to `ticks_diff()` or `ticks_add()` will also lead to
+    invalid results from the latter functions.
+
+.. function:: ticks_us()
+
+   Just like `ticks_ms()` above, but in microseconds.
+
+.. function:: ticks_cpu()
+
+   Similar to `ticks_ms()` and `ticks_us()`, but with the highest possible resolution
+   in the system. This is usually CPU clocks, and that's why the function is named that
+   way. But it doesn't have to be a CPU clock, some other timing source available in a
+   system (e.g. high-resolution timer) can be used instead. The exact timing unit
+   (resolution) of this function is not specified on ``utime`` module level, but
+   documentation for a specific port may provide more specific information. This
+   function is intended for very fine benchmarking or very tight real-time loops.
+   Avoid using it in portable code.
+
+   Availability: Not every port implements this function.
+
+
+.. function:: ticks_add(ticks, delta)
+
+   Offset ticks value by a given number, which can be either positive or negative.
+   Given a *ticks* value, this function allows to calculate ticks value *delta*
+   ticks before or after it, following modular-arithmetic definition of tick values
+   (see `ticks_ms()` above). *ticks* parameter must be a direct result of call
+   to `ticks_ms()`, `ticks_us()`, or `ticks_cpu()` functions (or from previous
+   call to `ticks_add()`). However, *delta* can be an arbitrary integer number
+   or numeric expression. `ticks_add()` is useful for calculating deadlines for
+   events/tasks. (Note: you must use `ticks_diff()` function to work with
+   deadlines.)
+
+   Examples::
+
+        # Find out what ticks value there was 100ms ago
+        print(ticks_add(time.ticks_ms(), -100))
+
+        # Calculate deadline for operation and test for it
+        deadline = ticks_add(time.ticks_ms(), 200)
+        while ticks_diff(deadline, time.ticks_ms()) > 0:
+            do_a_little_of_something()
+
+        # Find out TICKS_MAX used by this port
+        print(ticks_add(0, -1))
+
+
+.. function:: ticks_diff(ticks1, ticks2)
+
+   Measure ticks difference between values returned from `ticks_ms()`, `ticks_us()`,
+   or `ticks_cpu()` functions, as a signed value which may wrap around.
+
+   The argument order is the same as for subtraction
+   operator, ``ticks_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``.
+   However, values returned by `ticks_ms()`, etc. functions may wrap around, so
+   directly using subtraction on them will produce incorrect result. That is why
+   `ticks_diff()` is needed, it implements modular (or more specifically, ring)
+   arithmetics to produce correct result even for wrap-around values (as long as they not
+   too distant inbetween, see below). The function returns **signed** value in the range
+   [*-TICKS_PERIOD/2* .. *TICKS_PERIOD/2-1*] (that's a typical range definition for
+   two's-complement signed binary integers). If the result is negative, it means that
+   *ticks1* occurred earlier in time than *ticks2*. Otherwise, it means that
+   *ticks1* occurred after *ticks2*. This holds **only** if *ticks1* and *ticks2*
+   are apart from each other for no more than *TICKS_PERIOD/2-1* ticks. If that does
+   not hold, incorrect result will be returned. Specifically, if two tick values are
+   apart for *TICKS_PERIOD/2-1* ticks, that value will be returned by the function.
+   However, if *TICKS_PERIOD/2* of real-time ticks has passed between them, the
+   function will return *-TICKS_PERIOD/2* instead, i.e. result value will wrap around
+   to the negative range of possible values.
+
+   Informal rationale of the constraints above: Suppose you are locked in a room with no
+   means to monitor passing of time except a standard 12-notch clock. Then if you look at
+   dial-plate now, and don't look again for another 13 hours (e.g., if you fall for a
+   long sleep), then once you finally look again, it may seem to you that only 1 hour
+   has passed. To avoid this mistake, just look at the clock regularly. Your application
+   should do the same. "Too long sleep" metaphor also maps directly to application
+   behavior: don't let your application run any single task for too long. Run tasks
+   in steps, and do time-keeping inbetween.
+
+   `ticks_diff()` is designed to accommodate various usage patterns, among them:
+
+   * Polling with timeout. In this case, the order of events is known, and you will deal
+     only with positive results of `ticks_diff()`::
+
+        # Wait for GPIO pin to be asserted, but at most 500us
+        start = time.ticks_us()
+        while pin.value() == 0:
+            if time.ticks_diff(time.ticks_us(), start) > 500:
+                raise TimeoutError
+
+   * Scheduling events. In this case, `ticks_diff()` result may be negative
+     if an event is overdue::
+
+        # This code snippet is not optimized
+        now = time.ticks_ms()
+        scheduled_time = task.scheduled_time()
+        if ticks_diff(now, scheduled_time) > 0:
+            print("Too early, let's nap")
+            sleep_ms(ticks_diff(now, scheduled_time))
+            task.run()
+        elif ticks_diff(now, scheduled_time) == 0:
+            print("Right at time!")
+            task.run()
+        elif ticks_diff(now, scheduled_time) < 0:
+            print("Oops, running late, tell task to run faster!")
+            task.run(run_faster=true)
+
+   Note: Do not pass `time()` values to `ticks_diff()`, you should use
+   normal mathematical operations on them. But note that `time()` may (and will)
+   also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem .
+
+
+.. function:: time()
+
+   Returns the number of seconds, as an integer, since the Epoch, assuming that
+   underlying RTC is set and maintained as described above. If an RTC is not set, this
+   function returns number of seconds since a port-specific reference point in time (for
+   embedded boards without a battery-backed RTC, usually since power up or reset). If you
+   want to develop portable MicroPython application, you should not rely on this function
+   to provide higher than second precision. If you need higher precision, use
+   `ticks_ms()` and `ticks_us()` functions, if you need calendar time,
+   `localtime()` without an argument is a better choice.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      In CPython, this function returns number of
+      seconds since Unix epoch, 1970-01-01 00:00 UTC, as a floating-point,
+      usually having microsecond precision. With MicroPython, only Unix port
+      uses the same Epoch, and if floating-point precision allows,
+      returns sub-second precision. Embedded hardware usually doesn't have
+      floating-point precision to represent both long time ranges and subsecond
+      precision, so they use integer value with second precision. Some embedded
+      hardware also lacks battery-powered RTC, so returns number of seconds
+      since last power-up or from other relative, hardware-specific point
+      (e.g. reset).

docs/library/uzlib.rst

@@ -0,0 +1,38 @@
+:mod:`uzlib` -- zlib decompression
+==================================
+
+.. module:: uzlib
+   :synopsis: zlib decompression
+
+|see_cpython_module| :mod:`python:zlib`.
+
+This module allows to decompress binary data compressed with
+`DEFLATE algorithm <https://en.wikipedia.org/wiki/DEFLATE>`_
+(commonly used in zlib library and gzip archiver). Compression
+is not yet implemented.
+
+Functions
+---------
+
+.. function:: decompress(data, wbits=0, bufsize=0)
+
+   Return decompressed *data* as bytes. *wbits* is DEFLATE dictionary window
+   size used during compression (8-15, the dictionary size is power of 2 of
+   that value). Additionally, if value is positive, *data* is assumed to be
+   zlib stream (with zlib header). Otherwise, if it's negative, it's assumed
+   to be raw DEFLATE stream. *bufsize* parameter is for compatibility with
+   CPython and is ignored.
+
+.. class:: DecompIO(stream, wbits=0)
+
+   Create a stream wrapper which allows transparent decompression of
+   compressed data in another *stream*. This allows to process compressed
+   streams with data larger than available heap size. In addition to
+   values described in :func:`decompress`, *wbits* may take values
+   24..31 (16 + 8..15), meaning that input stream has gzip header.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      This class is MicroPython extension. It's included on provisional
+      basis and may be changed considerably or removed in later versions.

docs/library/wipy.rst

@@ -0,0 +1,17 @@
+*************************************
+:mod:`wipy` -- WiPy specific features
+*************************************
+
+.. module:: wipy
+   :synopsis: WiPy specific features
+
+The ``wipy`` module contains functions to control specific features of the
+WiPy, such as the heartbeat LED.
+
+Functions
+---------
+
+.. function:: heartbeat([enable])
+
+   Get or set the state (enabled or disabled) of the heartbeat LED. Accepts and
+   returns boolean values (``True`` or ``False``).

docs/license.rst

@@ -0,0 +1,24 @@
+MicroPython license information
+===============================
+
+The MIT License (MIT)
+
+Copyright (c) 2013-2017 Damien P. George, and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

docs/make.bat

@@ -0,0 +1,242 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\MicroPython.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\MicroPython.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

docs/pyboard/general.rst

@@ -0,0 +1,80 @@
+General information about the pyboard
+=====================================
+
+.. contents::
+
+Local filesystem and SD card
+----------------------------
+
+There is a small internal filesystem (a drive) on the pyboard, called ``/flash``,
+which is stored within the microcontroller's flash memory.  If a micro SD card
+is inserted into the slot, it is available as ``/sd``.
+
+When the pyboard boots up, it needs to choose a filesystem to boot from.  If
+there is no SD card, then it uses the internal filesystem ``/flash`` as the boot
+filesystem, otherwise, it uses the SD card ``/sd``. After the boot, the current
+directory is set to one of the directories above.
+
+If needed, you can prevent the use of the SD card by creating an empty file
+called ``/flash/SKIPSD``.  If this file exists when the pyboard boots
+up then the SD card will be skipped and the pyboard will always boot from the
+internal filesystem (in this case the SD card won't be mounted but you can still
+mount and use it later in your program using ``os.mount``).
+
+(Note that on older versions of the board, ``/flash`` is called ``0:/`` and ``/sd``
+is called ``1:/``).
+
+The boot filesystem is used for 2 things: it is the filesystem from which
+the ``boot.py`` and ``main.py`` files are searched for, and it is the filesystem
+which is made available on your PC over the USB cable.
+
+The filesystem will be available as a USB flash drive on your PC.  You can
+save files to the drive, and edit ``boot.py`` and ``main.py``.
+
+*Remember to eject (on Linux, unmount) the USB drive before you reset your
+pyboard.*
+
+Boot modes
+----------
+
+If you power up normally, or press the reset button, the pyboard will boot
+into standard mode: the ``boot.py`` file will be executed first, then the
+USB will be configured, then ``main.py`` will run.
+
+You can override this boot sequence by holding down the user switch as
+the board is booting up.  Hold down user switch and press reset, and then
+as you continue to hold the user switch, the LEDs will count in binary.
+When the LEDs have reached the mode you want, let go of the user switch,
+the LEDs for the selected mode will flash quickly, and the board will boot.
+
+The modes are:
+
+1. Green LED only, *standard boot*: run ``boot.py`` then ``main.py``.
+2. Orange LED only, *safe boot*: don't run any scripts on boot-up.
+3. Green and orange LED together, *filesystem reset*: resets the flash
+   filesystem to its factory state, then boots in safe mode.
+
+If your filesystem becomes corrupt, boot into mode 3 to fix it.
+If resetting the filesystem while plugged into your compute doesn't work,
+you can try doing the same procedure while the board is plugged into a USB
+charger, or other USB power supply without data connection.
+
+Errors: flashing LEDs
+---------------------
+
+There are currently 2 kinds of errors that you might see:
+
+1. If the red and green LEDs flash alternatively, then a Python script
+    (eg ``main.py``) has an error.  Use the REPL to debug it.
+2. If all 4 LEDs cycle on and off slowly, then there was a hard fault.
+   This cannot be recovered from and you need to do a hard reset.
+
+Guide for using the pyboard with Windows
+----------------------------------------
+
+The following PDF guide gives information about using the pyboard with Windows,
+including setting up the serial prompt and downloading new firmware using
+DFU programming:
+`PDF guide <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`__.
+
+.. include:: hardware/index.rst

docs/pyboard/hardware/index.rst

@@ -0,0 +1,30 @@
+.. _hardware_index:
+
+The pyboard hardware
+--------------------
+
+For the pyboard:
+
+* `PYBv1.0 schematics and layout <http://micropython.org/resources/PYBv10b.pdf>`_ (2.4MiB PDF)
+* `PYBv1.0 metric dimensions <http://micropython.org/resources/PYBv10b-metric-dimensions.pdf>`_ (360KiB PDF)
+* `PYBv1.0 imperial dimensions <http://micropython.org/resources/PYBv10b-imperial-dimensions.pdf>`_ (360KiB PDF)
+
+For the official skin modules:
+
+* `LCD32MKv1.0 schematics <http://micropython.org/resources/LCD32MKv10-schematics.pdf>`_ (194KiB PDF)
+* `AMPv1.0 schematics <http://micropython.org/resources/AMPv10-schematics.pdf>`_ (209KiB PDF)
+* LCD160CRv1.0: see :mod:`lcd160cr`
+
+Datasheets for the components on the pyboard
+--------------------------------------------
+
+* The microcontroller: `STM32F405RGT6 <http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144>`_ (link to manufacturer's site)
+* The accelerometer: `Freescale MMA7660 <http://micropython.org/resources/datasheets/MMA7660FC.pdf>`_ (800kiB PDF)
+* The LDO voltage regulator: `Microchip MCP1802 <http://micropython.org/resources/datasheets/MCP1802-22053C.pdf>`_ (400kiB PDF)
+
+Datasheets for other components
+-------------------------------
+
+* The LCD display on the LCD touch-sensor skin: `Newhaven Display NHD-C12832A1Z-FSW-FBW-3V3 <http://micropython.org/resources/datasheets/NHD-C12832A1Z-FSW-FBW-3V3.pdf>`_ (460KiB PDF)
+* The touch sensor chip on the LCD touch-sensor skin: `Freescale MPR121 <http://micropython.org/resources/datasheets/MPR121.pdf>`_ (280KiB PDF)
+* The digital potentiometer on the audio skin: `Microchip MCP4541 <http://micropython.org/resources/datasheets/MCP4541-22107B.pdf>`_ (2.7MiB PDF)

docs/pyboard/quickref.rst

@@ -0,0 +1,217 @@
+.. _quickref:
+
+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
+
+General board control
+---------------------
+
+See :mod:`pyb`. ::
+
+    import pyb
+
+    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(time.ticks_ms(), start) # compute time difference
+
+Internal LEDs
+-------------
+
+See :ref:`pyb.LED <pyb.LED>`. ::
+
+    from pyb import LED
+
+    led = LED(1) # 1=red, 2=green, 3=yellow, 4=blue
+    led.toggle()
+    led.on()
+    led.off()
+    
+    # LEDs 3 and 4 support PWM intensity (0-255)
+    LED(4).intensity()    # get intensity
+    LED(4).intensity(128) # set intensity to half
+
+Internal switch
+---------------
+
+See :ref:`pyb.Switch <pyb.Switch>`. ::
+
+    from pyb import Switch
+
+    sw = Switch()
+    sw.value() # returns True or False
+    sw.callback(lambda: pyb.LED(1).toggle())
+
+Pins and GPIO
+-------------
+
+See :ref:`pyb.Pin <pyb.Pin>`. ::
+
+    from pyb import Pin
+
+    p_out = Pin('X1', Pin.OUT_PP)
+    p_out.high()
+    p_out.low()
+
+    p_in = Pin('X2', Pin.IN, Pin.PULL_UP)
+    p_in.value() # get value, 0 or 1
+
+Servo control
+-------------
+
+See :ref:`pyb.Servo <pyb.Servo>`. ::
+
+    from pyb import Servo
+
+    s1 = Servo(1) # servo on position 1 (X1, VIN, GND)
+    s1.angle(45) # move to 45 degrees
+    s1.angle(-60, 1500) # move to -60 degrees in 1500ms
+    s1.speed(50) # for continuous rotation servos
+
+External interrupts
+-------------------
+
+See :ref:`pyb.ExtInt <pyb.ExtInt>`. ::
+
+    from pyb import Pin, ExtInt
+
+    callback = lambda e: print("intr")
+    ext = ExtInt(Pin('Y1'), ExtInt.IRQ_RISING, Pin.PULL_NONE, callback)
+
+Timers
+------
+
+See :ref:`pyb.Timer <pyb.Timer>`. ::
+
+    from pyb import Timer
+
+    tim = Timer(1, freq=1000)
+    tim.counter() # get counter value
+    tim.freq(0.5) # 0.5 Hz
+    tim.callback(lambda t: pyb.LED(1).toggle())
+
+RTC (real time clock)
+---------------------
+
+See :ref:`pyb.RTC <pyb.RTC>` ::
+
+    from pyb import RTC
+
+    rtc = RTC()
+    rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time
+    rtc.datetime() # get date and time
+
+PWM (pulse width modulation)
+----------------------------
+
+See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.Timer <pyb.Timer>`. ::
+
+    from pyb import Pin, Timer
+
+    p = Pin('X1') # X1 has TIM2, CH1
+    tim = Timer(2, freq=1000)
+    ch = tim.channel(1, Timer.PWM, pin=p)
+    ch.pulse_width_percent(50)
+
+ADC (analog to digital conversion)
+----------------------------------
+
+See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.ADC <pyb.ADC>`. ::
+
+    from pyb import Pin, ADC
+
+    adc = ADC(Pin('X19'))
+    adc.read() # read value, 0-4095
+
+DAC (digital to analog conversion)
+----------------------------------
+
+See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.DAC <pyb.DAC>`. ::
+
+    from pyb import Pin, DAC
+
+    dac = DAC(Pin('X5'))
+    dac.write(120) # output between 0 and 255
+
+UART (serial bus)
+-----------------
+
+See :ref:`pyb.UART <pyb.UART>`. ::
+
+    from pyb import UART
+
+    uart = UART(1, 9600)
+    uart.write('hello')
+    uart.read(5) # read up to 5 bytes
+
+SPI bus
+-------
+
+See :ref:`pyb.SPI <pyb.SPI>`. ::
+
+    from pyb import SPI
+
+    spi = SPI(1, SPI.MASTER, baudrate=200000, polarity=1, phase=0)
+    spi.send('hello')
+    spi.recv(5) # receive 5 bytes on the bus
+    spi.send_recv('hello') # send and receive 5 bytes
+
+I2C bus
+-------
+
+See :ref:`pyb.I2C <pyb.I2C>`. ::
+
+    from pyb import I2C
+
+    i2c = I2C(1, I2C.MASTER, baudrate=100000)
+    i2c.scan() # returns list of slave addresses
+    i2c.send('hello', 0x42) # send 5 bytes to slave with address 0x42
+    i2c.recv(5, 0x42) # receive 5 bytes from slave
+    i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10
+    i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10
+
+CAN bus (controller area network)
+---------------------------------
+
+See :ref:`pyb.CAN <pyb.CAN>`. ::
+
+    from pyb import CAN
+
+    can = CAN(1, CAN.LOOPBACK)
+    can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126))
+    can.send('message!', 123)   # send a message with id 123
+    can.recv(0)                 # receive message on FIFO 0
+
+Internal accelerometer
+----------------------
+
+See :ref:`pyb.Accel <pyb.Accel>`. ::
+
+    from pyb import Accel
+
+    accel = Accel()
+    print(accel.x(), accel.y(), accel.z(), accel.tilt())

docs/pyboard/tutorial/accel.rst

@@ -0,0 +1,92 @@
+The accelerometer
+=================
+
+Here you will learn how to read the accelerometer and signal using LEDs states like tilt left and tilt right.
+
+Using the accelerometer
+-----------------------
+
+The pyboard has an accelerometer (a tiny mass on a tiny spring) that can be used
+to detect the angle of the board and motion. There is a different sensor for
+each of the x, y, z directions. To get the value of the accelerometer, create a
+pyb.Accel() object and then call the x() method. ::
+
+    >>> accel = pyb.Accel()
+    >>> accel.x()
+    7
+
+This returns a signed integer with a value between around -30 and 30. Note that
+the measurement is very noisy, this means that even if you keep the board
+perfectly still there will be some variation in the number that you measure.
+Because of this, you shouldn't use the exact value of the x() method but see if
+it is in a certain range.
+
+We will start by using the accelerometer to turn on a light if it is not flat. ::
+
+    accel = pyb.Accel()
+    light = pyb.LED(3)
+    SENSITIVITY = 3
+
+    while True:
+        x = accel.x()
+        if abs(x) > SENSITIVITY: 
+            light.on()
+        else:
+            light.off()
+
+        pyb.delay(100)
+
+We create Accel and LED objects, then get the value of the x direction of the
+accelerometer. If the magnitude of x is bigger than a certain value ``SENSITIVITY``,
+then the LED turns on, otherwise it turns off. The loop has a small ``pyb.delay()``
+otherwise the LED flashes annoyingly when the value of x is close to
+``SENSITIVITY``. Try running this on the pyboard and tilt the board left and right
+to make the LED turn on and off.
+
+**Exercise: Change the above script so that the blue LED gets brighter the more
+you tilt the pyboard.  HINT: You will need to rescale the values, intensity goes
+from 0-255.**
+
+Making a spirit level
+---------------------
+
+The example above is only sensitive to the angle in the x direction but if we
+use the ``y()`` value and more LEDs we can turn the pyboard into a spirit level. ::
+
+    xlights = (pyb.LED(2), pyb.LED(3))
+    ylights = (pyb.LED(1), pyb.LED(4))
+
+    accel = pyb.Accel()
+    SENSITIVITY = 3
+
+    while True:
+        x = accel.x()
+        if x > SENSITIVITY: 
+            xlights[0].on()
+            xlights[1].off()
+        elif x < -SENSITIVITY:
+            xlights[1].on()
+            xlights[0].off()
+        else:
+            xlights[0].off()
+            xlights[1].off()
+
+        y = accel.y()
+        if y > SENSITIVITY: 
+            ylights[0].on()
+            ylights[1].off()
+        elif y < -SENSITIVITY:
+            ylights[1].on()
+            ylights[0].off()
+        else:
+            ylights[0].off()
+            ylights[1].off()
+
+        pyb.delay(100)
+
+We start by creating a tuple of LED objects for the x and y directions. Tuples
+are immutable objects in python which means they can't be modified once they are
+created. We then proceed as before but turn on a different LED for positive and
+negative x values. We then do the same for the y direction. This isn't
+particularly sophisticated but it does the job. Run this on your pyboard and you
+should see different LEDs turning on depending on how you tilt the board.