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

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.

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.

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.

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 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

Open File

Save As

Save + Run

Serial Mode

In serial mode, you can see the output of the CircuitPython device and even enter commands through the REPL.

Restart

Mobile Sizing

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.