examples/index.md

   1 # About Adafruit_Micropython_Blinka
   2
   3 This repository is structured around integration tests rooted at the `test/src`
   4 directory, intended to test the compatibility layer rooted in `src`.
   5
   6 The tests offer a procedural way to assert equivalence between 'native' CircuitPython behaviour and behaviour of the **adafruit_blinka** compatibility layer.
   7
   8 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).
   9
  10 Automated introspection of the python runtime combines with interactive prompts
  11 to configure a scenario for testing (e.g. which platform, which board, what is wired to it)
  12 so the same routines can be carried out on Micropython boards, dual boards running either CircuitPython or Micropython, or dedicated CircuitPython boards.
  13
  14 Typically the tests have first run on a native CircuitPython platform, and are then used to
  15 prove equivalence on a Micropython platform running the **adafruit_blinka** compatibility layer.
  16
  17 # Tests so far
  18
  19 Tests of compatible versions of **digitalio**, **board** and **microcontroller** have successfully demonstrated
  20 the same code running on either platform, setting and getting pin values and using pull.
  21
  22 Tests have also proven compatibility of the following unmodified CircuitPython libraries...
  23
  24 * adafruit_bme280
  25 * adafruit_mma8451
  26 * adafruit_gps
  27
  28 ...which proves the fundamentals of bitbangio.I2C, busio.I2C and busio.UART
  29
  30 # Example
  31
  32 To take a minimal example, the following should assert the default behaviour of the DigitalInOut
  33 constructor, checks the behaviour of switch_to_input/output(), configures a pin as a pull-up button, a pull-down button and an LED.
  34
  35 ```python
  36 from testing import test_module_name
  37 test_module_name("testing.universal.digitalio")
  38 ```
  39
  40 To prove this on a newly-flashed Feather Huzzah running Micropython 1.9.3,
  41 it should be possible (on a posix-compliant platform with adafruit_ampy installed)
  42 to `cd test/scripts` then run `./upload_feather_huzzah_micropython_put.sh` to
  43 synchronize relevant files to the filesystem of the huzzah, reset the huzzah then
  44 connect using `screen /dev/ttyUSB0 115200` before running the above commands.
  45
  46 Micropython hosts require a micropython repository alongside
  47 the Adafruit_Micropython_Blinka repository. For circuitpython,
  48 the repository is expected to be called circuitpython_2.2.3.
  49 In each case, the matching version should have been checked out from github
  50 and `make` needs to have been run in the `mpy-cross` folder. This provides a tool
  51 to make bytecode-compiled .mpy versions of all .py files before upload so that
  52 tests can be achieved within the limited memory available on many target platforms.
  53
  54 ## Comments
  55
  56 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.