Merge pull request #8 from cefn/master

[hackapet/Adafruit_Blinka.git] / examples / index.md

diff --git a/examples/index.md b/examples/index.md
index 33e3a341c03406f08efada565d01bbc7e7c35b9b..184ca33b76e3e04a656d99064a8407f97dcca0f8 100644 (file)
--- a/examples/index.md
+++ b/examples/index.md
@@ -1,3 +1,5 @@
+# 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`. 
 
 This repository is structured around integration tests rooted at the `test/src`
 directory, intended to test the compatibility layer rooted in `src`. 
 


@@ -12,6 +14,8 @@ so the same routines can be carried out on Micropython boards, dual boards runni
 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.
 
 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 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.
 


@@ -33,6 +37,33 @@ from testing import test_module_name
 test_module_name("testing.universal.digitalio")
 ```
 
 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
 ## 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