{"id":15655311,"url":"https://github.com/carlosperate/microbit-dev-env","last_synced_at":"2025-10-19T16:40:28.447Z","repository":{"id":69432459,"uuid":"56334129","full_name":"carlosperate/microbit-dev-env","owner":"carlosperate","description":"Easily install and configure a development environment for the BBC micro:bit in C/C++, MakeCode, and MicroPython using Vagrant (virtual machine).","archived":false,"fork":false,"pushed_at":"2022-03-28T17:09:06.000Z","size":73,"stargazers_count":25,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T21:33:12.118Z","etag":null,"topics":["developer-tools","microbit","vagrant","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/carlosperate.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}},"created_at":"2016-04-15T16:24:48.000Z","updated_at":"2022-06-04T21:16:09.000Z","dependencies_parsed_at":"2023-03-11T06:04:28.004Z","dependency_job_id":null,"html_url":"https://github.com/carlosperate/microbit-dev-env","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosperate%2Fmicrobit-dev-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosperate%2Fmicrobit-dev-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosperate%2Fmicrobit-dev-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosperate%2Fmicrobit-dev-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlosperate","download_url":"https://codeload.github.com/carlosperate/microbit-dev-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252134265,"owners_count":21699684,"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":["developer-tools","microbit","vagrant","virtual-machine"],"created_at":"2024-10-03T12:57:55.838Z","updated_at":"2025-10-19T16:40:23.400Z","avatar_url":"https://github.com/carlosperate.png","language":"Shell","readme":"# BBC micro:bit Development Environment for C/C++, MakeCode, and MicroPython\n\nThis repository contains a Vagrant box configured to facilitate the development of MicroPython, MakeCode, and C/C++ programs for the BBC micro:bit.\n\n[Vagrant](https://www.vagrantup.com/intro/index.html) is a tool to easily build and manage virtual machine environments.\n\nIf you prefer to use 🐳 Docker this other project might interest you:\n[Docker micro:bit Toolchain](https://github.com/carlosperate/docker-microbit-toolchain)\n\n\n## 🗂️ Table of contents:\n\n* [✨ Features](#-features)\n* [📀 Install](#-install)\n* [🚀 Getting Started](#-getting-started)\n* [🔁 Workflow](#-workflow)\n* [🏞️ Environments](#%EF%B8%8F-environments)\n    * [©️ C/C++ DAL (V1)](#%EF%B8%8F-cc-dal-v1)\n    * [©️ C/C++ CODAL (V2)](#%EF%B8%8F-cc-codal-v2)\n    * [🐍 MicroPython V1](#-micropython-v1)\n    * [🐍 MicroPython V2](#-micropython-v2)\n    * [Ⓜ️ MakeCode](#ⓜ%EF%B8%8F-makecode)\n* [📑 License](#-license)\n* [⚖️ Trademarks](#%EF%B8%8F-trademarks)\n\n\n## ✨ Features\n\nThis virtual machine is very easy to use and contains everything you need to:\n* Build micro:bit MicroPython from source\n\t* Easily load Python scripts using your own built MicroPython\n\t* Easily access the MicroPython REPL\n* Run a local version of MakeCode/PXT\n* Develop your own MakeCode packages\n* Build C/C++ applications for the micro:bit using the DAL (micro:bit runtime)\n\nWith a single command this project takes care of creating a virtual machine, installing all the development tools and dependencies required, download all the source code into a shared folder, compile everything, and get it ready for use.\n\nIt offers a replicable development environment that is independent of your operating system, working the same way under Windows, macOS, or Linux.\n\n\n## 📀 Install\n\n### Prerequisites\nYou will need the following applications first:\n\n* [VirtualBox](https://www.virtualbox.org/)\n* [Vagrant](https://www.vagrantup.com/)\n* (Optional) [Python](https://www.python.org/) (2.7 or \u003e=3.4)\n\n### Vagrant Project Bring-up\n\nClone, or [download](https://github.com/carlosperate/microbit-dev-env.git) this repository:\n\n```bash\ngit clone https://github.com/carlosperate/microbit-dev-env.git\ncd microbit-dev-env\n```\n\nGetting the virtual machine up and running with Vagrant is extremely easy, on the Command Line Interface just run:\n\n```bash\nvagrant up --provision\n```\n\nThis will first ask you what project would you like to build. Selecting only the project you are interested will significantly reduce the bring up time.\n\n```\n$ vagrant up --provision\nBuild MakeCode? (y/n): y ✅\nBuild C++ samples (DAL)? (y/n): y ✅\nBuild CODAL? (y/n): y ✅\nBuild MicroPython V1? (y/n): y ✅\nBuild MicroPython V2? (y/n): y ✅\n```\n\nAfter the questions have been answered, it will download an Ubuntu 16.04 64-bit Virtual Box image, so it might take a while depending on your internet connection.\nIt will also install the build tool-chain, download and build all the source code for the selected projects, ensuring everything is ready to develop your application in any of these platforms.\n\n\n## 🚀 Getting Started\n\nFirst, start-up the virtual machine:\n```bash\nvagrant up\n```\n\nIf this is the first time you've run this command it will ask you which projects you would like to build. Enter `y` to select any of the prompted projects.\n\nYou can now SSH into the virtual machine with Vagrant itself:\n\n```bash\nvagrant ssh\n```\n\nOr with your preferred SSH client:\n\n```\nHost: 127.0.0.1\nPort: 2222\nUsername: vagrant\nPassword: vagrant\n```\n\nThis will give you command line access to the virtual machine, allowing you to compile the source code contained in the `vagrant_shared` folder. By default you will find the `cpp-samples`, `micropython`, `pxt-workspace` and a couple of extra folders there, which can be accessed from the virtual machine to build the projects. So within the SSH connection you can:\n\n```bash\ncd vagrant_shared/micropython\nmake all\n```\n\nTo stop the virtual machine from running, you can use the following command on the host:\n\n```\nvagrant halt\n```\n\nMore information can be found in the [Vagrant documentation](https://www.vagrantup.com/docs/).\n\n\n## 🔁 Workflow\n\nThe general workflow concept is to have one folder that is accessible by both the host operating system (your computer), and the virtual machine.\n\nThis allows you to create and edit your code like you would normally do, using any IDE or editor you prefer, and then use the virtual machine to build it or compile it.\n\nIn essence the steps are:\n\n* Edit the code inside the `vagrant_shared` folder in your OS as you would normally do\n* SSH into the virtual machine\n* Compile/build the project from the SSH session (accessible via `~/vagrant_shared/`)\n* The built output can be accessed from the `vagrant_shared` folder within your OS\n\nThe `vagrant_shared` folder is where the source code and projects have to be located, as Vagrant configures it as a shared folder that can be accessed indiscriminately by both your OS and the virtual machine.\nRemember! If you delete something within the virtual machine `~/vagrant_shared/` directory it will also be removed from the folder you see in your Operating System.\n\nThe `vagrant_shared` directory has been gitignored, so feel free to add or clone your own repositories there without interference from this one.\n\n\n## 🏞️ Environments\n\n### ©️ C/C++ DAL (V1)\n#### Project/code location\nThe [microbit samples](https://github.com/lancaster-university/microbit-samples) project contains a collection of example programs using the micro:bit runtime (DAL).\nThe project directory can be found at:\n```\nvagrant_shared/cpp-samples/\n```\n\n\n#### Building\nThis C/C++ project has already been built, but if you wish to recompile the examples you can access the virtual machine via SSH, and run:\n\n```bash\ncd ~/vagrant_shared/cpp-samples/\nyt clean\nyt build\n```\n\nThe `cpp-samples/source/examples` folder contains a selection of samples demonstrating the capabilities and usage of the runtime APIs. To select a sample, simply copy the .cpp files from the relevant folder into the `cpp-samples/source/` folder. More info can be found in the [microbit samples](https://github.com/lancaster-university/microbit-samples) repository.\n\n#### Built output location\nTo load the application into the micro:bit you will need to copy the `microbit-xxx-combined.hex` file into the micro:bit USB drive.\n\n```\nvagrant_shared/cpp-samples/build/bbc-microbit-classic-gcc/source/microbit-samples-combined.hex\n```\n\n### ©️ C/C++ CODAL (V2)\n#### Project/code location\nThe [microbit samples](https://github.com/lancaster-university/microbit-v2-samples) project contains a collection of example programs using the micro:bit runtime for V2 (CODAL).\nThe project directory can be found at:\n```\nvagrant_shared/microbit-v2-samples/\n```\n\n\n#### Building\nThis C/C++ project has already been built, but if you wish to recompile the examples you can access the virtual machine via SSH, and run:\n\n```bash\ncd ~/vagrant_shared/microbit-v2-samples/\npython3 build.py\n```\n\nThe `microbit-v2-samples/source/samples/` folder contains a selection of samples demonstrating the capabilities and usage of the runtime APIs. To select a sample, simply copy the .cpp files from the relevant folder into the `cpp-samples/source/` folder. More info can be found in the [micro:bit V2 samples](https://github.com/lancaster-university/microbit-v2-samples) repository.\n\n#### Built output location\nTo load the application into the micro:bit you will need to copy the `MICROBIT.hex` file into the micro:bit USB drive.\n\n```\nvagrant_shared/microbit-v2-samples/MICROBIT.hex\n```\n\n### 🐍 MicroPython V1\n#### Project/code location\nThe MicroPython source code can be found in:\n\n```bash\nvagrant_shared/micropython/\n```\n\n#### Building\nMicroPython has already been built, but if you wish to build it again, you can open an SSH session and run:\n\n```bash\ncd ~/vagrant_shared/micropython/\nyt clean\nmake all\n```\n\n#### Built output location\nThe MicroPython hex file is saved into the following path:\n\n```bash\nvagrant_shared/micropython/build/firmware.hex\n```\n\n#### Flashing to the micro:bit\nYou can simply copy the MicroPython hex into your micro:bit USB drive.\n\nTo simplify the process and be able to load MicroPython with or without an additional Python program, [uflash](https://github.com/ntoll/uflash/) (by [Nicholas Tollervey](https://github.com/ntoll)) has been included with a wrapper script. So, from the host operating system you can run the following if you have Python (2 or 3) installed.\n\nTo load only the new MicroPython simply run this script:\n\n```bash\npython upy.py flash\n``` \n\nTo load the new MicroPython together with your Python code:\n\n```bash\npython upy.py flash \u003cpath to your python file\u003e\n```\n\nFor a quick test you could load any of the included MicroPython examples for the microbit:\n\n```bash\npython upy.py flash vagrant_shared/micropython/examples/conway.py\n```\n\nAll command line arguments sent to the `upy_load.py` wrapper script are sent over to uFlash (more info about available options in the [uFlash's README](https://github.com/ntoll/uflash)). So, for example, if you'd like to save the combined `micropython.hex` file (MicroPython + user Python code) into the current directory (indicated using `.`), you can do so with the following command:\n\n```bash\npython upy.py flash vagrant_shared/micropython/examples/conway.py .\n```\n\n#### Access the MicroPython REPL\nOnce MicroPython is flashed, you will have access to the REPL on the USB CDC serial port, with baud rate 115200 (eg `picocom /dev/ttyACM0 -b 115200` on Linux, `screen /dev/tty.usbmodem* 115200` on OS X, or a tool like putty/TeraTerm on Windows).\n\nThe [microrepl](https://github.com/ntoll/microrepl) tool (by [Nicholas Tollervey](https://github.com/ntoll))is also bundled and easily accessible via a provided helper script. If you'd like to access the micro:bit REPL using your host computer terminal/console you can simply run the following Python (2 or 3) script:\n\n```bash\npython upy.py repl\n```\n\nIf you are running Windows you might need to install the microbit driver, which can be found at: https://developer.mbed.org/handbook/Windows-serial-configuration\n\n#### Access the MicroPython file system\nMicroPython implements a simple file system inside the micro:bit flash, allowing you to read and write small files. The [microfs](https://github.com/ntoll/microfs) Python command line utility (by [Nicholas Tollervey](https://github.com/ntoll)), is bundled with a wrapper script to enable easy access from the host computer.\n\nYou can use the following commands:\n* List the files on the micro:bit: `python upy.py fs ls`\n* Copy a file onto the micro:bit: `python upy.py fs put path/to/local.txt`\n* Get a file from the micro:bit: `python upy.py fs get remote.txt`\n* Delete a file on the micro:bit: `python upy.py fs rm remote.txt`\n* More info in the built-in help: `python upy.py fs --help`\n\n### 🐍 MicroPython V2\n#### Project/code location\nThe MicroPython source code can be found in:\n\n```bash\nvagrant_shared/micropython-microbit-v2/\n```\n\n#### Building\nMicroPython has already been built, but if you wish to build it again, you can open an SSH session and run:\n\n```bash\ncd ~/vagrant_shared/micropython-microbit-v2/src\nmake\n```\n\n#### Built output location\nThe MicroPython hex file is saved into the following path:\n\n```bash\nvagrant_shared/micropython-microbit-v2/src/MICROBIT.hex\n```\n\n### Ⓜ️ MakeCode\n\nWIP\n\n#### Project/code location\n\nThe PXT workspace is installed in the following directory:\n\n```bash\nvagrant_shared/pxtworkspace/\n```\n\n#### Launch MakeCode server\n\nTo run MakeCode, open an SSH session and run:\n\n```bash\ncd ~/vagrant_shared/pxtworkspace\npxt serve --no-browser --no-serial --hostname 0.0.0.0 --port 3232 --wsport 3233\n```\n\n**VERY IMPORTANT**: From your host OS open a browser and go to the address displayed in the SSH terminal with one **CHANGE**: Replace `0.0.0.0` with `localhost`.\n\nThe terminal session should have showed you a message similar to the one below, but with a different token in the URL, which you need to keep:\n\n```\n---------------------------------------------\n\nTo launch the editor, open this URL:\nhttp://0.0.0.0:3232/#local_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\u0026wsport=3233\n\n---------------------------------------------\n```\n\nSo in the example above, point your browser to `http://localhost:3232/#local_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\u0026wsport=3233` instead.\n\n\n## 📑 License\n\n[MIT](LICENSE)\n\n\n## ⚖️ Trademarks\n\nThis projects is not endorsed, sponsored or associated with the BBC or the Micro:bit Educational Foundation.\n\"BBC” and “micro:bit” are trade marks of the BBC. https://microbit.org\n","funding_links":[],"categories":["🛠️ Programming Tools","编程工具"],"sub_categories":["🎓 Machine Learning Resources \u0026 Projects","其他交互语言"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosperate%2Fmicrobit-dev-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlosperate%2Fmicrobit-dev-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosperate%2Fmicrobit-dev-env/lists"}