djsundog
/
circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'adafruit/2.x' into merge_2x

This commit is contained in:
Scott Shawcroft 2018-02-27 15:24:16 -08:00
parent 5eb3b208e8 892d5cda63
commit bf05183158
319 changed files with 751 additions and 52089 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
CODECONVENTIONS.md
View File

@ -1,210 +0,0 @@
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
=======================
Python code follows [PEP 8](http://legacy.python.org/dev/peps/pep-0008/).
Naming conventions:
- Module names are short and all lowercase; eg pyb, stm.
- Class names are CamelCase, with abbreviations all uppercase; eg I2C, not
I2c.
- Function and method names are all lowercase with words separated by
a single underscore as necessary to improve readability; eg mem_read.
- Constants are all uppercase with words separated by a single underscore;
eg GPIO_IDR.
C code conventions
==================
When writing new C code, please adhere to the following conventions.
White space:
- Expand tabs to 4 spaces.
- Don't leave trailing whitespace at the end of a line.
- For control blocks (if, for, while), put 1 space between the
keyword and the opening parenthesis.
- Put 1 space after a comma, and 1 space around operators.
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
a new line.
- For else-statements, put the else on the same line as the previous
closing brace.
Header files:
- Header files should be protected from multiple inclusion with #if
directives. See an existing header for naming convention.
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, spaces, names and comments:
#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 + TO_ADD, some_value - 1);
}
for (int my_counter = 0; my_counter < x; my_counter++) {
}
}
Type declarations:
typedef struct _my_struct_t {
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

217
README.md
View File

@ -1,217 +0,0 @@
# Adafruit CircuitPython
[![Build Status](https://travis-ci.org/adafruit/circuitpython.svg?branch=master)](https://travis-ci.org/adafruit/circuitpython)
[![Doc Status](https://readthedocs.org/projects/circuitpython/badge/?version=latest)](http://circuitpython.readthedocs.io/)
[![Gitter](https://badges.gitter.im/adafruit/circuitpython.svg)](https://gitter.im/adafruit/circuitpython?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[![Discord](https://img.shields.io/discord/327254708534116352.svg)](https://discord.gg/nBQh6qu)
**[Status](#status)** |
**[Supported Boards](#supported-boards)** |
**[Download](#download)** |
**[Documentation](#documentation)** |
**[Contributing](#contributing)** |
**[Differences from Micropython](#differences-from-micropython)** |
**[Project Structure](#project-structure)**
**Adafruit CircuitPython** is an open source derivative of
[MicroPython](http://www.micropython.org) for use on educational
development boards designed and sold by [Adafruit](https://www.adafruit.com).
**CircuitPython**, a MicroPython derivative, implements Python 3.x on
microcontrollers such as the SAMD21 and ESP8266.
## Status
This project is in beta. Most APIs should be stable going forward.
## Supported Boards
### Designed for CircuitPython
* [Adafruit CircuitPlayground Express][]
* [Adafruit Feather M0 Express][]
* [Adafruit Metro M0 Express][]
* [Adafruit Gemma M0][]
* [Adafruit Trinket M0][]
### Other
* [Adafruit Feather HUZZAH][]
* [Adafruit Feather M0 Basic][]
* [Adafruit Feather M0 Bluefruit LE][] (uses M0 Basic binaries)
* [Adafruit Feather M0 Adalogger][] (MicroSD card supported using the [Adafruit CircuitPython SD library](https://github.com/adafruit/Adafruit_CircuitPython_SD))
* [Arduino Zero][]
## Download
Official binaries are available through the
[latest GitHub releases](https://github.com/adafruit/circuitpython/releases).
Continuous (one per commit) builds are available
[here](https://adafruit-circuit-python.s3.amazonaws.com/index.html?prefix=bin)
and includes experimental hardware support.
## Documentation
Guides and videos are available through the [Adafruit Learning System](https://learn.adafruit.com/)
under the [CircuitPython category](https://learn.adafruit.com/category/circuitpython)
and [MicroPython category](https://learn.adafruit.com/category/micropython).
An API reference is also available on [Read the Docs](http://circuitpython.readthedocs.io/en/latest/?).
## Contributing
See [CONTRIBUTING.md](https://github.com/adafruit/circuitpython/blob/master/CONTRIBUTING.md)
for full guidelines but please be aware that by contributing to this
project you are agreeing to the [Code of Conduct][]. Contributors who
follow the [Code of Conduct][] are welcome to submit pull requests and
they will be promptly reviewed by project admins. Please join the
[Gitter chat](https://gitter.im/adafruit/circuitpython) or
[Discord](https://discord.gg/nBQh6qu) too.
---
## Differences from [MicroPython][]
CircuitPython:
* includes a port for Atmel SAMD21 (Commonly known as M0
in Adafruit product names.)
* supports only Atmel SAMD21 and ESP8266 ports.
* tracks MicroPython's releases (not master).
### Behavior
* The order that files are run and the state that is shared between them.
CircuitPython's goal is to clarify the role of each file and make each
file independent from each other.
* `boot.py` (or `settings.py`) runs only once on start up before
USB is initialized. This lays the ground work for configuring USB
at startup rather than it being fixed. Since serial is not
available, output is written to `boot_out.txt`.
* `code.py` (or `main.py`) is run after every reload until it
finishes or is interrupted. After it is done running, the vm and hardware is
reinitialized. **This means you cannot read state from `code.py`
in the REPL anymore.** CircuitPython's goal for this change includes
reduce confusion about pins and memory being used.
* After `code.py` the REPL can be entered by pressing any key. It no
longer shares state with `code.py` so it is a fresh vm.
* Autoreload state will be maintained across reload.
* Adds a safe mode that does not run user code after a hard crash or
brown out. The hope is that this will make it easier to fix code that
causes nasty crashes by making it available through mass storage after
the crash. A reset (the button) is needed after its fixed to get back
into normal mode.
### API
* Unified hardware APIs:
[`audioio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/audioio/__init__.html),
[`analogio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/analogio/__init__.html),
[`busio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/busio/__init__.html),
[`digitalio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/digitalio/__init__.html),
[`pulseio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/pulseio/__init__.html),
[`touchio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/touchio/__init__.html),
[`microcontroller`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/microcontroller/__init__.html),
[`board`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/board/__init__.html),
[`bitbangio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/bitbangio/__init__.html) (Only available on atmel-samd21 and ESP8266 currently.)
* No `machine` API on Atmel SAMD21 port.
### Modules
* No module aliasing. (`uos` and `utime` are not available as `os` and
`time` respectively.) Instead `os`, `time`, and `random` are CPython
compatible.
* New `storage` module which manages file system mounts. (Functionality
from `uos` in MicroPython.)
* Modules with a CPython counterpart, such as `time`, `os` and `random`,
are strict [subsets](https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html)
of their [CPython version](https://docs.python.org/3.4/library/time.html?highlight=time#module-time).
Therefore, code from CircuitPython is runnable on CPython but not
necessarily the reverse.
* tick count is available as [`time.monotonic()`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html#time.monotonic)
### atmel-samd21 features
* RGB status LED
* Auto-reload after file write over mass storage. (Disable with
`samd.disable_autoreload()`)
* Wait state after boot and main run, before REPL.
* Main is one of these: `code.txt`, `code.py`, `main.py`, `main.txt`
* Boot is one of these: `settings.txt`, `settings.py`, `boot.py`,
`boot.txt`
---
## Project Structure
Here is an overview of the top-level source code directories.
### Core
The core code of [MicroPython][] is shared amongst ports including
CircuitPython:
* `docs` High level user documentation in Sphinx reStructuredText
format.
* `drivers` External device drivers written in Python.
* `examples` A few example Python scripts.
* `extmod` Shared C code used in multiple ports' modules.
* `lib` Shared core C code including externally developed libraries such
as FATFS.
* `logo` The MicroPython logo.
* `mpy-cross` A cross compiler that converts Python files to byte code
prior to being run in MicroPython. Useful for reducing library size.
* `py` Core Python implementation, including compiler, runtime, and
core library.
* `shared-bindings` Shared definition of Python modules, their docs and
backing C APIs. Ports must implement the C API to support the
corresponding module.
* `shared-module` Shared implementation of Python modules that may be
based on `common-hal`.
* `supervisor` Code and headers related to the supervisor which monitors and
runs individual MicroPython virtual machines (from code in `py`).
* `tests` Test framework and test scripts.
* `tools` Various tools, including the pyboard.py module.
### Ports
Ports include the code unique to a microcontroller line and also
variations based on the board.
* `ports/atmel-samd` Support for SAMD21 based boards such as [Arduino Zero][],
[Adafruit Feather M0 Basic][], and [Adafruit Feather M0 Bluefruit LE][].
* `ports/bare-arm` A bare minimum version of MicroPython for ARM MCUs.
* `ports/cc3200` Support for boards based [CC3200](http://www.ti.com/product/CC3200)
from TI such as the [WiPy 1.0](https://www.pycom.io/solutions/py-boards/wipy1/).
* `ports/esp8266` Support for boards based on ESP8266 WiFi modules such as the
[Adafruit Feather HUZZAH][].
* `ports/minimal` A minimal MicroPython port. Start with this if you want
to port MicroPython to another microcontroller.
* `ports/pic16bit` Support for 16-bit PIC microcontrollers.
* `ports/qemu-arm` Support for ARM emulation through [QEMU](https://qemu.org).
* `ports/stm32` Support for boards based on STM32 microcontrollers including
the MicroPython flagship [PyBoard](https://store.micropython.org/store/#/products/PYBv1_1).
* `ports/teensy` Support for the Teensy line of boards such as the
[Teensy 3.1](https://www.pjrc.com/teensy/teensy31.html).
* `ports/unix` Support for UNIX.
* `ports/windows` Support for [Windows](https://www.microsoft.com/en-us/windows/).
* `ports/zephyr` Support for [Zephyr](https://www.zephyrproject.org/), a
real-time operating system by the Linux Foundation.
CircuitPython only maintains the `atmel-samd` and `esp8266` ports. The
rest are here to maintain compatibility with the
[MicroPython][] parent project.
**[⬆ back to top](#adafruit-circuitpython)**
[Adafruit CircuitPlayground Express]: https://www.adafruit.com/product/3333
[Adafruit Feather M0 Express]: https://www.adafruit.com/product/3403
[Adafruit Metro M0 Express]: https://www.adafruit.com/product/3505
[Adafruit Gemma M0]: https://www.adafruit.com/product/3501
[Adafruit Trinket M0]: https://www.adafruit.com/product/3500
[Adafruit Feather HUZZAH]: https://www.adafruit.com/products/2821
[Adafruit Feather M0 Basic]: https://www.adafruit.com/products/2772
[Adafruit Feather M0 Bluefruit LE]: https://www.adafruit.com/products/2995
[Adafruit Feather M0 Adalogger]: https://www.adafruit.com/product/2796
[Arduino Zero]: https://www.arduino.cc/en/Main/ArduinoBoardZero
[MicroPython]: https://github.com/micropython/micropython
[Code of Conduct]: https://github.com/adafruit/circuitpython/blob/master/CODE_OF_CONDUCT.md

243
README.rst Normal file
View File

@ -0,0 +1,243 @@
Adafruit CircuitPython
======================
|Build Status| |Doc Status| |Discord|
`Status <#status>`__ \| `Supported Boards <#supported-boards>`__
\| `Download <#download>`__ \|
`Documentation <#documentation>`__ \|
`Contributing <#contributing>`__ \| `Differences from
Micropython <#differences-from-micropython>`__ \| `Project
Structure <#project-structure>`__
**CircuitPython** is an *education friendly* open source derivative of
`MicroPython <https://micropython.org>`_. CircuitPython supports use
on educational development boards designed and sold by
`Adafruit <https://adafruit.com>`_. Adafruit CircuitPython features
unified Python core APIs and a growing list of Adafruit libraries and
drivers of that work with it.
Status
------
This project is stable. Most APIs should be stable going forward. Those
that change will change on major version numbers such as 2.0.0 and
3.0.0.
Supported Boards
----------------
Designed for CircuitPython
~~~~~~~~~~~~~~~~~~~~~~~~~~
- `Adafruit CircuitPlayground
Express <https://www.adafruit.com/product/3333>`__
- `Adafruit Feather M0
Express <https://www.adafruit.com/product/3403>`__
- `Adafruit Metro M0 Express <https://www.adafruit.com/product/3505>`__
- `Adafruit Gemma M0 <https://www.adafruit.com/product/3501>`__
Other
~~~~~
- `Adafruit Feather HUZZAH <https://www.adafruit.com/products/2821>`__
- `Adafruit Feather M0
Basic <https://www.adafruit.com/products/2772>`__
- `Adafruit Feather M0 Bluefruit
LE <https://www.adafruit.com/products/2995>`__ (uses M0 Basic
binaries)
- `Adafruit Feather M0
Adalogger <https://www.adafruit.com/product/2796>`__ (MicroSD card
supported using the `Adafruit CircuitPython SD
library <https://github.com/adafruit/Adafruit_CircuitPython_SD>`__)
- `Arduino Zero <https://www.arduino.cc/en/Main/ArduinoBoardZero>`__
Download
--------
Official binaries are available through the `latest GitHub
releases <https://github.com/adafruit/circuitpython/releases>`__.
Continuous (one per commit) builds are available
`here <https://adafruit-circuit-python.s3.amazonaws.com/index.html?prefix=bin>`__
and includes experimental hardware support.
Documentation
-------------
Guides and videos are available through the `Adafruit Learning
System <https://learn.adafruit.com/>`__ under the `CircuitPython
category <https://learn.adafruit.com/category/circuitpython>`__ and
`MicroPython
category <https://learn.adafruit.com/category/micropython>`__. An API
reference is also available on `Read the
Docs <http://circuitpython.readthedocs.io/en/latest/?>`__.
Contributing
------------
See
`CONTRIBUTING.md <https://github.com/adafruit/circuitpython/blob/master/CONTRIBUTING.md>`__
for full guidelines but please be aware that by contributing to this
project you are agreeing to the `Code of
Conduct <https://github.com/adafruit/circuitpython/blob/master/CODE_OF_CONDUCT.md>`__.
Contributors who follow the `Code of
Conduct <https://github.com/adafruit/circuitpython/blob/master/CODE_OF_CONDUCT.md>`__
are welcome to submit pull requests and they will be promptly reviewed
by project admins. Please join the `Gitter
chat <https://gitter.im/adafruit/circuitpython>`__ or
`Discord <https://discord.gg/nBQh6qu>`__ too.
--------------
Differences from `MicroPython <https://github.com/micropython/micropython>`__
-----------------------------------------------------------------------------
CircuitPython:
- includes a port for Atmel SAMD21 (Commonly known as M0 in Adafruit
product names.)
- supports only Atmel SAMD21 and ESP8266 ports.
- tracks MicroPython's releases (not master).
Behavior
~~~~~~~~
- The order that files are run and the state that is shared between
them. CircuitPython's goal is to clarify the role of each file and
make each file independent from each other.
- ``boot.py`` (or ``settings.py``) runs only once on start up before
USB is initialized. This lays the ground work for configuring USB at
startup rather than it being fixed. Since serial is not available,
output is written to ``boot_out.txt``.
- ``code.py`` (or ``main.py``) is run after every reload until it
finishes or is interrupted. After it is done running, the vm and
hardware is reinitialized. **This means you cannot read state from
``code.py`` in the REPL anymore.** CircuitPython's goal for this
change includes reduce confusion about pins and memory being used.
- After ``code.py`` the REPL can be entered by pressing any key. It no
longer shares state with ``code.py`` so it is a fresh vm.
- Autoreload state will be maintained across reload.
- Adds a safe mode that does not run user code after a hard crash or
brown out. The hope is that this will make it easier to fix code that
causes nasty crashes by making it available through mass storage
after the crash. A reset (the button) is needed after its fixed to
get back into normal mode.
API
~~~
- Unified hardware APIs: `audioio <https://circuitpython.readthedocs.io/en/latest/shared-bindings/audioio/__init__.html>`_, `analogio <https://circuitpython.readthedocs.io/en/latest/shared-bindings/analogio/__init__.html>`_, `busio <https://circuitpython.readthedocs.io/en/latest/shared-bindings/busio/__init__.html>`_, `digitalio <https://circuitpython.readthedocs.io/en/latest/shared-bindings/digitalio/__init__.html>`_, `pulseio <https://circuitpython.readthedocs.io/en/latest/shared-bindings/pulseio/__init__.html>`_, `touchio <https://circuitpython.readthedocs.io/en/latest/shared-bindings/touchio/__init__.html>`_, `microcontroller <https://circuitpython.readthedocs.io/en/latest/shared-bindings/microcontroller/__init__.html>`_, `board <https://circuitpython.readthedocs.io/en/latest/shared-bindings/board/__init__.html>`_, `bitbangio <https://circuitpython.readthedocs.io/en/latest/shared-bindings/bitbangio/__init__.html>`_
- No ``machine`` API on Atmel SAMD21 port.
Modules
~~~~~~~
- No module aliasing. (``uos`` and ``utime`` are not available as
``os`` and ``time`` respectively.) Instead ``os``, ``time``, and
``random`` are CPython compatible.
- New ``storage`` module which manages file system mounts.
(Functionality from ``uos`` in MicroPython.)
- Modules with a CPython counterpart, such as ``time``, ``os`` and
``random``, are strict
`subsets <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html>`__
of their `CPython
version <https://docs.python.org/3.4/library/time.html?highlight=time#module-time>`__.
Therefore, code from CircuitPython is runnable on CPython but not
necessarily the reverse.
- tick count is available as
`time.monotonic() <https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html#time.monotonic>`__
atmel-samd21 features
~~~~~~~~~~~~~~~~~~~~~
- RGB status LED
- Auto-reload after file write over mass storage. (Disable with
``samd.disable_autoreload()``)
- Wait state after boot and main run, before REPL.
- Main is one of these: ``code.txt``, ``code.py``, ``main.py``,
``main.txt``
- Boot is one of these: ``settings.txt``, ``settings.py``, ``boot.py``,
``boot.txt``
--------------
Project Structure
-----------------
Here is an overview of the top-level source code directories.
Core
~~~~
The core code of
`MicroPython <https://github.com/micropython/micropython>`__ is shared
amongst ports including CircuitPython:
- ``docs`` High level user documentation in Sphinx reStructuredText
format.
- ``drivers`` External device drivers written in Python.
- ``examples`` A few example Python scripts.
- ``extmod`` Shared C code used in multiple ports' modules.
- ``lib`` Shared core C code including externally developed libraries
such as FATFS.
- ``logo`` The MicroPython logo.
- ``mpy-cross`` A cross compiler that converts Python files to byte
code prior to being run in MicroPython. Useful for reducing library
size.
- ``py`` Core Python implementation, including compiler, runtime, and
core library.
- ``shared-bindings`` Shared definition of Python modules, their docs
and backing C APIs. Ports must implement the C API to support the
corresponding module.
- ``shared-module`` Shared implementation of Python modules that may be
based on ``common-hal``.
- ``tests`` Test framework and test scripts.
- ``tools`` Various tools, including the pyboard.py module.
Ports
~~~~~
Ports include the code unique to a microcontroller line and also
variations based on the board.
- ``atmel-samd`` Support for SAMD21 based boards such as `Arduino
Zero <https://www.arduino.cc/en/Main/ArduinoBoardZero>`__, `Adafruit
Feather M0 Basic <https://www.adafruit.com/products/2772>`__, and
`Adafruit Feather M0 Bluefruit
LE <https://www.adafruit.com/products/2995>`__.
- ``bare-arm`` A bare minimum version of MicroPython for ARM MCUs.
- ``cc3200`` Support for boards based
`CC3200 <http://www.ti.com/product/CC3200>`__ from TI such as the
`WiPy 1.0 <https://www.pycom.io/solutions/py-boards/wipy1/>`__.
- ``esp8266`` Support for boards based on ESP8266 WiFi modules such as
the `Adafruit Feather
HUZZAH <https://www.adafruit.com/products/2821>`__.
- ``minimal`` A minimal MicroPython port. Start with this if you want
to port MicroPython to another microcontroller.
- ``pic16bit`` Support for 16-bit PIC microcontrollers.
- ``qemu-arm`` Support for ARM emulation through
`QEMU <https://qemu.org>`__.
- ``stmhal`` Support for boards based on STM32 microcontrollers
including the MicroPython flagship
`PyBoard <https://store.micropython.org/store/#/products/PYBv1_1>`__.
- ``teensy`` Support for the Teensy line of boards such as the `Teensy
3.1 <https://www.pjrc.com/teensy/teensy31.html>`__.
- ``unix`` Support for UNIX.
- ``windows`` Support for
`Windows <https://www.microsoft.com/en-us/windows/>`__.
- ``zephyr`` Support for `Zephyr <https://www.zephyrproject.org/>`__, a
real-time operating system by the Linux Foundation.
CircuitPython only maintains the ``atmel-samd`` and ``esp8266`` ports.
The rest are here to maintain compatibility with the
`MicroPython <https://github.com/micropython/micropython>`__ parent
project.
`⬆ back to top <#adafruit-circuitpython>`__
.. |Build Status| image:: https://travis-ci.org/adafruit/circuitpython.svg?branch=master
:target: https://travis-ci.org/adafruit/circuitpython
.. |Doc Status| image:: https://readthedocs.org/projects/circuitpython/badge/?version=latest
:target: http://circuitpython.readthedocs.io/
.. |Discord| image:: https://img.shields.io/discord/327254708534116352.svg
:target: https://discord.gg/nBQh6qu

19
conf.py
View File

@ -23,9 +23,7 @@ from recommonmark.parser import CommonMarkParser
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('.'))
# Specify a custom master document based on the port name
master_doc = 'index'
master_doc = 'docs/index'
# -- General configuration ------------------------------------------------
@ -83,13 +81,15 @@ version = release = '0.0.0'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ["**/build-*",
exclude_patterns = ["**/build*",
".venv",
"docs/README.md",
"drivers",
"examples",
"extmod",
"frozen",
"lib",
"main.c",
"mpy-cross",
"ports/*/*.c",
"ports/*/*.h",
@ -98,12 +98,17 @@ exclude_patterns = ["**/build-*",
"ports/*/supervisor",
"ports/atmel-samd/asf4",
"ports/atmel-samd/asf4_conf",
"ports/atmel-samd/external_flash",
"ports/atmel-samd/freetouch",
"ports/atmel-samd/QTouch",
"ports/atmel-samd/tools",
"ports/bare-arm",
"ports/cc3200",
"ports/cc3200/FreeRTOS",
"ports/cc3200/hal",
"ports/esp8266",
"ports/esp8266/boards",
"ports/esp8266/common-hal",
"ports/esp8266/modules",
"ports/minimal",
"ports/nrf/device",
"ports/nrf/drivers",
@ -121,7 +126,9 @@ exclude_patterns = ["**/build-*",
"ports/windows",
"ports/zephyr",
"py",
"shared-bindings/util.*",
"shared-module",
"supervisor",
"tests",
"tools"]
@ -153,7 +160,7 @@ pygments_style = 'sphinx'
# of rst_prolog, so we follow. Absolute paths below mean "from the base
# of the doctree".
rst_epilog = """
.. include:: /templates/replace.inc
.. include:: /docs/templates/replace.inc
"""
# -- Options for HTML output ----------------------------------------------

13
docs/design_guide.rst
View File

@ -215,7 +215,7 @@ Renders as:
Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Attributes are state on objects. (See `Getters/Setters` above for more discussion
Attributes are state on objects. (See `Getters/Setters`_ above for more discussion
about when to use them.) They can be defined internally in a number of different
ways. Each approach is enumerated below with an explanation of where the comment
goes.
@ -400,10 +400,11 @@ For example, if you are writing a driver for an I2C device, then take in an I2C
object instead of the pins themselves. This allows the calling code to provide
any object with the appropriate methods such as an I2C expansion board.
Another example is to expect a `DigitalInOut` for a pin to toggle instead of a
`microcontroller.Pin` from `board`. Taking in the `~microcontroller.Pin` object
alone would limit the driver to pins on the actual microcontroller instead of pins
provided by another driver such as an IO expander.
Another example is to expect a :py:class:`~digitalio.DigitalInOut` for a pin to
toggle instead of a :py:class:`~microcontroller.Pin` from `board`. Taking in the
:py:class:`~microcontroller.Pin` object alone would limit the driver to pins on
the actual microcontroller instead of pins provided by another driver such as an
IO expander.
Lots of small modules
--------------------------------------------------------------------------------
@ -441,7 +442,7 @@ Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ustruct.pack
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use `ustruct.pack_into` instead of `ustruct.pack`.

10
docs/differences/index_template.txt
View File

@ -1,10 +0,0 @@
.. _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

187
docs/esp8266/general.rst
View File

@ -1,187 +0,0 @@
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.

BIN
docs/esp8266/img/adafruit_products_pinoutstop.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 78 KiB

8
docs/esp8266/index.rst
View File

@ -1,8 +0,0 @@
ESP8266
========================================
.. toctree::
quickref.rst
general.rst
tutorial/index.rst

375
docs/esp8266/quickref.rst
View File

@ -1,375 +0,0 @@
.. _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.

19
docs/esp8266/tutorial/adc.rst
View File

@ -1,19 +0,0 @@
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.

65
docs/esp8266/tutorial/dht.rst
View File

@ -1,65 +0,0 @@
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.

69
docs/esp8266/tutorial/filesystem.rst
View File

@ -1,69 +0,0 @@
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.

33
docs/esp8266/tutorial/index.rst
View File

@ -1,33 +0,0 @@
.. _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

202
docs/esp8266/tutorial/intro.rst
View File

@ -1,202 +0,0 @@
.. _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.

84
docs/esp8266/tutorial/neopixel.rst
View File

@ -1,84 +0,0 @@
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)

81
docs/esp8266/tutorial/network_basics.rst
View File

@ -1,81 +0,0 @@
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.

122
docs/esp8266/tutorial/network_tcp.rst
View File

@ -1,122 +0,0 @@
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()

12
docs/esp8266/tutorial/nextsteps.rst
View File

@ -1,12 +0,0 @@
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!

37
docs/esp8266/tutorial/onewire.rst
View File

@ -1,37 +0,0 @@
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.

75
docs/esp8266/tutorial/pins.rst
View File

@ -1,75 +0,0 @@
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.

61
docs/esp8266/tutorial/powerctrl.rst
View File

@ -1,61 +0,0 @@
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')

87
docs/esp8266/tutorial/pwm.rst
View File

@ -1,87 +0,0 @@
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(t/1000)
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)

212
docs/esp8266/tutorial/repl.rst
View File

@ -1,212 +0,0 @@
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.

12
docs/esp8266_index.rst
View File

@ -1,12 +0,0 @@
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

54
docs/index.rst Normal file
View File

@ -0,0 +1,54 @@
Adafruit CircuitPython API Reference
====================================
Welcome to the API reference documentation for Adafruit CircuitPython.
This contains low-level API reference docs which may link out to separate
*"getting started"* guides. `Adafruit <https://adafruit.com>`_ has many
excellent tutorials available through the
`Adafruit Learning System <https://learn.adafruit.com/>`_.
.. include:: ../README.rst
.. _contents:
Full Table of Contents
----------------------
.. toctree::
:maxdepth: 3
:caption: API and Usage
../shared-bindings/index.rst
supported_ports.rst
troubleshooting.rst
drivers.rst
.. toctree::
:maxdepth: 1
:caption: Design and porting reference
design_guide
porting
common_hal
.. toctree::
:maxdepth: 2
:caption: MicroPython specific
library/index.rst
.. toctree::
:maxdepth: 1
:caption: About the project
../README
../CONTRIBUTING
../CODE_OF_CONDUCT
../license.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

4
docs/library/array.rst
View File

@ -1,10 +1,12 @@
:mod:`array` -- arrays of numeric data
======================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: array
:synopsis: efficient arrays of numeric data
|see_cpython_module| :mod:`python:array`.
|see_cpython_module| :mod:`cpython:array`.
Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
``L``, ``q``, ``Q``, ``f``, ``d`` (the latter 2 depending on the

4
docs/library/btree.rst
View File

@ -1,6 +1,8 @@
:mod:`btree` -- simple BTree database
=====================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: btree
:synopsis: simple BTree database
@ -78,7 +80,7 @@ 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
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):

14
docs/library/builtins.rst
View File

@ -1,6 +1,12 @@
Builtin functions and exceptions
================================
.. warning::
These builtins are inherited from MicroPython and may not work in CircuitPython
as documented or at all! If work differently from CPython, then their behavior
may change.
All builtin functions and exceptions are described here. They are also
available via ``builtins`` module.
@ -21,7 +27,7 @@ Functions and types
.. class:: bytes()
|see_cpython| `python:bytes`.
|see_cpython| `bytes`.
.. function:: callable()
@ -176,7 +182,7 @@ Exceptions
.. exception:: OSError
|see_cpython| `python:OSError`. MicroPython doesn't implement ``errno``
|see_cpython| `OSError`. MicroPython doesn't implement ``errno``
attribute, instead use the standard way to access exception arguments:
``exc.args[0]``.
@ -188,11 +194,11 @@ Exceptions
.. exception:: SystemExit
|see_cpython| `python:SystemExit`.
|see_cpython| :py:class:`python:SystemExit`.
.. exception:: TypeError
|see_cpython| `python:TypeError`.
|see_cpython| :py:class:`python:TypeError`.
.. exception:: ValueError

63
docs/library/cmath.rst
View File

@ -1,63 +0,0 @@
: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

2
docs/library/esp.rst
View File

@ -1,6 +1,8 @@
:mod:`esp` --- functions related to the ESP8266
===============================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: esp
:synopsis: functions related to the ESP8266

2
docs/library/framebuf.rst
View File

@ -1,6 +1,8 @@
:mod:`framebuf` --- Frame buffer manipulation
=============================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: framebuf
:synopsis: Frame buffer manipulation

4
docs/library/gc.rst
View File

@ -1,10 +1,12 @@
:mod:`gc` -- control the garbage collector
==========================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: gc
:synopsis: control the garbage collector
|see_cpython_module| :mod:`python:gc`.
|see_cpython_module| :mod:`cpython:gc`.
Functions
---------

159
docs/library/index.rst
View File

@ -5,74 +5,20 @@ MicroPython libraries
.. warning::
Important summary of this section
These modules are inherited from MicroPython and may not work in CircuitPython
as documented or at all! If they do work, they may change at any time.
* 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 and CircuitPython. 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
@ -81,82 +27,11 @@ it will fallback to loading the built-in ``ujson`` module.
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
@ -171,40 +46,10 @@ the following libraries.
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
---------------------------------

394
docs/library/lcd160cr.rst
View File

@ -1,394 +0,0 @@
: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`.

74
docs/library/machine.ADC.rst
View File

@ -1,74 +0,0 @@
.. 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.

172
docs/library/machine.I2C.rst
View File

@ -1,172 +0,0 @@
.. 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``.

248
docs/library/machine.Pin.rst
View File

@ -1,248 +0,0 @@
.. 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.

69
docs/library/machine.RTC.rst
View File

@ -1,69 +0,0 @@
.. 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

42
docs/library/machine.SD.rst
View File

@ -1,42 +0,0 @@
.. 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.

97
docs/library/machine.SPI.rst
View File

@ -1,97 +0,0 @@
.. 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

123
docs/library/machine.Signal.rst
View File

@ -1,123 +0,0 @@
.. 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.

160
docs/library/machine.Timer.rst
View File

@ -1,160 +0,0 @@
.. 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.

142
docs/library/machine.UART.rst
View File

@ -1,142 +0,0 @@
.. 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

36
docs/library/machine.WDT.rst
View File

@ -1,36 +0,0 @@
.. 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.

170
docs/library/machine.rst
View File

@ -1,170 +0,0 @@
: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

185
docs/library/math.rst
View File

@ -1,185 +0,0 @@
: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

2
docs/library/micropython.rst
View File

@ -1,6 +1,8 @@
:mod:`micropython` -- access and control MicroPython internals
==============================================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: micropython
:synopsis: access and control MicroPython internals

322
docs/library/network.rst
View File

@ -2,6 +2,8 @@
:mod:`network` --- network configuration
****************************************
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: network
:synopsis: network configuration
@ -39,7 +41,7 @@ Common network adapter interface
================================
This section describes an (implied) abstract base class for all network
interface classes implemented by `MicroPython ports <MicroPython port>`
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.
@ -131,168 +133,8 @@ parameter should be `id`.
# 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
=========
@ -420,7 +262,7 @@ parameter should be `id`.
print(ap.config('channel'))
Following are commonly supported parameters (availability of a specific parameter
depends on network technology type, driver, and `MicroPython port`).
depends on network technology type, driver, and ``MicroPython port``).
============= ===========
Parameter Description
@ -433,159 +275,3 @@ parameter should be `id`.
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

143
docs/library/pyb.ADC.rst
View File

@ -1,143 +0,0 @@
.. 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)

57
docs/library/pyb.Accel.rst
View File

@ -1,57 +0,0 @@
.. 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.

223
docs/library/pyb.CAN.rst
View File

@ -1,223 +0,0 @@
.. 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

109
docs/library/pyb.DAC.rst
View File

@ -1,109 +0,0 @@
.. 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)

114
docs/library/pyb.ExtInt.rst
View File

@ -1,114 +0,0 @@
.. 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

175
docs/library/pyb.I2C.rst
View File

@ -1,175 +0,0 @@
.. 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

97
docs/library/pyb.LCD.rst
View File

@ -1,97 +0,0 @@
.. 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.

46
docs/library/pyb.LED.rst
View File

@ -1,46 +0,0 @@
.. 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.

280
docs/library/pyb.Pin.rst
View File

@ -1,280 +0,0 @@
.. 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

83
docs/library/pyb.RTC.rst
View File

@ -1,83 +0,0 @@
.. 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

132
docs/library/pyb.SPI.rst
View File

@ -1,132 +0,0 @@
.. 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

80
docs/library/pyb.Servo.rst
View File

@ -1,80 +0,0 @@
.. 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.

46
docs/library/pyb.Switch.rst
View File

@ -1,46 +0,0 @@
.. 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.

286
docs/library/pyb.Timer.rst
View File

@ -1,286 +0,0 @@
.. 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%.

245
docs/library/pyb.UART.rst
View File

@ -1,245 +0,0 @@
.. 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.

40
docs/library/pyb.USB_HID.rst
View File

@ -1,40 +0,0 @@
.. 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).

103
docs/library/pyb.USB_VCP.rst
View File

@ -1,103 +0,0 @@
.. 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.

321
docs/library/pyb.rst
View File

@ -1,321 +0,0 @@
: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

7
docs/library/sys.rst
View File

@ -1,10 +1,12 @@
:mod:`sys` -- system specific functions
=======================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: sys
:synopsis: system specific functions
|see_cpython_module| :mod:`python:sys`.
|see_cpython_module| :mod:`cpython:sys`.
Functions
---------
@ -27,8 +29,7 @@ Functions
``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`.
positional; further arguments are not supported.
Constants
---------

4
docs/library/ubinascii.rst
View File

@ -1,10 +1,12 @@
:mod:`ubinascii` -- binary/ASCII conversions
============================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ubinascii
:synopsis: binary/ASCII conversions
|see_cpython_module| :mod:`python:binascii`.
|see_cpython_module| :mod:`cpython:binascii`.
This module implements conversions between binary data and various
encodings of it in ASCII form (in both directions).

4
docs/library/ucollections.rst
View File

@ -1,10 +1,12 @@
:mod:`ucollections` -- collection and container types
=====================================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ucollections
:synopsis: collection and container types
|see_cpython_module| :mod:`python:collections`.
|see_cpython_module| :mod:`cpython:collections`.
This module implements advanced collection and container types to
hold/accumulate various objects.

4
docs/library/uctypes.rst
View File

@ -1,6 +1,8 @@
:mod:`uctypes` -- access binary data in a structured way
========================================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uctypes
:synopsis: access binary data in a structured way
@ -13,7 +15,7 @@ sub-fields.
.. seealso::
Module :mod:`ustruct`
Module :mod:`struct`
Standard Python way to access binary data structures (doesn't scale
well to large and complex structures).

12
docs/library/uerrno.rst
View File

@ -1,13 +1,14 @@
:mod:`uerrno` -- system error codes
===================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uerrno
:synopsis: system error codes
|see_cpython_module| :mod:`python:errno`.
|see_cpython_module| :mod:`cpython:errno`.
This module provides access to symbolic error codes for `OSError` exception.
A particular inventory of codes depends on `MicroPython port`.
Constants
---------
@ -15,12 +16,11 @@ 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::
"E". Errors are usually accessible as ``exc.args[0]``
where ``exc`` is an instance of `OSError`. Usage example::
try:
uos.mkdir("my_dir")
os.mkdir("my_dir")
except OSError as exc:
if exc.args[0] == uerrno.EEXIST:
print("Directory already exists")

4
docs/library/uhashlib.rst
View File

@ -1,10 +1,12 @@
:mod:`uhashlib` -- hashing algorithms
=====================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uhashlib
:synopsis: hashing algorithms
|see_cpython_module| :mod:`python:hashlib`.
|see_cpython_module| :mod:`cpython:hashlib`.
This module implements binary data hashing algorithms. The exact inventory
of available algorithms depends on a board. Among the algorithms which may

4
docs/library/uheapq.rst
View File

@ -1,10 +1,12 @@
:mod:`uheapq` -- heap queue algorithm
=====================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uheapq
:synopsis: heap queue algorithm
|see_cpython_module| :mod:`python:heapq`.
|see_cpython_module| :mod:`cpython:heapq`.
This module implements the heap queue algorithm.

6
docs/library/uio.rst
View File

@ -1,10 +1,12 @@
:mod:`uio` -- input/output streams
==================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uio
:synopsis: input/output streams
|see_cpython_module| :mod:`python:io`.
|see_cpython_module| :mod:`cpython:io`.
This module contains additional types of stream (file-like) objects
and helper functions.
@ -81,7 +83,7 @@ Functions
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.
``mode`` parameter, but support for other arguments vary by port.
Classes
-------

4
docs/library/ujson.rst
View File

@ -1,10 +1,12 @@
:mod:`ujson` -- JSON encoding and decoding
==========================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ujson
:synopsis: JSON encoding and decoding
|see_cpython_module| :mod:`python:json`.
|see_cpython_module| :mod:`cpython:json`.
This modules allows to convert between Python objects and the JSON
data format.

110
docs/library/uos.rst
View File

@ -1,110 +0,0 @@
: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.

4
docs/library/ure.rst
View File

@ -1,10 +1,12 @@
:mod:`ure` -- simple regular expressions
========================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ure
:synopsis: regular expressions
|see_cpython_module| :mod:`python:re`.
|see_cpython_module| :mod:`cpython:re`.
This module implements regular expression operations. Regular expression
syntax supported is a subset of CPython ``re`` module (and actually is

6
docs/library/uselect.rst
View File

@ -1,10 +1,12 @@
:mod:`uselect` -- wait for events on a set of streams
========================================================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uselect
:synopsis: wait for events on a set of streams
|see_cpython_module| :mod:`python:select`.
|see_cpython_module| :mod:`cpython:select`.
This module provides functions to efficiently wait for events on multiple
streams (select streams which are ready for operations).
@ -69,7 +71,7 @@ Methods
.. 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
``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

25
docs/library/usocket.rst
View File

@ -2,10 +2,12 @@
:mod:`usocket` -- socket module
*******************************
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: usocket
:synopsis: socket module
|see_cpython_module| :mod:`python:socket`.
|see_cpython_module| :mod:`cpython:socket`.
This module provides access to the BSD socket interface.
@ -36,11 +38,7 @@ 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.
addresses using tuples, as described below.
Summing up:
@ -60,8 +58,7 @@ Tuple address format for ``socket`` module:
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`.
they should be resolved first using `usocket.getaddrinfo()`.
Functions
---------
@ -99,7 +96,7 @@ Functions
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
:py:mod:`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
@ -127,7 +124,7 @@ Constants
.. data:: AF_INET
AF_INET6
Address family types. Availability depends on a particular `MicroPython port`.
Address family types. Availability depends on a particular ``MicroPython port``.
.. data:: SOCK_STREAM
SOCK_DGRAM
@ -137,7 +134,7 @@ Constants
.. data:: IPPROTO_UDP
IPPROTO_TCP
IP protocol numbers. Availability depends on a particular `MicroPython port`.
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
@ -146,12 +143,12 @@ Constants
.. data:: usocket.SOL_*
Socket option levels (an argument to `setsockopt()`). The exact
inventory depends on a `MicroPython port`.
inventory depends on a ``MicroPython port``.
.. data:: usocket.SO_*
Socket options (an argument to `setsockopt()`). The exact
inventory depends on a `MicroPython port`.
inventory depends on a ``MicroPython port``.
Constants specific to WiPy:
@ -245,7 +242,7 @@ Methods
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
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::

10
docs/library/ussl.rst
View File

@ -1,10 +1,12 @@
:mod:`ussl` -- SSL/TLS module
=============================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ussl
:synopsis: TLS/SSL wrapper for socket objects
|see_cpython_module| :mod:`python:ssl`.
|see_cpython_module| :mod:`cpython:ssl`.
This module provides access to Transport Layer Security (previously and
widely known as “Secure Sockets Layer”) encryption and peer authentication
@ -18,13 +20,13 @@ Functions
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
``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.
``MicroPython port``, some or all keyword arguments above may be not supported.
.. warning::

4
docs/library/ustruct.rst
View File

@ -1,10 +1,12 @@
:mod:`ustruct` -- pack and unpack primitive data types
======================================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ustruct
:synopsis: pack and unpack primitive data types
|see_cpython_module| :mod:`python:struct`.
|see_cpython_module| :mod:`cpython:struct`.
Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``.

229
docs/library/utime.rst
View File

@ -1,229 +0,0 @@
: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).

4
docs/library/uzlib.rst
View File

@ -1,10 +1,12 @@
:mod:`uzlib` -- zlib decompression
==================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uzlib
:synopsis: zlib decompression
|see_cpython_module| :mod:`python:zlib`.
|see_cpython_module| :mod:`cpython:zlib`.
This module allows to decompress binary data compressed with
`DEFLATE algorithm <https://en.wikipedia.org/wiki/DEFLATE>`_

17
docs/library/wipy.rst
View File

@ -1,17 +0,0 @@
*************************************
: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``).

2
docs/porting.rst
View File

@ -45,7 +45,7 @@ these resources are compatible with the MIT License of the rest of the code!
Step 2: Init
--------------
Once your build is setup, the next step should be to get your clocks going as
you expect from the supervisor. The supervisor calls `port_init` to allow for
you expect from the supervisor. The supervisor calls ``port_init`` to allow for
initialization at the beginning of main. This function also has the ability to
request a safe mode state which prevents the supervisor from running user code
while still allowing access to the REPL and other resources.

80
docs/pyboard/general.rst
View File

@ -1,80 +0,0 @@
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

30
docs/pyboard/hardware/index.rst
View File

@ -1,30 +0,0 @@
.. _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)

9
docs/pyboard/index.rst
View File

@ -1,9 +0,0 @@
PyBoard
========================================
.. toctree::
quickref.rst
general.rst
tutorial/index.rst
hardware/index.rst

217
docs/pyboard/quickref.rst
View File

@ -1,217 +0,0 @@
.. _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())

92
docs/pyboard/tutorial/accel.rst
View File

@ -1,92 +0,0 @@
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.

98
docs/pyboard/tutorial/amp_skin.rst
View File

@ -1,98 +0,0 @@
The AMP audio skin
==================
Soldering and using the AMP audio skin.
.. image:: img/skin_amp_1.jpg
:alt: AMP skin
:width: 250px
.. image:: img/skin_amp_2.jpg
:alt: AMP skin
:width: 250px
The following video shows how to solder the headers, microphone and speaker onto the AMP skin.
.. raw:: html
<iframe style="margin-left:3em;" width="560" height="315" src="http://www.youtube.com/embed/fjB1DuZRveo?rel=0" frameborder="0" allowfullscreen></iframe>
For circuit schematics and datasheets for the components on the skin see :ref:`hardware_index`.
Example code
------------
The AMP skin has a speaker which is connected to ``DAC(1)`` via a small
power amplifier. The volume of the amplifier is controlled by a digital
potentiometer, which is an I2C device with address 46 on the ``IC2(1)`` bus.
To set the volume, define the following function::
import pyb
def volume(val):
pyb.I2C(1, pyb.I2C.MASTER).mem_write(val, 46, 0)
Then you can do::
>>> volume(0) # minimum volume
>>> volume(127) # maximum volume
To play a sound, use the ``write_timed`` method of the ``DAC`` object.
For example::
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)
You can also play WAV files using the Python ``wave`` module. You can get
the wave module `here <http://micropython.org/resources/examples/wave.py>`__ and you will also need
the chunk module available `here <http://micropython.org/resources/examples/chunk.py>`__. Put these
on your pyboard (either on the flash or the SD card in the top-level directory). You will need an
8-bit WAV file to play, such as `this one <http://micropython.org/resources/examples/test.wav>`_,
or to convert any file you have with the command::
avconv -i original.wav -ar 22050 -codec pcm_u8 test.wav
Then you can do::
>>> import wave
>>> from pyb import DAC
>>> dac = DAC(1)
>>> f = wave.open('test.wav')
>>> dac.write_timed(f.readframes(f.getnframes()), f.getframerate())
This should play the WAV file. Note that this will read the whole file into RAM
so it has to be small enough to fit in it.
To play larger wave files you will have to use the micro-SD card to store it.
Also the file must be read and sent to the DAC in small chunks that will fit
the RAM limit of the microcontroller. Here is an example function that can
play 8-bit wave files with up to 16kHz sampling::
import wave
from pyb import DAC
from pyb import delay
dac = DAC(1)
def play(filename):
f = wave.open(filename, 'r')
total_frames = f.getnframes()
framerate = f.getframerate()
for position in range(0, total_frames, framerate):
f.setpos(position)
dac.write_timed(f.readframes(framerate), framerate)
delay(1000)
This function reads one second worth of data and sends it to DAC. It then waits
one second and moves the file cursor to the new position to read the next second
of data in the next iteration of the for-loop. It plays one second of audio at
a time every one second.

131
docs/pyboard/tutorial/assembler.rst
View File

@ -1,131 +0,0 @@
.. _pyboard_tutorial_assembler:
Inline assembler
================
Here you will learn how to write inline assembler in MicroPython.
**Note**: this is an advanced tutorial, intended for those who already
know a bit about microcontrollers and assembly language.
MicroPython includes an inline assembler. It allows you to write
assembly routines as a Python function, and you can call them as you would
a normal Python function.
Returning a value
-----------------
Inline assembler functions are denoted by a special function decorator.
Let's start with the simplest example::
@micropython.asm_thumb
def fun():
movw(r0, 42)
You can enter this in a script or at the REPL. This function takes no
arguments and returns the number 42. ``r0`` is a register, and the value
in this register when the function returns is the value that is returned.
MicroPython always interprets the ``r0`` as an integer, and converts it to an
integer object for the caller.
If you run ``print(fun())`` you will see it print out 42.
Accessing peripherals
---------------------
For something a bit more complicated, let's turn on an LED::
@micropython.asm_thumb
def led_on():
movwt(r0, stm.GPIOA)
movw(r1, 1 << 13)
strh(r1, [r0, stm.GPIO_BSRRL])
This code uses a few new concepts:
- ``stm`` is a module which provides a set of constants for easy
access to the registers of the pyboard's microcontroller. Try
running ``import stm`` and then ``help(stm)`` at the REPL. It will
give you a list of all the available constants.
- ``stm.GPIOA`` is the address in memory of the GPIOA peripheral.
On the pyboard, the red LED is on port A, pin PA13.
- ``movwt`` moves a 32-bit number into a register. It is a convenience
function that turns into 2 thumb instructions: ``movw`` followed by ``movt``.
The ``movt`` also shifts the immediate value right by 16 bits.
- ``strh`` stores a half-word (16 bits). The instruction above stores
the lower 16-bits of ``r1`` into the memory location ``r0 + stm.GPIO_BSRRL``.
This has the effect of setting high all those pins on port A for which
the corresponding bit in ``r0`` is set. In our example above, the 13th
bit in ``r0`` is set, so PA13 is pulled high. This turns on the red LED.
Accepting arguments
-------------------
Inline assembler functions can accept up to 4 arguments. If they are
used, they must be named ``r0``, ``r1``, ``r2`` and ``r3`` to reflect the registers
and the calling conventions.
Here is a function that adds its arguments::
@micropython.asm_thumb
def asm_add(r0, r1):
add(r0, r0, r1)
This performs the computation ``r0 = r0 + r1``. Since the result is put
in ``r0``, that is what is returned. Try ``asm_add(1, 2)``, it should return
3.
Loops
-----
We can assign labels with ``label(my_label)``, and branch to them using
``b(my_label)``, or a conditional branch like ``bgt(my_label)``.
The following example flashes the green LED. It flashes it ``r0`` times. ::
@micropython.asm_thumb
def flash_led(r0):
# get the GPIOA address in r1
movwt(r1, stm.GPIOA)
# get the bit mask for PA14 (the pin LED #2 is on)
movw(r2, 1 << 14)
b(loop_entry)
label(loop1)
# turn LED on
strh(r2, [r1, stm.GPIO_BSRRL])
# delay for a bit
movwt(r4, 5599900)
label(delay_on)
sub(r4, r4, 1)
cmp(r4, 0)
bgt(delay_on)
# turn LED off
strh(r2, [r1, stm.GPIO_BSRRH])
# delay for a bit
movwt(r4, 5599900)
label(delay_off)
sub(r4, r4, 1)
cmp(r4, 0)
bgt(delay_off)
# loop r0 times
sub(r0, r0, 1)
label(loop_entry)
cmp(r0, 0)
bgt(loop1)
Further reading
---------------
For further information about supported instructions of the inline assembler,
see the :ref:`reference documentation <asm_thumb2_index>`.

37
docs/pyboard/tutorial/debounce.rst
View File

@ -1,37 +0,0 @@
Debouncing a pin input
======================
A pin used as input from a switch or other mechanical device can have a lot
of noise on it, rapidly changing from low to high when the switch is first
pressed or released. This noise can be eliminated using a capacitor (a
debouncing circuit). It can also be eliminated using a simple function that
makes sure the value on the pin is stable.
The following function does just this. It gets the current value of the given
pin, and then waits for the value to change. The new pin value must be stable
for a continuous 20ms for it to register the change. You can adjust this time
(to say 50ms) if you still have noise. ::
import pyb
def wait_pin_change(pin):
# wait for pin to change value
# it needs to be stable for a continuous 20ms
cur_value = pin.value()
active = 0
while active < 20:
if pin.value() != cur_value:
active += 1
else:
active = 0
pyb.delay(1)
Use it something like this::
import pyb
pin_x1 = pyb.Pin('X1', pyb.Pin.IN, pyb.Pin.PULL_DOWN)
while True:
wait_pin_change(pin_x1)
pyb.LED(4).toggle()

89
docs/pyboard/tutorial/fading_led.rst
View File

@ -1,89 +0,0 @@
Fading LEDs
===========
In addition to turning LEDs on and off, it is also possible to control the brightness of an LED using `Pulse-Width Modulation (PWM) <http://en.wikipedia.org/wiki/Pulse-width_modulation>`_, a common technique for obtaining variable output from a digital pin. This allows us to fade an LED:
.. image:: http://upload.wikimedia.org/wikipedia/commons/a/a9/Fade.gif
Components
----------
You will need:
- Standard 5 or 3 mm LED
- 100 Ohm resistor
- Wires
- `Breadboard <http://en.wikipedia.org/wiki/Breadboard>`_ (optional, but makes things easier)
Connecting Things Up
--------------------
For this tutorial, we will use the ``X1`` pin. Connect one end of the resistor to ``X1``, and the other end to the **anode** of the LED, which is the longer leg. Connect the **cathode** of the LED to ground.
.. image:: img/fading_leds_breadboard_fritzing.png
Code
----
By examining the :ref:`quickref`, we see that ``X1`` is connected to channel 1 of timer 5 (``TIM5 CH1``). Therefore we will first create a ``Timer`` object for timer 5, then create a ``TimerChannel`` object for channel 1::
from pyb import Timer
from time import sleep
# timer 5 will be created with a frequency of 100 Hz
tim = pyb.Timer(5, freq=100)
tchannel = tim.channel(1, Timer.PWM, pin=pyb.Pin.board.X1, pulse_width=0)
Brightness of the LED in PWM is controlled by controlling the pulse-width, that is the amount of time the LED is on every cycle. With a timer frequency of 100 Hz, each cycle takes 0.01 second, or 10 ms.
To achieve the fading effect shown at the beginning of this tutorial, we want to set the pulse-width to a small value, then slowly increase the pulse-width to brighten the LED, and start over when we reach some maximum brightness::
# maximum and minimum pulse-width, which corresponds to maximum
# and minimum brightness
max_width = 200000
min_width = 20000
# how much to change the pulse-width by each step
wstep = 1500
cur_width = min_width
while True:
tchannel.pulse_width(cur_width)
# this determines how often we change the pulse-width. It is
# analogous to frames-per-second
sleep(0.01)
cur_width += wstep
if cur_width > max_width:
cur_width = min_width
Breathing Effect
----------------
If we want to have a breathing effect, where the LED fades from dim to bright then bright to dim, then we simply need to reverse the sign of ``wstep`` when we reach maximum brightness, and reverse it again at minimum brightness. To do this we modify the ``while`` loop to be::
while True:
tchannel.pulse_width(cur_width)
sleep(0.01)
cur_width += wstep
if cur_width > max_width:
cur_width = max_width
wstep *= -1
elif cur_width < min_width:
cur_width = min_width
wstep *= -1
Advanced Exercise
-----------------
You may have noticed that the LED brightness seems to fade slowly, but increases quickly. This is because our eyes interprets brightness logarithmically (`Weber's Law <http://www.telescope-optics.net/eye_intensity_response.htm>`_
), while the LED's brightness changes linearly, that is by the same amount each time. How do you solve this problem? (Hint: what is the opposite of the logarithmic function?)
Addendum
--------
We could have also used the digital-to-analog converter (DAC) to achieve the same effect. The PWM method has the advantage that it drives the LED with the same current each time, but for different lengths of time. This allows better control over the brightness, because LEDs do not necessarily exhibit a linear relationship between the driving current and brightness.

BIN
docs/pyboard/tutorial/img/fading_leds_breadboard_fritzing.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 60 KiB

BIN
docs/pyboard/tutorial/img/pyboard_servo.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 69 KiB

BIN
docs/pyboard/tutorial/img/pyboard_usb_micro.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 85 KiB

BIN
docs/pyboard/tutorial/img/skin_amp_1.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 82 KiB

BIN
docs/pyboard/tutorial/img/skin_amp_2.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 73 KiB

Some files were not shown because too many files have changed in this diff Show More