CircuitPython Kernel¶

Contents:

CircuitPython Kernel¶

https://cdn-learn.adafruit.com/guides/images/000/002/051/medium310/Untitled-3.png?1528919538

The CircuitPython Kernel is a Jupyter Kernel designed to interact with Adafruit boards running CircuitPython from within a Jupyter Notebook

Status¶

This project’s status is experimental. It has been tested with CircuitPython (SAMD) boards and the Feather HUZZAH (ESP8266) using CircuitPython 2.x Stable and 3.0.0 Beta 1.

It may break, and if it does, please file an issue on this repository.

Compatible Boards¶

Designed for CircuitPython (SAMD21 and SAMD51)¶

Other Boards¶

Adafruit Feather HUZZAH ESP8266

Download¶

Official .zip files are available through the latest GitHub releases.

Documentation¶

This kernel is fully documented on the Adafruit Learning System (Guide Coming Soon!)

There’s also documentation for this kernel listed on the ReadTheDocs page for this repo..

Installing Jupyter¶

Option 1. Installing Jupyter with Anaconda

Don’t have a Python installation on your computer? If you’re new to all this, the Jupyter Project recommends installing Anaconda , which installs Python, the Jupyter Notebook, and other commonly used packages for scientific computing and data science.

Option 2. Installing Jupyter with PIP

If you have a Python installation already on your computer, you may want to use the Python package manager (pip) instead of Anaconda. You’ll need Python 3.3+.

First, ensure that you have the latest version of pip:

$ pip3 install --upgrade pip

Install the Jupyter Notebook using:

$ pip3 install jupyter

Ok, now that we have Jupyter installed, let’s start the notebook server.

We can launch the server from a command line (either Terminal on macOS/Linux or Command Prompt on Windows) by running:

$ jupyter notebook

If your installation went well, you’ll see information about the notebook server in your command line. Also, your web browser will open to the URL displayed in your command line (http://localhost:8888), displaying the Notebook Dashboard.

Installing the CircuitPython Kernel¶

First, clone this repository.

$ git clone https://github.com/adafruit/circuitpython_kernel.git

Navigate into the cloned repository directory. Install this kernel into Jupyter by running:

$ pip3 install circuitpython_kernel

Then, run

$ python3 -m circuitpython_kernel.install

if you encounter errors running this command on macOS/Linux, you’ll need to prefix this command with sudo

Finally, let’s verify the kernel was installed correctly in Jupyter. To do this, run:

$ jupyter kernelspec list

Your output should show circuitpython as an available kernel:

https://cdn-learn.adafruit.com/assets/assets/000/055/226/original/circuitpython_jupyter-kernelspec-list.png?1528483983

Launching a CircuitPython Notebook¶

Launch jupyter by running:

$ jupyter notebook

Make sure your board is plugged into USB and running CircuitPython by opening a file explorer. It should show up as a removable drive named CIRCUITPY.

Then click new -> circuitpython to open a new CircuitPython Notebook

https://cdn-learn.adafruit.com/assets/assets/000/055/305/original/circuitpython_newnotebook.gif?1528755209

A new CircuitPython Notebook should open and you should be able to execute code from within a cell.

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/adafruit/circuitpython_kernel/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation¶

CircuitPython Kernel could always use more documentation, whether as part of the official CircuitPython Kernel docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/adafruit/circuitpython_kernel/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up circuitpython_kernel for local development.

Fork the circuitpython_kernel repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/circuitpython_kernel.git

Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
```
$ mkvirtualenv circuitpython_kernel
$ cd circuitpython_kernel/
$ python setup.py develop
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
```
$ flake8 circuitpython_kernel tests
$ python setup.py test or py.test
$ tox
```
To get flake8 and tox, just pip install them into your virtualenv.

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check https://travis-ci.org/adafruit/circuitpython_kernel/pull_requests and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ python -m unittest tests.test_circuitpython_kernel

Credits¶

Development Lead¶

Carol Willing <carolcode@willingconsulting.com>

Contributors¶

Brent Rubell <brent@adafruit.com>

History¶

0.2.0 (2018-02-08)¶

update examples

0.1.0 (2017-03-23)¶

First release on PyPI.

Board Preparation¶

Before you start using the CircuitPython_Kernel, you’ll need a board running CircuitPython. If you’re not sure if the board plugged into your computer is running CircuitPython, check your file explorer for a drive named CIRCUITPY

Designed for CircuitPython (SAMD21 and SAMD51)¶

Boards Supported:¶

Installing CircuitPython Firmware¶

Download the CircuitPython Firmware (.uf2 file) from the CircuitPython Repo
Plug in board and double click the reset button to enter bootloader mode.
Drag and drop the *.uf2 CircuitPython file to the USB drive.
If you see the CIRCUITPY as the new name of the USB drive, you’re ready to go.

Adafruit Feather Huzzah ESP8266¶

While they do work with CircuitPython_Kernel, ESP8266-based boards require a different type of installation and configuration from the boards designed for circuitpython.

Installing CircuitPython Firmware¶

python3 -m pip install esptool
- Download the CircuitPython Firmware (.bin file) from the CircuitPython Repo
Install the SiLabs CP210x driver
Erase flash python3 esptool.py --port /path/to/ESP8266 erase_flash
Load firmware: esptool.py --port /path/to/ESP8266 --baud 460800 write_flash --flash_size=detect 0 firmware.bin
Press reset or unplug/plug the board.

Access the REPL¶

Use screen program:

screen <device> 115200

ampy¶

Install ampy python3 -m pip install adafruit-ampy
To get options for listing files and moving files: ampy --help

CircuitPython Kernel¶