README.rst

   1 Introduction
   2 ============
   3
   4 .. image:: https://readthedocs.org/projects/adafruit-micropython-blinka/badge/?version=latest
   5     :target: https://circuitpython.readthedocs.io/projects/blinka/en/latest/
   6     :alt: Documentation Status
   7
   8 .. image:: https://img.shields.io/discord/327254708534116352.svg
   9     :target: https://adafru.it/discord
  10     :alt: Discord
  11
  12 .. image:: https://travis-ci.com/adafruit/Adafruit_Blinka.svg?branch=master
  13     :target: https://travis-ci.com/adafruit/Adafruit_Blinka
  14     :alt: Build Status
  15
  16 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
  17     :target: https://github.com/psf/black
  18     :alt: Code Style: Black
  19
  20 This repository contains a selection of packages emulating the CircuitPython API
  21 for devices or hosts running CPython or MicroPython. Working code exists to emulate these CircuitPython packages:
  22
  23 * **analogio** - analog input/output pins, using pin identities from board+microcontroller packages
  24 * **bitbangio** - software-driven interfaces for I2C, SPI
  25 * **board** - breakout-specific pin identities
  26 * **busio** - hardware-driven interfaces for I2C, SPI, UART
  27 * **digitalio** - digital input/output pins, using pin identities from board+microcontroller packages
  28 * **keypad** - support for scanning keys and key matrices
  29 * **microcontroller** - chip-specific pin identities
  30 * **micropython** - MicroPython-specific module
  31 * **neopixel_write** - low-level interface to NeoPixels
  32 * **pulseio** - contains classes that provide access to basic pulse IO (PWM)
  33 * **pwmio** - contains classes that provide access to basic pulse IO (PWM)
  34 * **rainbowio** - provides the colorwheel() function
  35 * **usb_hid** - act as a hid-device using usb_gadget kernel driver
  36
  37 For details, see the `Blinka API reference
  38 <https://circuitpython.readthedocs.io/projects/blinka/en/latest/index.html>`_.
  39
  40 Dependencies
  41 =============
  42
  43 The emulation described above is intended to provide a
  44 CircuitPython-like API for devices which are running CPython or
  45 Micropython. Since corresponding packages should be built-in to any
  46 standard CircuitPython image, they have no value on a device already
  47 running CircuitPython and would likely conflict in unhappy ways.
  48
  49 The test suites in the test/src folder under **testing.universal** are by design
  50 intended to run on *either* CircuitPython *or* CPython/Micropython+compatibility layer to prove conformance.
  51
  52 Installing from PyPI
  53 =====================
  54
  55 On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
  56 PyPI <https://pypi.org/project/Adafruit-Blinka/>`_. To install for current user:
  57
  58 .. code-block:: shell
  59
  60     pip3 install Adafruit-Blinka
  61
  62 To install system-wide (this may be required in some cases):
  63
  64 .. code-block:: shell
  65
  66     sudo pip3 install Adafruit-Blinka
  67
  68 To install in a virtual environment in your current project:
  69
  70 .. code-block:: shell
  71
  72     mkdir project-name && cd project-name
  73     python3 -m venv .env
  74     source .env/bin/activate
  75     pip3 install Adafruit-Blinka
  76
  77 Usage Example
  78 =============
  79
  80 At the time of writing (`git:7fc1f8ab <https://github.com/cefn/Adafruit_Micropython_Blinka/tree/7fc1f8ab477124628a5afebbf6826005955805f9>`_),
  81 the following sequence runs through some basic testing of the digitalio compatibility layer...
  82
  83 .. code-block:: python
  84
  85     from testing import test_module_name
  86     test_module_name("testing.universal.digitalio")
  87
  88 An example log from running the suites is `here <https://github.com/cefn/Adafruit_Micropython_Blinka/issues/2#issuecomment-366713394>`_ .
  89
  90 Contributing
  91 ============
  92
  93 Contributions are welcome! Please read our `Code of Conduct
  94 <https://github.com/adafruit/Adafruit_Blinka/blob/master/CODE_OF_CONDUCT.md>`_
  95 before contributing to help this project stay welcoming.
  96
  97 Building locally
  98 ================
  99
 100 Sphinx documentation
 101 -----------------------
 102
 103 Sphinx is used to build the documentation based on rST files and comments in the code. First,
 104 install dependencies (feel free to reuse the virtual environment from above):
 105
 106 .. code-block:: shell
 107
 108     python3 -m venv .env
 109     source .env/bin/activate
 110     pip install Sphinx sphinx-rtd-theme Adafruit-PlatformDetect
 111
 112 Now, once you have the virtual environment activated:
 113
 114 .. code-block:: shell
 115
 116     cd docs
 117     sphinx-build -E -W -b html . _build/html
 118
 119 This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
 120 view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
 121 locally verify it will pass.