Wirelessly Code your Bluetooth Device with CircuitPython
2024-03-18 | By Adafruit Industries
License: See Original Project Programmers Adafruit Feather
Courtesy of Adafruit
Guide by M. LeBlanc-Williams
Overview
Many people are familiar with Bluetooth Low Energy (BLE) for connecting peripherals such as mice and keyboards or event some headphones or earbuds. However, BLE can do so much more. Did you know you can transfer files over BLE? This is the basis for being able to edit CircuitPython files directly on your device.
Adafruit has been working on a new web-based Code Editor for CircuitPython. This allows you to edit files directly on your Bluetooth devices using just the Chrome web browser without installing any additional software. The great thing about this code editor is it is written completely in JavaScript, so it only runs on your computer and none of your data is ever uploaded to a server.
Last year's guide called Using the Bluefruit Dashboard with Web Bluetooth in Chrome used Web Bluetooth to read sensors on a few of the devices Adafruit offers. This was great for being able to test out all of the sensors on the boards, but the code running on the board was written in Arduino.
With the Code Editor, however, all of the BLE functions are built into CircuitPython itself and so you can have it run any CircuitPython script you would like while still retaining the ability to remotely edit your files.
To get started, all you will need are a Bluetooth board with the nRF52840 chip such as the Circuit Playground Bluefruit, Adafruit CLUE, Feather nRF52840 Express, Feather nRF52840 Sense, BBC micro:bit V2, LED Glasses Driver, or one of a number of other Bluetooth boards that run CircuitPython.
Parts
- Circuit Playground Bluefruit - Bluetooth Low Energy
- Adafruit CLUE - nRF52840 Express with Bluetooth LE
- Adafruit Feather nRF52840 Express
- Adafruit Feather nRF52840 Sense
- BBC micro:bit v2
- Adafruit LED Glasses Driver - nRF52840 Sensor Board
Preparing Chrome
To use the Code Editor, you will need to do a little bit of setup in Chrome. This involves setting a couple of flags to enable Web Bluetooth and should be done regardless of your device or OS. There are some basic instructions on the website when you first get there, but the instructions below cover those in a bit more detail.
The flags are mostly required for storing the bond and reconnecting because some of the functions fairly new. The exception is on Linux where the flags are required to connect at all. So if you are on a non-Linux platform and would rather not enable the flags, keep in mind that the connect button will not function and you will need to create a new Bluetooth pairing each time you connect.
In the address bar for Chrome, type chrome://flags and press enter. This will take you to the internal Chrome flags settings. In the search box, type in enable-experimental-web-platform-features and you should see only one result.
Change disabled to enabled.
In the search box, type in enable-web-bluetooth-new-permissions-backend and you should again see only one result. Change the setting to Enabled and click the Relaunch button.
That's it! You should be ready to go.
Device Setup
In order to connect, first make sure you are running the latest version of Adafruit CircuitPython for your board. You will need to be running CircuitPython 7.1.0-beta.0 or later.
Once you have that installed, head on over to https://code.circuitpython.org.
Bluetooth Advertising Mode
Before connecting, you will need to place the device in Bluetooth Advertising Mode. This allows devices to see the Bluetooth device. When you power up the device, pay attention to the lights. It should show a solid red light, followed by a blinking yellow light, and then a blinking blue light. When the blinking blue light appears, press the reset button.
You should see the lights go through the same sequence except this time the blue light should be solid. Be sure to place the device in fairly close proximity to the computer or mobile device or it may not show up.
Connecting a New Device for the First Time
The first time you connect, it you will need to create a bond with the device. This allows it to access the files and stores the device information in Chrome.
Android Devices
At this time, only Android devices with BLE hardware running a more recent version of the operating system such as 6.0 or later will work. If your device meets those requirements and once you have enabled the options in Chrome, the connection steps are the same as Chrome on Linux and macOS.
Chrome on macOS and Linux
With macOS or Linux, the Code Editor should work without additional modification. Just click the Request Bluetooth Device button, select the device from the list, and click Pair. The Bond Bluetooth Device button should turn purple after a moment, and you can click that.
Chrome on Windows
Chrome for windows has a known bug where if you attempt to connect the Bluetooth device directly through the browser, it will have errors connecting.
Of the different operating systems, Windows seems to be the most finicky and sometimes will have difficulties reconnecting after the first time.
To work around this, first go to the Bluetooth Devices settings. You can get there by going to Settings, Devices, and make sure you are on the Bluetooth & other devices tab.
Click Add Bluetooth or other device.
When the dialog comes up, choose Bluetooth.
Your device may appear as CIRC or CIRPY or something similar. Click the device to connect. If you don't see it, make sure it has the required version of CircuitPython, is in Bluetooth Advertising mode, and is close enough to the computer.
Once you do that, you should be able to connect using the Connect Button in the upper righthand corner in chrome.
Reconnecting
Once you have connected a device, Chrome saves the Bluetooth connection information for that device. To reconnect, make sure your device is in Bluetooth Advertising mode and just click the Connect Button in the upper righthand corner.
Troubleshooting Connection Issues
Unfortunately connecting with Bluetooth, the first time doesn't always go so smoothly and can involve several attempts before it successfully pairs and shows you the document. Also, Web Bluetooth in general can be a little finicky at times.
Here are a few things to try if you are having trouble connecting:
- Try reloading the web page.
- Restart the device and put into advertising mode again.
- Try removing any existing pairings from the device.
- Try connecting through your Operating System Bluetooth Devices first.
- Try restarting your Browser.
- Try going to chrome://bluetooth-internals, choose the devices tab, and removing any existing devices in there.
- In Chrome, go to Settings → Privacy and Security → Site Settings → Additional Permissions → Bluetooth Devices and make sure Sites can ask to connect to Bluetooth devices is selected. Also, try removing any devices from here.
- Open up the Console through the toolbar with 3 Dots Menu → More Tools → Developer Tools and see if there are any messages that might provide more clues.
The code editor is relatively new and there may be some bugs, so if you find a reproducible bug, you can always open a new issue at https://github.com/circuitpython/web-editor.
Usage
Once you are connected, using the File Editor is pretty straightforward. Currently you can only edit one file at a time to reduce the design complexity.
Editor Mode
The editor mode is the main mode you will be using the CircuitPython Code Editor in. This will allow you to do most of the operations you need to edit and write new code. When you first open the editor, it will attempt to load code.py from the root directory of the circuit board. If the file is not found, it will create a new unsaved document for you to edit.
New File
This option will close any files you are currently working on after making sure they are saved and create a brand-new file.
Open File
This option will allow you to open an existing file to work on editing. The code editor tries to determine if the file you are trying to open is a text file or binary file based on the file extension.
Save As
This will allow you to choose a filename to save your code as. If the file already exists, it will prompt you if you want to overwrite the file. Keep in mind that you can name it anything you want, but it is naming it with an unexpected extension could have unexpected results.
Save + Run
These options will save your file. If you are working on a file, it will prompt you to choose a filename and location. If you are working on code.py, it will send a Control+C and Control+D command to restart CircuitPython. If you are working on another filename, it will attempt to import the filename through the REPL.
Serial Mode
In serial mode, you can see the output of the CircuitPython device and even enter commands through the REPL.
Restart
This button will send a Control+C and Control+D to the device in order to soft restart CircuitPython.
Mobile Sizing
When the window is small enough, a mobile menu will appear as 3 bars in order to reduce the amount of screen real estate that the editor takes up. Additionally, only the filename and not the full path will be displayed.
Clicking on the menu will display the editor functions that were hidden allowing for full functionality even in mobile mode.
That's it! Enjoy using and if you would like to contribute to improving the editor, you can submit a Pull Request to https://github.com/circuitpython/web-editor.
Have questions or comments? Continue the conversation on TechForum, DigiKey's online community and technical resource.
Visit TechForum