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 +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
|
||||
|
||||
[](https://travis-ci.org/adafruit/circuitpython)
|
||||
[](http://circuitpython.readthedocs.io/)
|
||||
[](https://gitter.im/adafruit/circuitpython?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
[](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
|
||||
@ -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
|
||||
|
||||
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.
|
||||
@ -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.
|
||||
@ -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
|
||||
@ -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
|
||||