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://github.com/adafruit/Adafruit_Blinka.svg/workflows/Build%20CI/badge.svg
  13     :target: https://github.com/adafruit/Adafruit_Blinka/actions
  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 The pin names may vary by board, so you may need to change the pin names in the code. This
  81 example runs on the Raspberry Pi boards to blink an LED connected to GPIO 18 (Pin 12):
  82
  83 .. code-block:: python
  84
  85     import time
  86     import board
  87     import digitalio
  88
  89     PIN = board.D18
  90
  91     print("hello blinky!")
  92
  93     led = digitalio.DigitalInOut(PIN)
  94     led.direction = digitalio.Direction.OUTPUT
  95
  96     while True:
  97         led.value = True
  98         time.sleep(0.5)
  99         led.value = False
 100         time.sleep(0.5)
 101
 102 Contributing
 103 ============
 104
 105 Contributions are welcome! Please read our `Code of Conduct
 106 <https://github.com/adafruit/Adafruit_Blinka/blob/master/CODE_OF_CONDUCT.md>`_
 107 before contributing to help this project stay welcoming.
 108
 109 Building locally
 110 ================
 111
 112 Sphinx documentation
 113 -----------------------
 114
 115 Sphinx is used to build the documentation based on rST files and comments in the code. First,
 116 install dependencies (feel free to reuse the virtual environment from above):
 117
 118 .. code-block:: shell
 119
 120     python3 -m venv .env
 121     source .env/bin/activate
 122     pip install Sphinx sphinx-rtd-theme Adafruit-PlatformDetect
 123
 124 Now, once you have the virtual environment activated:
 125
 126 .. code-block:: shell
 127
 128     cd docs
 129     sphinx-build -E -W -b html . _build/html
 130
 131 This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
 132 view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
 133 locally verify it will pass.