# micropython-magic
<img src="docs/logo_S.jpg" width="100" align="right">
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](https://github.com/micropython/micropython/blob/master/tools/mpremote/README.md) 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
<table>
<tr>
<td>
Live Plot of the cpu temperature
<img src="docs/cpu_plot.gif" width="300" />
</td>
<td>
Visualize the memory map of the MCU
<img src="docs/memory_map.gif" width="300" />
</td>
</tr>
<tr>
<td>
</td>
<td>
Memory allocation of the MCU over time
<img src="docs/memory_map_sequence.gif" width="300" />
</td>
</tr>
</table>
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**](https://code.visualstudio.com/docs/languages/python#_jupyter-notebooks) ,
- [Jupyter Notebook](https://jupyter.org/install#jupyter-notebook)
- [JupyterLab ](https://jupyter.org/install)
- create a new notebook
**2) Load the magic**
```python
%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**
```python
# %%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**
```python
%pip install micropython-esp32-stubs==1.20.0.*
# installs the stubs for MicroPython syntax checking (one time install per environment)
```
```python
# %%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](https://marketplace.visualstudio.com/items?itemName=ms-python.python) extension
- [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) extension
## More Examples
Please refer to the [samples folder](samples/) for more examples
1. [install](samples/install.ipynb) - install the magic
1. [board_control](samples/board_control.ipynb) - basic board control
1. [board_selection.](samples/board_selection.ipynb) - list connected boards and loop through them
1. [device_info](samples/device_info.ipynb) - Get simple access to port, board and hardware and firmware information
1. [WOKWI](samples/wokwi.ipynb) - Use MicroPython magic with WOKWI as a simulator (no device needed)
1. [Plot rp2 CPU temp](samples/plot_cpu_temp_rp2.ipynb) - create a plot of the CPU temperature of a rp2040 MCU(bqplot)
1. [Display Memory Map](samples/mem_info.ipynb) - Micropython memory map visualizer
1. [Plot Memory Usage](samples/mem_info-plot.ipynb) - plot the memory usage of a Micropython script running on a MCU over time
<!-- 1. [](samples/mem_info_list.ipynb) - not currently working used to trace the m -->
## 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`)
```python
c = get_config()
c.InteractiveShellApp.extensions = [
'micropython_magic'
]
```
## Configuration options
Configuration can be done via the `%config` magic
```python
%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](development_status.md) and on Github
Raw data
{
"_id": null,
"home_page": "",
"name": "micropython-magic",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "MicroPython,stubs,Jupyter,notebooks,Jupyter Labs,vscode",
"author": "Jos Verlinde",
"author_email": "jos_verlinde@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/fc/f0/a16667c8869e77ee29470caf959b015da5f9f21246e2529503a804aa7b26/micropython_magic-0.10.2.tar.gz",
"platform": null,
"description": "# micropython-magic\n\n\n\n\n\n<img src=\"docs/logo_S.jpg\" width=\"100\" align=\"right\">\n\n\n\nThese Jupyter magic methods allow MicroPython to be used from within any Jupyter Notebook or JupyterLab (formerly IPython Notebook)\nThe magics make use of the [mpremote tool](https://github.com/micropython/micropython/blob/master/tools/mpremote/README.md) to enable communication with the MCUs \n\n\nThis allows: \n * Mixing of Host and MCU Code ( and languages if you wish)\n * Creating graphs of the data captured by MCU sensors \n * create re-uasable sequences ( download/compile firmware - flash firmware - uploade code - run expiriment - same outcome) \n * Create and execute tests that require orchestration across multiple MCUs and hosts \n * Rapid Prototyping \n * Capturing the results and outputs of your expiriments in a consistent way\n * Mixing documentation with code \n\n\n## A few of the possibilities\n\n<table>\n\n<tr>\n<td>\nLive Plot of the cpu temperature \n\n<img src=\"docs/cpu_plot.gif\" width=\"300\" />\n</td>\n<td>\nVisualize the memory map of the MCU\n\n<img src=\"docs/memory_map.gif\" width=\"300\" />\n</td>\n</tr>\n\n<tr>\n<td>\n</td>\n<td>\nMemory allocation of the MCU over time\n\n<img src=\"docs/memory_map_sequence.gif\" width=\"300\" />\n</td>\n</tr>\n</table>\n\nFor the source please refer to the samples folder\n## Installation\n- create and activate a venv `python3 -m venv .venv`\n - [ ] `pip install -U \"micropython-magic\"`\n\n- or install directly into your notbook environment/kernel using the '%pip' magic by running\n - [ ] `%pip install -U \"micropython-magic\"`\n\nRecommended : install stubs for your MCU of choice\n- [ ] Install stubs for MicroPython syntax checking `pip install micropython-rp2-stubs` (or your port of choise)\n\n## Usage\n\n**1) Create a notebook**\n- install your desired notebook environment:\n - [VScode and the **Juypyter extension**](https://code.visualstudio.com/docs/languages/python#_jupyter-notebooks) ,\n - [Jupyter Notebook](https://jupyter.org/install#jupyter-notebook) \n - [JupyterLab ](https://jupyter.org/install)\n\n- create a new notebook \n\n**2) Load the magic**\n```python\n%load_ext micropython_magic\n```\nThis can also be configured once to always load automatically ( see below)\n\n\n**3) add a cell with some code to run on the MCU**\n```python\n# %%micropython \nfrom machine import Pin\nled = Pin(25, Pin.OUT)\nled.value(1)\n```\nThe `%%micropython` cell magic will instruct Jupyter to run the code on the connected MCU\n\n**4) enable code highlighting for MicroPython**\n```python\n%pip install micropython-esp32-stubs==1.20.0.*\n# installs the stubs for MicroPython syntax checking (one time install per environment) \n```\n\n```python\n# %%micropython \nfrom machine import Pin\nled = Pin(25, Pin.OUT)\nled.value(1)\n```\nThis allows for syntax highlighting and code completion of MicroPython code.\nTested in VSCode with\n- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) extension\n- [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) extension\n\n## More Examples\n\nPlease refer to the [samples folder](samples/) for more examples\n\n\n1. [install](samples/install.ipynb) - install the magic \n1. [board_control](samples/board_control.ipynb) - basic board control\n1. [board_selection.](samples/board_selection.ipynb) - list connected boards and loop through them\n1. [device_info](samples/device_info.ipynb) - Get simple access to port, board and hardware and firmware information\n1. [WOKWI](samples/wokwi.ipynb) - Use MicroPython magic with WOKWI as a simulator (no device needed)\n1. [Plot rp2 CPU temp](samples/plot_cpu_temp_rp2.ipynb) - create a plot of the CPU temperature of a rp2040 MCU(bqplot)\n1. [Display Memory Map](samples/mem_info.ipynb) - Micropython memory map visualizer\n1. [Plot Memory Usage](samples/mem_info-plot.ipynb) - plot the memory usage of a Micropython script running on a MCU over time\n\n<!-- 1. [](samples/mem_info_list.ipynb) - not currently working used to trace the m -->\n\n\n\n## Automatically load the magic on startup\n\nIn order to automatically load the magic on startup, you can add the following to your `ipython_config.py` file:\n\n- create a ipython profile \n - `ipython profile create`\n - add the following to the configuration file (`.../.ipython/profile_default/ipython_config.py`)\n\n ```python\n c = get_config()\n\n c.InteractiveShellApp.extensions = [\n 'micropython_magic'\n ]\n ```\n## Configuration options\n\nConfiguration can be done via the `%config` magic\n\n```python\n%config MicroPythonMagic\n\n MicroPythonMagic(Magics) options\n ------------------------------\n MicroPythonMagic.loglevel=<UseEnum>\n Choices: any of ['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR']\n Current: <LogLevel.WARNING: 'WARNING'>\n MicroPythonMagic.timeout=<Float>\n Current: 300.0\n\n# example\n%config MicroPythonMagic.loglevel = 'TRACE'\n```\n- loglevel : set the loglevel for the magic ( default WARNING)\n- timeout : set the timeout for the mpremote connection ( default 300 seconds - 5 minutes)\n\n## Development and contributions\n\nThe most welcome contributions are : \n- Testing on different platforms (OS) but also different Jupyter environments ( Jupyter Notebook, JupyterLab, VSCode)\n- Provide additional sample notebooks \n- Help add documentation (preferably in a notebook or .md file)\n- Share this with other people that may be interested in this.\n\n[See current status](development_status.md) and on Github\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MicroPython Magic commands for use with Jupyter notebooks and Jupyter Labs",
"version": "0.10.2",
"project_urls": null,
"split_keywords": [
"micropython",
"stubs",
"jupyter",
"notebooks",
"jupyter labs",
"vscode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f81b620f5428ed6f857d95890458e4cfb9e4f1088df471612b32d8866573ef8c",
"md5": "52e5e50a931da607c5f37cbb8b150566",
"sha256": "29c0697cd59ebc35e8e0292f7bb3917861943893b294133c35837fa4158e5217"
},
"downloads": -1,
"filename": "micropython_magic-0.10.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52e5e50a931da607c5f37cbb8b150566",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 27012,
"upload_time": "2024-01-24T14:38:57",
"upload_time_iso_8601": "2024-01-24T14:38:57.107024Z",
"url": "https://files.pythonhosted.org/packages/f8/1b/620f5428ed6f857d95890458e4cfb9e4f1088df471612b32d8866573ef8c/micropython_magic-0.10.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fcf0a16667c8869e77ee29470caf959b015da5f9f21246e2529503a804aa7b26",
"md5": "eff41118b5bba83f4ac48ef428cc2f0a",
"sha256": "5094a986d056968f92cc768c8b6b9b078b6f64e17c0e4f4e00e560a66fa00e1b"
},
"downloads": -1,
"filename": "micropython_magic-0.10.2.tar.gz",
"has_sig": false,
"md5_digest": "eff41118b5bba83f4ac48ef428cc2f0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 25875,
"upload_time": "2024-01-24T14:38:58",
"upload_time_iso_8601": "2024-01-24T14:38:58.945741Z",
"url": "https://files.pythonhosted.org/packages/fc/f0/a16667c8869e77ee29470caf959b015da5f9f21246e2529503a804aa7b26/micropython_magic-0.10.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-24 14:38:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "micropython-magic"
}
JSON