{"id":29643391,"url":"https://github.com/pybricks/micropython-bleradio","last_synced_at":"2025-07-21T23:36:29.421Z","repository":{"id":242494010,"uuid":"809699213","full_name":"pybricks/micropython-bleradio","owner":"pybricks","description":"Connectionless messaging via BLE with MicroPython boards (and LEGO hubs).","archived":false,"fork":false,"pushed_at":"2024-07-11T10:49:51.000Z","size":17,"stargazers_count":11,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-09T14:12:24.640Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/pybricks.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":"2024-06-03T09:25:44.000Z","updated_at":"2025-01-08T09:26:26.000Z","dependencies_parsed_at":"2024-06-03T11:34:35.240Z","dependency_job_id":"968414a2-b3ac-48a7-b1f9-8a1f2c3647a6","html_url":"https://github.com/pybricks/micropython-bleradio","commit_stats":null,"previous_names":["pybricks/micropython-bleradio"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pybricks/micropython-bleradio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pybricks%2Fmicropython-bleradio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pybricks%2Fmicropython-bleradio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pybricks%2Fmicropython-bleradio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pybricks%2Fmicropython-bleradio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pybricks","download_url":"https://codeload.github.com/pybricks/micropython-bleradio/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pybricks%2Fmicropython-bleradio/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266403332,"owners_count":23923406,"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","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-07-21T23:36:27.703Z","updated_at":"2025-07-21T23:36:29.406Z","avatar_url":"https://github.com/pybricks.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Connectionless messaging via Bluetooth Low Energy (BLE) with MicroPython\n\nThis MicroPython library allows boards with BLE to broadcast (advertise) and\nobserve (scan) small amounts of data without setting up any connections.\n\nThis allows very simple many-to-many communication between broadcasters\nand multiple observers. Each board can broadcast on one channel (0-255), and\nobserver on multiple channels.\n\nThe starting order does not matter, and you can add or remove boards to and\nfrom the network as you go.\n\nIt matches the protocol used on LEGO hubs that run Pybricks. This means you\ncan also communicate with these LEGO hubs from any MicroPython board with BLE.\n\n## What can you send and receive?\n\nYou can send signed integer values, floating point numbers, booleans, strings,\nor bytes. Or a list/tuple of these objects.\n\nFor example, you can broadcast one of the following:\n\n```python\n\ndata = 12345\n\ndata = \"Hello, world!\"\n\ndata = b\"\\x01\\x02\\x03\"\n\ndata = (123, 3.14, True, \"Hello World\")\n```\n\nBoolean values are packed into one byte. All other types are packed into their\nrespective sizes plus one byte for the type.\n\nSince advertisements payloads are limited to 31 bytes by the Bluetooth spec and\nthere are 5 bytes of overhead, the combined size of all type headers and values\nis limited to 26 bytes.\n\nWhen no data is observed, the `observe` method returns `None`.\n\nTo stop broadcasting, use `broadcast(None)`.\n\nThe full specification is available in the [protocol](https://github.com/pybricks/technical-info/blob/master/pybricks-ble-broadcast-observe.md) file.\n\n## States versus events\n\nDue to the nature of communication, this technique works best for sending\n_states_, not _events_. Values are broadcast all the time until you change the\ndata, but there is no guarantee that one single value will be received.\n\nFor example, if you want to use a button to incrementally turn a motor by 90\ndegrees, you should not broadcast a message for each button press. Instead, you could\nmaintain the target angle on the broadcaster, and broadcast `90`, `180`, `270`,\nand so on, incrementing every time the button is pressed.\n\n## Installation\n\nCopy [bleradio.py](https://raw.githubusercontent.com/pybricks/micropython-bleradio/master/bleradio.py) to your board manually.\n\nOr use the `mpremote` tool to install it directly from GitHub:\n\n```\nmpremote mip install https://raw.githubusercontent.com/pybricks/micropython-bleradio/master/bleradio.py\n```\n\n## Example (run this one one board...)\n\n```python\n# Basic usage of the radio module.\n\nfrom time import sleep_ms\nfrom bleradio import BLERadio\n\n# A board can broadcast small amounts of data on one channel. Here we broadcast\n# on channel 5. This board will listen for other boards on channels 4 and 18.\nradio = BLERadio(broadcast_channel=5, observe_channels=[4, 18])\n\n# You can run a variant of this script on another board, and have it broadcast\n# on channel 4 or 18, for example. This board will then receive it.\n\ncounter = 0\n\nwhile True:\n\n    # Data observed on channel 4, as broadcast by another board.\n    # It gives None if no data is detected.\n    observed = radio.observe(4)\n    print(observed)\n\n    # Broadcast some data on our channel, which is 5.\n    radio.broadcast([\"hello, world!\", 3.14, counter])\n    counter += 1\n    sleep_ms(100)\n```\n\n## Example (... run this on any number of other boards)\n\n```python\nfrom bleradio import BLERadio\n\nradio = BLERadio(observe_channels=[5])\n\nold_data = None\n\nwhile True:\n\n    new_data = radio.observe(5)\n    strength = radio.signal_strength(5)\n\n    if new_data == old_data:\n        continue\n\n    print(strength, \"dBm:\", new_data)\n    old_data = new_data\n```\n\n## Mixing it with other BLE code\n\nSee [examples/custom_irq](examples/custom_irq.py) to see how you can set up the\nobserve IRQ manually so you can mix it with other BLE code.\n\n## Mixing it with LEGO Hubs that run Pybricks\n\nYou can use this library to communicate with LEGO hubs that run Pybricks. For\nexample, you can use a MicroPython board to control a LEGO hub.\n\nHubs running Pybricks already have this functionality built in so you won't\nneed to install this library on those hubs. The API is mostly the same, but the\nchannels are specified [during hub\nsetup](https://docs.pybricks.com/en/latest/hubs/primehub.html).\n\nSee [this video for an example](https://www.youtube.com/watch?v=WzmcihSV2YE).\nAny hub shown here could be replaced by a MicroPython board with BLE.\n\n## Local development\n\nIf you use `vscode`, run the build task (`Ctrl+Shift+B`) to automatically\nupload the local library to the board and then run the currently open example.\nThis method requires `mpremote`.\n\n## Contributing\n\nYou can use the library as shown [here](./LICENSE), but we kindly ask you to\nsuggest changes to the protocol here in an issue so we don't end up with too\nmany incompatible versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpybricks%2Fmicropython-bleradio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpybricks%2Fmicropython-bleradio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpybricks%2Fmicropython-bleradio/lists"}