Rework the READMEs to clarify that this is a MicroPython derivative and
not MicroPython proper.
This commit is contained in:
Scott Shawcroft
parent
0584ba1218
commit
005b4505f5
198
README.md
198
README.md
@ -1,152 +1,64 @@
|
|||||||
[![Build Status][travis-img]][travis-repo] [![Coverage Status][coveralls-img]][coveralls-repo]
|
# Adafruit MicroPython
|
||||||
[travis-img]: https://travis-ci.org/micropython/micropython.png?branch=master
|
|
||||||
[travis-repo]: https://travis-ci.org/micropython/micropython
|
|
||||||
[coveralls-img]: https://coveralls.io/repos/micropython/micropython/badge.png?branch=master
|
|
||||||
[coveralls-repo]: https://coveralls.io/r/micropython/micropython?branch=master
|
|
||||||
|
|
||||||
The MicroPython project
|
This is an open source derivative of [MicroPython](http://www.micropython.org)
|
||||||
=======================
|
for use on educational development boards designed and sold by Adafruit
|
||||||
<p align="center">
|
including the [Arduino Zero](https://www.arduino.cc/en/Main/ArduinoBoardZero), [Adafruit Feather M0 Basic](https://www.adafruit.com/products/2772), [Adafruit Feather HUZZAH](https://www.adafruit.com/products/2821) and
|
||||||
<img src="https://raw.githubusercontent.com/micropython/micropython/master/logo/upython-with-micro.jpg" alt="MicroPython Logo"/>
|
[Adafruit Feather M0 Bluefruit LE](https://www.adafruit.com/products/2995).
|
||||||
</p>
|
|
||||||
|
|
||||||
This is the MicroPython project, which aims to put an implementation
|
As a MicroPython derivative, this implements Python 3.x on microcontrollers such
|
||||||
of Python 3.x on microcontrollers and small embedded systems.
|
as the SAMD21 and ESP8266.
|
||||||
You can find the official website at [micropython.org](http://www.micropython.org).
|
|
||||||
|
|
||||||
WARNING: this project is in beta stage and is subject to changes of the
|
## Project Status
|
||||||
code-base, including project-wide name changes and API changes.
|
This project is in beta and the APIs will change in the near future.
|
||||||
|
|
||||||
MicroPython implements the entire Python 3.4 syntax (including exceptions,
|
## Documentation
|
||||||
"with", "yield from", etc., and additionally "async" keyword from Python 3.5).
|
|
||||||
The following core datatypes are provided: str (including basic Unicode
|
|
||||||
support), bytes, bytearray, tuple, list, dict, set, frozenset, array.array,
|
|
||||||
collections.namedtuple, classes and instances. Builtin modules include sys,
|
|
||||||
time, and struct. Note that only subset of Python 3.4 functionality
|
|
||||||
implemented for the data types and modules.
|
|
||||||
|
|
||||||
See the repository www.github.com/micropython/pyboard for the Micro
|
Guides and videos are available through the [Adafruit Learning System](https://learn.adafruit.com/) under the [MicroPython category](https://learn.adafruit.com/category/micropython). An API reference is also available on [Read the Docs](http://adafruit-micropython.readthedocs.io/en/latest/?).
|
||||||
Python board, the officially supported reference electronic circuit board.
|
|
||||||
|
|
||||||
Major components in this repository:
|
## Contributing
|
||||||
- py/ -- the core Python implementation, including compiler, runtime, and
|
See [CONTRIBUTING.md](https://github.com/adafruit/micropython/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/micropython/blob/master/CODE_OF_CONDUCT.md).
|
||||||
|
Contributors who follow the
|
||||||
|
[Code of Conduct](https://github.com/adafruit/micropython/blob/master/CODE_OF_CONDUCT.md)
|
||||||
|
are welcome to submit pull requests and they will be promptly reviewed by
|
||||||
|
project admins.
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
Here is an overview of the top-level directories.
|
||||||
|
|
||||||
|
### Core
|
||||||
|
The core of MicroPython is code shared amongst ports.
|
||||||
|
- `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.
|
core library.
|
||||||
- unix/ -- a version of MicroPython that runs on Unix.
|
- `shared-bindings` Shared definition of Python modules, their docs and backing C APIs. Ports must implement the C API to support the corresponding module.
|
||||||
- stmhal/ -- a version of MicroPython that runs on the MicroPython board
|
- `tests` Test framework and test scripts.
|
||||||
with an STM32F405RG (using ST's Cube HAL drivers).
|
- `tools` Various tools, including the pyboard.py module.
|
||||||
- minimal/ -- a minimal MicroPython port. Start with this if you want
|
|
||||||
|
### 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.
|
to port MicroPython to another microcontroller.
|
||||||
- tests/ -- test framework and test scripts.
|
- `pic16bit` Support for 16-bit PIC microcontrollers.
|
||||||
- docs/ -- user documentation in Sphinx reStructuredText format.
|
- `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.
|
||||||
|
|
||||||
Additional components:
|
This derivative 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.
|
||||||
- bare-arm/ -- a bare minimum version of MicroPython for ARM MCUs. Used
|
|
||||||
mostly to control code size.
|
|
||||||
- teensy/ -- a version of MicroPython that runs on the Teensy 3.1
|
|
||||||
(preliminary but functional).
|
|
||||||
- pic16bit/ -- a version of MicroPython for 16-bit PIC microcontrollers.
|
|
||||||
- cc3200/ -- a version of MicroPython that runs on the CC3200 from TI.
|
|
||||||
- esp8266/ -- an experimental port for ESP8266 WiFi modules.
|
|
||||||
- tools/ -- various tools, including the pyboard.py module.
|
|
||||||
- examples/ -- a few example Python scripts.
|
|
||||||
|
|
||||||
The subdirectories above may include READMEs with additional info.
|
|
||||||
|
|
||||||
"make" is used to build the components, or "gmake" on BSD-based systems.
|
|
||||||
You will also need bash and Python (at least 2.7 or 3.3).
|
|
||||||
|
|
||||||
The Unix version
|
|
||||||
----------------
|
|
||||||
|
|
||||||
The "unix" port requires a standard Unix environment with gcc and GNU make.
|
|
||||||
x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
|
|
||||||
as ARM and MIPS. Making full-featured port to another architecture requires
|
|
||||||
writing some assembly code for the exception handling and garbage collection.
|
|
||||||
Alternatively, fallback implementation based on setjmp/longjmp can be used.
|
|
||||||
|
|
||||||
To build (see section below for required dependencies):
|
|
||||||
|
|
||||||
$ cd unix
|
|
||||||
$ make axtls
|
|
||||||
$ make
|
|
||||||
|
|
||||||
Then to give it a try:
|
|
||||||
|
|
||||||
$ ./micropython
|
|
||||||
>>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
|
|
||||||
|
|
||||||
Use `CTRL-D` (i.e. EOF) to exit the shell.
|
|
||||||
Learn about command-line options (in particular, how to increase heap size
|
|
||||||
which may be needed for larger applications):
|
|
||||||
|
|
||||||
$ ./micropython --help
|
|
||||||
|
|
||||||
Run complete testsuite:
|
|
||||||
|
|
||||||
$ make test
|
|
||||||
|
|
||||||
Unix version comes with a builtin package manager called upip, e.g.:
|
|
||||||
|
|
||||||
$ ./micropython -m upip install micropython-pystone
|
|
||||||
$ ./micropython -m pystone
|
|
||||||
|
|
||||||
Browse available modules on
|
|
||||||
[PyPI](https://pypi.python.org/pypi?%3Aaction=search&term=micropython).
|
|
||||||
Standard library modules come from
|
|
||||||
[micropython-lib](https://github.com/micropython/micropython-lib) project.
|
|
||||||
|
|
||||||
External dependencies
|
|
||||||
---------------------
|
|
||||||
|
|
||||||
Building Unix version requires some dependencies installed. For
|
|
||||||
Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`
|
|
||||||
(includes toolchain and make), `libffi-dev`, and `pkg-config` packages.
|
|
||||||
|
|
||||||
Other dependencies can be built together with MicroPython. Oftentimes,
|
|
||||||
you need to do this to enable extra features or capabilities. To build
|
|
||||||
these additional dependencies, first fetch git submodules for them:
|
|
||||||
|
|
||||||
$ git submodule update --init
|
|
||||||
|
|
||||||
Use this same command to get the latest versions of dependencies, as
|
|
||||||
they are updated from time to time. After that, in `unix/` dir, execute:
|
|
||||||
|
|
||||||
$ make deplibs
|
|
||||||
|
|
||||||
This will build all available dependencies (regardless whether they
|
|
||||||
are used or not). If you intend to build MicroPython with additional
|
|
||||||
options (like cross-compiling), the same set of options should be passed
|
|
||||||
to `make deplibs`. To actually enabled use of dependencies, edit
|
|
||||||
`unix/mpconfigport.mk` file, which has inline descriptions of the options.
|
|
||||||
For example, to build SSL module (required for `upip` tool described above),
|
|
||||||
set `MICROPY_PY_USSL` to 1.
|
|
||||||
|
|
||||||
In `unix/mpconfigport.mk`, you can also disable some dependencies enabled
|
|
||||||
by default, like FFI support, which requires libffi development files to
|
|
||||||
be installed.
|
|
||||||
|
|
||||||
The STM version
|
|
||||||
---------------
|
|
||||||
|
|
||||||
The "stmhal" port requires an ARM compiler, arm-none-eabi-gcc, and associated
|
|
||||||
bin-utils. For those using Arch Linux, you need arm-none-eabi-binutils and
|
|
||||||
arm-none-eabi-gcc packages. Otherwise, try here:
|
|
||||||
https://launchpad.net/gcc-arm-embedded
|
|
||||||
|
|
||||||
To build:
|
|
||||||
|
|
||||||
$ cd stmhal
|
|
||||||
$ make
|
|
||||||
|
|
||||||
You then need to get your board into DFU mode. On the pyboard, connect the
|
|
||||||
3V3 pin to the P1/DFU pin with a wire (on PYBv1.0 they are next to each other
|
|
||||||
on the bottom left of the board, second row from the bottom).
|
|
||||||
|
|
||||||
Then to flash the code via USB DFU to your device:
|
|
||||||
|
|
||||||
$ make deploy
|
|
||||||
|
|
||||||
This will use the included `tools/pydfu.py` script. If flashing the firmware
|
|
||||||
does not work it may be because you don't have the correct permissions, and
|
|
||||||
need to use `sudo make deploy`.
|
|
||||||
See the README.md file in the stmhal/ directory for further details.
|
|
||||||
|
|||||||
@ -1,21 +1,17 @@
|
|||||||
# SAMD21x18
|
# SAMD21x18
|
||||||
|
|
||||||
This port is intended to be a full featured MicroPython port for SAMD21x18 based
|
This port brings MicroPython to SAMD21x18 based development boards including the
|
||||||
development boards including the Arduino Zero, Adafruit Feather M0 and Adafruit
|
Arduino Zero, Adafruit Feather M0 and Adafruit M0 BLE.
|
||||||
M0 BLE.
|
|
||||||
|
|
||||||
## Building
|
## Building
|
||||||
|
|
||||||
The Makefile has the ability to build for a SAMD21x18, and by default
|
To build for the Arduino Zero:
|
||||||
includes some start-up code and also enables a UART for communication. To
|
|
||||||
build:
|
|
||||||
|
|
||||||
make CROSS=1
|
make
|
||||||
|
|
||||||
It will build for the Arduino Zero by default. You may change it by setting
|
To build for other boards you must change it by setting `BOARD`. For example:
|
||||||
`BOARD`. For example:
|
|
||||||
|
|
||||||
make CROSS=1 BOARD=feather_m0_ble
|
make BOARD=feather_m0_ble
|
||||||
|
|
||||||
Board names are the directory names in the `boards` folder.
|
Board names are the directory names in the `boards` folder.
|
||||||
|
|
||||||
@ -50,6 +46,9 @@ In another terminal from `micropython/atmel-samd`:
|
|||||||
(gdb) continue
|
(gdb) continue
|
||||||
|
|
||||||
## Connecting
|
## Connecting
|
||||||
|
|
||||||
|
### Serial
|
||||||
|
|
||||||
All boards are currently configured to work over USB rather than UART. To
|
All boards are currently configured to work over USB rather than UART. To
|
||||||
connect to it from OSX do something like this:
|
connect to it from OSX do something like this:
|
||||||
|
|
||||||
@ -57,3 +56,8 @@ connect to it from OSX do something like this:
|
|||||||
|
|
||||||
You may not see a prompt immediately because it doesn't know you connected. To
|
You may not see a prompt immediately because it doesn't know you connected. To
|
||||||
get one either hit enter to get `>>>` or do CTRL-B to get the full header.
|
get one either hit enter to get `>>>` or do CTRL-B to get the full header.
|
||||||
|
|
||||||
|
### Mass storage
|
||||||
|
|
||||||
|
All boards will also show up as a mass storage device. Make sure to eject it
|
||||||
|
before referring to any files.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user