Connecting with Web Workflow

To use the Code Editor, you will need an internet browser such as Google Chrome, Mozilla Firefox, or Microsoft Edge. It's possible that it may work in other browsers as well, but these ones have been more thoroughly tested.

While there are several possible entry points for using the editor, the recommended way is to open up your browser and navigate to http://circuitpython.local/code/. Note that it is important that you go to http and not https and the trailing slash must be there as well. This should forward you to the first device that it finds and load the editor.

You can also get there by going to http://circuitpython.local/ and selecting the full code editor link on the Welcome screen.

Another way to get there is by navigating to https://code.circuitpython.org/ and selecting WiFi on the dialog prompt that comes up.

This will display a page of instructions along with a link to http://circuitpython.local/code/. Any code you've written in the editor should be automatically transferred by clicking that link.

You may be prompted for a password at this point. Leave the username blank. For the password, type the value that you assigned to the CIRCUITPY_WEB_API_PASSWORD setting in you settings.toml file.

Once you have connected, a current Device Info box should appear which also shows other discovered devices on the network.

The Connect button in the upper Right-hand corner should also change to a Disconnect button.

Read Only Mode

In order to avoid file corruption, CircuitPython requires that there is only one way to write to the device. This means that in order to use Web Workflow to write to the device, the USB Mass Storage must first be disabled. Directions on disabling it are on the Device Setup page.

A notice that you are in Read Only mode will appear if your device's USB Mass Storage is still enabled.

Connecting to Other Devices

If you have multiple devices available on your network, navigating to circuitpython.local will use the first device that it finds. If you would like to connect to other devices, you can use the information box that appears when you connect.

Simply select a device you would like to connect to listed under More Connected Devices. If there is a device that you know is online, but is not appearing under this list and there hasn't been any recent network activity, the current device may just believe it is offline. You can reset the device and it should show up in the list.

To refresh your devices, you can just click the Refresh Device List icon that is above the devices.

If you would like to open the device information and discovery dialog, you can click the Info button while you are connected.

Opening and Saving Files

Opening and Saving files is designed to be like to most other applications. Just use the buttons along the top of the editor window.

Clicking the Open or Save As buttons along the top will open the File Dialog. Clicking the Save + Run button will save your file and run the code. If your file hasn't been saved yet, this will also bring up the file dialog box.

The file dialog that appears is a simplified dialog that displays the current path at the top, allows you to navigate through the file tree to select the file you would like to open, and has buttons on the bottom to open or save the file you would like to use.

Canceling will tell the editor that you do not want to continue with the current operation.

The X at the top performs the same function as the Cancel button as does clicking outside of the dialog.

On the Save As dialog, you can also type in a filename in the field next to the button.

Running Code

As mentioned above, the Save + Run button will first save your file, then run the code. The logic to run the code however is currently very simplistic in that it will try a couple of basic strategies to run your code, but doesn't currently do much beyond that.

The way it works is if you are working on code.py in the root folder, a soft reset will be performed, which automatically runs code.py. If you were working on some code in another file, the editor will attempt to perform an import on this code, which should run it. When you run your code, it will automatically switch over to the serial terminal.

Click the Save + Run button to save and run the code current code.

File Dialog Toolbar

The file Dialog toolbar along the top allows you to perform common operations on files and folders regardless of whether you are saving or opening. Clicking the cancel button at the bottom will not undo any operations that were performed with these buttons.

Renaming and Deleting Files and Folders

You can rename or delete both files and folders. An item must be selected first for the buttons to become available.

Use the delete and rename buttons here to perform the corresponding operation on the currently selected file or folder.

Creating New Folders

This feature allows you to create a new folder to store your work inside of.

Clicking the new folder button at the top will prompt you for a folder name. It will inform you of invalid folder names such as the same name as an existing file or folder or a folder that begins with a period.

Uploading and Downloading Files and Folders

This feature allows you to upload or download files as long as they fit in the available space. If you need to add images or sound files for your project, you can use the upload button to add them. If you need to retrieve a file from your device for whatever reason, the download button will give you access to do that.

You can also download folders. When you select a folder and click download, the contents of that folder are automatically zipped into a single file. If nothing is selected when you click the download button, the current folder will be used.

Use the upload or download buttons to easily add files or retrieve them from your board.

Moving Files and Folders

This feature allows you to move files and folders to a different location on the device. When you click the move button, another prompt will appear on top of the dialog that allows you to navigate to where you would like to move the currently selected item. 

Use the move button to move files or folders to a new location on the device.

The second dialog that appears will show only folders and allow you to navigate to where you would like to move the file.

Using the Serial Terminal

The serial terminal allows you to watch the output of your device as well as type inputs just like you can from a separate application like PuTTY, except there's nothing you need to configure. This allows you to access the REPL or view the output of your currently running code.

Use the mode buttons in the bottom left-hand corner to switch between editor and serial terminal mode.

More Features to Come

The CircuitPython Code Editor is still under development, so expect more features to be added. If you would like to contribute on GitHub, you can submit any new issues or pull requests for review.

This guide was first published on Sep 07, 2022. It was last updated on Apr 15, 2024.

This page (Usage) was last updated on Mar 08, 2024.

Text editor powered by tinymce.