{"id":13813411,"url":"https://github.com/whaleygeek/bitio","last_synced_at":"2025-05-15T00:33:08.204Z","repository":{"id":77757971,"uuid":"93845009","full_name":"whaleygeek/bitio","owner":"whaleygeek","description":"A micro:bit I/O device library for Python","archived":false,"fork":false,"pushed_at":"2022-11-26T09:55:07.000Z","size":1197,"stargazers_count":92,"open_issues_count":23,"forks_count":31,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-08-04T04:04:02.429Z","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":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whaleygeek.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":"2017-06-09T09:55:33.000Z","updated_at":"2024-05-29T05:20:14.000Z","dependencies_parsed_at":"2023-03-05T20:00:44.086Z","dependency_job_id":null,"html_url":"https://github.com/whaleygeek/bitio","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/whaleygeek%2Fbitio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaleygeek%2Fbitio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaleygeek%2Fbitio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaleygeek%2Fbitio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whaleygeek","download_url":"https://codeload.github.com/whaleygeek/bitio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225319220,"owners_count":17455727,"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-08-04T04:01:16.917Z","updated_at":"2024-11-19T08:30:33.444Z","avatar_url":"https://github.com/whaleygeek.png","language":"Python","funding_links":[],"categories":["Python","编程","🐍 Python"],"sub_categories":["Python","🐍 Python Libraries"],"readme":"# bitio - A Micro:bit IO device\n\n## What is this?\n\nbitio (pronounced bitty-o) is a micro:bit I/O library for Python.\nIt allows you to run code in Python on a PC/Mac/Linux/Raspberry Pi\nand interact directly with the micro:bit. It works with both Python 2 and\nwith Python 3 on Mac, PC, Raspberry Pi and Linux.\n\n![bitio logo](bitio.png)\n\nI gave a presentation at PyconUK 2017, which someone kindly recorded\nand uploaded to YouTube - here:\n\n[YouTube PyconUK 2017](https://www.youtube.com/watch?v=MnjMLWvRV6Q)\n\n## NEWSFLASH - using with a V2.0 micro:bit or V1.5 micro:bit\n\nThe Python API's for sound and other touch features are still stabilising at present\non V2. I hope to add more support for V2 when things are a bit more stable.\n\nIf you have a V1.5 micro:bit, a new sensor was fitted for the accelerometer and compass.\nThis requires new hardware drivers in order to work.\n\nYou can get both a V1.5 and a V2 micro:bit to work by using the bitio.hex on the \nnewarch branch here: https://github.com/whaleygeek/bitio/tree/newarch\n\nI am currently testing all the examples on this new branch, and will pull\nthem back on to the main branch here when they pass there tests.\n\n## Where is the latest version?\n\nThe bitio library was written in part to support a new chapter to the highly successful\nchildrens coding book 'Adventures in Minecraft'.\n\nYou can get the official version of the library that supports the book from here:\n\n[Official version - on Adventures in Minecraft site](https://github.com/AdventuresInMinecraft/bitio)\n\nIf you want something a bit more leading edge with some experimental new features,\ngo right to the author's website and get the latest code from here:\n\n[Development version - on whaleygeek site](https://github.com/whaleygeek/bitio)\n\n\n## What can I do with it?\n\nThis package is useful if you want to use the micro:bit as an input or an output\ndevice for other programs, e.g. for Minecraft. Tilt your micro:bit, and\nsomething happens in the Minecraft world. It can be used for anything\nthough, where you want to use the input and output devices on the micro:bit\ninside a Python program on a bigger computer.\n\n[About the Micro:bit](https://microbit.org)\n\n[About MicroPython](https://python.microbit.org)\n\n[About Minecraft](https://minecraft.net)\n\n# Show me some projects!\n\nKevin Thomas from MyTechnoTalent, Washington DC, attended micro:bit Live 2020 and was\nsignposted to bitio. He then went on to make some fantastic resources using bitio\nas a way to get internet connectivity.\n\n[ML with micro:bit](https://github.com/mytechnotalent/MicroPython-micro-bit_Talking_ML)\n\nJosh from EduBlocks added bitio support, after we met at PyconUK 2017.\n\n[Edublocks and bitio](https://edublocks.org/)\n\nMr NCSComputing (Chris Penn) has written up a lot of projects using bitio and minecraft\ntogether: \n\n[Bitio with Minecraft](http://warksjammy.blogspot.co.uk/2017/07/bitio-blogs-in-one-place.html?view=timeslide)\n\nSean M. Tracey has written a NodeRed wrapper for it:\n\n[NodeRed](https://flows.nodered.org/node/node-red-contrib-bitio-wrapper)\n\nGiles Booth has built an internet controlled Radio with it:\n\n[Internet Radio](http://www.suppertime.co.uk/blogmywiki/2017/08/microbit-controlled-radio/)\n\nDr Simon Monk wrote about BitIO in his new MicroPython book:\n\n[Dr Simon Monk](https://www.amazon.com/Programming-BBC-micro-Getting-MicroPython/dp/1260117588)\n\nMusab Kılıç used with pyuserinput to build a motorbike simulator:\n\n[MicroBike](https://github.com/musabkilic/MicroBike)\n\nMuzaffer Yağız Yasak used with instructions from MicroBike and w10toast to build a reminder system:\n\n[MicroReminder](https://github.com/codermyagiz/MicroReminder)\n\nAnd of course, David Whale added a chapter to the book Adventures in Minecraft all about\nmicro:bit and it uses bitio:\n\n[Adventures in Minecraft](https://www.amazon.co.uk/Adventures-Minecraft-David-Whale/dp/1119439582)\n\n\n# Getting Started\n\nThere are a number of ways you could get bitio installed, however this route is\ndesigned to be mostly 'install free', specifically to make it easy for \nschools to use the package where there is a mostly locked-down Python\nenvironment.\n\nPress the green CODE button which shows a download icon\n\nchoose DOWNLOAD ZIP\n\nUnzip the zip file\n\nFlash the bitio.hex file onto your micro:bit by dragging and dropping\nit onto the MICROBIT drive that appears when you plug in your micro:bit.\nThe bitio logo will appear on the display to show you that it has\nloaded correctly.\n\nThe best way to use the package in a restricted school environment is to\nthen just copy the 'microbit' folder into the students home folder.\nAny Python programs that they write and store in their home folder will\nnow automatically find the 'microbit' package when they 'import microbit'\nfrom any of their Python programs.\n\n\nIf you are on Windows, you first need to install the mbed serial driver\nfirst before you can use the serial port on your micro:bit. You don't need to\ndo this on Mac/Pi/Linux as they have a compatible driver already built into the OS.\nNote that you need admin access to your PC and the micro:bit must be plugged in\nwhen you install the driver for it to work (but it says that on the web page\nlinked below)\n\nFor windows, follow these instructions:\n\n[How to install the Windows mbed serial driver](https://support.microbit.org/solution/articles/19000022103-how-do-i-use-the-serial-port-with-a-micro-bit-on-windows)\n\n## Making a connection\n\nRun (in Python 2 or Python 3, both are supported) the counter.py example\nthat is in the src folder.\n\nYou could run this from the command prompt if you know how. But it is\nalso just as easy to open counter.py from within the IDLE editor\nand run it, and it should work fine.\n\nFollow the on screen instructions which will walk you through unplugging and\nplugging back in the micro:bit, as a way to detect which serial port it is\nconnected to on your computer.\n\n```\nconnecting...\nwarning:Could not open the serial port that was remembered from last time\nScanning for serial ports\nremove micro:bit, then press ENTER\nscanning...\nfound 132 micro:bit(s)\nplug in micro:bit, then press ENTER\nscanning...\nfound 133 micro:bit(s)\nfound 1 new micro:bit\nselected:/dev/tty.usbmodem1422\nDo you want this micro:bit to be remembered? (Y/N)y\nYour micro:bit has been detected\nNow running your program\n```\n\nYou could also specify the connected port by setting the environment variable\n`BITIO_PORT`:\n\n- Windows ```set BITIO_PORT=COM7```\n- GNU/Linux ```export BITIO_PORT=COM7```\n\nFinally, you should get a counter counting from 00 to 99 in the WhaleySans font\n(2x5 sized digits) on the display.\n\n# Documentation\n\nThere are no official docs yet, but here is a short quick-reference to get you started.\nNote I have added a microbit.sleep(2000) at the end of some examples, because\nonce your Python program finishes the bitio icon will be displayed on the\nmicro:bit again and this will overwrite whatever is on the micro:bit screen.\n\n## Connecting to the micro:bit\n\n```\n    NOTE: Make sure bitio.hex is installed\n    import microbit\n```\n\n## Scrolling text on the screen\n\n```\n    import microbit\n    microbit.display.scroll(\"Hello\")\n    microbit.sleep(2000)\n```\n\n## Displaying a single character\n\n```\n    import microbit\n    microbit.display.show(\"A\")\n    microbit.sleep(2000)\n```\n\n## Displaying numbers\n\n```\n    import microbit\n    microbit.display.scroll(2345)\n    microbit.sleep(2000)\n```\n\n## Displaying numbers using a 2-digit font\n\n```\n    import microbit\n    for n in range(99):\n        microbit.display.show(n)\n        microbit.sleep(250)\n```\n\n## Getting a list of pre-defined images\n\n```\n    import microbit\n    print(microbit.Image.STD_IMAGE_NAMES)\n    microbit.sleep(2000)\n```\n\n## Displaying a pre-defined image\n\n```\n    import microbit\n    microbit.display.show(microbit.Image.HAPPY)\n    microbit.sleep(2000)\n```\n\n## Spinning a clock\n\n```\n    import microbit\n    for c in microbit.Image.ALL_CLOCKS:\n        microbit.display.show(c)\n        microbit.sleep(250)\n```\n    \n## Defining a custom image\n\n```\n    import microbit\n    BANANA = microbit.Image(\"00090:00090:00990:09900:99000\")\n    microbit.display.show(BANANA)\n    microbit.sleep(2000)\n```\n\n## Clearing the display\n\n```\n    import microbit\n    microbit.display.clear()\n    microbit.sleep(2000)\n```\n\n## Sensing when a button is pressed\n\n```\n    import microbit\n    while True:\n        if microbit.button_a.was_pressed():\n            microbit.display.show(\"A\")\n            microbit.sleep(500)\n            microbit.display.clear()\n```\n    \n## Sensing when a pin is touched\n\n```\n    import microbit\n    while True:\n        if microbit.pin0.is_touched():\n            microbit.display.show(\"T\")\n            microbit.sleep(500)\n            microbit.display.clear()\n```\n    \n## Reading accelerometer values\n\n```\n    import microbit\n    while True:\n        print(microbit.accelerometer.get_values())\n        microbit.sleep(250)\n```\n  \n## Sensing tilt in the X plane\n\n```\n    import microbit\n    while True:\n        x = microbit.accelerometer.get_x()\n        x = abs(x)\n        if x \u003e 200:\n            print(\"Tilted\")\n        else:\n            print(\"Not Tilted\")\n        microbit.sleep(500)\n```\n\n## Reading the temperature\n\n```\n    import microbit\n    while True:  \n        print(microbit.temperature())\n        microbit.sleep(500)\n```\n\n## Using the radio\n\n(see also radio.py example).\n\nThanks to @jarvisteach for this contribution.\n\n```\n    import microbit\n    microbit.radio.config(group=132, queue=10)\n    microbit.radio.on()\n\n    while True:\n        time.sleep(0.1)\n        incoming = microbit.radio.receive_bytes()\n\n        if incoming != \"None\":  #TODO: api.py will need better None handler.\n            incoming = stripMakeCodeHeader(incoming)\n            print(incoming)\n```\n\n# TODO ITEMS\n\nThese items are currently not implemented in this release, but will be added soon.\n\npin[3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]\n  digital_read()\n  digital_write()\n  analog_read()\n  analog_write()\n  set_pull()\n\ndisplay\n  get_pixel(x, y)\n  set_pixel(x, y, value)\n  on()\n  off()\n  is_on()\n\n\n\n# Sample programs\n\nHere are a few sample programs you can use to get started\n\n```\nbutton.py  - sense a button press\ncounter.py - count from 00 to 99\nsensing.py - sense buttons and accelerometer values\ntouched.py - sense pin touch\nstd_image.py - use in-built standard images\ncustom_image.py - define your own custom images\ntilt.py - show how to sense tilt movements\ntilt_mc.py - use the tilt with Minecraft\nclocks.py - show a spinning clock\narrows.py - show a spinning arrow\nradio.py - receive messages from a radio and log to a file (contributed)\n```\n\nNot all of the features of the micro:bit are made available via this\nAPI yet, but we're working on it!\n\n## MicroPython\n\nThe bitio code that runs at the micro:bit end is MicroPython.\nThe version of MicroPython cached inside this project is from here:\n\n[MicroPython](https://codewith.mu/help/0.9.13/)\n\n\n## Historical Perspective and timeline\n\nOn 9th May 2014 I published a package called 'anyio'. This was as a result of developing\na coding book called Adventures in Minecraft, and the desire to add some hardware chapters.\nAt the time, there wasn't a credible off the shelf GPIO like platform that worked out of the\nbox, for PC/Mac/Linux. So I created something a bit like RPi.GPIO but called it anyio,\nso that it was possible to write Adventure 5, 9 and 10 of the book with minimal changes\nbetween all platforms. Some work was done by SKPangUK as a local distributor, who\n'finishes off' the board by soldering headers and pre-loading the anyio firmware, as well\nas selling a bundled package with everything you need to follow the book.\n\nAnother key innovation inside anyio is the portscan package that I wrote. This works\non PC/Mac/Linux/Raspberry Pi and walks the user through a workflow of removing and inserting\nthe USB cable as a simple method to self-identify the port. This was key to reducing the size\nof the setup instructions inside the 'Adventures in Minecraft' book, as it makes the workflow\nidentical on all 4 platforms. I have since used this workflow and package in lots of my\nother example micro:bit programs inside my github code repository.\n\n[anyio](https://github.com/whaleygeek/anyio)\n\n[skpang anyio](http://skpang.co.uk/catalog/pro-micro-33v8mhz-with-headers-and-anyio-firmware-p-1327.html)\n\n\nOn 28th Jan 2016, I wrote a proof-of-concept in a project called 'mb_remote', which is here:\n\n[mb_remote](https://github.com/whaleygeek/mb_remote)\n\nThis was built using an older version of MicroPython, and the API has changed since.\nI spoke to a number of people that attended PyCon UK that year, and raised some interest.\n\nThis spawned similar work, e.g. this from Joe Glancy and Andrew Mulholland published on\n9th May 2016 here:\n\n[microperi](https://github.com/c0d3st0rm/microperi)\n\nMuch as I like this work, I never agreed with the name. The main reason is that I wanted\nit to be possible to take an unmodified program written for the micro:bit, run it\non a PC/Mac/Linux/Raspberry Pi machine, and for it to work unmodified. Hence the module\nname needs to be called 'microbit'.\n\nAlso, you will note that microperi requires manual connection to the micro:bit, whereas\nbitio automatically connects when you import the module.\n\nThere are many places where I have used this, but the most recent is a 'micro:bit\nradio gateway' project here:\n\n[radio gateway](https://github.com/whaleygeek/microbit-gateway)\n\n\nIn May 2016, I had discussions with Ryan Walmsley from Ryantek, and he wanted to\nbuild a board a bit like my anyio board but with Raspberry Pi HAT headers on it, and \nhe asked for permissions to use my anyio library as a basis, which I agreed to. Ryan\nran a successful kickstarter and ended up building a retail packaged board with support\nfor I2C, SPI, and many of the boards in the huge Raspberry Pi HAT eco-system.\n\n[RTk.GPIO board](https://ryanteck.uk/electronics/166-rtkgpio.html)\n\n\nRoll forward to 2017, and discussions start to take place between myself and my co-author\nMartin O'Hanlon about developing a 2nd edition of our highly successful childrens coding\nbook 'Adventures in Minecraft'. I had this idea that now that the micro:bit is widely\ndeployed and you can walk into real shops and buy them off of the shelf, it would be a much\neasier to obtain platform than the Arduino/anyio board, and also provide progression\nin both directions between Python on the micro:bit and Python on larger platforms.\n\nNote a very influential (private) discussion with Nicholas Tollervy of the Python Software Foundation,\nwhere he states that 'using Raw REPL would be a more robust protocol for driving this\nsort of interface'. bitio uses the Raw REPL extensively.\n\n[raw REPL](http://docs.micropython.org/en/v1.8.6/pyboard/reference/repl.html)\n\nSo, bitio is a step towards using the micro:bit as a general purpose IO device for bigger\ncomputers like PC/Mac/Linux. You can of course also use it on the Raspberry Pi in addition\nor instead of RPi.GPIO, but you get some lovely on-board sensors and a display built-in with the\nmicro:bit.\n\n## What is next?\n\nI have a big todo list (look in the docs folder). \n\nOne key thing I want to do is to pull all my various micro:bit comms projects into this single package, \nincluding bringing in the microbit-gateway project for linking via the micro:bit radio network, amongst other features.\n\nI also have a microbit.GPIO idea in the making, where it could be used a bit like RPi.GPIO\nand form part of my anyio package as another supported platform.\n\n\nDavid Whale\n\n@whaleygeek\n\n5th September 2020\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhaleygeek%2Fbitio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhaleygeek%2Fbitio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhaleygeek%2Fbitio/lists"}