From 7c302c395ec699738bade269673c06a38cbedbff Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Thu, 5 Jan 2017 16:20:46 -0800 Subject: Improve docs and update to CircuitPython. --- README.md | 24 +++++++-- atmel-samd/README.md | 63 ------------------------ atmel-samd/README.rst | 79 ++++++++++++++++++++++++++++++ atmel-samd/bindings/samd/__init__.c | 10 ++-- conf.py | 44 +++++++++++++++-- docs/drivers.rst | 2 +- index.rst | 1 - license.rst | 6 +-- shared-bindings/help.c | 9 ++-- shared-bindings/index.rst | 1 + shared-bindings/microcontroller/__init__.c | 16 +++--- shared-bindings/nativeio/__init__.c | 2 + shared-bindings/uheap/__init__.c | 6 +-- 13 files changed, 168 insertions(+), 95 deletions(-) delete mode 100644 atmel-samd/README.md create mode 100644 atmel-samd/README.rst diff --git a/README.md b/README.md index dd950bc04..fc3cbb170 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.md deleted file mode 100644 index 105f629e8..000000000 --- a/atmel-samd/README.md +++ /dev/null @@ -1,63 +0,0 @@ -# SAMD21x18 - -This port brings MicroPython to SAMD21x18 based development boards including the -Arduino Zero, Adafruit Feather M0 Basic and Adafruit M0 Bluefruit LE. - -## Building - -To build for the Arduino Zero: - - make - -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. - -## Deploying - -### 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, -run bossac: - - tools/bossac_osx -e -w -v -b -R build-feather_m0_basic/firmware.bin - -### No Bootloader via GDB -This method works for loading MicroPython onto the Arduino Zero via the -programming port rather than the native USB port. - -Note: These instructions are tested on Mac OSX and will vary for different -platforms. - - openocd -f ~/Library/Arduino15/packages/arduino/hardware/samd/1.6.6/variants/arduino_zero/openocd_scripts/arduino_zero.cfg - -In another terminal from `micropython/atmel-samd`: - - arm-none-eabi-gdb build-arduino_zero/firmware.elf - (gdb) tar ext :3333 - ... - (gdb) load - ... - (gdb) monitor reset init - ... - (gdb) continue - -## Connecting - -### Serial - -All boards are currently configured to work over USB rather than UART. To -connect to it from OSX do something like this: - - screen /dev/tty.usbmodem142422 115200 - -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 - -All boards will also show up as a mass storage device. Make sure to eject it -before referring to any files. diff --git a/atmel-samd/README.rst b/atmel-samd/README.rst new file mode 100644 index 000000000..f9f60dc27 --- /dev/null +++ b/atmel-samd/README.rst @@ -0,0 +1,79 @@ +SAMD21x18 +========= + +This port brings MicroPython to SAMD21x18 based development boards including the +Arduino Zero, Adafruit Feather M0 Basic and Adafruit M0 Bluefruit LE. + +Building +-------- + +To build for the Arduino Zero: + + make + +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. + +Deploying +--------- + +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, +run bossac: + + tools/bossac_osx -e -w -v -b -R build-feather_m0_basic/firmware.bin + +No Bootloader via GDB +^^^^^^^^^^^^^^^^^^^^^ + +This method works for loading MicroPython onto the Arduino Zero via the +programming port rather than the native USB port. + +Note: These instructions are tested on Mac OSX and will vary for different +platforms. + + openocd -f ~/Library/Arduino15/packages/arduino/hardware/samd/1.6.6/variants/arduino_zero/openocd_scripts/arduino_zero.cfg + +In another terminal from `micropython/atmel-samd`: + + arm-none-eabi-gdb build-arduino_zero/firmware.elf + (gdb) tar ext :3333 + ... + (gdb) load + ... + (gdb) monitor reset init + ... + (gdb) continue + +Connecting +---------- + +Serial +^^^^^^ + +All boards are currently configured to work over USB rather than UART. To +connect to it from OSX do something like this: + + screen /dev/tty.usbmodem142422 115200 + +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 +^^^^^^^^^^^^ + +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 59bded69d..62deb78c5 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 f9094886b..07c1aa027 100644 --- a/conf.py +++ b/conf.py @@ -59,17 +59,18 @@ source_parsers = {'.md': CommonMarkParser, #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 @@ release = '1.8.6' # 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 474022b28..8768f92e2 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 13be692a5..d2453b267 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 bbc5016ed..7e97341cd 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 dfdd72680..ef819a366 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 c1c63276c..ebea3c16a 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 031bfe35c..214436687 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 9bcc252cd..3d4b8c823 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 55050cfa3..df18237ac 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); -- cgit v1.2.3