{"id":14967277,"url":"https://github.com/goatchurchprime/jupyter_micropython_kernel","last_synced_at":"2025-04-07T12:07:55.446Z","repository":{"id":43043277,"uuid":"103026362","full_name":"goatchurchprime/jupyter_micropython_kernel","owner":"goatchurchprime","description":"Jupyter kernel to interact with a MicroPython/ESP8266 over the serial REPL","archived":false,"fork":false,"pushed_at":"2023-05-04T18:10:15.000Z","size":115,"stargazers_count":155,"open_issues_count":28,"forks_count":34,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-31T09:04:20.793Z","etag":null,"topics":["jupyter","micropython","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goatchurchprime.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-10T12:08:22.000Z","updated_at":"2025-03-23T09:06:17.000Z","dependencies_parsed_at":"2024-09-14T04:02:08.578Z","dependency_job_id":null,"html_url":"https://github.com/goatchurchprime/jupyter_micropython_kernel","commit_stats":{"total_commits":71,"total_committers":4,"mean_commits":17.75,"dds":"0.14084507042253525","last_synced_commit":"9f781d2e01503c08928b74091ec313dcf8af8f96"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatchurchprime%2Fjupyter_micropython_kernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatchurchprime%2Fjupyter_micropython_kernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatchurchprime%2Fjupyter_micropython_kernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatchurchprime%2Fjupyter_micropython_kernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goatchurchprime","download_url":"https://codeload.github.com/goatchurchprime/jupyter_micropython_kernel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648977,"owners_count":20972945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter","micropython","python"],"created_at":"2024-09-24T13:37:46.672Z","updated_at":"2025-04-07T12:07:55.426Z","avatar_url":"https://github.com/goatchurchprime.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jupyter MicroPython Kernel\n\nJupyter kernel to interact with a MicroPython ESP8266 or ESP32 over its serial REPL.  \n\nAlso with capabilities to work through the WEBREPL (available on ESP8266 only), \ndo Ctrl-C, transfer files and esptools flashing (useful for deployment).\nSee https://github.com/goatchurchprime/jupyter_micropython_developer_notebooks \nfor examples.\n\n## Installation\n\nFirst install Jupyter: http://jupyter.org/install.html (the Python3 version).\n**They strongly recommended you use the [Anaconda Distribution](https://www.anaconda.com/download/)**\n\n### Via PyPi\n\n```\npip install jupyter_micropython_kernel\npython -m jupyter_micropython_kernel.install\n```\n\n### Manual Installation (more maintainable)\n\nClone this repository to a directory using TortoiseGIT or with the shell command (ie on a command line):\n\n    git clone https://github.com/goatchurchprime/jupyter_micropython_kernel.git\n\nOn **Windows**, Install this library (in editable mode) into Python3 using the shell command:\n\n    pip install jupyter_micropython_kernel\n\nOn **Linux**, you can install this library in editable mode using symlinks, which makes it easy to `git pull` a debugged version later:\n\n    pip install -e jupyter_micropython_kernel\n\nThings can go wrong here, and you might need \"pip3\" or \"sudo pip\" if you have \nnumerous different versions of python installed\n\nInstall the kernel into jupyter itself using the shell command:\n\n    python -m jupyter_micropython_kernel.install\n\nThis creates the small file \".local/share/jupyter/kernels/micropython/kernel.json\" \nthat jupyter uses to reference it's kernels\n\n### Post-Install\n\nTo find out where your kernelspecs are stored, you can type:\n\n    jupyter kernelspec list\n\n\n## Running\n\nNow run Jupyter notebooks:\n\n    jupyter notebook\n\nIn the notebook click the New notebook button in the upper right, you should see your\nMicroPython kernel display name listed.  \n\nIf you have an ESP32 or ESP8266 already running MicroPython, plug it in, put the following command into the first cell and run it:\n\n    %serialconnect\n    \nIf you are on **Linux** and don't have the correct permissions to access the Serial ports you will get a \"permissions error\".  Fix it by adding yourself to the dialout and tty groups:\n\n    sudo usermod -a -G tty your_user_name\n    sudo usermod -a -G dialout your_user_name\n\nIf you are on **Windows** you need to have the right driver for the USB chip on the ESP32/ESP8266 breakout board.  \nLook for the USB connection in the Device List to identify the supplier and look for instructions relating to that supplier.  \n\nThe notebook scans the serial ports (the COM-values in Windows) and tells you the possibilities and tries one of them.  If it picks the wrong port you may need to be more specific and use the command:\n\n    %serialconnect --port=COM5\n\n## Uploading the MicroPython firmware onto a new board \n\nThis is done using the `esptool.py`.  The Jupyter micropython kernel has features to help you execute this command.  \n\n    %esptool erase\n\nand\n\n    %esptool esp8266 /home/julian/executables/micropythonbins/esp8266-20200902-v1.13.bin\n\nor\n\n    %esptool esp32 /home/julian/executables/micropythonbins/esp32-20191006-v1.11-406-g4a6974bea.bin\n\nDownload these Micropython firmware files from https://micropython.org/download\n\n\n## Further notes\n\nThere is a micropythondemo.ipynb file in the directory you could \nlook at with some of the features shown.\n\nIf a cell is taking too long to interrupt, it may respond \nto a \"Kernel\" -\u003e \"Interrupt\" command. \n\nAlternatively hit Escape and then 'i' twice.\n\nTo upload the contents of a cell to a file, write: \n    %sendtofile yourfilename.py \n    \nas the first line of the cell\n\nTo do a soft reboot (when you need to clear out the modules \nand recover some memory) type:\n    %reboot\n\nNote: Restarting the kernel does not actually reboot the device.  \nAlso, pressing the reset button will probably mess things up, because \nthis interface relies on the ctrl-A non-echoing paste mode to do its stuff.\n\nYou can list all the functions with:\n    %lsmagic\n\n\n## Debugging\n\nFor reference, the notebooks here might be useful:\n  https://github.com/goatchurchprime/jupyter_micropython_developer_notebooks\n\nThe system works by finding and connecting to a serial line and\nthen issuing the enter paste mode command Ctrl-A (hex 0x01)\n\nIn this mode blocks of to-be-executed text are ended with a Ctrl-D\n(hex 0x04).\n\nThe response that comes back begins with an \"OK\" followed by the \nactual program response, followed by Ctrl-D, followed by any \nerror messages, followed by a second Ctrl-D, followed by a '\u003e'.\n\nYou can implement this interface (for debugging purposes) to find out \nhow it's snarling up beginning with:\n \"%serialconnect --raw\"\nand then doing\n %writebytes -b \"sometext\"\nand \n %readbytes\n \n## Background\n\nThis had been proposed as an enhancement to webrepl with the idea of a jupyter-like \ninterface to webrepl rather than their faithful emulation of a command line: https://github.com/micropython/webrepl/issues/32\n\nMy first implementation operated a spawned-process asyncronous sub-kernel that handled the serial connection. \nAscync technology requires the whole program to work this way, or none of it.  \nSo my next iteration was going to do it using standard python threads to handle the blocking \nof the serial connections.  \n\nHowever, further review proved that this was unnecessarily complex if you consider the whole \nkernel itself to be operating asyncronously with the front end notebook UI.  In particular, \nif the notebook can independently issue Ctrl-C KeyboardInterrupt signals into the kernel, there is no longer \na need to worry about what happens when it hangs waiting for input from a serial connection.  \n\nOther known projects that have implemented a Jupyter Micropython kernel are:\n* https://github.com/adafruit/jupyter_micropython_kernel\n* https://github.com/willingc/circuitpython_kernel\n* https://github.com/TDAbboud/mpkernel\n* https://github.com/takluyver/ubit_kernel\n* https://github.com/jneines/nodemcu_kernel\n* https://github.com/zsquareplusc/mpy-repl-tool\n\nIn my defence, this is not an effect of not-invented-here syndrome; I did not discover most of these \nother projects until I had mostly written this one.  \n\nI do think that for robustness it is important to expose the full processes \nof making connections.  For my purposes this is more robust and contains debugging (of the \nserial connections) capability through its %lsmagic functions.\n\nOther known projects to have made Jupyter-like or secondary interfaces to Micropython:\n* https://github.com/nickzoic/mpy-webpad\n* https://github.com/BetaRavener/uPyLoader\n\nThe general approach of all of these is to make use of the Ctrl-A \npaste mode with its Ctrl-D end of message signals.  \nThe problem with this mode is it was actually designed for \nautomatic testing rather than supporting an interactive REPL (Read Execute Print Loop) system\n(citation required), so there can be reliability issues to do with \naccidentally escaping from this mode or not being able to detect the state \nof being in it.  \n\nFor example, you can't safely do a Ctrl-B to leave the paste mode and then a \nCtrl-A to re-enter paste mode cleanly, because a Ctrl-B in the non-paste mode \nwill reboot the device.  \n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatchurchprime%2Fjupyter_micropython_kernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoatchurchprime%2Fjupyter_micropython_kernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatchurchprime%2Fjupyter_micropython_kernel/lists"}