From: Scott Shawcroft Date: Wed, 27 Jun 2018 18:36:23 +0000 (-0700) Subject: Merge pull request #12 from tannewt/auto_pypi X-Git-Tag: 0.1.0~1 X-Git-Url: https://git.ayoreis.com/hackapet/Adafruit_Blinka.git/commitdiff_plain/f8fda4a76906791017ac9004b76837ce80699be7?hp=611b05f44622790688bb9e074254ce6adf35c5a4 Merge pull request #12 from tannewt/auto_pypi Lint! Untested. --- diff --git a/.gitignore b/.gitignore index cc5b9ac..25364da 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ _build .env build* bundles +*.DS_Store diff --git a/.travis.yml b/.travis.yml old mode 100644 new mode 100755 index 70d0c70..252c176 --- a/.travis.yml +++ b/.travis.yml @@ -32,7 +32,7 @@ install: - pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme script: - - pylint adafruit_blinka.py + - pylint src/**/*.py - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace examples/*.py) - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-blinka --library_location . - cd docs && sphinx-build -E -W -b html . _build/html diff --git a/docs/api.rst b/docs/api.rst old mode 100644 new mode 100755 index ab40507..66bca16 --- a/docs/api.rst +++ b/docs/api.rst @@ -6,3 +6,21 @@ .. automodule:: adafruit_blinka :members: + +.. automodule:: adafruit_blinka.agnostic + :members: + +.. automodule:: adafruit_blinka.microcontroller + :members: + +.. automodule:: bitbangio + :members: + +.. automodule:: board + :members: + +.. automodule:: busio + :members: + +.. automodule:: digitalio + :members: diff --git a/docs/conf.py b/docs/conf.py old mode 100644 new mode 100755 index 5976c17..4e0f359 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,7 +2,7 @@ import os import sys -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../src')) # -- General configuration ------------------------------------------------ @@ -18,9 +18,10 @@ extensions = [ # Uncomment the below if you use native CircuitPython modules such as # digitalio, micropython and busio. List the modules you use. Without it, the # autodoc module docs will fail to generate with a warning. -# autodoc_mock_imports = ["digitalio", "busio"] +autodoc_mock_imports = ["machine"] -intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)} +intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None), + 'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)} # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/examples.rst b/docs/examples.rst old mode 100644 new mode 100755 index 83f5ffe..c174f0c --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,8 +1,5 @@ -Simple test ------------- +examples +-------- -Ensure your device works with this simple test. - -.. literalinclude:: ../examples/blinka_simpletest.py - :caption: examples/blinka_simpletest.py - :linenos: +No examples are currently available. See the `CircuitPython docs +`_ for extensive API documentation. diff --git a/docs/index.rst b/docs/index.rst old mode 100644 new mode 100755 index 8d71e1b..07e52d5 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,18 +20,6 @@ Table of Contents api -.. toctree:: - :caption: Tutorials - -.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave - the toctree above for use later. - -.. toctree:: - :caption: Related Products - -.. todo:: Add any product links here. If there are none, then simply delete this todo and leave - the toctree above for use later. - .. toctree:: :caption: Other Links diff --git a/examples/index.md b/examples/index.md deleted file mode 100644 index 184ca33..0000000 --- a/examples/index.md +++ /dev/null @@ -1,69 +0,0 @@ -# About Adafruit_Micropython_Blinka - -This repository is structured around integration tests rooted at the `test/src` -directory, intended to test the compatibility layer rooted in `src`. - -The tests offer a procedural way to assert equivalence between 'native' CircuitPython behaviour and behaviour of the **adafruit_blinka** compatibility layer. - -The structure of the testing modules permits test suites to be imported and configured selectively on different implementations, platforms and boards (see `adafruit_blinka.agnostic.py` for definitions of these terms). - -Automated introspection of the python runtime combines with interactive prompts -to configure a scenario for testing (e.g. which platform, which board, what is wired to it) -so the same routines can be carried out on Micropython boards, dual boards running either CircuitPython or Micropython, or dedicated CircuitPython boards. - -Typically the tests have first run on a native CircuitPython platform, and are then used to -prove equivalence on a Micropython platform running the **adafruit_blinka** compatibility layer. - -# Tests so far - -Tests of compatible versions of **digitalio**, **board** and **microcontroller** have successfully demonstrated -the same code running on either platform, setting and getting pin values and using pull. - -Tests have also proven compatibility of the following unmodified CircuitPython libraries... - -* adafruit_bme280 -* adafruit_mma8451 -* adafruit_gps - -...which proves the fundamentals of bitbangio.I2C, busio.I2C and busio.UART - -# Example - -To take a minimal example, the following should assert the default behaviour of the DigitalInOut -constructor, checks the behaviour of switch_to_input/output(), configures a pin as a pull-up button, a pull-down button and an LED. - -```python -from testing import test_module_name -test_module_name("testing.universal.digitalio") -``` - -Or to take a more involved example of constructing a test suite requiring hardware, -the following should verify I2C communication with a BME280 module. - -```python -import unittest -import testing.universal.i2c -suite = unittest.TestSuite() -suite.addTest(testing.universal.i2c.TestBME280Interactive) -runner = unittest.TestRunner() -runner.run(suite) -``` - - -To prove this on a newly-flashed Feather Huzzah running Micropython 1.9.3, -it should be possible (on a posix-compliant platform with adafruit_ampy installed) -to `cd test/scripts` then run `./upload_feather_huzzah_micropython_put.sh` to -synchronize relevant files to the filesystem of the huzzah, reset the huzzah then -connect using `screen /dev/ttyUSB0 115200` before running the above commands. - -Micropython hosts require a micropython repository alongside -the Adafruit_Micropython_Blinka repository. For circuitpython, -the repository is expected to be called circuitpython_2.2.3. -In each case, the matching version should have been checked out from github -and `make` needs to have been run in the `mpy-cross` folder. This provides a tool -to make bytecode-compiled .mpy versions of all .py files before upload so that -tests can be achieved within the limited memory available on many target platforms. - -## Comments - -There are reference routines in `test/scripts` like `upload_feather_huzzah_micropython_put.sh` which execute a selective bytecode-compile to .mpy format and an ampy upload for CircuitPython/Micropython on esp8266, or `upload_pyboard_micropython_cp.sh` which selectively bytecode-compiles and synchronizes files with cp to the CIRCUITPY or PYBFLASH disk mount for stm32 and samd21 platforms. \ No newline at end of file diff --git a/src/adafruit_blinka/__init__.py b/src/adafruit_blinka/__init__.py old mode 100644 new mode 100755 index 08ec27e..845c802 --- a/src/adafruit_blinka/__init__.py +++ b/src/adafruit_blinka/__init__.py @@ -1,5 +1,9 @@ -"""Module providing runtime utility objects to support the Micro/CircuitPython api""" +""" +`adafruit_blinka` - Runtime utility objects for re-implementation of CircuitPython API +====================================================================================== +* Author(s): cefn +""" class Enum(object): """ @@ -27,35 +31,43 @@ class Enum(object): """ for key in dir(cls): val = getattr(cls, key) - if type(val) is cls: + if isinstance(cls, val): yield (key, val) class ContextManaged: + """An object that automatically deinitializes hardware with a context manager.""" def __enter__(self): return self def __exit__(self, exc_type, exc_value, traceback): self.deinit() + def deinit(self): + """Free any hardware used by the object.""" + pass + class Lockable(ContextManaged): + """An object that must be locked to prevent collisions on a microcontroller resource.""" _locked = False def try_lock(self): + """Attempt to grab the lock. Return True on success, False if the lock is already taken.""" if self._locked: return False - else: - self._locked = True - return True + self._locked = True + return True def unlock(self): + """Release the lock so others may use the resource.""" if self._locked: self._locked = False else: raise ValueError("Not locked") def patch_system(): + """Patch modules that may be different due to the platform.""" import sys from adafruit_blinka.agnostic import time - sys.modules['time'] = time \ No newline at end of file + sys.modules['time'] = time diff --git a/src/adafruit_blinka/agnostic/__init__.py b/src/adafruit_blinka/agnostic/__init__.py old mode 100644 new mode 100755 index 85670bf..8d60cff --- a/src/adafruit_blinka/agnostic/__init__.py +++ b/src/adafruit_blinka/agnostic/__init__.py @@ -8,10 +8,10 @@ import gc import sys gc.collect() -try: - microcontroller = sys.platform -except: - microcontroller = None + +# We intentionally are patching into this namespace as module names so skip the name check. +# pylint: disable=invalid-name +microcontroller = sys.platform board = None if microcontroller is not None: diff --git a/src/adafruit_blinka/agnostic/time.py b/src/adafruit_blinka/agnostic/time.py old mode 100644 new mode 100755 index 078b833..eefaa56 --- a/src/adafruit_blinka/agnostic/time.py +++ b/src/adafruit_blinka/agnostic/time.py @@ -1,4 +1,10 @@ +"""Platform agnostic time implementation""" + from adafruit_blinka import agnostic + +# We intentionally are patching into this namespace so skip the wildcard check. +# pylint: disable=unused-wildcard-import,wildcard-import + if agnostic.implementation == "circuitpython": from time import * elif agnostic.implementation == "micropython": @@ -6,22 +12,29 @@ elif agnostic.implementation == "micropython": from utime import sleep from ucollections import namedtuple - _struct_time = namedtuple("struct_time", ("tm_year", "tm_mon", "tm_mday", "tm_hour", "tm_min", "tm_sec", "tm_wday", "tm_yday", "tm_isdst")) + _struct_time = namedtuple("struct_time", ("tm_year", "tm_mon", "tm_mday", + "tm_hour", "tm_min", "tm_sec", + "tm_wday", "tm_yday", "tm_isdst")) - def marshal_time(tm_year, tm_mon, tm_mday, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=-1, tm_yday=-1, tm_isdst=-1): + #pylint: disable=too-many-arguments + def _marshal_time(tm_year, tm_mon, tm_mday, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=-1, + tm_yday=-1, tm_isdst=-1): + """Construct struct_time with default values.""" _struct_time(tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst) - def struct_time(t): - return marshal_time(*t) + def struct_time(time_tuple): + """Create a struct_time""" + return _marshal_time(*time_tuple) - total_ms = 0 - prev_ticks_ms = utime.ticks_ms() + #pylint: disable=invalid-name + _total_ms = 0 + _prev_ticks_ms = utime.ticks_ms() def monotonic(): - """ - Assumes that monotonic is called more frequently than the wraparound of micropython's utime.ticks_ms() - """ - global prev_ticks_ms, total_ms + """A monotonically increasing time in seconds. No defined start time.""" + # Assumes that monotonic is called more frequently than the wraparound of micropython's + # utime.ticks_ms() + global _prev_ticks_ms, _total_ms #pylint: disable=global-statement ticks_ms = utime.ticks_ms() - total_ms += utime.ticks_diff(ticks_ms, prev_ticks_ms) - prev_ticks_ms = ticks_ms - return total_ms * 0.001 \ No newline at end of file + _total_ms += utime.ticks_diff(ticks_ms, _prev_ticks_ms) + _prev_ticks_ms = ticks_ms + return _total_ms * 0.001 diff --git a/src/adafruit_blinka/board/feather_huzzah.py b/src/adafruit_blinka/board/feather_huzzah.py old mode 100644 new mode 100755 index 60dd863..f02f647 --- a/src/adafruit_blinka/board/feather_huzzah.py +++ b/src/adafruit_blinka/board/feather_huzzah.py @@ -1,6 +1,9 @@ +"""Feather Huzzah pin names""" + from adafruit_blinka.microcontroller.esp8266 import pin -# TODO need equiv of INPUT_PULL_DOWN_16 ? see https://tttapa.github.io/ESP8266/Chap04%20-%20Microcontroller.html +# TODO need equiv of INPUT_PULL_DOWN_16 ? +# See https://tttapa.github.io/ESP8266/Chap04%20-%20Microcontroller.html GPIO0 = pin.GPIO0 GPIO1 = pin.GPIO1 @@ -24,4 +27,4 @@ RX = GPIO3 TX = GPIO1 SDA = GPIO4 -SCL = GPIO5 \ No newline at end of file +SCL = GPIO5 diff --git a/src/adafruit_blinka/board/nodemcu.py b/src/adafruit_blinka/board/nodemcu.py old mode 100644 new mode 100755 index 83e4ca8..256e836 --- a/src/adafruit_blinka/board/nodemcu.py +++ b/src/adafruit_blinka/board/nodemcu.py @@ -1,3 +1,5 @@ +"""NodeMCU pin names""" + from adafruit_blinka.microcontroller.esp8266 import pin D0 = pin.GPIO16 @@ -26,4 +28,4 @@ RX0 = D9 TX0 = D10 # GPIO0 and GPIO2 have built-in pull-ups on common ESP8266 -# breakout boards making them suitable for I2C SDA and SCL \ No newline at end of file +# breakout boards making them suitable for I2C SDA and SCL diff --git a/src/adafruit_blinka/board/pyboard.py b/src/adafruit_blinka/board/pyboard.py old mode 100644 new mode 100755 index 4bf49de..4c5eb10 --- a/src/adafruit_blinka/board/pyboard.py +++ b/src/adafruit_blinka/board/pyboard.py @@ -1,3 +1,5 @@ +"""PyBoard pin names""" + from adafruit_blinka.microcontroller.stm32 import pin X1 = pin.A0 diff --git a/src/adafruit_blinka/microcontroller/esp8266/__init__.py b/src/adafruit_blinka/microcontroller/esp8266/__init__.py index 8b13789..e69de29 100644 --- a/src/adafruit_blinka/microcontroller/esp8266/__init__.py +++ b/src/adafruit_blinka/microcontroller/esp8266/__init__.py @@ -1 +0,0 @@ - diff --git a/src/adafruit_blinka/microcontroller/esp8266/pin.py b/src/adafruit_blinka/microcontroller/esp8266/pin.py old mode 100644 new mode 100755 index c37e053..986b968 --- a/src/adafruit_blinka/microcontroller/esp8266/pin.py +++ b/src/adafruit_blinka/microcontroller/esp8266/pin.py @@ -1,3 +1,5 @@ +"""ESP8266 pin names""" + from microcontroller import Pin GPIO0 = Pin(0) @@ -14,12 +16,13 @@ GPIO16 = Pin(16) TOUT = Pin("TOUT") # ordered as spiId, sckId, mosiId, misoId -spiPorts = ((1, GPIO14, GPIO13, GPIO12)) +SPI_PORTS = ((1, GPIO14, GPIO13, GPIO12)) # ordered as uartId, txId, rxId -uartPorts = ( +UART_PORTS = ( (0, GPIO1, GPIO3), - # (0, GPIO15, GPIO13) # TODO secondary pins for UART0 configurable from Micropython? How to flag? + # TODO secondary pins for UART0 configurable from Micropython? How to flag? + # (0, GPIO15, GPIO13) (1, GPIO2, None)) -i2cPorts = () \ No newline at end of file +I2C_PORTS = () diff --git a/src/adafruit_blinka/microcontroller/stm32/pin.py b/src/adafruit_blinka/microcontroller/stm32/pin.py old mode 100644 new mode 100755 index 3f46781..870e240 --- a/src/adafruit_blinka/microcontroller/stm32/pin.py +++ b/src/adafruit_blinka/microcontroller/stm32/pin.py @@ -1,3 +1,5 @@ +"""STM32 pins""" + from microcontroller import Pin A0 = Pin('A0') @@ -49,10 +51,10 @@ C13 = Pin('C13') D2 = Pin('D2') # ordered as spiId, sckId, mosiId, misoId -spiPorts = ((1, B13, B15, B14), (2, A5, A6, A7)) +SPI_PORTS = ((1, B13, B15, B14), (2, A5, A6, A7)) # ordered as uartId, txId, rxId -uartPorts = ( +UART_PORTS = ( (1, B6, B7), (2, A2, A3), (3, B10, B11), @@ -60,8 +62,7 @@ uartPorts = ( (6, C6, C7), ) -i2cPorts = ( +I2C_PORTS = ( (1, B6, B7), (2, B10, B11), ) - diff --git a/src/bitbangio.py b/src/bitbangio.py old mode 100644 new mode 100755 index 101bfff..aa679f0 --- a/src/bitbangio.py +++ b/src/bitbangio.py @@ -1,3 +1,12 @@ +""" +`bitbangio` - Bitbanged bus protocols +============================================================== + +See `CircuitPython:bitbangio` in CircuitPython for more details. + +* Author(s): cefn +""" + from adafruit_blinka import Lockable, agnostic diff --git a/src/board.py b/src/board.py old mode 100644 new mode 100755 index 536bc6b..d1c04c4 --- a/src/board.py +++ b/src/board.py @@ -22,16 +22,14 @@ """ `board` - Define ids for available pins ================================================= -Conditionally imports and re-exports a submodule, such as boards.esp8266 based on -platform introspection + +See `CircuitPython:board` in CircuitPython for more details. * Author(s): cefn """ +import sys -import gc -gc.collect() from adafruit_blinka.agnostic import board -gc.collect() if board == "feather_huzzah": from adafruit_blinka.board.feather_huzzah import * @@ -39,6 +37,7 @@ elif board == "nodemcu": from adafruit_blinka.board.nodemcu import * elif board == "pyboard": from adafruit_blinka.board.pyboard import * +elif "sphinx" in sys.modules: + pass else: raise NotImplementedError("Board not supported") -gc.collect() diff --git a/src/busio.py b/src/busio.py old mode 100644 new mode 100755 index 0c6e296..6c5e76f --- a/src/busio.py +++ b/src/busio.py @@ -1,3 +1,12 @@ +""" +`busio` - Bus protocol support like I2C and SPI +================================================= + +See `CircuitPython:busio` in CircuitPython for more details. + +* Author(s): cefn +""" + from adafruit_blinka import Enum, Lockable, agnostic class I2C(Lockable): diff --git a/src/digitalio.py b/src/digitalio.py old mode 100644 new mode 100755 index 45cada2..8fb5385 --- a/src/digitalio.py +++ b/src/digitalio.py @@ -1,8 +1,16 @@ +""" +`digitalio` - Digital input and output control +================================================= + +See `CircuitPython:digitalio` in CircuitPython for more details. + +* Author(s): cefn +""" + from machine import Pin from adafruit_blinka.agnostic import board as boardId from adafruit_blinka import Enum, ContextManaged - class DriveMode(Enum): PUSH_PULL = None OPEN_DRAIN = None diff --git a/src/microcontroller/__init__.py b/src/microcontroller/__init__.py old mode 100644 new mode 100755 index c1b0027..5957a91 --- a/src/microcontroller/__init__.py +++ b/src/microcontroller/__init__.py @@ -1,10 +1,12 @@ -from adafruit_blinka import Enum, agnostic +"""Microcontroller pins""" +from adafruit_blinka import Enum, agnostic class Pin(Enum): - def __init__(self, id): + """Reference Pin object""" + def __init__(self, pin_id): """Identifier for pin, referencing platform-specific pin id""" - self.id = id + self._id = pin_id def __repr__(self): import board @@ -17,10 +19,12 @@ class Pin(Enum): return "microcontroller.pin.{}".format(key) return repr(self) +# We intentionally are patching into this namespace so skip the wildcard check. +# pylint: disable=unused-wildcard-import,wildcard-import if agnostic.microcontroller == "esp8266": from adafruit_blinka.microcontroller.esp8266 import * elif agnostic.microcontroller == "stm32": from adafruit_blinka.microcontroller.stm32 import * else: - raise NotImplementedError("Microcontroller not supported") \ No newline at end of file + raise NotImplementedError("Microcontroller not supported") diff --git a/src/microcontroller/pin.py b/src/microcontroller/pin.py old mode 100644 new mode 100755 index 2b6199b..2109544 --- a/src/microcontroller/pin.py +++ b/src/microcontroller/pin.py @@ -1,8 +1,13 @@ +"""Pins named after their chip name.""" + from adafruit_blinka import agnostic +# We intentionally are patching into this namespace so skip the wildcard check. +# pylint: disable=unused-wildcard-import,wildcard-import + if agnostic.microcontroller == "esp8266": from adafruit_blinka.microcontroller.esp8266.pin import * elif agnostic.microcontroller == "stm32": from adafruit_blinka.microcontroller.stm32.pin import * else: - raise NotImplementedError("Microcontroller not supported") \ No newline at end of file + raise NotImplementedError("Microcontroller not supported")