Skip to content

murilopolese/webrepl-client

Repository files navigation

MicroPython's WebREPL Client

MicroPython's WebREPL allows an REPL (interactive prompt) over WebSocket. It makes possible to interact with MicroPython using only a browser without additional drivers and software installation or cables. It also offers file transfer capabilities.

To use webrepl-client you must have configured and started WebREPL on your board. It's also necessary both computer and board to be connected to the same wifi network (even if it's the network created by the board).

This library extracts most logic to interact with MicroPython's WebREPL from the official repository.

Available features

  • Connects to board running MicroPython's WebREPL
  • Optionally inputs password without prompting user
  • Emits events on connection opening, authentication and incoming messages
  • Send, retrieve and remove files from MicroPython's filesystem
  • Evaluate commands and string containing lines of code
  • Enter and exit "raw repl" mode
  • Send keyboard interrupt and software reset
  • "Raw repl" and file operations return promises.
  • Optional interval between lines of code on execFromString necessary for the ESP32 implementation of the WebREPL protocol.
  • Offers ES6 module, CommonJS and "iife" support.

Documentation and examples

You can find class documentation generated with JSDoc, which mean the code itself contains documentation on how to use it with examples. There are also few examples using Custom Elements (v1) to create an interactive prompt, file manager and run code from a text editor. Be aware those examples are educational and not production ready.

How to use it

  1. Run yarn add murilopolese/webrepl-client (or bower install murilopolese/webrepl-client)
  2. Import webrepl.js and optionally FileSaver.js
    • import { WebREPL } from 'node_modules/webrepl-client/webrepl.js'
  3. Check the examples and documentation to see what's possible to do.

Roadmap

  • Build production ready single, minified, gziped file (on a CDN?).
  • Offer AMD support
  • Nodejs support using a WebSocket module
  • Finish tests (ops!)
  • Clearer documentation of WebREPL protocol