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

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