{"id":21070742,"url":"https://github.com/microbit-foundation/micropython-microbit-v2-simulator","last_synced_at":"2025-05-16T05:31:04.749Z","repository":{"id":37422801,"uuid":"469720093","full_name":"microbit-foundation/micropython-microbit-v2-simulator","owner":"microbit-foundation","description":"Wasm-based MicroPython micro:bit v2 simulator","archived":false,"fork":false,"pushed_at":"2024-04-15T11:07:42.000Z","size":395,"stargazers_count":12,"open_issues_count":11,"forks_count":9,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-22T20:22:26.163Z","etag":null,"topics":["microbit","micropython"],"latest_commit_sha":null,"homepage":"https://python-simulator.usermbit.org/v/0.1/demo.html","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/microbit-foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2022-03-14T12:18:51.000Z","updated_at":"2024-04-24T11:38:44.455Z","dependencies_parsed_at":"2023-12-19T12:16:00.177Z","dependency_job_id":"5693f177-3338-47f6-aba7-3265d47b02d6","html_url":"https://github.com/microbit-foundation/micropython-microbit-v2-simulator","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fmicropython-microbit-v2-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fmicropython-microbit-v2-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fmicropython-microbit-v2-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fmicropython-microbit-v2-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microbit-foundation","download_url":"https://codeload.github.com/microbit-foundation/micropython-microbit-v2-simulator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254473866,"owners_count":22077189,"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":["microbit","micropython"],"created_at":"2024-11-19T18:48:09.488Z","updated_at":"2025-05-16T05:30:59.737Z","avatar_url":"https://github.com/microbit-foundation.png","language":"JavaScript","readme":"# MicroPython-micro:bit simulator\n\n## Try it out\n\nTo try the simulator use the [micro:bit Python Editor](https://python.microbit.org).\n\nThe rest of this page explains how to embed the simulator in an application\nand develop the simulator software.\n\n## License\n\nThis software is under the MIT open source license.\n\n[SPDX-License-Identifier: MIT](LICENSE)\n\n## Embedding\n\nThe simulator is designed to be embedded into other web applications\nas an iframe. The embedding API and URLs are not yet stable and are\nsubject to change. If you are interested in embedding the simulator\nin your application please [get in touch](mailto:support@microbit.org).\n\nThe URL to embed is https://python-simulator.usermbit.org/v/0.1/simulator.html.\nYou can embed this in your application directly. We would love to hear about\nyour use of the simulator so please open an issue to get in touch.\n\nThe iframe provides the micro:bit board user interface and some limited\ninteractions. It does not provide a terminal for serial/the REPL or any UI to change the board sensor state.\n\nA value for a brand color can be passed to the simulator via a query\nstring and is used to style the play button. E.g., https://python-simulator.usermbit.org/v/0.1/simulator.html?color=blue\n\n[demo.html](./src/demo.html) is an example of embedding the simulator.\nIt connects the iframe to a terminal and provides a simple interface for\nsensors.\n\nThe following sections document the messages supported by the iframe embed\nvia postMessage.\n\n### Messages sent to parent window from iframe\n\nThese messages are sent as the result of user interactions or actions taken\nby the running program. The simulator starts stopped with no program flashed.\n\n\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eKind\n\u003cth\u003eExample\n\u003cth\u003eDescription\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd\u003eready\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"ready\",\n  \"state\": {\n    \"lightLevel\": {\n      \"id\": \"lightLevel\",\n      \"type\": \"range\",\n      \"min\": 0,\n      \"max\": 255\n    },\n    \"soundLevel\": {\n      \"id\": \"soundLevel\",\n      \"type\": \"range\",\n      \"min\": 0,\n      \"max\": 255\n      // Microphone sensor only:\n      \"lowThreshold\": 50,\n      \"highThreshold\": 150\n    }\n    // Full state continues here.\n  }\n}\n```\n\n\u003ctd\u003eSent when the simulator is ready for input. Includes a description of the available sensors.\n\n\u003ctr\u003e\n\u003ctd\u003esensor_change\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"state_change\",\n  \"change\": {\n      \"soundLevel\": {\n        \"id\": \"soundLevel\",\n        \"type\": \"range\",\n        \"min\": 0,\n        \"max\": 255\n        // Microphone sensor only:\n        \"lowThreshold\": 50,\n        \"highThreshold\": 150\n      }\n      // Optionally, further keys here.\n  }\n  ]\n}\n```\n\n\u003ctd\u003eSent when the simulator state changes. The keys are a subset of the original state. The values are always sent in full.\n\n\u003ctr\u003e\n\u003ctd\u003erequest_flash\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"request_flash\",\n}\n```\n\n\u003ctd\u003eSent when the user requests the simulator starts. The embedder should flash the latest code via the \u003ccode\u003eflash\u003c/code\u003e message.\n\n\u003ctr\u003e\n\u003ctd\u003eserial_output\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"serial_output\",\n  \"data\": \"text\"\n}\n```\n\n\u003ctd\u003eSerial output suitable for a terminal or other use.\n\n\u003ctr\u003e\n\u003ctd\u003eradio_output\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"radio_output\",\n  \"data\": new Uint8Array([])\n}\n```\n\n\u003ctd\u003eRadio output (sent from the user's program) as bytes.\nIf you send string data from the program then it will be prepended with the three bytes 0x01, 0x00, 0x01.\n\n\u003ctr\u003e\n\u003ctd\u003einternal_error\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"internal_error\",\n  \"error\": new Error()\n}\n```\n\n\u003ctd\u003eA debug message sent for internal (unexpected) errors thrown by the simulator. Suitable for application-level logging. Please raise issues in this project as these indicate a bug in the simulator.\n\n\u003c/table\u003e\n\n### Messages you can send to the iframe from the embedding app\n\n\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eKind\n\u003cth\u003eExample\n\u003cth\u003eDescription\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd\u003eflash\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"flash\",\n  \"filesystem\": {\n    \"main.py\":\n      new TextEncoder()\n        .encode(\"# your program here\")\n  }\n}\n```\n\n\u003ctd\u003eUpdate the micro:bit filesystem and restart the program. You must send this in response to the request_flash message.\n\n\u003ctr\u003e\n\u003ctd\u003estop\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"stop\"\n}\n```\n\n\u003ctd\u003eStop the program.\u003ctr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003ereset\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"reset\"\n}\n```\n\n\u003ctd\u003eReset the program.\u003ctr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003emute\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"mute\"\n}\n```\n\n\u003ctd\u003eMute the simulator.\u003ctr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003eunmute\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"unmute\"\n}\n```\n\n\u003ctd\u003eUnmute the simulator.\u003ctr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003eserial_input\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"serial_input\",\n  \"data\": \"text\"\n}\n```\n\n\u003ctd\u003eSerial input. If the REPL is active it will echo this text via \u003ccode\u003eserial_write\u003c/code\u003e.\n\u003ctr\u003e\n\u003ctd\u003esensor_set\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"set_value\",\n  \"id\": \"lightLevel\",\n  \"value\": 255\n}\n```\n\n\u003ctd\u003eSet a sensor, button or pin value. The sensor, button or pin is identified by the top-level key in the state. Buttons and pins (touch state) have 0 and 1 values. In future, analog values will be supported for pins.\n\n\u003ctr\u003e\n\u003ctd\u003eradio_input\n\u003ctd\u003e\n\n```javascript\n{\n  \"kind\": \"radio_input\",\n  \"data\": new Uint8Array([])\n}\n```\n\n\u003ctd\u003eRadio input (received by the user's program as if sent from another micro:bit) as bytes.\nIf you want to send string data then prepend the byte array with the three bytes \u003ccode\u003e0x01\u003c/code\u003e, \u003ccode\u003e0x00\u003c/code\u003e, \u003ccode\u003e0x01\u003c/code\u003e.\nOtherwise, the user will need to use \u003ccode\u003eradio.receive_bytes\u003c/code\u003e or \u003ccode\u003eradio.receive_full\u003c/code\u003e. The input is assumed to be sent to the currently configured radio group.\n\n\u003c/table\u003e\n\n## Developing the simulator\n\n### Build steps\n\nThe simulator is a variant of the MicroPython codal_port which is compiled with\nEmscripten. It provides a simulated micro:bit (including REPL) in the browser.\n\nTo build, first fetch the submodules (don't use recursive fetch):\n\n    $ git submodule update --init lib/micropython-microbit-v2\n    $ git -C lib/micropython-microbit-v2 submodule update --init lib/micropython\n\nThen run (from this top-level directory):\n\n    $ make\n\nOnce it is built the pages in build/ need to be served, e.g. via:\n\n    $ npx serve build\n\nView at http://localhost:3000/demo.html\n\n    $ (cd build \u0026\u0026 python -m http.server)\n\nView at http://localhost:8000/demo.html\n\n### Branch deployments\n\nThere is a CloudFlare pages based build for development purposes only. Do not\nembed the simulator via this URL as it may be removed at any time. CloudFlare's\nGitHub integration will comment on PRs with deployment details.\n\nBranches in this repository are also deployed via CircleCI to https://review-python-simulator.usermbit.org/{branchName}/. This requires the user pushing code to have\npermissions for the relevant Micro:bit Educational Foundation infrastructure.\n\nSimilarly, the main branch is deployed to https://python-simulator.usermbit.org/staging/.\n\nTagged releases with a `v` prefix are deployed to https://python-simulator.usermbit.org/v/{number}/\n\n### Upgrading micropython-microbit-v2\n\n1. Update the lib/micropython-microbit-v2 to the relevant hash. Make sure that its lib/micropython submodule is updated (see checkout instructions above).\n2. Review the full diff for micropython-microbit-v2. In particular, note changes to:\n   1. main.c, src/Makefile and mpconfigport.h all which have simulator versions that may need updates\n   2. the HAL, which may require implementing in the simulator\n   3. the filesystem, which has a JavaScript implementation.\n\n### Web Assembly debugging\n\nSteps for WASM debugging in Chrome:\n\n- Add the source folder in dev tools\n- Install the C/C++ debug extension: https://helpgoo.gle/wasm-debugging-extension\n- Enable \"WebAssembly Debugging: Enable DWARF support\" in DevTools Experiments\n- DEBUG=1 make\n\n## Code of Conduct\n\nTrust, partnership, simplicity and passion are our core values we live and\nbreathe in our daily work life and within our projects. Our open-source\nprojects are no exception. We have an active community which spans the globe\nand we welcome and encourage participation and contributions to our projects\nby everyone. We work to foster a positive, open, inclusive and supportive\nenvironment and trust that our community respects the micro:bit code of\nconduct. Please see our [code of conduct](https://microbit.org/safeguarding/)\nwhich outlines our expectations for all those that participate in our\ncommunity and details on how to report any concerns and what would happen\nshould breaches occur.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fmicropython-microbit-v2-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrobit-foundation%2Fmicropython-microbit-v2-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fmicropython-microbit-v2-simulator/lists"}