Let's walk through creating a new Jupyter Notebook using the CircuitPython Kernel.
To create a new Jupyter Notebook for use with the circuitpython kernel, navigate to the Notebook Dashboard and click New -> Notebook -> CircuitPython
Your notebook should connect to your board using the CircuitPython kernel. You can verify this by checking two things on the toolbar: the Trusted and CircuitPython badges should display
All Jupyter Notebooks contain three areas: menu, toolbar, and the code cells
The Menu contains actions on the notebook and the kernel. You can add/remove cells, restart the kernel, and perform file operations, all from the menubar.
The toolbar has buttons for common actions within the notebook. You can switch cell modes (between code/text), run/restart cells, and save the Notebook state.
Cells are text-input fields which can be executed (the code gets sent to the kernel) and display output. They're the interactive part of Jupyter, and a bit different from any other software out there. There are three different types of cells, we'll cover into the first two in this guide:
- Code Cells
- Markdown Cells
- Raw Cells
Like the Vim Editor, there are two different keyboard input modes in Jupyter which control whether you're controlling the notebook (command mode) or editing the code (edit mode) within a cell.
Command Mode allows you to perform notebook actions such as switching cell-type (code to markdown), executing code on the kernel, stopping the kernel and inserting cells. You can get into command mode by pressing the enter key, the cell will turn blue (green on newer versions of Jupyter).
To enter edit mode, press the escape key on your keyboard. The cell's border will turn blue and you're able to type into the text-box of the cell (multi-line code is supported).
Want to write some CircuitPython code? You'll need a code cell. You'll be able to execute the code cell using the run button on the toolbar or by pressing shift+enter
To create new code cell, click Insert -> Insert Cell Below (or Above)
Code Cells are also capable of returning errors from the CircuitPython REPL so you'll know when your code is broken.
Want to document your progress by adding text, images, rich media, or even equations? You'll want to use a Markdown Cell.
You can switch to a markdown cell by clicking the cell selection dropdown on the toolbar and clicking Markdown
Not familiar with the features of Markdown? Check out the Working with Markdown Cells example notebook
Finished writing in your notebook? Even if you've closed the tab where you're working in, the notebook is still running.
From your dashboard, navigate to the Running tab. You'll see your active notebooks, click Shutdown to shut the kernel down.
Now that we've learned about creating and editing a Jupyter Notebook, we're going to learn how to share it with others.
If your notebook is unresponsive, don't disconnect your board just yet. Code sometimes fails or freezes. Luckily, Jupyter Notebooks have controls for kernels built in so you can stop any errors/infinite loops you encounter.
First, we can interrupt the kernel's code execution by clicking kernel -> interrupt. This'll retain the program execution state and variables which may have been created earlier.
Still frozen? Try restarting your kernel. There are three options for this:
- Restart: Restarts the kernel and loses state (variables, etc). The board resets its connection with the kernel. The output from the previous run will be retained along with the cells.
- Restart & Clear Output: You can also restart (as explained above) and clear the output of your cells. The code/markdown within the cell will be retained.
- Restart & Run All: Restarts the kernel, loses variable states, reconnects the board, and runs all cells.
Still no luck? Having a critical issue?
You can reconnect (this will re-establish a connection with the board) or shutdown the kernel (however, all variables will be lost if you choose this).
Text editor powered by tinymce.
