{"id":14967229,"url":"https://github.com/micropython/webrepl","last_synced_at":"2025-05-16T14:08:16.253Z","repository":{"id":41125057,"uuid":"52560510","full_name":"micropython/webrepl","owner":"micropython","description":"WebREPL client and related tools for MicroPython","archived":false,"fork":false,"pushed_at":"2024-08-16T11:44:59.000Z","size":84,"stargazers_count":645,"open_issues_count":45,"forks_count":297,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-04-09T08:06:31.999Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/micropython.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":"2016-02-25T22:10:59.000Z","updated_at":"2025-04-04T04:25:33.000Z","dependencies_parsed_at":"2024-09-14T03:49:51.544Z","dependency_job_id":"db849acf-bcd0-4e78-ba6d-0921819b3d92","html_url":"https://github.com/micropython/webrepl","commit_stats":{"total_commits":62,"total_committers":9,"mean_commits":6.888888888888889,"dds":0.3870967741935484,"last_synced_commit":"1e09d9a1d90fe52aba11d1e659afbc95a50cf088"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropython%2Fwebrepl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropython%2Fwebrepl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropython%2Fwebrepl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micropython%2Fwebrepl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micropython","download_url":"https://codeload.github.com/micropython/webrepl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"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":[],"created_at":"2024-09-24T13:37:40.183Z","updated_at":"2025-05-16T14:08:11.240Z","avatar_url":"https://github.com/micropython.png","language":"JavaScript","readme":"WebREPL client for MicroPython\n==============================\n\nThis repository contains the WebREPL client and related tools, for\naccessing a MicroPython REPL (interactive prompt) over WebSockets.\n\nTo start WebREPL terminal client, clone or download this repository\n(in full) and open webrepl.html in a browser. Recent versions of\nFirefox and Chrome (or Chromium) are supported.\n\nThe latest version of the client is also hosted online at\nhttp://micropython.org/webrepl (note: while it's hosted online,\nall interaction with your boards still happen locally in your\nown network).\n\nAt this time, WebREPL client cannot be accessed over HTTPS connections.\nThis is due to not widely published policy that HTTPS pages may\naccess only WSS (WebSocket Secure) protocol. This is somewhat\nsimilar to warnings issued when e.g. an HTTPS page loads an image\nover plain HTTP. However, in case of WebSockets, some browsers\ndon't even issue a user-visible warning, and others may word it\nconfusingly, so it's hard to understand that it applies to WebSocket\nconnections. As WebREPL is intended to be used only within a user's\nlocal network, HTTPS isn't strictly required, and not accessing\nwebrepl.html over HTTPS is a suggested workaround.\n\nWebREPL file transfer\n---------------------\n\nWebREPL protocol includes experimental support for file transfer.\nThis feature is currently in alpha and has known issues on systems\nwhich have it enabled (ESP8266).\n\nTo use WebREPL file transfer capabilities, a separate command line\nutility is provided, webrepl_cli.py (file transfer is not supported\nvia webrepl.html client). Run\n\n    webrepl_cli.py --help\n\nto see usage information. Note that there can be only one active\nWebREPL connection, so while webrepl.html is connected to device,\nwebrepl_cli.py can't transfer files, and vice versa.\n\n\nTechnical details\n-----------------\n\nWebREPL is the latest standard (in the sense of an Internet RFC) for\ncommunicating with and controlling a MicroPython-based board. Following\nwere the requirements for the protocol design:\n\n1. Single connection/channel, multiplexing terminal access, filesystem\naccess, and board control.\n\n2. Network ready and Web technologies ready (allowing access directly\nfrom a browser with an HTML-based client).\n\nBased on these requirements, WebREPL uses a single connection over\n[WebSocket](https://en.wikipedia.org/wiki/WebSocket) as a transport\nprotocol. Note that while WebREPL is primarily intended for network\n(usually, wireless) connection, due to its single-connection,\nmultiplexed nature, the same protocol can be used over a lower-level,\nwired connection like UART, SPI, I2C, etc.\n\nFew other traits of WebREPL:\n\n1. It is intended (whenever possible) to work in background, i.e.\nwhile WebREPL operations are executed (like a file transfer), normal\nREPL/user application should continue to run and be responsive\n(though perhaps with higher latency, as WebREPL operations may\ntake its share of CPU time and other system resources). (Some\nsystems may not allow such background operation, and then WebREPL\naccess/operations will be blocking).\n\n2. While it's intended to run in background, like a Unix daemon,\nit's not intended to support multiple, per-connection sessions.\nThere's a single REPL session, and this same session is accessible\nvia different media, like UART or WebREPL. This also means that\nthere's usually no point in having more than one WebREPL connection\n(multiple connections would access the same session), and a\nparticular system may actually limit number of concurrent\nconnections to ease implementation and save system resources.\n\nWebREPL protocol consists of 2 sub-protocols:\n\n* Terminal protocol\n\nThis protocol is finalized and is very simple in its nature, akin\nto Telnet protocol. WebSocket \"text\"-flagged messages are used to\ncommunicate terminal input and output between a client and a WebREPL-\nenabled device (server). There's a guaranteed password prompt, which\ncan be detected by the appearance of characters ':', ' ' (at this\npoint, server expected a password ending with '\\n' from client).\nIf you're interested in developing a 3rd-party application to communicate\nusing WebREPL terminal protocol, the information above should be enough\nto implement it (or feel free to study implementation of the official\nclients in this repository).\n\n* File transfer/board control protocol\n\nThis protocol uses WebSocket \"binary\"-flagged messages. At this point,\nthis protocol is in early research/design/proof-of-concept phase. The\nonly available specification of it is the reference code implementation,\nand the protocol is subject to frequent and incompatible changes.\nThe `webrepl_cli.py` module mentioned above intended to be both a\ncommand-line tool and a library for 3rd-party projects to use, though\nit may not be there yet. If you're interested in integrating WebREPL\ntransfer/control capabilities into your application, please submit\na ticket to GitHub with information about your project and how it is\nuseful to MicroPython community, to help us prioritize this work.\n\nWhile the protocol is (eventually) intended to provide full-fledged\nfilesystem access and means to control a board (all subject to\nresource constraints of a deeply embedded boards it's intended to\nrun on), currently, only \"get file\" and \"put file\" operations are\nsupported. As above, sharing information with us on features you\nmiss and how they can be helpful to the general MicroPython\ncommunity will help us prioritize our plans. If you're interested\nin reducing wait time for new features, you're also welcome to\ncontribute to their implementation. Please start with discussing\nthe design first, and with small changes and improvements. Please\nkeep in mind that WebREPL is just one of the many features on which\nMicroPython developers work, so having sustainable (vs revolutionary)\ndevelopment process is a must to have long-term success.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicropython%2Fwebrepl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicropython%2Fwebrepl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicropython%2Fwebrepl/lists"}