update documentation

Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>

Author: Josverl

development_status.md

@@ -0,0 +1,74 @@
+
+# initial 
+
+ - [x] run a code cell on a MCU 
+ - [x] mpremote primitives
+   - [x] list connected boards and loop through them 
+   - [x] switch the active MCU
+   - [x] avoid resetting MCU between cells ( use `resume`)
+   - [x] soft-reset a MCU
+   - [/] hard-reset a MCU
+       - only works on non-rp2040 devices 
+       - report / fix hardware reset  issue on rp2040 `machine.reset()` ?
+   - [x] mount folder 
+   - [?] recursive delete wipe files from MCU - as a built-in magic ? / wait for / create PR for mpremote update ?
+   - [x] cellmagic to copy cell content to specific files on the MCS 
+       - [x] %%micropython --writefile main.py
+       - [x] %%micropython --readfile boot.py
+
+
+   **`!mpremote` can be use to run any other command**
+   - [x] **`!mpremote`** mip install 
+   - [x] direct - copy file / files to / from 
+   - [x] ls and other file operations 
+- [ ] Notebook essentials
+   - [x] load magics from `%pip install micropython-magic`
+   - [x] get the output from the MCU into a python variable `local = %eval remote`
+         - eval is not quite the same as mpremote
+         - [x] retain type through json - works for the majority of standard types
+         - [?] can this be done with repr(instead) of json ?
+   - [x] plot data from a MCU
+            - [x] using bqplot ( > pyplot > vscode-Jupyter) 
+            - [/] add documentation / sample
+-   
+   - [ ] copy/echo MCU global vars to local vars ( sync_from / sync_to)?
+   - [ ] get a data series onto the notebook and plot the outcome 
+       - [x] loop one by one and update plot
+       - [ ] get larger series 
+   - [ ] loop and update plot 
+         https://ipywidgets.readthedocs.io/en/7.x/examples/Widget%20Asynchronous.html#Updating-a-widget-in-the-background
+   - [ ] long running via mqtt / async / folder mount ?
+ - [ ] is there a way to avoid needing to set %%micropython on all cells ?
+       this could be done via an input_transformer - but keeping the state between cells may be quite hard / confusing
+ - [ ] %timeit / %%timeit for micropython code to avoid measuring the mpremote startup overhead 
+
+Samples
+   - [x] Install
+   - [x] basic board control
+   - [x] blink
+   - [x] list connected boards and loop through them 
+   - [~] read sensor and build series ( file / list / plot)
+   - [ ] flash a mcu with new firmware ( sample per port )
+   - [ ] mip install 
+   - [ ] upload a repo / folder to a MCU
+
+## development
+## Testing 
+
+- using Pytest
+- using testbook for testing notebooks
+  - located in the `./tests/` folder
+  - tests are paired with notebooks that contain the cells and magic commands to be tested
+  - tests have not been mocked - and therefore require a connected MCU to run ( rp2040 )
+
+  - [x] Local on windows
+    - [x] on windows 
+    - [x] on linux
+    - [ ] on MacOS
+  - Manual test:
+    - [x] jupyter notebook
+    - [x] jupyter labs 
+
+  - [ ] CI - using WOKWI as a device simulator ? 
+        Blocked as WOKWI CI does not implement serial connection
+

docs/logo.jpg

@@ -1,5 +1,12 @@
 # micropython-magic
