Delete a bunch of docs, drivers and examples not relevant to CircuitPython.

This fixes #345 and fixes #215.
crypto-aes
Scott Shawcroft 5 years ago
parent ee90056866
commit 20dd3b1e43
  1. 210
      CODECONVENTIONS.md
  2. 213
      README.md
  3. 253
      README.rst
  4. 68
      atmel-samd/README.rst
  5. 19
      conf.py
  6. 9
      docs/design_guide.rst
  7. 10
      docs/differences/index_template.txt
  8. 147
      docs/esp8266/general.rst
  9. BIN
      docs/esp8266/img/adafruit_products_pinoutstop.jpg
  10. 8
      docs/esp8266/index.rst
  11. 364
      docs/esp8266/quickref.rst
  12. 19
      docs/esp8266/tutorial/adc.rst
  13. 65
      docs/esp8266/tutorial/dht.rst
  14. 69
      docs/esp8266/tutorial/filesystem.rst
  15. 33
      docs/esp8266/tutorial/index.rst
  16. 202
      docs/esp8266/tutorial/intro.rst
  17. 70
      docs/esp8266/tutorial/neopixel.rst
  18. 81
      docs/esp8266/tutorial/network_basics.rst
  19. 122
      docs/esp8266/tutorial/network_tcp.rst
  20. 12
      docs/esp8266/tutorial/nextsteps.rst
  21. 37
      docs/esp8266/tutorial/onewire.rst
  22. 75
      docs/esp8266/tutorial/pins.rst
  23. 61
      docs/esp8266/tutorial/powerctrl.rst
  24. 87
      docs/esp8266/tutorial/pwm.rst
  25. 212
      docs/esp8266/tutorial/repl.rst
  26. 12
      docs/esp8266_index.rst
  27. 53
      docs/index.rst
  28. 4
      docs/library/array.rst
  29. 4
      docs/library/btree.rst
  30. 14
      docs/library/builtins.rst
  31. 63
      docs/library/cmath.rst
  32. 2
      docs/library/esp.rst
  33. 2
      docs/library/framebuf.rst
  34. 4
      docs/library/gc.rst
  35. 216
      docs/library/index.rst
  36. 394
      docs/library/lcd160cr.rst
  37. 74
      docs/library/machine.ADC.rst
  38. 172
      docs/library/machine.I2C.rst
  39. 248
      docs/library/machine.Pin.rst
  40. 69
      docs/library/machine.RTC.rst
  41. 42
      docs/library/machine.SD.rst
  42. 97
      docs/library/machine.SPI.rst
  43. 96
      docs/library/machine.Signal.rst
  44. 160
      docs/library/machine.Timer.rst
  45. 142
      docs/library/machine.UART.rst
  46. 36
      docs/library/machine.WDT.rst
  47. 170
      docs/library/machine.rst
  48. 4
      docs/library/math.rst
  49. 2
      docs/library/micropython.rst
  50. 504
      docs/library/network.rst
  51. 143
      docs/library/pyb.ADC.rst
  52. 56
      docs/library/pyb.Accel.rst
  53. 222
      docs/library/pyb.CAN.rst
  54. 109
      docs/library/pyb.DAC.rst
  55. 114
      docs/library/pyb.ExtInt.rst
  56. 175
      docs/library/pyb.I2C.rst
  57. 96
      docs/library/pyb.LCD.rst
  58. 46
      docs/library/pyb.LED.rst
  59. 280
      docs/library/pyb.Pin.rst
  60. 83
      docs/library/pyb.RTC.rst
  61. 132
      docs/library/pyb.SPI.rst
  62. 80
      docs/library/pyb.Servo.rst
  63. 45
      docs/library/pyb.Switch.rst
  64. 286
      docs/library/pyb.Timer.rst
  65. 245
      docs/library/pyb.UART.rst
  66. 39
      docs/library/pyb.USB_HID.rst
  67. 102
      docs/library/pyb.USB_VCP.rst
  68. 321
      docs/library/pyb.rst
  69. 7
      docs/library/sys.rst
  70. 4
      docs/library/ubinascii.rst
  71. 4
      docs/library/ucollections.rst
  72. 4
      docs/library/uctypes.rst
  73. 12
      docs/library/uerrno.rst
  74. 4
      docs/library/uhashlib.rst
  75. 4
      docs/library/uheapq.rst
  76. 6
      docs/library/uio.rst
  77. 4
      docs/library/ujson.rst
  78. 96
      docs/library/uos.rst
  79. 4
      docs/library/ure.rst
  80. 4
      docs/library/uselect.rst
  81. 21
      docs/library/usocket.rst
  82. 8
      docs/library/ussl.rst
  83. 4
      docs/library/ustruct.rst
  84. 229
      docs/library/utime.rst
  85. 4
      docs/library/uzlib.rst
  86. 17
      docs/library/wipy.rst
  87. 80
      docs/pyboard/general.rst
  88. 30
      docs/pyboard/hardware/index.rst
  89. 9
      docs/pyboard/index.rst
  90. 169
      docs/pyboard/quickref.rst
  91. 92
      docs/pyboard/tutorial/accel.rst
  92. 98
      docs/pyboard/tutorial/amp_skin.rst
  93. 131
      docs/pyboard/tutorial/assembler.rst
  94. 37
      docs/pyboard/tutorial/debounce.rst
  95. 89
      docs/pyboard/tutorial/fading_led.rst
  96. BIN
      docs/pyboard/tutorial/img/fading_leds_breadboard_fritzing.png
  97. BIN
      docs/pyboard/tutorial/img/pyboard_servo.jpg
  98. BIN
      docs/pyboard/tutorial/img/pyboard_usb_micro.jpg
  99. BIN
      docs/pyboard/tutorial/img/skin_amp_1.jpg
  100. BIN
      docs/pyboard/tutorial/img/skin_amp_2.jpg
  101. Some files were not shown because too many files have changed in this diff Show More

@ -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

@ -1,213 +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][]
### 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`.
* `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][],
[Adafruit Feather M0 Basic][], and [Adafruit Feather M0 Bluefruit LE][].
* `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][].
* `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][] 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 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

@ -0,0 +1,253 @@
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>`__
(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 <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

@ -15,39 +15,39 @@ different names. The table below matches the pin order in
and omits the pins only available on the largest package because all supported
boards use smaller version.
===================== =============== =========================== ==================== ================ ================== ========================= ================ ================
===================== =============== =========================== ====================== ================ ================== ========================= ================ ================
`microcontroller.pin` `board`
--------------------- -----------------------------------------------------------------------------------------------------------------------------------------------------------------------
Datasheet arduino_zero circuitplayground_express feather_m0_adalogger feather_m0_basic feather_m0_express gemma_m0 metro_m0_express trinket_m0
===================== =============== =========================== ==================== ================ ================== ========================= ================ ================
PA00 ``ACCELEROMETER_SDA`` ``APA102_MOSI`` ``APA102_MOSI``
PA01 ``ACCELEROMETER_SCL`` ``APA102_SCK`` ``APA102_SCK``
PA02 ``A0`` ``A0`` / ``SPEAKER`` ``A0`` ``A0`` ``A0`` ``A0`` / ``D1`` ``A0`` ``D1`` / ``A0``
--------------------- -------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Datasheet arduino_zero circuitplayground_express feather_m0_adalogger feather_m0_basic feather_m0_express gemma_m0 metro_m0_express trinket_m0
===================== =============== =========================== ====================== ================ ================== ========================= ================ ================
PA00 ``ACCELEROMETER_SDA`` ``APA102_MOSI`` ``APA102_MOSI``
PA01 ``ACCELEROMETER_SCL`` ``APA102_SCK`` ``APA102_SCK``
PA02 ``A0`` ``A0`` / ``SPEAKER`` ``A0`` ``A0`` ``A0`` ``A0`` / ``D1`` ``A0`` ``D1`` / ``A0``
PA03
PB08 ``A1`` ``A7`` / ``TX`` ``A1`` ``A1`` ``A1`` ``A1``
PB09 ``A2`` ``A6`` / ``RX`` ``A2`` ``A2`` ``A2`` ``A2``
PA04 ``A3`` ``IR_PROXIMITY`` ``A3`` ``A3`` ``A3`` ``D0`` / ``TX`` / ``SDA`` ``A3``
PA05 ``A4`` ``A1`` ``A4`` ``A4`` ``A4`` ``D2`` / ``RX`` / ``SCL`` ``A4``
PA06 ``D8`` ``A2`` ``D8`` / ``GREEN_LED`` ``NEOPIXEL`` ``D8`` ``D4`` / ``TX``
PA07 ``D9`` ``A3`` ``D9`` ``D9`` ``D9`` ``D9`` ``D3`` / ``RX``
PA08 ``D4`` ``MICROPHONE_DO`` ``D4`` / ``SD_CS`` ``D4`` ``D0`` / ``SDA``
PA09 ``D3`` ``TEMPERATURE`` / ``A9`` ``D3`` ``D2`` / ``SCL``
PA10 ``D1`` / ``TX`` ``MICROPHONE_SCK`` ``D1`` / ``TX`` ``D1`` / ``TX`` ``D1`` / ``TX`` ``D1`` / ``TX`` ``D13``
PA11 ``D0`` / ``RX`` ``LIGHT`` / ``A8`` ``D0`` / ``RX`` ``D0`` / ``RX`` ``D0`` / ``RX`` ``D0`` / ``RX``
PB10 ``MOSI`` ``MOSI`` ``MOSI`` ``MOSI`` ``MOSI``
PB11 ``SCK`` ``SCK`` ``SCK`` ``SCK`` ``SCK``
PA12 ``MISO`` ``REMOTEIN`` / ``IR_RX`` ``MISO`` ``MISO`` ``MISO`` ``MISO``
PA13 ``ACCELEROMETER_INTERRUPT`` ``FLASH_CS``
PA14 ``D2`` ``BUTTON_B`` / ``D5`` ``D2``
PA15 ``D5`` ``SLIDE_SWITCH`` / ``D7`` ``D5`` ``D5`` ``D5`` ``D5``
PA16 ``D11`` ``MISO`` ``D11`` ``D11`` ``D11`` ``D11``
PA17 ``D13`` ``D13`` ``D13`` / ``RED_LED`` ``D13`` ``D13`` ``D13``
PA18 ``D10`` ``D10`` ``D10`` ``D10`` ``D10``
PA19 ``D12`` ``D12`` ``D12`` ``D12`` ``D12``
PA20 ``D6`` ``MOSI`` ``D6`` ``D6`` ``D6`` ``D6``
PA21 ``D7`` ``SCK`` ``D7`` / ``SD_CD`` ``D7``
PA22 ``SDA`` ``SDA`` ``SDA`` ``SDA`` ``SDA``
PA23 ``SCL`` ``REMOTEOUT`` / ``IR_TX`` ``SCL`` ``SCL`` ``SCL`` ``L`` / ``D13`` ``SCL``
PB08 ``A1`` ``A7`` / ``TX`` ``A1`` ``A1`` ``A1`` ``A1``
PB09 ``A2`` ``A6`` / ``RX`` ``A2`` ``A2`` ``A2`` ``A2``
PA04 ``A3`` ``IR_PROXIMITY`` ``A3`` ``A3`` ``A3`` ``D0`` / ``TX`` / ``SDA`` ``A3``
PA05 ``A4`` ``A1`` ``A4`` ``A4`` ``A4`` ``D2`` / ``RX`` / ``SCL`` ``A4``
PA06 ``D8`` ``A2`` ``D8`` / ``GREEN_LED`` ``NEOPIXEL`` ``D8`` ``D4`` / ``TX``
PA07 ``D9`` ``A3`` ``D9`` ``D9`` ``D9`` ``D9`` ``D3`` / ``RX``
PA08 ``D4`` ``MICROPHONE_DO`` ``D4`` / ``SD_CS`` ``D4`` ``D0`` / ``SDA``
PA09 ``D3`` ``TEMPERATURE`` / ``A9`` ``D3`` ``D2`` / ``SCL``
PA10 ``D1`` / ``TX`` ``MICROPHONE_SCK`` ``D1`` / ``TX`` ``D1`` / ``TX`` ``D1`` / ``TX`` ``D1`` / ``TX`` ``D13``
PA11 ``D0`` / ``RX`` ``LIGHT`` / ``A8`` ``D0`` / ``RX`` ``D0`` / ``RX`` ``D0`` / ``RX`` ``D0`` / ``RX``
PB10 ``MOSI`` ``MOSI`` ``MOSI`` ``MOSI`` ``MOSI``
PB11 ``SCK`` ``SCK`` ``SCK`` ``SCK`` ``SCK``
PA12 ``MISO`` ``REMOTEIN`` / ``IR_RX`` ``MISO`` ``MISO`` ``MISO`` ``MISO``
PA13 ``ACCELEROMETER_INTERRUPT`` ``FLASH_CS``
PA14 ``D2`` ``BUTTON_B`` / ``D5`` ``D2``
PA15 ``D5`` ``SLIDE_SWITCH`` / ``D7`` ``D5`` ``D5`` ``D5`` ``D5``
PA16 ``D11`` ``MISO`` ``D11`` ``D11`` ``D11`` ``D11``
PA17 ``D13`` ``D13`` ``D13`` / ``RED_LED`` ``D13`` ``D13`` ``D13``
PA18 ``D10`` ``D10`` ``D10`` ``D10`` ``D10``
PA19 ``D12`` ``D12`` ``D12`` ``D12`` ``D12``
PA20 ``D6`` ``MOSI`` ``D6`` ``D6`` ``D6`` ``D6``
PA21 ``D7`` ``SCK`` ``D7`` / ``SD_CD`` ``D7``
PA22 ``SDA`` ``SDA`` ``SDA`` ``SDA`` ``SDA``
PA23 ``SCL`` ``REMOTEOUT`` / ``IR_TX`` ``SCL`` ``SCL`` ``SCL`` ``L`` / ``D13`` ``SCL``
PA24
PA25
PB22 ``FLASH_CS``
@ -55,11 +55,11 @@ PB23 ``NEOPIXEL`` / ``D8``
PA27
PA28 ``BUTTON_A`` / ``D4``
PA29
PA30 ``SPEAKER_ENABLE`` ``NEOPIXEL``
PA30 ``SPEAKER_ENABLE`` ``NEOPIXEL``
PA31
PB02 ``A5`` ``A5`` / ``SDA`` ``A5`` ``A5`` ``A5`` ``A5``
PB02 ``A5`` ``A5`` / ``SDA`` ``A5`` ``A5`` ``A5`` ``A5``
PB03 ``A4`` / ``SCL``
===================== =============== =========================== ==================== ================ ================== ========================= ================ ================
===================== =============== =========================== ====================== ================ ================== ========================= ================ ================
Here is a table about which pins can do what in CircuitPython terms. However,
just because something is listed, doesn't mean it will always work. Existing use

@ -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 ------------------------------------------------
@ -60,7 +58,7 @@ source_parsers = {'.md': CommonMarkParser,
# General information about the project.
project = 'Adafruit CircuitPython'
copyright = '2014-2017, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)'
copyright = '2014-2018, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)'
# These are overwritten on ReadTheDocs.
# The version info for the project you're documenting, acts as replacement for
@ -83,21 +81,27 @@ 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",
"atmel-samd/asf",
"atmel-samd/asf_conf",
"atmel-samd/common-hal",
"atmel-samd/boards",
"atmel-samd/QTouch",
"atmel-samd/freetouch",
"atmel-samd/*.c",
"atmel-samd/*.h",
"bare-arm",
"cc3200",
"cc3200/FreeRTOS",
"cc3200/hal",
"docs/README.md",
"drivers",
"esp8266",
"esp8266/boards",
"esp8266/common-hal",
"esp8266/modules",
"esp8266/*.c",
"esp8266/*.h",
"examples",
"extmod",
"frozen",
@ -107,6 +111,7 @@ exclude_patterns = ["*/build-*",
"pic16bit",
"py",
"qemu-arm",
"shared-bindings/util.*",
"shared-module",
"stmhal",
"stmhal/hal",
@ -148,7 +153,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 ----------------------------------------------

@ -305,10 +305,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
--------------------------------------------------------------------------------

@ -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

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

Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

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

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

@ -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.

@ -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