X-Git-Url: https://git.ayoreis.com/hackapet/Adafruit_Blinka.git/blobdiff_plain/6c5b910981e69b5710654ac08f81d9f776a84deb..a75b48ca9e7241a0b876258d31efaa907090c2a8:/examples/index.md diff --git a/examples/index.md b/examples/index.md index b2c1a82..184ca33 100644 --- a/examples/index.md +++ b/examples/index.md @@ -1,62 +1,69 @@ -This repository is structured around integration tests found in the python/testing -directory. The tests offer a procedural way to assert equivalence between 'native' CircuitPython (CP) behaviour and -behaviour of the MicropythonCircuitPython (MCP) layer. +# 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`. -In particular, 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) meaning that -the same routines can be carried out on Micropython boards, dual boards running either CP or MCP -or dedicated CP boards. +The tests offer a procedural way to assert equivalence between 'native' CircuitPython behaviour and behaviour of the **adafruit_blinka** compatibility layer. -From a project-management point of view, tests can provide a strictly-interpreted way to -communicate missing features, also providing the implicit means of verifying that intended -features for the MCP layer are in fact already served from the CP 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 asserts the default behaviour of the DigitalInOut +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 -import testing -testing.main() +from testing import test_module_name +test_module_name("testing.universal.digitalio") ``` -## Comments - -There are routines in the top level of the repo like `upload_feather_m0_watch.py` which selectively synchronize files it with the CIRCUITPY or PYBFLASH folder for stm32 and samd21 (with a file-watching behaviour for edits), or which execute a selective ampy upload for CircuitPython/Micropython on esp8266. - -Given the limited memory available, on the Feather M0 Express, running the test case requires that -the [micropython-lib unittest library](https://github.com/micropython/micropython-lib/blob/master/unittest/unittest.py) -is distributed as a compatible Micropython bytecode .mpy file -pre-compiled under an mpy-cross version from the CircuitPython 2.2.3-tagged repository. Otherwise -simply loading the unittest module already busts the available memory. - -# Test Suite Structure +Or to take a more involved example of constructing a test suite requiring hardware, +the following should verify I2C communication with a BME280 module. -The structure of the testing modules is as follows, to permit test suites to be imported selectively -on different implementations, platforms and boards (see agnostic.py for definitions of these terms)... +```python +import unittest +import testing.universal.i2c +suite = unittest.TestSuite() +suite.addTest(testing.universal.i2c.TestBME280Interactive) +runner = unittest.TestRunner() +runner.run(suite) +``` -* _testing_ - common function definitions for suite-execution -* _testing.mcp_ - test suite for hardware-agnostic elements of MCP layer (e.g. Enum) -* _testing.implementation_ - calculates implementation-specific parameters for test fixtures -* _testing.implementation.all_ - suites expected to run on all platforms -* _testing.implementation.micropython_ - suites testing MCP-specific classes and behaviours (under the hood of the hardware compatibility layer) and only -expected to run on Micropython -* _testing.implementation.circuitpython - suites testing CircuitPython-specific -classes and behaviours, and only expected to run in CircuitPython_ -e.g. -* testing.implementation.all.digitalio - tests against the -digitalio module regardless of platform -* testing.implementation.circuitpython.digitalio - tests of digitalio against a -native circuitpython host -* testing.implementation.micropython.digitalio - tests of digitalio against the MCP -compatibility layer +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. -# Next Steps +## Comments -To be able to run a substantial series of testing modules, a dedicated -feather m0 express firmware image should be prepared with [frozen modules](https://learn.adafruit.com/micropython-for-samd21/frozen-modules) which -minimises overhead by holding test definitions in flash instead of RAM. +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