-[![CodeFactor](https://www.codefactor.io/repository/github/josverl/micropython-magic/badge/main)](https://www.codefactor.io/repository/github/josverl/micropython-magic/overview/main)
+![PyPI](https://img.shields.io/pypi/v/micropython-magic?style=plastic)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/micropython-magic?style=plastic)
+![PyPI - License](https://img.shields.io/pypi/l/micropython-magic?style=plastic)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/micropython-magic?style=plastic)
+
+<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 
@@ -9,20 +16,19 @@ 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 
+ * Create and execute tests that require orchestration across multiple MCUs and hosts 
  * Rapid Prototyping 
- * Capturing the results and outputs in a consistent way
+ * Capturing the results and outputs of your expiriments in a consistent way
  * Mixing documentation with code  
 
 
-
-## Samples 
+## A few of the possibilities
 
 <table>
 
 <tr>
 <td>
-Plot cpu temperature  
+Live Plot of the cpu temperature  
 
 <img src="docs/cpu_plot.gif" width="300" />
 </td>
@@ -98,12 +104,23 @@ 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 -->
+
 
-## Advanced 
-List the connected devices 
-```python
-%mpy --list
-```
 
 ## Automatically load the magic on startup
 
@@ -114,77 +131,39 @@ In order to automatically load the magic on startup, you can add the following t
   - add the following to the configuration file (`.../.ipython/profile_default/ipython_config.py`)
 
     ```python
-    c = get_config()  #noqa
+    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
 
-# initial 
-
- - [x] run a code cell on a MCU 
- - [ ] mpremote primitives
-   - [x] list connected boards and loop through them 
-   - [x] switch the active MCU
-   - [x] avoid resetting MCU between cells ( use `resume`)
-   - [x] soft-reset a MCU
-   - [/] hard-reset a MCU
-       - only works on non-rp2040 devices 
-       - report / fix hardware reset  issue on rp2040 `machine.reset()` ?
-   - all mpremote commands are possible using `!mpremote`
-   - [ ] mip install 
-   - [ ] direct - copy file / files to / from 
-   - [ ] mount folder 
-   - [ ] ls and other file operations 
-   - [ ] recursive delete wipe files from MCU - as a built-in magic ? / wait for / create PR for mpremote update ?
-   - [ ] cellmagic to copy cell content to specific files on the MCS 
-       - [ ] %%micropython --writefile main.py
-       - [ ] %%micropython --readfile boot.py
-- [ ] Notebook essentials
-   - [x] load magics from `%pip install micropython-magic`
-   - [x] get the output from the MCU into a python variable `local = %eval remote`
-         - eval is not quite the same as mpremote
-         - retain type through json ?
-         - [?] can this be done with repr(insted) of json ?
-   - [x] plot data from a MCU
-            - [x] using bqplot ( > pyplot > vscode-Jupyter) 
-            - [/] add documentation / sample
--   
-   - [ ] copy/echo MCU global vars to local vars ( sync_from / sync_to)?
-   - [ ] get a data series onto the notebook and plot the outcome 
-       - [x] loop one by one and update plot
-       - [ ] get larger series 
-   - [ ] loop and update plot 
-         https://ipywidgets.readthedocs.io/en/7.x/examples/Widget%20Asynchronous.html#Updating-a-widget-in-the-background
-   - [ ] long running via mqtt / async / folder mount ?
- - [ ] is there a way to avoid needing to set %%micropython on all cells ?
-       this could be done via an input_transformer - but keeping the state between cells may be quuite hard / confusing
- - [ ] %timeit / %%timeit for micropython code to avoid measuring the mpremote startup overhead 
-
-Samples
-   - [x] Install
-   - [x] basic board control
-   - [x] blink
-   - [x] list connected boards and loop through them 
-   - [~] read sensor and build series ( file / list / plot)
-   - [ ] flash a mcu with new firmware ( sample per port )
-   - [ ] mip install 
-   - [ ] upload a repo / folder to a MCU
-
-## development
-## Testing 
-
-- using Pytest
-- using testbook for testing notebooks
-  - located in the `./tests/` folder
-  - tests are paired with notebooks that contain the cells and magic commands to be tested
-  - tests have not been mocked - and therefore require a connected MCU to run ( rp2040 )
-
-- TODO: add tests for (remote) kernels 
-  - [x] Local (on windows)
-  - [ ] on windows 
-  - [ ] on linux
-  - [ ] jupyter notebook
-  - [ ] jupyter labs 
+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

docs/logo_M.jpg

@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**Get simple access to port, board and firmware information and many other details**"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -137,7 +144,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.11.7"
   },
   "orig_nbformat": 4
  },

docs/logo_S.jpg

@@ -215,28 +215,30 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [
     {
-     "ename": "ConnectionError",
-     "evalue": "no device found",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[1;31mConnectionError\u001b[0m                           Traceback (most recent call last)",
-      "Cell \u001b[1;32mIn[12], line 1\u001b[0m\n\u001b[1;32m----> 1\u001b[0m get_ipython()\u001b[39m.\u001b[39;49mrun_line_magic(\u001b[39m'\u001b[39;49m\u001b[39mmpy\u001b[39;49m\u001b[39m'\u001b[39;49m, \u001b[39m'\u001b[39;49m\u001b[39m--eval 2*3*7\u001b[39;49m\u001b[39m'\u001b[39;49m)\n",
-      "File \u001b[1;32mc:\\develop\\MyPython\\micropython-magic\\.venv\\Lib\\site-packages\\IPython\\core\\interactiveshell.py:2414\u001b[0m, in \u001b[0;36mInteractiveShell.run_line_magic\u001b[1;34m(self, magic_name, line, _stack_depth)\u001b[0m\n\u001b[0;32m   2412\u001b[0m     kwargs[\u001b[39m'\u001b[39m\u001b[39mlocal_ns\u001b[39m\u001b[39m'\u001b[39m] \u001b[39m=\u001b[39m \u001b[39mself\u001b[39m\u001b[39m.\u001b[39mget_local_scope(stack_depth)\n\u001b[0;32m   2413\u001b[0m \u001b[39mwith\u001b[39;00m \u001b[39mself\u001b[39m\u001b[39m.\u001b[39mbuiltin_trap:\n\u001b[1;32m-> 2414\u001b[0m     result \u001b[39m=\u001b[39m fn(\u001b[39m*\u001b[39;49margs, \u001b[39m*\u001b[39;49m\u001b[39m*\u001b[39;49mkwargs)\n\u001b[0;32m   2416\u001b[0m \u001b[39m# The code below prevents the output from being displayed\u001b[39;00m\n\u001b[0;32m   2417\u001b[0m \u001b[39m# when using magics with decodator @output_can_be_silenced\u001b[39;00m\n\u001b[0;32m   2418\u001b[0m \u001b[39m# when the last Python token in the expression is a ';'.\u001b[39;00m\n\u001b[0;32m   2419\u001b[0m \u001b[39mif\u001b[39;00m \u001b[39mgetattr\u001b[39m(fn, magic\u001b[39m.\u001b[39mMAGIC_OUTPUT_CAN_BE_SILENCED, \u001b[39mFalse\u001b[39;00m):\n",
-      "File \u001b[1;32mC:\\develop\\MyPython\\micropython-magic\\src\\micropython_magic\\octarine.py:247\u001b[0m, in \u001b[0;36mMpyMagics.mpy_line\u001b[1;34m(self, line)\u001b[0m\n\u001b[0;32m    245\u001b[0m     \u001b[39mreturn\u001b[39;00m \u001b[39mself\u001b[39m\u001b[39m.\u001b[39mlist_devices()\n\u001b[0;32m    246\u001b[0m \u001b[39melif\u001b[39;00m args\u001b[39m.\u001b[39meval:\n\u001b[1;32m--> 247\u001b[0m     \u001b[39mreturn\u001b[39;00m \u001b[39mself\u001b[39;49m\u001b[39m.\u001b[39;49meval(args\u001b[39m.\u001b[39;49meval)\n\u001b[0;32m    249\u001b[0m \u001b[39melif\u001b[39;00m args\u001b[39m.\u001b[39mstatement:\n\u001b[0;32m    250\u001b[0m     \u001b[39m# Assemble the command to run\u001b[39;00m\n\u001b[0;32m    251\u001b[0m     statement \u001b[39m=\u001b[39m \u001b[39m\"\u001b[39m\u001b[39m\\n\u001b[39;00m\u001b[39m\"\u001b[39m\u001b[39m.\u001b[39mjoin(args\u001b[39m.\u001b[39mstatement)\n",
-      "File \u001b[1;32mC:\\develop\\MyPython\\micropython-magic\\src\\micropython_magic\\octarine.py:272\u001b[0m, in \u001b[0;36mMpyMagics.eval\u001b[1;34m(self, line)\u001b[0m\n\u001b[0;32m    270\u001b[0m cmd \u001b[39m=\u001b[39m \u001b[39mf\u001b[39m\u001b[39m'''\u001b[39m\u001b[39mexec \u001b[39m\u001b[39m\"\u001b[39m\u001b[39mimport json; print(\u001b[39m\u001b[39m'\u001b[39m\u001b[39m{\u001b[39;00mJSON_START\u001b[39m}\u001b[39;00m\u001b[39m'\u001b[39m\u001b[39m,json.dumps(\u001b[39m\u001b[39m{\u001b[39;00mstatement\u001b[39m}\u001b[39;00m\u001b[39m),\u001b[39m\u001b[39m'\u001b[39m\u001b[39m{\u001b[39;00mJSON_END\u001b[39m}\u001b[39;00m\u001b[39m'\u001b[39m\u001b[39m)\u001b[39m\u001b[39m\"\u001b[39m\u001b[39m'''\u001b[39m\n\u001b[0;32m    271\u001b[0m \u001b[39m# print(cmd)\u001b[39;00m\n\u001b[1;32m--> 272\u001b[0m output \u001b[39m=\u001b[39m \u001b[39mself\u001b[39;49m\u001b[39m.\u001b[39;49mMCU\u001b[39m.\u001b[39;49mrun_cmd(cmd)\n\u001b[0;32m    273\u001b[0m matchers \u001b[39m=\u001b[39m [\u001b[39mr\u001b[39m\u001b[39m\"\u001b[39m\u001b[39m^.*Error:\u001b[39m\u001b[39m\"\u001b[39m, \u001b[39mr\u001b[39m\u001b[39m\"\u001b[39m\u001b[39m^.*Exception:\u001b[39m\u001b[39m\"\u001b[39m]\n\u001b[0;32m    275\u001b[0m \u001b[39mfor\u001b[39;00m ln \u001b[39min\u001b[39;00m output\u001b[39m.\u001b[39ml:\n\u001b[0;32m    276\u001b[0m     \u001b[39m# check for errors and raise them\u001b[39;00m\n",
-      "File \u001b[1;32mC:\\develop\\MyPython\\micropython-magic\\src\\micropython_magic\\mpr.py:45\u001b[0m, in \u001b[0;36mMPRemote2.run_cmd\u001b[1;34m(self, cmd, auto_connect)\u001b[0m\n\u001b[0;32m     43\u001b[0m \u001b[39massert\u001b[39;00m \u001b[39misinstance\u001b[39m(output, SList)\n\u001b[0;32m     44\u001b[0m \u001b[39mif\u001b[39;00m \u001b[39mlen\u001b[39m(output) \u001b[39m>\u001b[39m \u001b[39m0\u001b[39m \u001b[39mand\u001b[39;00m output[\u001b[39m0\u001b[39m]\u001b[39m.\u001b[39mstrip() \u001b[39m==\u001b[39m \u001b[39m\"\u001b[39m\u001b[39mno device found\u001b[39m\u001b[39m\"\u001b[39m:\n\u001b[1;32m---> 45\u001b[0m     \u001b[39mraise\u001b[39;00m \u001b[39mConnectionError\u001b[39;00m(\u001b[39m\"\u001b[39m\u001b[39mno device found\u001b[39m\u001b[39m\"\u001b[39m)\n\u001b[0;32m     46\u001b[0m \u001b[39mreturn\u001b[39;00m output\n",
-      "\u001b[1;31mConnectionError\u001b[0m: no device found"
-     ]
+     "data": {
+      "text/plain": [
+       "42"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
     }
    ],
    "source": [
     "%mpy --eval 2*3*7 "
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {