8000 Rework the READMEs to clarify that this is a MicroPython derivative and · cpforbes/circuitpython@005b450 · GitHub
[go: up one dir, main page]
Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 005b450

Browse files
tannewttannewt
committed
Rework the READMEs to clarify that this is a MicroPython derivative and
not MicroPython proper.
1 parent 0584ba1 commit 005b450

File tree

2 files changed

+76
-160
lines changed

2 files changed

+76
-160
lines changed

‎README.md

Lines changed: 62 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,64 @@
1-
[![Build Status][travis-img]][travis-repo] [![Coverage Status][coveralls-img]][coveralls-repo]
2-
[travis-img]: https://travis-ci.org/micropython/micropython.png?branch=master
3-
[travis-repo]: https://travis-ci.org/micropython/micropython
4-
[coveralls-img]: https://coveralls.io/repos/micropython/micropython/badge.png?branch=master
5-
[coveralls-repo]: https://coveralls.io/r/micropython/micropython?branch=master
6-
7-
The MicroPython project
8-
=======================
9-
<p align="center">
10-
<img src="https://raw.githubusercontent.com/micropython/micropython/master/logo/upython-with-micro.jpg" alt="MicroPython Logo"/>
11-
</p>
12-
13-
This is the MicroPython project, which aims to put an implementation
14-
of Python 3.x on microcontrollers and small embedded systems.
15-
You can find the official website at [micropython.org](http://www.micropython.org).
16-
17-
WARNING: this project is in beta stage and is subject to changes of the
18-
code-base, including project-wide name changes and API changes.
19-
20-
MicroPython implements the entire Python 3.4 syntax (including exceptions,
21-
"with", "yield from", etc., and additionally "async" keyword from Python 3.5).
22-
The following core datatypes are provided: str (including basic Unicode
23-
support), bytes, bytearray, tuple, list, dict, set, frozenset, array.array,
24-
collections.namedtuple, classes and instances. Builtin modules include sys,
25-
time, and struct. Note that only subset of Python 3.4 functionality
26-
implemented for the data types and modules.
27-
28-
See the repository www.github.com/micropython/pyboard for the Micro
29-
Python board, the officially supported reference electronic circuit board.
30-
31-
Major components in this repository:
32-
- py/ -- the core Python implementation, including compiler, runtime, and
1+
# Adafruit MicroPython
2+
3+
This is an open source derivative of [MicroPython](http://www.micropython.org)
4+
for use on educational development boards designed and sold by Adafruit
5+
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
6+
[Adafruit Feather M0 Bluefruit LE](https://www.adafruit.com/products/2995).
7+
8+
As a MicroPython derivative, this implements Python 3.x on microcontrollers such
9+
as the SAMD21 and ESP8266.
10+
11+
## Project Status
12+
This project is in beta and the APIs will change in the near future.
13+
14+
## Documentation
15+
16+
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/?).
17+
18+
## Contributing
19+
See [CONTRIBUTING.md](https://github.com/adafruit/micropython/blob/master/CONTRIBUTING.md)
20+
for full guidelines but please be aware that by contributing to this project you
21+
are agreeing to the
22+
[Code of Conduct](https://github.com/adafruit/micropython/blob/master/CODE_OF_CONDUCT.md).
23+
Contributors who follow the
24+
[Code of Conduct](https://github.com/adafruit/micropython/blob/master/CODE_OF_CONDUCT.md)
25+
are welcome to submit pull requests and they will be promptly reviewed by
26+
project admins.
27+
28+
## Project Structure
29+
Here is an overview of the top-level directories.
30+
31+
### Core
32+
The core of MicroPython is code shared amongst ports.
33+
- `docs` High level user documentation in Sphinx reStructuredText format.
34+
- `drivers` External device drivers written in Python.
35+
- `examples` A few example Python scripts.
36+
- `extmod` Shared C code used in multiple ports' modules.
37+
- `lib` Shared core C code including externally developed libraries such as FATFS.
38+
- `logo` The MicroPython logo.
39+
- `mpy-cross` A cross compiler that converts Python files to byte code prior to being run in MicroPython. Useful for reducing library size.
40+
- `py` Core Python implementation, including compiler, runtime, and
3341
core library.
34-
- unix/ -- a version of MicroPython that runs on Unix.
35-
- stmhal/ -- a version of MicroPython that runs on the MicroPython board
36-
with an STM32F405RG (using ST's Cube HAL drivers).
37-
- minimal/ -- a minimal MicroPython port. Start with this if you want
42+
- `shared-bindings` Shared definition of Python modules, their docs and backing C APIs. Ports must implement the C API to support the corresponding module.
43+
- `tests` Test framework and test scripts.
44+
- `tools` Various tools, including the pyboard.py module.
45+
46+
### Ports
47+
Ports include the code unique to a microcontroller line and also variations
48+
based on the board.
49+
- `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
50+
[Adafruit Feather M0 Bluefruit LE](https://www.adafruit.com/products/2995).
51+
- `bare-arm` A bare minimum version of MicroPython for ARM MCUs.
52+
- `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/).
53+
- `esp8266` Support for boards based on ESP8266 WiFi modules such as the [Adafruit Feather HUZZAH](https://www.adafruit.com/products/2821).
54+
- `minimal` A minimal MicroPython port. Start with this if you want
3855
to port MicroPython to another microcontroller.
39-
- tests/ -- test framework and test scripts.
40-
- docs/ -- user documentation in Sphinx reStructuredText format.
41-
42-
Additional components:
43-
- bare-arm/ -- a bare minimum version of MicroPython for ARM MCUs. Used
44-
mostly to control code size.
45-
- teensy/ -- a version of MicroPython that runs on the Teensy 3.1
46-
(preliminary but functional).
47-
- pic16bit/ -- a version of MicroPython for 16-bit PIC microcontrollers.
48-
- cc3200/ -- a version of MicroPython that runs on the CC3200 from TI.
49-
- esp8266/ -- an experimental port for ESP8266 WiFi modules.
50-
- tools/ -- various tools, including the pyboard.py module.
51-
- examples/ -- a few example Python scripts.
52-
53-
The subdirectories above may include READMEs with additional info.
54-
55-
"make" is used to build the components, or "gmake" on BSD-based systems.
56-
You will also need bash and Python (at least 2.7 or 3.3).
57-
58-
The Unix version
59-
----------------
60-
61-
The "unix" port requires a standard Unix environment with gcc and GNU make.
62-
x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
63-
as ARM and MIPS. Making full-featured port to another architecture requires
64-
writing some assembly code for the exception handling and garbage collection.
65-
Alternatively, fallback implementation based on setjmp/longjmp can be used.
66-
67-
To build (see section below for required dependencies):
68-
69-
$ cd unix
70-
$ make axtls
71-
$ make
72-
73-
Then to give it a try:
74-
75-
$ ./micropython
76-
>>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
77-
78-
Use `CTRL-D` (i.e. EOF) to exit the shell.
79-
Learn about command-line options (in particular, how to increase heap size
80-
which may be needed for larger applications):
81-
82-
$ ./micropython --help
83-
84-
Run complete testsuite:
85-
86-
$ make test
87-
88-
Unix version comes with a builtin package manager called upip, e.g.:
89-
90-
$ ./micropython -m upip install micropython-pystone
91-
$ ./micropython -m pystone
92-
93-
Browse available modules on
94-
[PyPI](https://pypi.python.org/pypi?%3Aaction=search&term=micropython).
95-
Standard library modules come from
96-
[micropython-lib](https://github.com/micropython/micropython-lib) project.
97-
98-
External dependencies
99-
---------------------
100-
101-
Building Unix version requires some dependencies installed. For
102-
Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`
103-
(includes toolchain and make), `libffi-dev`, and `pkg-config` packages.
104-
105-
Other dependencies can be built together with MicroPython. Oftentimes,
106-
you need to do this to enable extra features or capabilities. To build
107-
these additional dependencies, first fetch git submodules for them:
108-
109-
$ git submodule update --init
110-
111-
Use this same command to get the latest versions of dependencies, as
112-
they are updated from time to time. After that, in `unix/` dir, execute:
113-
114-
$ make deplibs
115-
116-
This will build all available dependencies (regardless whether they
117-
are used or not). If you intend to build MicroPython with additional
118-
options (like cross-compiling), the same set of options should be passed
119-
to `make deplibs`. To actually enabled use of dependencies, edit
120-
`unix/mpconfigport.mk` file, which has inline descriptions of the options.
121-
For example, to build SSL module (required for `upip` tool described above),
122-
set `MICROPY_PY_USSL` to 1.
123-
124-
In `unix/mpconfigport.mk`, you can also disable some dependencies enabled
125-
by default, like FFI support, which requires libffi development files to
126-
be installed.
127-
128-
The STM version
129-
---------------
130-
131-
The "stmhal" port requires an ARM compiler, arm-none-eabi-gcc, and associated
132-
bin-utils. For those using Arch Linux, you need arm-none-eabi-binutils and
133-
arm-none-eabi-gcc packages. Otherwise, try here:
134-
https://launchpad.net/gcc-arm-embedded
135-
136-
To build:
137-
138-
$ cd stmhal
139-
$ make
140-
141-
You then need to get your board into DFU mode. On the pyboard, connect the
142-
3V3 pin to the P1/DFU pin with a wire (on PYBv1.0 they are next to each other
143-
on the bottom left of the board, second row from the bottom).
144-
145-
Then to flash the code via USB DFU to your device:
146-
147-
$ make deploy
148-
149-
This will use the included `tools/pydfu.py` script. If flashing the firmware
150-
does not work it may be because you don't have the correct permissions, and
151-
need to use `sudo make deploy`.
152-
See the README.md file in the stmhal/ directory for further details.
56+
- `pic16bit` Support for 16-bit PIC microcontrollers.
57+
- `qemu-arm` Support for ARM emulation through [QEMU](https://qemu.org).
58+
- `stmhal` Support for boards based on STM32 microcontrollers including the MicroPython flagship [PyBoard](https://store.micropython.org/store/#/products/PYBv1_1).
59+
- `teensy` Support for the Teensy line of boards such as the [Teensy 3.1](https://www.pjrc.com/teensy/teensy31.html).
60+
- `unix` Support for UNIX.
61+
- `windows` Support for [Windows](https://www.microsoft.com/en-us/windows/).
62+
- `zephyr` Support for [Zephyr](https://www.zephyrproject.org/), a real-time operating system by the Linux Foundation.
63+
64+
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.

‎atmel-samd/README.md

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,17 @@
11
# SAMD21x18
22

3-
This port is intended to be a full featured MicroPython port for SAMD21x18 based
4-
development boards including the Arduino Zero, Adafruit Feather M0 and Adafruit
5-
M0 BLE.
3+
This port brings MicroPython to SAMD21x18 based development boards including the
4+
Arduino Zero, Adafruit Feather M0 and Adafruit M0 BLE.
65

76
## Building
87

9-
The Makefile has the ability to build for a SAMD21x18, and by default
10-
includes some start-up code and also enables a UART for communication. To
11-
build:
8+
To build for the Arduino Zero:
129

13-
make CROSS=1
10+
make
1411

15-
It will build for the Arduino Zero by default. You may change it by setting
16-
`BOARD`. For example:
12+
To build for other boards you must change it by setting `BOARD`. For example:
1713

18-
make CROSS=1 BOARD=feather_m0_ble
14+
make BOARD=feather_m0_ble
1915

2016
Board names are the directory names in the `boards` folder.
2117

@@ -50,10 +46,18 @@ In another terminal from `micropython/atmel-samd`:
5046
(gdb) continue
5147

5248
## Connecting
49+
50+
### Serial
51+
5352
All boards are currently configured to work over USB rather than UART. To
5453
connect to it from OSX do something like this:
5554

5655
screen /dev/tty.usbmodem142422 115200
5756

5857
You may not see a prompt immediately because it doesn't know you connected. To
5958
get one either hit enter to get `>>>` or do CTRL-B to get the full header.
59+
60+
### Mass storage
61+
62+
All boards will also show up as a mass storage device. Make sure to eject it
63+
before referring to any files.

0 commit comments

Comments
 (0)
0