micropython-magic

These Jupyter magic methods allow MicroPython to be used from within any Jupyter Notebook or JupyterLab (formerly IPython Notebook) The magics make use of the mpremote tool to enable communication with the MCUs

This allows:

• Mixing of Host and MCU Code ( and languages if you wish)
• Creating graphs of the data captured by MCU sensors
• create re-uasable sequences ( download/compile firmware - flash firmware - uploade code - run expiriment - same outcome)
• Create and execute tests that require orchestration across multiple MCUs and hosts
• Rapid Prototyping
• Capturing the results and outputs of your expiriments in a consistent way
• Mixing documentation with code

A few of the possibilities

Live Plot of the cpu temperature	Visualize the memory map of the MCU
	Memory allocation of the MCU over time

For the source please refer to the samples folder

Installation

• create and activate a venv python3 -m venv .venv

• pip install -U "micropython-magic"

• or install directly into your notbook environment/kernel using the '%pip' magic by running

  • %pip install -U "micropython-magic"

Recommended : install stubs for your MCU of choice

• Install stubs for MicroPython syntax checking pip install micropython-rp2-stubs (or your port of choise)

Usage

1) Create a notebook

• install your desired notebook environment:

  • VScode and the Juypyter extension ,
  • Jupyter Notebook
  • JupyterLab

• create a new notebook

2) Load the magic

%load_ext micropython_magic

This can also be configured once to always load automatically ( see below)

3) add a cell with some code to run on the MCU

# %%micropython  
from machine import Pin
led = Pin(25, Pin.OUT)
led.value(1)

The %%micropython cell magic will instruct Jupyter to run the code on the connected MCU

4) enable code highlighting for MicroPython

%pip install micropython-esp32-stubs==1.20.0.*
# installs the stubs for MicroPython syntax checking (one time install per environment) 

# %%micropython  
from machine import Pin
led = Pin(25, Pin.OUT)
led.value(1)

This allows for syntax highlighting and code completion of MicroPython code. Tested in VSCode with

• Python extension
• Pylance extension

More Examples

Please refer to the samples folder for more examples

1. install - install the magic
2. board_control - basic board control
3. board_selection. - list connected boards and loop through them
4. device_info - Get simple access to port, board and hardware and firmware information
5. WOKWI - Use MicroPython magic with WOKWI as a simulator (no device needed)
6. Plot rp2 CPU temp - create a plot of the CPU temperature of a rp2040 MCU(bqplot)
7. Display Memory Map - Micropython memory map visualizer
8. Plot Memory Usage - plot the memory usage of a Micropython script running on a MCU over time

Automatically load the magic on startup

In order to automatically load the magic on startup, you can add the following to your ipython_config.py file:

• create a ipython profile

  • ipython profile create

  • add the following to the configuration file (.../.ipython/profile_default/ipython_config.py)

    c = get_config()
    
    c.InteractiveShellApp.extensions = [
        'micropython_magic'
    ]

Configuration options

Configuration can be done via the %config magic

%config MicroPythonMagic

    MicroPythonMagic(Magics) options
    ------------------------------
    MicroPythonMagic.loglevel=<UseEnum>
        Choices: any of ['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR']
        Current: <LogLevel.WARNING: 'WARNING'>
    MicroPythonMagic.timeout=<Float>
        Current: 300.0

# example
%config MicroPythonMagic.loglevel = 'TRACE'

• loglevel : set the loglevel for the magic ( default WARNING)
• timeout : set the timeout for the mpremote connection ( default 300 seconds - 5 minutes)

Development and contributions

The most welcome contributions are :

• Testing on different platforms (OS) but also different Jupyter environments ( Jupyter Notebook, JupyterLab, VSCode)
• Provide additional sample notebooks
• Help add documentation (preferably in a notebook or .md file)
• Share this with other people that may be interested in this.

See current status and on Github