{"id":21016345,"url":"https://github.com/josejuansanchez/microbit-ble-spotify","last_synced_at":"2025-07-05T03:33:54.867Z","repository":{"id":151991865,"uuid":"144910513","full_name":"josejuansanchez/microbit-ble-spotify","owner":"josejuansanchez","description":"Bluetooth Low Energy remote control for Spotify on macOS with Node.js and AppleScript.","archived":false,"fork":false,"pushed_at":"2018-08-27T11:00:23.000Z","size":1644,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-15T05:35:00.807Z","etag":null,"topics":["applescript","microbit","microbit-ble","nodejs","spotify"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josejuansanchez.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,"zenodo":null}},"created_at":"2018-08-15T22:44:38.000Z","updated_at":"2023-09-08T17:43:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"c3a4d76e-4f06-4a41-9987-31199d7dad19","html_url":"https://github.com/josejuansanchez/microbit-ble-spotify","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/josejuansanchez/microbit-ble-spotify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josejuansanchez%2Fmicrobit-ble-spotify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josejuansanchez%2Fmicrobit-ble-spotify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josejuansanchez%2Fmicrobit-ble-spotify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josejuansanchez%2Fmicrobit-ble-spotify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josejuansanchez","download_url":"https://codeload.github.com/josejuansanchez/microbit-ble-spotify/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josejuansanchez%2Fmicrobit-ble-spotify/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263677004,"owners_count":23494615,"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":["applescript","microbit","microbit-ble","nodejs","spotify"],"created_at":"2024-11-19T10:12:57.007Z","updated_at":"2025-07-05T03:33:54.855Z","avatar_url":"https://github.com/josejuansanchez.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bluetooth Low Energy remote control for Spotify [![Build Status](https://travis-ci.org/josejuansanchez/microbit-ble-spotify.svg?branch=master)](https://travis-ci.org/josejuansanchez/microbit-ble-spotify)\n\n[Bluetooth Low Energy][0] remote control for [Spotify][1] on **macOS** with [Node.js][2] and [AppleScript][3].\n\n![Diagram](resources/diagram/hacksterio.png)\n\n## Description\n\nThis project allows you to configure your [micro:bit][4] to work as a [Bluetooth Low Energy (BLE)][0] remote control to control an instance of [Spotify][1] running on **macOS** with [Node.js][2] and [AppleScript][3]. Users can use [micro:bit][4] to perform several actions like play or pause tracks, turn volume up or down and go to next or previous track. To carry out this actions, a custom event with a specific value for each action is raised over [BLE][0] when the [micro:bit][4] buttons are pressed by the user. The events raised by the [micro:bit][4] are catched by a [Node.js][2] script that is running on a computer with **macOS**.\n\nThe project is composed by two pieces of software: \n\n* the **remote control**, that is the software that runs on the [micro:bit][4].\n* the **event listener**, that is the software that runs on your computer.\n\n## Video\n\n[![YouTube Video](https://img.youtube.com/vi/jZdrvi8mveU/0.jpg)](http://www.youtube.com/watch?v=jZdrvi8mveU)\n\n## How it works\n\n![Diagram](resources/diagram/diagram.png)\n\n1. In this diagram the [micro:bit][4] is ready in the *Play* state, this is known because the [micro:bit][4] is showing the letter `P` on the LED screen. An user press the `A` button and then a custom event is raised over [BLE][0], with an specific value to indicate that we want to play or pause a track on [Spotify][1].\n\n2. The event listener is a [Node.js][2] script that is running on the computer and is waiting for the events raised over [BLE][0] by the [micro:bit][4] device.\n\n3. When a custom event is catched by the [Node.js][2] script it uses the API of the [spotify-node-applescript][3] package in order to control the instance of [Spotify][1] running on the computer.\n\n## Remote Control details\n\n### States\n\nThe [micro:bit][4] device can be in one of a finite number of states at any given time. The list of available states are the following:\n\n\u003c!--\n|  Symbol |     State   |  Description |\n|---------|-------------|--------------|\n| **D**  | Disconnected | The [micro:bit][4] device is **not connected** with the computer via [BLE][0].\n| **C**  | Connected | The [micro:bit][4] device is **connected** with the computer via [BLE][0].\n| **P**  | Play | The [micro:bit][4] device is ready to play or pause a track.\n| **V**  | Volume | The [micro:bit][4] device is ready to turn volume up or down.\n| **N**  | Next | The [micro:bit][4] device is ready to go to next or previous track.\n--\u003e\n\n|  micro:bit's LED screen | State | Description |\n|-------------------------|-------|-------------|\n| ![Disconnected State](resources/img/d.png) | **D**isconnected | The [micro:bit][4] device is **not connected** with the computer via [BLE][0].\n| ![Connected State](resources/img/c.png) | **C**onnected | The [micro:bit][4] device is **connected** with the computer via [BLE][0].\n| ![Play State](resources/img/p.png) | **P**lay | The [micro:bit][4] device is ready to play or pause a track.\n| ![Volume State](resources/img/v.png) | **V**olume | The [micro:bit][4] device is ready to turn volume up or down.\n| ![Next State](resources/img/n.png) | **N**ext | The [micro:bit][4] device is ready to go to next or previous track.\n\n### Inputs\n\nThe state machine can change from one state to another in response to external inputs. In our project there are two possible inputs:\n\n| Input |      Description |\n|-------|------------------|\n| **BLE** | When the [micro:bit][4] establishes a [BLE][0] connection with a computer. |\n| **AB**  | When the [micro:bit][4] buttons `A` and `B` are pressed together. |\n\n### Transitions\n\nThe change from one state to another is called a transition.\n\n### State machine diagram\n\nThe state diagram for the project can be modeled as follows:\n\n![State Machine](resources/img/state_machine.png)\n\nWhere each state is represented by a node (circle) and the edges (arrows) show the transitions from one state to another. Each arrow is labeled with the input that triggers that transition.\n\n### Actions\n\nThe actions that users can perform to control [Spotify][1] via [BLE][0] are:\n\n* Play or pause tracks.\n* Turn volume up or down.\n* Go to next or previous track.\n\nTo run these actions the [micro:bit][4] device needs to be in one of these states: \n\n* **P** (Play).\n* **V** (Volume).\n* **N** (Next).\n\nWhen the [micro:bit][4] is in one of these states the user can press the `A` or `B` buttons in order to raise a custom event to control [Spotify][1]. This table shows what are the different possibilities that an user can perform.\n\n|  Input \\ State | **P** | **V** | **N** |\n|----------------|-------|-------|-------|\n| **Press `A` button**  | Play or pause track | Turn volume up | Go previous track |\n| **Press `B` button**  |  | Turn volume down | Go next track |\n\n## No pairing security\n\nAlthough this script is using [BLE][0] there is no need to pair your [micro:bit][4] with your computer. In order to get this, the `pxt.json` file has been configured as follows. The property of the bluetooth json object called `open` has been configured with a value of `1` which means *no security*.\n\n```json\n\"yotta\": {\n    \"config\": {\n        \"microbit-dal\": {\n            \"bluetooth\": {\n                \"open\": 1\n            }\n        }\n    }\n}\n```\n\n## How to build and deploy the *remote control*\n\n1. Install [node.js][2].\n\n2. Install the PXT [(Microsoft Programming Experience Toolkit)][6] command line tool with `npm`.\n\n```\nnpm install -g pxt\n```\n\n3. Clone this repository to your computer.\n\n```\ngit clone https://github.com/josejuansanchez/microbit-ble-spotify.git\ncd microbit-ble-spotify\ncd ble-remote-control\n```\n\n4. Install the [micro:bit][4] target for PXT. This target allows you to program a [micro:bit][4] using PXT.\n\n```\npxt target microbit\n```\n\n5. Install the required PXT packages for this project (`core` and `bluetooth`). The dependencies of the project are defined in `pxt.json`.\n\n```\npxt install\n```\n\n6. Connect the [micro:bit][4] to your computer via USB.\n\n7. To build and deploy the project, execute `pxt` with no arguments or run `make`. Doing this, PXT will compile and link the code into an `.hex` file and will deploy it into your connected [micro:bit][4].\n\n```\npxt\n```\n\nWhen you run the `pxt` command, you will see a similar message to this:\n\n```\nUsing target PXT/microbit with build engine yotta\n  Target dir:   /microbit-ble-rc-spotify/node_modules/pxt-microbit\n  PXT Core dir: /microbit-ble-rc-spotify/node_modules/pxt-core\nrunning 'pxt deploy' (run 'pxt help' for usage)\nPackage built; written to binary.hex; size: 605847\ncopying binary.hex to /Volumes/MICROBIT/\n   wrote hex file to /Volumes/MICROBIT/\n```\n\nNow, your [micro:bit][4] device is ready to work as a remote control for [Spotify][1] on **macOS** with [Node.js][2] and [AppleScript][3]. The next step is to run the `ble-event-listener` script to listen to the custom events raised by the BBC micro:bit over [BLE][0].\n\n## Compiled Firmware\n\nThe compiled firmware is available in the `resources/firmware` folder of the project. If your want you can avoid the build process and copy the `.hex` file to [micro:bit][4] disk drive.\n\n## How to run the *event listener*\n\n1. Go to `ble-event-listener` directory.\n\n```\ncd ble-event-listener\n```\n\n2. Run the [Node.js][2] script:\n\n```\nnode index.js\n```\n\nWhen you run the script, you will see a similar message to this:\n\n```\nScanning for micro:bit...\n```\n\nNow, your *event listener* is ready to accept [BLE][0] connections from a [micro:bit][4] device.\n\n## Packages used in this project\n\n* [node-bbc-microbit](https://github.com/sandeepmistry/node-bbc-microbit).\n* [spotify-node-applescript](https://github.com/andrehaveman/spotify-node-applescript).\n\n## References\n\n* [How to switch off the need to pair your micro:bit when using Bluetooth](http://bluetooth-mdw.blogspot.com/2016/08/how-to-switch-off-need-to-pair-your.html). Martin Woolley.\n* [Finite-state machine](https://en.wikipedia.org/wiki/Finite-state_machine). Wikipedia.\n\n## Author\n\nDeveloped by [José Juan Sánchez][5].\n\n## License\n\n```\nLicensed under the GNU General Public License, Version 3 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.gnu.org/licenses/gpl-3.0.en.html\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n[0]: https://en.wikipedia.org/wiki/Bluetooth_Low_Energy\n[1]: https://www.spotify.com\n[2]: https://nodejs.org\n[3]: https://www.npmjs.com/package/spotify-node-applescript\n[4]: https://microbit.org\n[5]: http://josejuansanchez.org\n[6]: https://github.com/Microsoft/pxt\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosejuansanchez%2Fmicrobit-ble-spotify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosejuansanchez%2Fmicrobit-ble-spotify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosejuansanchez%2Fmicrobit-ble-spotify/lists"}