Browse Source

Improve docs and update to CircuitPython.

crypto-aes
Scott Shawcroft 6 years ago
parent
commit
7c302c395e
  1. 24
      README.md
  2. 36
      atmel-samd/README.rst
  3. 10
      atmel-samd/bindings/samd/__init__.c
  4. 44
      conf.py
  5. 2
      docs/drivers.rst
  6. 1
      index.rst
  7. 6
      license.rst
  8. 9
      shared-bindings/help.c
  9. 1
      shared-bindings/index.rst
  10. 16
      shared-bindings/microcontroller/__init__.c
  11. 2
      shared-bindings/nativeio/__init__.c
  12. 6
      shared-bindings/uheap/__init__.c

24
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.

36
atmel-samd/README.md → 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 <https://github.com/adafruit/circuitpython/tree/master/atmel-samd/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__

10
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();

44
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.

2
docs/drivers.rst

@ -5,7 +5,7 @@ These are drivers available in separate GitHub repos.
.. toctree::
Register Library <http://adafruit-micropython-register.readthedocs.io/en/latest/>
Register Library <https://circuitpython.readthedocs.io/projects/register/en/latest/>
RGB Displays <http://micropython-rgb.readthedocs.io/>
Analog-to-digital converters: ADS1015 and ADS1115 <http://micropython-ads1015.readthedocs.io/>
DS3231 Real-time Clock (Precision RTC) <https://circuitpython.readthedocs.io/projects/ds3231/en/latest/>

1
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

6
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

9
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) {

1
shared-bindings/index.rst

@ -10,3 +10,4 @@ follow.
:maxdepth: 3
*/__init__
help

16
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();

2
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

6
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);

Loading…
Cancel
Save