{"id":13802696,"url":"https://github.com/Carglglz/jupyter_upydevice_kernel","last_synced_at":"2025-05-13T13:32:36.197Z","repository":{"id":43372289,"uuid":"240072957","full_name":"Carglglz/jupyter_upydevice_kernel","owner":"Carglglz","description":"Jupyter MicroPython Kernel made with upydevice","archived":false,"fork":false,"pushed_at":"2022-03-04T21:12:38.000Z","size":585,"stargazers_count":15,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-25T05:07:06.460Z","etag":null,"topics":["atom","ble","hydrogen-atom","ipython","jupyter","jupyter-notebook","jupyterlab","micropython","serial","vscode","webrepl"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/jupyter-micropython-upydevice/","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/Carglglz.png","metadata":{"files":{"readme":"README.rst","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-12T17:28:43.000Z","updated_at":"2025-04-23T21:56:46.000Z","dependencies_parsed_at":"2022-09-02T18:32:02.923Z","dependency_job_id":null,"html_url":"https://github.com/Carglglz/jupyter_upydevice_kernel","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carglglz%2Fjupyter_upydevice_kernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carglglz%2Fjupyter_upydevice_kernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carglglz%2Fjupyter_upydevice_kernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carglglz%2Fjupyter_upydevice_kernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Carglglz","download_url":"https://codeload.github.com/Carglglz/jupyter_upydevice_kernel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253950283,"owners_count":21989334,"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":["atom","ble","hydrogen-atom","ipython","jupyter","jupyter-notebook","jupyterlab","micropython","serial","vscode","webrepl"],"created_at":"2024-08-04T00:01:50.487Z","updated_at":"2025-05-13T13:32:35.915Z","avatar_url":"https://github.com/Carglglz.png","language":"Python","funding_links":[],"categories":["Development"],"sub_categories":["Shells"],"readme":"Jupyter MicroPython Upydevice Kernel\n=====================================\n\nJupyter kernel to interact with a MicroPython board over its REPL\ninterface.\n\nTypically used with MicroPython boards over the USB / Serial interface,\nor through the WebREPL.\n\nMicroPython\n-----------\nTested on MicroPython v1.11 - v1.16\n\nBoards\n-------\nTested on:\n  - PYBOARD V1.1/Lite\n  - ESP32\n  - ESP8266\n  - CIRCUITPLAYGROUND EXPRESS\n\n\nIDE/PLATFORMS\n-------------\n- Jupyter notebooks\n- Jupyter lab\n- Atom (`Hydrogen \u003chttps://github.com/nteract/hydrogen\u003e`_)\n- Visual Studio Code (`Jupyter notebooks \u003chttps://code.visualstudio.com/docs/python/jupyter-support\u003e`_)\n\nBackground\n----------\n\nThis Jupyter MicroPython Kernel is heavily based on the amazing work\ndone on https://github.com/goatchurchprime/jupyter_micropython_kernel\nand https://github.com/andrewleech/jupyter_micropython_remote\n\nTheir device connection library has been replaced by\nupydevice latest classes ``SerialDevice``, ``WebSocketDevice`` and ``AsyncBleDevice``\nthat allows Serial, WiFi (websocket-WebREPL) and Bluetooth Low Energy (BleREPL) connections.\nThe kernel has also been reworked to support autocompletions on tab which works\nfor MicroPython, iPython and %cell magic commands.\nSome %cell magic commands were dropped and some new were added e.g: ``%is_reachable``\n``%meminfo`` ``%whoami`` ``%gccollect`` ``%sync`` ``%logdata`` ``%devplot`` ``%connect``\n``%rssi``\n\nInstallation\n------------\n\nEnsure you have a new enough MicroPython installed on your board (see above).\n\nYou also need python 3.6 or above, ensuring it’s available from your current\ncommand line. Optionally (recommended) use your favourite pipenv / virtualenv to set\nup a clean environment to run jupyter from.\n\nThen install this module:\n\n::\n\n   pip install jupyter-micropython-upydevice\n\nInstall the kernel into jupyter itself using the shell command:\n\n::\n\n   python -m mpy_kernel_upydevice.install\n\nThis registers the kernel with Jupyter so it can be selected for use in\nnotebooks\n\nRunning\n-------\n\nNow run Jupyter notebooks or Jupyter lab:\n\nFor Jupyter lab do:\n\n::\n\n   jupyter lab\n\nIn the launcher click on the MicroPython upydevice button to create a new notebook\n\nSerial device\n-------------\n\nTo connect through serial/USB: ``%serialconnect [SERIAL PORT] [BAUDRATE]``\nor if a device already configured (see `upydev \u003chttps://github.com/Carglglz/upydev\u003e`_)\nin the global group 'UPY_G',  ``%serialconnect @[DEVICE]`` which has autocompletion\non tab.\n\nThis command has autocompletion on tab, so hit tab and select a port from the list\n\nBaudrate default is 115200\n\n*Use -kbi option to interrupt any running loop*\n\neg:\n::\n\n   %serialconnect /dev/tty.usbmodem3370377430372 115200\n\n\n\nor\n\n::\n\n    %serialconnect @pybV1.1\n\n::\n\n  ** Serial connected **\n\n  SerialDevice @ /dev/tty.usbmodem3370377430372, Type: pyboard, Class: SerialDevice\n  Firmware: MicroPython v1.17-217-gde7e3cd79-dirty on 2021-11-30; PYBv1.1 with STM32F405RG\n  Pyboard Virtual Comm Port in FS Mode, Manufacturer: MicroPython\n  (MAC: 3c:00:3d:00:02:47:37:30:38:37:33:33)\n\n  MicroPython v1.17-217-gde7e3cd79-dirty on 2021-11-30; PYBv1.1 with STM32F405RG\n  Type \"help()\" for more information.\n\n\nWireless Device: WiFi\n---------------------\n\nTo connect through WebREPL: ``%websocketconnect [IP] --password \"[PASSWORD]\"``\nor if a device already configured (see `upydev \u003chttps://github.com/Carglglz/upydev\u003e`_)\nin the global group 'UPY_G',  ``%websocketconnect @[DEVICE]`` which has autocompletion\non tab.\n\n*Use -kbi option to interrupt any running loop*\n\neg:\n\n::\n\n    %websocketconnect 192.168.1.42 --password \"mypass\"\n\n\n\nor\n\n::\n\n    %websocketconnect @esp_room1\n\n::\n\n  ** WebREPL connected **\n\n  WebSocketDevice @ ws://192.168.1.66:8266, Type: esp32, Class: WebSocketDevice\n  Firmware: MicroPython v1.17 on 2021-09-02; ESP32 module with ESP32\n  (MAC: 7c:9e:bd:3d:9d:f4, Host Name: gkesp32, RSSI: -58 dBm)\n\n  MicroPython v1.17 on 2021-09-02; ESP32 module with ESP32\n  Type \"help()\" for more information.\n\n\nWireless Device: BLE\n--------------------\n\nTo connect through BLEREPL: ``%bleconnect [ADDRESS] \"``\nor if a device already configured (see `upydev \u003chttps://github.com/Carglglz/upydev\u003e`_)\nin the global group 'UPY_G',  ``%bleconnect @[DEVICE]`` which has autocompletion\non tab.\n\n\neg:\n\n::\n\n    %bleconnect 9998175F-9A91-4CA2-B5EA-482AFC3453B9\n\n\n\nor\n\n::\n\n    %bleconnect @bledev\n\n::\n\n  [Service] 6e400001-b5a3-f393-e0a9-e50e24dcca9e: Nordic UART Service\n  [Characteristic] 6e400003-b5a3-f393-e0a9-e50e24dcca9e: (notify) | Name: Nordic UART TX\n    [Descriptor] [00002902-0000-1000-8000-00805f9b34fb]: Client Characteristic Configuration (Handle: 22)\n  [Characteristic] 6e400002-b5a3-f393-e0a9-e50e24dcca9e: (write) | Name: Nordic UART RX\n\n  ** BleREPL connected **\n\n  BleDevice @ 9998175F-9A91-4CA2-B5EA-482AFC3453B9, Type: esp32 , Class: BleDevice\n  Firmware: MicroPython v1.16 on 2021-06-24; ESP32 module with ESP32\n  (MAC: 30:ae:a4:23:35:64, Local Name: esp32-34, RSSI: -50 dBm)\n\n  MicroPython v1.16 on 2021-06-24; ESP32 module with ESP32\n  Type \"help()\" for more information.\n\n\nThe ``%connect`` magic command allows any type of device:\n::\n\n    %connect @esp_room1\n\n::\n\n    %connect @pybV1.1\n\n::\n\n    %connect @bledev\n\n\n\nYou should now be able to execute MicroPython commands by running the\ncells.\n\nThere is a *upydevice_kernel_demo.ipynb* file in the directory you could look at\nwith some of the features shown.\n\nIf a cell is taking too long, or if you want to stop an ongoing loop\nTo interrupt / ^C use “Interrupt the kernel” button and this will raise a ``KeyboardInterrupt``\nin the device.\n\nAlternatively hit Escape and then ‘i’ twice.\n\nTo do a soft reset (it will reconnect automatically) type:\n\n::\n\n   %rebootdevice\n\n  Note: Restarting the kernel does not actually reboot the device.\n  Also, pressing the reset button will mess things up (at least for WebREPL, BleREPL\n  and for serial this is probably true as well).\n\n%Cell magic Commands\n--------------------\nCell magic commands have autocompletion on tab, so hit tab and see what Commands\nare available, or to see more information about each command do:\n::\n\n   %lsmagic\n\n\n::\n\n  %disconnect\n    disconnects device\n\n  %lsmagic\n      list magic commands\n\n  %rebootdevice\n      reboots device\n\n  %is_reachable\n      Test if device is reachable (must be connected first)\n\n  %connect\n      connects to a device based on addres or configuration\n\n  %serialconnect [-kbi] [portname] [baudrate]\n      connects to a device over USB, default baudrate is 115200\n\n  %websocketconnect [--password PASSWORD] [-kbi] [-ssl] [websocketurl]\n      connects to the WebREPL over wifi (WebREPL daemon must be running)\n      websocketurl defaults to 192.168.4.1 (uri -\u003e ws://192.168.4.1:8266)\n\n  %bleconnect [bleaddress]\n      connects to the BleREPL over Bluetooth Low Energy(BleREPL must be running)\n\n  %meminfo\n      Shows RAM size/used/free/use% info\n\n  %whoami\n      Shows Device name, port, id, and system info\n\n  %rssi\n      Shows Device RSSI if wireless\n\n  %gccollect\n      To use the garbage collector and free some RAM if possible\n\n  %local\n      To run the cell contents in local iPython\n\n  %sync\n      To sync a variable/output data structure of the device into iPython\n      if no var name provided it stores the output into _\n\n  %logdata [-fs FS] [-tm TM] [-u U [U ...]] [-s] v [v ...]\n      To log output data of the device into iPython,\n      data is stored in 'devlog'\n\n     positional arguments:\n        v             Name of variables\n     optional arguments:\n        -fs FS        Sampling frequency in Hz\n        -tm TM        Sampling timeout in ms\n        -u U [U ...]  Unit of variables\n        -s            Silent mode\n\n  %devplot\n      To plot devlog data\n\nThe communications interface to the MicroPython device is based on `upydevice\n\u003chttps://github.com/Carglglz/upydevice\u003e`\n\n\nThis is also the core library of `upydev\n\u003chttps://github.com/Carglglz/upydev\u003e`_ .\nThe SERIAL SHELL-REPL can be used simultaneously\nwith the upydevice Kernel since the serial connection is non-blocking.\n\n%local\n------\nIndividual cells can also be run on the local iPython instead of the MicroPython\nkernel by starting a cell with ``%local``\n\nThis can be useful to work directly with local files, use ipywidgets, etc.\nCommands here will be run by the standard ipython kernel.\n\nIn `%local` cells, a special global function ``remote()`` is also available which\nwill pass a single string argument to the MicroPython board to be run, returning\nany stdout from the command. Eg:\n\nmicropython cell\n\n::\n\n   from machine import Pin\n   import neopixel\n   pixels = neopixel.NeoPixel(Pin(4, Pin.OUT), 1)\n\n   def set_colour(r, g, b):\n       pixels[0] = (r, g, b)\n       pixels.write()\n\n   set_colour(0xff, 0xff, 0xff)\n\nlocal cell\n\n::\n\n   %local\n   import colorsys\n   from ipywidgets import interact, Layout, FloatSlider\n\n   def set_hue(hue):\n       r, g, b = (int(p*255) for p in colorsys.hsv_to_rgb(hue, 1.0, 1.0))\n       remote(f\"set_colour({r}, {g}, {b})\")\n\n   slider = FloatSlider(min=0,max=1.0,step=0.01, layout=Layout(width='80%', height='80px'))\n   interact(set_hue, hue=slider)\n\n\n\n\\\n\n\n\n%sync\n-----\n\nAny variable/output of the device can be stored in local iPython easily.\nIf a var name is not provided the output will be stored locally in _ , e.g. :\n\n::\n\n    %sync\n    [1,2,3,5]\n\n::\n\n  [1, 2, 3, 5]\n\n\n::\n\n    %local\n    _\n\n::\n\n  [1, 2, 3, 5]\n\n\nIf device output is assigned to a variable it will be stored locally with the\nsame name e.g. :\n\n::\n\n    %sync\n    my_data = {'key1':[1,2,3], 'key2':[4,5,6]}\n\n\n::\n\n    %local\n    my_data\n\n\n::\n\n    {'key2': [4, 5, 6], 'key1': [1, 2, 3]}\n\n\n\n\n\nThis works for any type of output (bytes/bytearrays/arrays/ints/floats/strings/lists/dicts)\n\n%logdata\n---------\nThis allows to log any data from device stdout as long as the data is in tuple or list format.\nThe data will be stored in local iPython in 'devlog'. *(Serial and WebSocketDevices only)*\n\npositional arguments:\n   v             Name of variables\noptional arguments:\n   - -fs FS        Sampling frequency in Hz\n   - -tm TM        Sampling timeout in ms\n   - -u U [U ...]  Unit of variables\n   -  \\-s            Silent mode\n\ne.g. :\nLogging accelerometer data from an IMU sensor.\n\n*micropython cell*\n\n::\n\n    import time\n    from machine import I2C, Pin\n    from lsm9ds1 import LSM9DS1\n    i2c = I2C(scl=Pin(22), sda=Pin(23))\n    imu = LSM9DS1(i2c)\n\n    def stream_accel(n, tm):\n      for i in range(n):\n          print(imu.read_accel())\n          time.sleep_ms(tm)\n\n\n*%logdata cell*\n\n::\n\n    %logdata 'x' 'y' 'z' -tm 10 -u 'g(9.8m/s^2)'\n    stream_accel(400, 10)\n\n::\n\n    vars:['x', 'y', 'z'], fs:None Hz, tm:10 ms, u: ['g(9.8m/s^2)'], silent: False\n    ------------------------------\n    (-0.6851807, 0.6947632, 0.3374634)\n    (-0.6889038, 0.6830444, 0.3411255)\n    (-0.7027588, 0.6877441, 0.3455811)\n    (-0.7280884, 0.7080688, 0.3401489)\n    ....\n    (-0.734375, 0.7600098, -0.0004272461)\n    (-0.7210693, 0.7717896, -0.05194092)\n    (-0.7344971, 0.7575684, 0.006652832)\n\n\nNow data is stored in devlog\n\n::\n\n    %local\n    devlog\n\n::\n\n    {'x': [-0.6851807, ..., -0.7344971], 'y': [0.6947632, ..., 0.7575684],\n     'z': [-0.7280884, ..., 0.006652832], 'vars': ['x', 'y', 'z']\n     'fs': 100, 'ts': [0.0, ... , 4.0], 'u': ['g(9.8m/s^2)']}\n\n\n%devplot\n--------\nThis allows to plot *devlog* data, just do:\n\n\n::\n\n    %devplot\n\n\n\n.. image:: acc-plot.png\n    :width: 2140pt\n\n\nNow to save the plot do:\n\n::\n\n    %local\n    fig.savefig('acc-plot.png')\n\n\n::\n\n    %local\n    %ls\n\n::\n\n    LICENSE*                    mpy_kernel_upydevice/\n    README.rst*                 setup.py\n    acc-plot.png                upydevie_kernel_demo.ipynb\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCarglglz%2Fjupyter_upydevice_kernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCarglglz%2Fjupyter_upydevice_kernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCarglglz%2Fjupyter_upydevice_kernel/lists"}