diff --git a/README.md b/README.md index dd950bc04ca2..fc3cbb170999 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Adafruit CircuitPython -[![Build Status](https://travis-ci.org/adafruit/circuitpython.svg?branch=master)](https://travis-ci.org/adafruit/circuitpython) +[![Build Status](https://travis-ci.org/adafruit/circuitpython.svg?branch=master)](https://travis-ci.org/adafruit/circuitpython) [![Doc Status](https://readthedocs.org/projects/circuitpython/badge/?version=latest)](http://circuitpython.readthedocs.io/) This is an open source derivative of [MicroPython](http://www.micropython.org) -for use on educational development boards designed and sold by Adafruit +for use on educational development boards designed and sold by [Adafruit](https://www.adafruit.com) 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 [Adafruit Feather M0 Bluefruit LE](https://www.adafruit.com/products/2995). @@ -15,7 +15,7 @@ This project is in beta. Most APIs should be stable going forward. ## 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). An API reference is also available on [Read the Docs](http://circuitpython.readthedocs.io/en/latest/?). +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) @@ -27,6 +27,24 @@ Contributors who follow the are welcome to submit pull requests and they will be promptly reviewed by project admins. +## Differences from [MicroPython](https://github.com/micropython/micropython) + +* Port for Atmel SAMD21 (Commonly known as M0 in product names.) +* No `machine` API on Atmel SAMD21 port. +* Only supports Atmel SAMD21 and ESP8266 ports. +* Unified hardware API: [`nativeio`](https://circuitpython.readthedocs.io/en/latest/shared-bindings/nativeio/__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.) +* Tracks MicroPython's releases (not master). +* No module aliasing. (`uos` and `utime` are not available as `os` and `time` respectively.) +* Modules with a CPython counterpart, such as `time`, 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) +* `os` only available as `uos` +* atmel-samd21 features + * RGB status LED + * Auto-reset after file write over mass storage. (Disable with `samd.disable_autoreset()`) + * 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 directories. diff --git a/atmel-samd/README.md b/atmel-samd/README.rst similarity index 75% rename from atmel-samd/README.md rename to atmel-samd/README.rst index 105f629e8d1a..f9f60dc271e2 100644 --- a/atmel-samd/README.md +++ b/atmel-samd/README.rst @@ -1,23 +1,28 @@ -# SAMD21x18 +SAMD21x18 +========= This port brings MicroPython to SAMD21x18 based development boards including the Arduino Zero, Adafruit Feather M0 Basic and Adafruit M0 Bluefruit LE. -## Building +Building +-------- To build for the Arduino Zero: make -To build for other boards you must change it by setting `BOARD`. For example: +To build for other boards you must change it by setting ``BOARD``. For example: make BOARD=feather_m0_basic -Board names are the directory names in the `boards` folder. +Board names are the directory names in the `boards `_ folder. -## Deploying +Deploying +--------- + +Arduino Bootloader +^^^^^^^^^^^^^^^^^^ -### Arduino Bootloader If your board has an existing Arduino bootloader on it then you can use bossac to flash MicroPython. First, activate the bootloader. On Adafruit Feathers you can double click the reset button and the #13 will fade in and out. Finally, @@ -25,7 +30,9 @@ run bossac: tools/bossac_osx -e -w -v -b -R build-feather_m0_basic/firmware.bin -### No Bootloader via GDB +No Bootloader via GDB +^^^^^^^^^^^^^^^^^^^^^ + This method works for loading MicroPython onto the Arduino Zero via the programming port rather than the native USB port. @@ -45,9 +52,11 @@ In another terminal from `micropython/atmel-samd`: ... (gdb) continue -## Connecting +Connecting +---------- -### Serial +Serial +^^^^^^ All boards are currently configured to work over USB rather than UART. To connect to it from OSX do something like this: @@ -57,7 +66,14 @@ connect to it from OSX do something like this: 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. -### Mass storage +Mass storage +^^^^^^^^^^^^ All boards will also show up as a mass storage device. Make sure to eject it before referring to any files. + +Port Specific modules +--------------------- + +.. toctree:: + bindings/samd/__init__ diff --git a/atmel-samd/bindings/samd/__init__.c b/atmel-samd/bindings/samd/__init__.c index 59bded69d7d5..62deb78c55f0 100644 --- a/atmel-samd/bindings/samd/__init__.c +++ b/atmel-samd/bindings/samd/__init__.c @@ -35,9 +35,9 @@ //| :platform: SAMD21 //| -//| .. method:: enable_autoreset() +//| .. method:: enable_autoreset() //| -//| Enable autoreset based on USB file write activity. +//| Enable autoreset based on USB file write activity. //| STATIC mp_obj_t samd_enable_autoreset(void) { autoreset_enable(); @@ -45,10 +45,10 @@ STATIC mp_obj_t samd_enable_autoreset(void) { } MP_DEFINE_CONST_FUN_OBJ_0(samd_enable_autoreset_obj, samd_enable_autoreset); -//| .. method:: disable_autoreset() +//| .. method:: disable_autoreset() //| -//| Disable autoreset based on USB file write activity until the next reset -//| or until `enable_autoreset` is called. +//| Disable autoreset based on USB file write activity until the next reset +//| or until `enable_autoreset` is called. //| STATIC mp_obj_t samd_disable_autoreset(void) { autoreset_disable(); diff --git a/conf.py b/conf.py index f9094886bbf1..07c1aa027da9 100644 --- a/conf.py +++ b/conf.py @@ -59,17 +59,18 @@ #master_doc = 'index' # General information about the project. -project = 'Adafruit\'s MicroPython' -copyright = '2014-2016, MicroPython contributors (https://github.com/adafruit/micropython/graphs/contributors)' +project = 'Adafruit CircuitPython' +copyright = '2014-2017, MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)' +# These are overwritten on ReadTheDocs. # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '1.8' +version = '0.0' # The full version, including alpha/beta/rc tags. -release = '1.8.6' +release = '0.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -83,7 +84,40 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ["*/build-*", "atmel-samd/asf", "atmel-samd/**.c", "atmel-samd/**.h", "bare-arm", "cc3200", "cc3200/FreeRTOS", "cc3200/hal", "drivers", "esp8266", "examples", "extmod", "lib", "minimal", "mpy-cross", "pic16bit", "py", "qemu-arm", "stmhal", "stmhal/hal", "stmhal/cmsis", "stmhal/usbdev", "stmhal/usbhost", "teensy", "tests", "tools", "unix", "windows", "zephyr"] +exclude_patterns = ["*/build-*", + "atmel-samd/asf", + "atmel-samd/asf_conf", + "atmel-samd/common-hal", + "atmel-samd/boards", + "atmel-samd/QTouch", + "atmel-samd/*.c", + "atmel-samd/*.h", + "bare-arm", + "cc3200", + "cc3200/FreeRTOS", + "cc3200/hal", + "drivers", + "esp8266", + "examples", + "extmod", + "lib", + "minimal", + "mpy-cross", + "pic16bit", + "py", + "qemu-arm", + "shared-module", + "stmhal", + "stmhal/hal", + "stmhal/cmsis", + "stmhal/usbdev", + "stmhal/usbhost", + "teensy", + "tests", + "tools", + "unix", + "windows", + "zephyr"] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/drivers.rst b/docs/drivers.rst index 474022b2848d..8768f92e2840 100644 --- a/docs/drivers.rst +++ b/docs/drivers.rst @@ -5,7 +5,7 @@ These are drivers available in separate GitHub repos. .. toctree:: - Register Library + Register Library RGB Displays Analog-to-digital converters: ADS1015 and ADS1115 DS3231 Real-time Clock (Precision RTC) diff --git a/index.rst b/index.rst index 13be692a5205..d2453b267f06 100644 --- a/index.rst +++ b/index.rst @@ -24,7 +24,6 @@ docs are low-level API docs and may link out to separate getting started guides. docs/common_hal docs/drivers.rst docs/supported_ports.rst - docs/unsupported_ports.rst docs/library/index.rst README CONTRIBUTING diff --git a/license.rst b/license.rst index bbc5016ed7c5..7e97341cda7b 100644 --- a/license.rst +++ b/license.rst @@ -1,9 +1,9 @@ -MicroPython license information -=============================== +MicroPython & CircuitPython license information +=============================================== The MIT License (MIT) -Copyright (c) 2013-2015 Damien P. George, and others +Copyright (c) 2013-2017 Damien P. George, and others Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/shared-bindings/help.c b/shared-bindings/help.c index dfdd7268024f..ef819a366b63 100644 --- a/shared-bindings/help.c +++ b/shared-bindings/help.c @@ -27,10 +27,13 @@ #include "lib/utils/pyhelp.h" #include "shared-bindings/help.h" -//| .. method:: help(object=None) +//| :func:`help` - Built-in method to provide helpful information +//| ======================================================== //| -//| Prints a help method about the given object. When ``object`` is none, -//| prints general port information. +//| .. method:: help(object=None) +//| +//| Prints a help method about the given object. When ``object`` is none, +//| prints general port information. //| STATIC mp_obj_t pyb_help(uint n_args, const mp_obj_t *args) { if (n_args == 0) { diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst index c1c63276ce44..ebea3c16a0c7 100644 --- a/shared-bindings/index.rst +++ b/shared-bindings/index.rst @@ -10,3 +10,4 @@ follow. :maxdepth: 3 */__init__ + help diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c index 031bfe35c4dd..21443668736b 100644 --- a/shared-bindings/microcontroller/__init__.c +++ b/shared-bindings/microcontroller/__init__.c @@ -43,7 +43,7 @@ //| //| .. module:: microcontroller //| :synopsis: Pin references and core functionality -//| :platform: SAMD21 +//| :platform: SAMD21, ESP8266 //| //| The `microcontroller` module defines the pins from the perspective of the //| microcontroller. See `board` for board-specific pin mappings. @@ -56,10 +56,10 @@ //| Pin //| -//| .. method:: delay_us(delay) +//| .. method:: delay_us(delay) //| -//| Dedicated delay method used for very short delays. DO NOT do long delays -//| because it will stall any concurrent code. +//| Dedicated delay method used for very short delays. DO NOT do long delays +//| because it will stall any concurrent code. //| STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) { uint32_t delay = mp_obj_get_int(delay_obj); @@ -70,9 +70,9 @@ STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_delay_us_obj, mcu_delay_us); -//| .. method:: disable_interrupts() +//| .. method:: disable_interrupts() //| -//| Disable all interrupts. Be very careful, this can stall everything. +//| Disable all interrupts. Be very careful, this can stall everything. //| STATIC mp_obj_t mcu_disable_interrupts(void) { common_hal_mcu_disable_interrupts(); @@ -80,9 +80,9 @@ STATIC mp_obj_t mcu_disable_interrupts(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_disable_interrupts_obj, mcu_disable_interrupts); -//| .. method:: enable_interrupts() +//| .. method:: enable_interrupts() //| -//| Enable the interrupts that were enabled at the last disable. +//| Enable the interrupts that were enabled at the last disable. //| STATIC mp_obj_t mcu_enable_interrupts(void) { common_hal_mcu_enable_interrupts(); diff --git a/shared-bindings/nativeio/__init__.c b/shared-bindings/nativeio/__init__.c index 9bcc252cdf2e..3d4b8c82397a 100644 --- a/shared-bindings/nativeio/__init__.c +++ b/shared-bindings/nativeio/__init__.c @@ -76,6 +76,8 @@ //| I2C //| PWMOut //| SPI +//| TouchIn +//| UART //| //| All libraries change hardware state and should be deinitialized when they //| are no longer needed. To do so, either call :py:meth:`!deinit` or use a diff --git a/shared-bindings/uheap/__init__.c b/shared-bindings/uheap/__init__.c index 55050cfa3d3c..df18237accca 100644 --- a/shared-bindings/uheap/__init__.c +++ b/shared-bindings/uheap/__init__.c @@ -38,10 +38,10 @@ //| :synopsis: Heap size analysis //| -//| .. method:: info(object) +//| .. method:: info(object) //| -//| Prints memory debugging info for the given object and returns the -//| estimated size. +//| Prints memory debugging info for the given object and returns the +//| estimated size. //| STATIC mp_obj_t uheap_info(mp_obj_t obj) { uint32_t size = shared_module_uheap_info(obj);