{"id":21070727,"url":"https://github.com/microbit-foundation/microbit-firmata","last_synced_at":"2025-05-16T05:31:03.264Z","repository":{"id":37892786,"uuid":"165650813","full_name":"microbit-foundation/microbit-firmata","owner":"microbit-foundation","description":"Firmata-like or Firmata-light protocol to communicate with the micro:bit, initially over Serial","archived":false,"fork":false,"pushed_at":"2023-09-04T18:46:08.000Z","size":2329,"stargazers_count":16,"open_issues_count":6,"forks_count":7,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-09T14:41:28.228Z","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/microbit-foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","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":"2019-01-14T11:36:43.000Z","updated_at":"2025-02-07T10:13:00.000Z","dependencies_parsed_at":"2024-11-19T18:48:43.505Z","dependency_job_id":"2b8cb7fc-06e2-4308-96a8-b87692453e04","html_url":"https://github.com/microbit-foundation/microbit-firmata","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/microbit-foundation%2Fmicrobit-firmata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fmicrobit-firmata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fmicrobit-firmata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbit-foundation%2Fmicrobit-firmata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microbit-foundation","download_url":"https://codeload.github.com/microbit-foundation/microbit-firmata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254473859,"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":[],"created_at":"2024-11-19T18:48:06.461Z","updated_at":"2025-05-16T05:30:58.250Z","avatar_url":"https://github.com/microbit-foundation.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Firmata for the BBC micro:bit\n\nFirmata is a serial protocol that allows a host computer to interact with a microcontroller.\n\nThis BBC micro:bit version of Firmata supports all the core Firmata 2.6 protocol commands,\nallowing the host computer, or client, to perform digital and analog input and output\noperations on the micro:bit's pins. Firmata extension messages allow the client\nto manipulate the micro:bit display, receive events from its buttons and\naccelerometer, and read data from it's built-in sensors.\n\nThe Firmata protocol defines many optional extensions for features such as servo motors\nand i2c communications. Those optional Firmata features  are not currently supported,\nbut could be added later.\n\nThis project has two parts: (1) the Firmata firmware (written in C++ and based on\nthe Lancaster micro:bit runtime and ARM mbed libraries) that gets installed in a BBC micro:bit and\n(2) a client class written in Javascript that runs in Node.js and communicates with\nthe micro:bit over a USB-serial connection.\n\nA precompiled .hex file is provided for easy firmware installation (so you don't need\nto compile it yourself) and a Javascript test suite is provided to test and demonstrate\nthe system. This precompiled hex can be found as part of the latest GitHub Release.\n\n### Installing Firmata on your BBC micro:bit\n\nTo install the Firmata firmware, plug in your BBC micro:bit, then drag and drop\nthe most recent .hex file from the [**GitHub Releases**](https://github.com/microbit-foundation/microbit-firmata/releases) onto the micro:bit's virtual USB drive. The yellow\nlight will flash for a few seconds as the firmware loads. When it stops, the Firmata\nfirmware is installed.\n\n**Note:** If you install another program on your micro:bit you'll need to re-install the\nFirmata firmware before working with Firmata again. Fortunately, that's easy and only takes\na few seconds.\n\n### Running the Test Suite\n\nTo run the test suite or use the Javascript client, you'll need a recent version\nof Node.js and npm, the Node package manager. You can get those from\n\u003chttps://nodejs.org/en/download/\u003e\n\nYou will also need the Node \"serialport\" package. Get that by typing:\n\n\tnpm install serialport@8.0.5\n\n\u003e Note: This library uses calls from before the breaking changes introduced in the newer versions of serialport, and still needs to be updated.\n\nNow you can run the test suite by typing the following:\n\n\tcd client\n\tnode mbTests.js\n\n### Using Microbit Firmata as an NPM library\n\nCreate a new package.json if you don't have one already by running `npm init` and following the prompts, then install this library\nas a dependency with:\n\n```\nnpm install --save https://github.com/microbit-foundation/microbit-firmata.git#v1.3.1\n```\n\nThis should automatically pull any dependencies, including the serialport library.\n\nWhile it is possible to _not_ specify a tag version, we **strongly** recommend that you do include one to keep the library version stable in your application.\n\n\nTo use this in your application, simply `require()` the library and create a new MBFirmata control object:\n\n```\nconst MBFirmata = require(\"microbit-firmata\");\n\nconst microbit = new MBFirmata();\n\nconsole.log( `Microbit version: ${microbit.boardVersion()}` );\nmicrobit.setDigitalOutput( 0, true );\n```\n\n### Exploring the JavaScript Client\n\nYou can explore the JavaScript client interactively from the Node command line.\n\nFirst, start Node by typing:\n\n\tnode\n\nThen paste in these two lines of code to import and instatiate the Firmata client:\n\n\tvar MBFirmataClient = require('./MBFirmataClient.js');\n\tvar mb = new MBFirmataClient();\n\nRun the following line to connect the client to the board:\n\n\tmb.connect();\n\nThe connect() method will scan your serial/COM ports looking for one connected to a micro:bit,\nso it's easy to use. However, if you need more control, the client inclides an entry point\nthat lets you to pass in your own serial port.\n\nTo verify that the board is responding, run the following to check the firmata version:\n\n\tmb.firmataVersion\n\nIf the board has replied to the initial version request, this will return a non-empty string\nsuch as \"Firmata Protocol 2.6\".\n\nTo scroll a string across the display:\n\n\tmb.scrollString('Hello, Firmata!');\n\nYou can speed that up by specifying a delay parameter:\n\n\tmb.scrollString('Hello, Firmata!', 40);\n\nThe default delay is 120, so 40 is three times faster than normal.\n\n### Organization and Additional Documentation\n\nThe **client** folder contains Javascript code for the Firmata client class that\nruns in Node.js. This folder also contains the micro:bit Firmata test suite.\nBesides confirming that Firmata works, the test suite is a handy source of code\nyou can copy and modify to use in your own applications.\n\nThe **firmware** folder contains the C++ source code for the Firmata firmware that runs in\nthe micro:bit. It's easier to use the precompiled .hex file than to compile from source.\n\nAdditional MarkDown files document the client API and the firmware implementation.\n\n### Building the firmware from source\n\nIf you just want to use Firmata, you don't need to build it yourself. The latest\ncompiled version is available **precompiled** folder or from a GitHub release. You\ncan install it just by dragging and dropping the .hex file onto the USB drive of your\nBBC micro:bit.\n\nHowever, if you'd like to extend or improve the firmware,\nthen building it will be the first step.\n\n### Building the micro:bit V1 firmware from source\n\nBuilding the firmware is done with Yotta, and instructions for setting up your\nenvironment can be found at:\n\n[micro:bit runtime offline toolchain](https://lancaster-university.github.io/microbit-docs/offline-toolchains/)\n\nOnce you have verified your build toolchain works by building the `microbit-samples` example,\nyou can build the firmware as follows:\n\n\tcd firmware\n\tyt target bbc-microbit-classic-gcc@https://github.com/lancaster-university/yotta-target-bbc-microbit-classic-gcc\n\tyt build\n\nThe compiled firmware will be at:\n\n\t./build/bbc-microbit-classic-gcc/source/mbFirmate-combined.hex\n\nDrag this file to your micro:bit's USB drive to install it.\n\nYou can use the test suite to confirm that it works.\n\n### Building the micro:bit V2 firmware from source\n\nBuilding the firmware is done with the CODAL build system, and instructions for installing the pre-requisite tools can be found at:\n\n[microbit-v2-samples](https://github.com/lancaster-university/microbit-v2-samples)\n\nOnce you have verified your build toolchain works by building the `microbit-v2-samples` example,\nyou can build the firmware as follows:\n\n\tcd microbit-firmata\n\tgit submodule update --init\n\tcd firmware\n\tpython buildv2.py\n\nThe compiled firmware will be at:\n\n\t../microbit-v2-samples/MICROBIT.hex\n\nDrag this file to your micro:bit's USB drive to install it.\n\nYou can use the test suite to confirm that it works.\n\n### Creating a universal hex for micro:bit V1 and micro:bit V2\n\nA tool which can easily create a .hex file that will support all micro:bit variants can be found at:\n\n[micro:bit Universal Hex Creator](https://tech.microbit.org/software/universal-hex-creator/)\n\nThere is more information about the .HEX file format here:\n\n[.HEX file format](https://tech.microbit.org/software/hex-format/)\n\n### License\n\nThis software is under the MIT open source license.\n\nSPDX-License-Identifier: MIT\n\n### Code of Conduct\n\nTrust, partnership, simplicity and passion are our core values we live and breathe in our daily work life and within our projects. Our open-source projects are no exception. We have an active community which spans the globe and we welcome and encourage participation and contributions to our projects by everyone. We work to foster a positive, open, inclusive and supportive environment and trust that our community respects the micro:bit code of conduct. Please see our [code of conduct](https://microbit.org/safeguarding/) which outlines our expectations for all those that participate in our community and details on how to report any concerns and what would happen should breaches occur.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fmicrobit-firmata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrobit-foundation%2Fmicrobit-firmata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobit-foundation%2Fmicrobit-firmata/lists"}