X-Git-Url: https://git.ayoreis.com/Adafruit_Blinka-hackapet.git/blobdiff_plain/75ae0e97611f429f15c02c2b58254be6533419a0..8af0d36901552aaa3737ffd7229d5fed35187eb4:/README.rst diff --git a/README.rst b/README.rst old mode 100644 new mode 100755 index a018d69..d2957fd --- a/README.rst +++ b/README.rst @@ -6,57 +6,104 @@ Introduction :alt: Documentation Status .. image:: https://img.shields.io/discord/327254708534116352.svg - :target: https://discord.gg/nBQh6qu + :target: https://adafru.it/discord :alt: Discord -.. image:: https://travis-ci.org/adafruit/Adafruit_Micropython_Blinka.svg?branch=master - :target: https://travis-ci.org/adafruit/Adafruit__Micropython_Blinka +.. image:: https://github.com/adafruit/Adafruit_Blinka.svg/workflows/Build%20CI/badge.svg + :target: https://github.com/adafruit/Adafruit_Blinka/actions :alt: Build Status -Description -=========== +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/psf/black + :alt: Code Style: Black + +This repository contains a selection of packages emulating the CircuitPython API +for devices or hosts running CPython or MicroPython. Working code exists to emulate these CircuitPython packages: + +* **analogio** - analog input/output pins, using pin identities from board+microcontroller packages +* **bitbangio** - software-driven interfaces for I2C, SPI +* **board** - breakout-specific pin identities +* **busio** - hardware-driven interfaces for I2C, SPI, UART +* **digitalio** - digital input/output pins, using pin identities from board+microcontroller packages +* **keypad** - support for scanning keys and key matrices +* **microcontroller** - chip-specific pin identities +* **micropython** - MicroPython-specific module +* **neopixel_write** - low-level interface to NeoPixels +* **pulseio** - contains classes that provide access to basic pulse IO (PWM) +* **pwmio** - contains classes that provide access to basic pulse IO (PWM) +* **rainbowio** - provides the colorwheel() function +* **usb_hid** - act as a hid-device using usb_gadget kernel driver + +For details, see the `Blinka API reference +`_. -This repository contains a selection of packages mirroring the CircuitPython API -on hosts running micropython. At the time of writing drafts exist for +Dependencies +============= -* board - breakout-specific pin identities -* microcontroller - chip-specific pin identities -* digitalio - digital input/output pins, using pin identities from board/microcontroller +The emulation described above is intended to provide a +CircuitPython-like API for devices which are running CPython or +Micropython. Since corresponding packages should be built-in to any +standard CircuitPython image, they have no value on a device already +running CircuitPython and would likely conflict in unhappy ways. +The test suites in the test/src folder under **testing.universal** are by design +intended to run on *either* CircuitPython *or* CPython/Micropython+compatibility layer to prove conformance. -Dependencies -============= +Installing from PyPI +===================== -The CircuitPython compatibility layers described above are intended for devices which -are running Micropython. Given the top level packages should be provided by any standard -CircuitPython image, you shouldn't be trying to put those packages on any board -with CircuitPython already installed. +On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from +PyPI `_. To install for current user: -However, the test suites under testing.implementation.all are by design -intended to run on either CircuitPython or the Micropython+compatibility layer, so that -conformance can be achieved. +.. code-block:: shell + + pip3 install Adafruit-Blinka + +To install system-wide (this may be required in some cases): + +.. code-block:: shell -Similarly the test suites under testing.implementation.micropython should only be run -on Micropython and testing.implementation.circuitpython should only be run on CircuitPython + sudo pip3 install Adafruit-Blinka +To install in a virtual environment in your current project: + +.. code-block:: shell + + mkdir project-name && cd project-name + python3 -m venv .env + source .env/bin/activate + pip3 install Adafruit-Blinka Usage Example ============= -At the time of writing `git:3b2fc268 `, -the following sequence runs through some basic testing of the digitalio compatibility layer. +The pin names may vary by board, so you may need to change the pin names in the code. This +example runs on the Raspberry Pi boards to blink an LED connected to GPIO 18 (Pin 12): .. code-block:: python - import testing - testing.main() + import time + import board + import digitalio + + PIN = board.D18 + + print("hello blinky!") + + led = digitalio.DigitalInOut(PIN) + led.direction = digitalio.Direction.OUTPUT + while True: + led.value = True + time.sleep(0.5) + led.value = False + time.sleep(0.5) Contributing ============ Contributions are welcome! Please read our `Code of Conduct -`_ +`_ before contributing to help this project stay welcoming. Building locally @@ -72,7 +119,7 @@ install dependencies (feel free to reuse the virtual environment from above): python3 -m venv .env source .env/bin/activate - pip install Sphinx sphinx-rtd-theme + pip install Sphinx sphinx-rtd-theme Adafruit-PlatformDetect Now, once you have the virtual environment activated: