README.md 3.81 KB
Newer Older
1
2
3
[![Build Status][travis-img]][travis-repo]
[travis-img]:  https://travis-ci.org/micropython/micropython.png?branch=master
[travis-repo]: https://travis-ci.org/micropython/micropython
4

Damien's avatar
Damien committed
5
6
The Micro Python project
========================
7
<p align="center">
8
  <img src="https://raw2.github.com/micropython/micropython/master/logo/upython-with-micro.jpg" alt="MicroPython Logo"/>
9
</p>
Damien's avatar
Damien committed
10

Damien's avatar
Damien committed
11
This is the Micro Python project, which aims to put an implementation
12
of Python 3.x on a microcontroller.
Damien's avatar
Damien committed
13

14
WARNING: this project is in early beta stage and is subject to large
15
changes of the code-base, including project-wide name changes and API
Damien George's avatar
Damien George committed
16
changes.
17

18
19
Micro Python implements the entire Python 3.4 syntax (including exceptions,
"with", "yield from", etc.).  The following core datatypes are provided:
20
str (no Unicode support yet), bytes, bytearray, tuple, list, dict, set,
21
22
array.array, collections.namedtuple, classes and instances.  Builtin
modules include sys, time, and struct.  Note that only subset of
23
24
Python 3.4 functionality implemented for the data types and modules.

25
See the repository www.github.com/micropython/pyboard for the Micro
26
Python board, the officially supported reference electronic circuit board.
27
28

Major components in this repository:
Damien's avatar
Damien committed
29
30
- py/ -- the core Python implementation, including compiler and runtime.
- unix/ -- a version of Micro Python that runs on Unix.
Damien George's avatar
Damien George committed
31
- stmhal/ -- a version of Micro Python that runs on the Micro Python board
32
  with an STM32F405RG (using ST's Cube HAL drivers).
Damien George's avatar
Damien George committed
33
34
- teensy/ -- a version of Micro Python that runs on the Teensy 3.1
  (preliminary but functional).
Damien's avatar
Damien committed
35

Damien's avatar
Damien committed
36
Additional components:
Damien George's avatar
Damien George committed
37
38
- bare-arm/ -- a bare minimum version of Micro Python for ARM MCUs.  Start
  with this if you want to port Micro Python to another microcontroller.
Damien's avatar
Damien committed
39
40
- unix-cpy/ -- a version of Micro Python that outputs bytecode (for testing).
- tests/ -- test framework and test scripts.
Damien George's avatar
Damien George committed
41
- tools/ -- various tools, including the pyboard.py module.
Damien George's avatar
Damien George committed
42
- examples/ -- a few example Python scripts.
Damien's avatar
Damien committed
43

44
"make" is used to build the components, or "gmake" on BSD-based systems.
Damien George's avatar
Damien George committed
45
You will also need bash and Python (at least 2.7 or 3.3).
Damien's avatar
Damien committed
46

Damien's avatar
Damien committed
47
The Unix version
Damien's avatar
Damien committed
48
49
----------------

Damien George's avatar
Damien George committed
50
The "unix" port requires a standard Unix environment with gcc and GNU make.
51
x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
52
53
54
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.
Damien's avatar
Damien committed
55
56

To build:
Damien's avatar
Damien committed
57

Damien's avatar
Damien committed
58
59
60
    $ cd unix
    $ make

61
Then to give it a try:
Damien's avatar
Damien committed
62

63
    $ ./micropython
Damien's avatar
Damien committed
64
65
    >>> list(5 * x + y for x in range(10) for y in [4, 2, 1])

66
67
68
69
Run complete testsuite:

    $ make test

70
71
Debian/Ubuntu/Mint derivative Linux distros will require build-essentials and
libreadline-dev packages installed. To build FFI (Foreign Function Interface)
72
73
module, libffi-dev and pkg-config packages are required. If you have problems
with some dependencies, they can be disabled in unix/mpconfigport.mk .
Dr-Syn's avatar
Dr-Syn committed
74

Damien's avatar
Damien committed
75
The STM version
Damien's avatar
Damien committed
76
77
---------------

Damien George's avatar
Damien George committed
78
The "stmhal" port requires an ARM compiler, arm-none-eabi-gcc, and associated
Damien's avatar
Damien committed
79
80
81
82
83
bin-utils.  For those using Arch Linux, you need arm-none-eabi-binutils and
arm-none-eabi-gcc packages from the AUR.  Otherwise, try here:
https://launchpad.net/gcc-arm-embedded

To build:
Damien's avatar
Damien committed
84

Damien George's avatar
Damien George committed
85
    $ cd stmhal
Damien's avatar
Damien committed
86
87
    $ make

Damien George's avatar
Damien George committed
88
89
90
91
92
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:
Damien's avatar
Damien committed
93

94
    $ make deploy
Damien's avatar
Damien committed
95

96
97
98
99
You will need the dfu-util program, on Arch Linux it's dfu-util-git in the
AUR.  If the above does not work it may be because you don't have the
correct permissions.  Try then:

100
    $ sudo dfu-util -a 0 -d 0483:df11 -D build-PYBV10/firmware.dfu