# CircuitPython Web Workflow Code Editor Quick Start ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/114/857/medium800/wireless_Hero.png?1662510515) The CircuitPython Code Editor, available at [code.circuitpython.org](https://code.circuitpython.org/), provides a fuller and more enriching experience when editing files on your ESP32-based device running the latest version of CircuitPython. The editor allows you to edit files using web Bluetooth, USB, and Web Workflow over WiFi. To use Web Workflow with the CircuitPython Code Editor, a connection to the internet is required as well as access to the same Local Area Network that your device is connected to. While the editor is continuing to be developed and new features are still being added, it is still very usable at this point. No major revisions are expected to the overall usage anytime soon and this guide is intended will help get you started with everything at this point. One of the major changes that was added recently is that the flow now starts off allowing you to work in a disconnected state until you are ready to access files on the device. The USB Workflow and Bluetooth Workflow will not be covered in this guide. # CircuitPython Web Workflow Code Editor Quick Start ## Device Setup Make sure you are running version **8.0.0**  or later of CircuitPython. You can download it from the [downloads page on circuitpython.org](https://circuitpython.org/downloads). If you have previously installed it and you're not sure which version of CircuitPython your board is currently running, you can check the **boot\_out.txt** file in the root folder of your device. Assuming your mass storage has not been disabled, this should be in the **CIRCUITPY** drive. Once you have that downloaded, you will want to check out the appropriate learn guide for your specific board for installation instructions. If you are running an ESP32 board, the setup process is a little different and you will want to check out the [CircuitPython on ESP32 Quick Start](https://learn.adafruit.com/circuitpython-with-esp32-quick-start/overview) guide. If you would like a more general overview of [installing CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython), you can check out the [Welcome to CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython) guide. Warning: ## Creating a **settings.toml** File Once you have the correct version of CircuitPython installed and running, the next step is to create an **settings.toml** file in the root of the **CIRCUITPY** drive. Then configure it by adding the following contents and changing the values as appropriate: Warning: ```auto # To auto-connect to Wi-Fi CIRCUITPY_WIFI_SSID="yourwifissid" CIRCUITPY_WIFI_PASSWORD="yourpassword" # To enable modifying files from the web. Change this too! # Leave the User field blank when you type the password into the browser. CIRCUITPY_WEB_API_PASSWORD="passw0rd" CIRCUITPY_WEB_API_PORT=80 ``` A summary of the values is as follows: - **CIRCUITPY\_WIFI\_SSID** : This is the name of the WiFi network that you usually see advertised in a list of available WiFi networks on your computer. It should match exactly. - **CIRCUITPY\_WIFI\_PASSWORD** : This is the password for your WiFi network. It should also match exactly. - **CIRCUITPY\_WEB\_API\_PASSWORD** : This is the password that is used to protect access to the files on your device when connecting with Web Workflow. This is what you will type in when prompted for a password. You will want to change it to something that you'll remember. - **CIRCUITPY\_WEB\_API\_PORT** : This is the TCP port that the built-in Web Workflow web server on the device will use. At this point in time, the Code Editor hasn't been thoroughly tested with ports other than the default, so leaving it at **port 80 is recommended**. If you would like a more technical detail of the underlying aspects of Web Workflow, be sure to check out the [official CircuitPython documentation](https://docs.circuitpython.org/en/latest/docs/workflows.html#web). Info: After entering in your settings.toml, a "hard" reset is required: power cycle or press the reset button, a soft reset is not enough! ## Disabling USB Mass Storage One of the more challenging aspects of using web workflow is that in order to avoid corrupting files, the USB mass storage device needs to be disabled **on native USB chipsets like ESP32-S2/ESP32-S3** , otherwise the files will only be available in read-only mode over the WiFi link. The easiest way to do this is to simply eject the **CIRCUITPY** drive in your OS. However, this will only be temporary until the next time you reset the device or plug it back in. If you'd like it to stay disabled, you can create a **boot.py** file in the root folder of the **CIRCUITPY** drive with the following contents: ```python import storage storage.disable_usb_drive() ``` Once you have saved the file, go ahead and perform a hard reset on the board by pressing the reset button or by temporarily disconnecting it from power. After it starts back up, the **CIRCUITPY** drive should no longer appear. If you'd like to learn more about editing **boot.py** to customize the device, check out the [Customizing USB Devices in CircuitPython](https://learn.adafruit.com/customizing-usb-devices-in-circuitpython/circuitpy-midi-serial) guide. ### Re-enabling USB Mass Storage If you find you want to access the mass storage device after you have disabled it, there are a couple of ways you can do it. The first way to temporarily enable it is to boot it into safe mode. To do this, just reset the device and while it is booting, pay attention to the status NeoPixel. When it starts flashing yellow, press the boot button. Alternatively, if you'd like to permanently re-enable it, you can run the following code from a serial terminal to remove the **boot.py** file: ```python import storage import os storage.remount("/", False) os.remove("/boot.py") ``` After hard resetting your device, the **CIRCUITPY** drive should reappear, though re-enabling it will cause web workflow to be in read-only mode again. ## Dealing with Multiple WiFi Networks If you need to switch between multiple WiFi networks and would like to do so without re-enabling the Mass Storage Device and editing the **settings.toml**  file, you can use the following script to automatically switch between different **.toml** files. https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Web_Workflow_Quickstart/env.py To use the script, just copy it into the root folder of your **CIRCUITPY** drive. Then you will want to create at least 2 copies of the settings.toml file in the root folder as well. Just name them something like **home.toml** , **school.toml** , or **work.toml**. Make any changes to each file for the particular environment that you will be in. If you would like to reduce the clutter, you can place the toml files into a separate folder and then update the **SETTINGS\_FOLDER** variable to point to the folder making sure the value ends with a "/" character. To run the script, just connect to the device with a serial terminal, press a key to enter the REPL, and type `import env`. If you only have two files and one of them is identical to the **settings.toml** file, it will just ask you if you want to change to the other file. Just type ' **y**' or ' **yes**' followed by pressing enter to change it. Anything else will abort. If you have more files or at least 2 of them are different from the current **settings.toml**  file, it will prompt you to select the one you want to change to. Just enter the number of next to the file and press enter or you can press **Control+C** to stop the script and abort making changes. Warning: ![](https://cdn-learn.adafruit.com/assets/assets/000/114/693/medium800/wireless_env_script.png?1662163347) After you select a file, it will automatically hard reset the board and immediately start using the new **settings.toml** file. This makes it very easy to use the board in a variety of settings or even switch between different WiFi networks in the same location. # CircuitPython Web Workflow Code Editor Quick Start ## Connecting ## 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/](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/](http://circuitpython.local/code/) and selecting the **full code editor** link on the Welcome screen. ![wireless_Welcome_Screen.png](https://cdn-learn.adafruit.com/assets/assets/000/115/952/medium640/wireless_Welcome_Screen.png?1666046046) Another way to get there is by navigating to [https://code.circuitpython.org/](https://code.circuitpython.org/) and selecting WiFi on the dialog prompt that comes up. ![wireless_Connection_Selection_Dialog.png](https://cdn-learn.adafruit.com/assets/assets/000/115/962/medium640/wireless_Connection_Selection_Dialog.png?1666047827) This will display a page of instructions along with a link to [http://circuitpython.local/code/](http://circuitpython.local/code/). Any code you've written in the editor should be automatically transferred by clicking that link. ![wireless_Connect_Instructions.png](https://cdn-learn.adafruit.com/assets/assets/000/114/833/medium640/wireless_Connect_Instructions.png?1662484841) 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. ![wireless_Password.png](https://cdn-learn.adafruit.com/assets/assets/000/114/856/medium640/wireless_Password.png?1662510079) 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. ![wireless_Device_Discovery.png](https://cdn-learn.adafruit.com/assets/assets/000/114/891/medium640/wireless_Device_Discovery.png?1662672901) ![wireless_Disconnect_Button.png](https://cdn-learn.adafruit.com/assets/assets/000/114/892/medium640/wireless_Disconnect_Button.png?1662672956) ### 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. ![wireless_Read_Only.png](https://cdn-learn.adafruit.com/assets/assets/000/114/855/medium640/wireless_Read_Only.png?1662509823) ## 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. ![wireless_Device_Discovery_Refresh.png](https://cdn-learn.adafruit.com/assets/assets/000/114/887/medium640/wireless_Device_Discovery_Refresh.png?1662672561) ![wireless_Info_Button.png](https://cdn-learn.adafruit.com/assets/assets/000/114/890/medium640/wireless_Info_Button.png?1662672699) # CircuitPython Web Workflow Code Editor Quick Start ## Usage ## 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. ![wireless_Screenshot_2024-07-02_at_8.46.57_AM.png](https://cdn-learn.adafruit.com/assets/assets/000/130/980/medium640/wireless_Screenshot_2024-07-02_at_8.46.57_AM.png?1719935356) 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. ![wireless_File_dialog.png](https://cdn-learn.adafruit.com/assets/assets/000/115/953/medium640/wireless_File_dialog.png?1666046715) 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. ![wireless_File_dialog_2.png](https://cdn-learn.adafruit.com/assets/assets/000/115/954/medium640/wireless_File_dialog_2.png?1666046738) ## 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. ![wireless_Save_and_Run.png](https://cdn-learn.adafruit.com/assets/assets/000/114/853/medium640/wireless_Save_and_Run.png?1662509114) ## 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. ![wireless_Delete_and_Rename.png](https://cdn-learn.adafruit.com/assets/assets/000/115/955/medium640/wireless_Delete_and_Rename.png?1666047250) ### 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. ![wireless_New_Folder.png](https://cdn-learn.adafruit.com/assets/assets/000/115/956/medium640/wireless_New_Folder.png?1666047276) ![wireless_New_Folder_Prompt.png](https://cdn-learn.adafruit.com/assets/assets/000/115/957/medium640/wireless_New_Folder_Prompt.png?1666047296) ### 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. ![wireless_Upload_and_Download.png](https://cdn-learn.adafruit.com/assets/assets/000/115/958/medium640/wireless_Upload_and_Download.png?1666047325) ### 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. ![wireless_Move_Item.png](https://cdn-learn.adafruit.com/assets/assets/000/115/959/medium640/wireless_Move_Item.png?1666047519) ![wireless_Move_Item_Prompt.png](https://cdn-learn.adafruit.com/assets/assets/000/115/960/medium640/wireless_Move_Item_Prompt.png?1666047536) ## 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 open and close the serial and editor panes. ![wireless_Screenshot_2024-07-03_at_8.08.00_AM.png](https://cdn-learn.adafruit.com/assets/assets/000/131/075/medium640/wireless_Screenshot_2024-07-03_at_8.08.00_AM.png?1720019348) ## 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](https://github.com/circuitpython/web-editor/), you can submit any new issues or pull requests for review. ## Featured Products ### Adafruit ESP32-S3 TFT Feather - 4MB Flash, 2MB PSRAM, STEMMA QT [Adafruit ESP32-S3 TFT Feather - 4MB Flash, 2MB PSRAM, STEMMA QT](https://www.adafruit.com/product/5483) We've got a new machine here at Adafruit, it can uncover your deepest desires. Don't believe me? I'll turn it on right now to prove it to you! What, you want your very own soft serve ice cream machine? OK well, that's not something we can provide. But we can provide your... In Stock [Buy Now](https://www.adafruit.com/product/5483) [Related Guides to the Product](https://learn.adafruit.com/products/5483/guides) ### Adafruit ESP32-S2 TFT Feather - 4MB Flash, 2MB PSRAM, STEMMA QT [Adafruit ESP32-S2 TFT Feather - 4MB Flash, 2MB PSRAM, STEMMA QT](https://www.adafruit.com/product/5300) We've got a new machine here at Adafruit, it can uncover your deepest desires. Don't believe me? I'll turn it on right now to prove it to you! What, you want unlimited mozzarella sticks? OK well, that's not something we can provide. But we can provide your... Out of Stock [Buy Now](https://www.adafruit.com/product/5300) [Related Guides to the Product](https://learn.adafruit.com/products/5300/guides) ### Adafruit ESP32-S2 Feather - 4 MB Flash + 2 MB PSRAM [Adafruit ESP32-S2 Feather - 4 MB Flash + 2 MB PSRAM](https://www.adafruit.com/product/5000) What's Feather-shaped and has an ESP32-S2 WiFi module? What has a STEMMA QT connector for I2C devices? What has your favorite Espressif WiFi microcontroller and lots of Flash and RAM memory for your next IoT project? What will make your next IoT project flyyyyy? That's right -... Out of Stock [Buy Now](https://www.adafruit.com/product/5000) [Related Guides to the Product](https://learn.adafruit.com/products/5000/guides) ### Adafruit ESP32-S2 Feather with BME280 Sensor - STEMMA QT [Adafruit ESP32-S2 Feather with BME280 Sensor - STEMMA QT](https://www.adafruit.com/product/5303) What's Feather-shaped and has an ESP32-S2 WiFi module? What has a STEMMA QT connector for I2C devices and a built in ambient sensor? What has your favorite Espressif WiFi microcontroller and lots of Flash and RAM memory for your next IoT project? What will make your next IoT project sensor... In Stock [Buy Now](https://www.adafruit.com/product/5303) [Related Guides to the Product](https://learn.adafruit.com/products/5303/guides) ### Adafruit QT Py ESP32-S3 WiFi Dev Board with STEMMA QT [Adafruit QT Py ESP32-S3 WiFi Dev Board with STEMMA QT](https://www.adafruit.com/product/5426) The ESP32-S3 has arrived in QT Py format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native USB, this QT Py is great for powering your IoT projects. The ESP32-S3 is a highly-integrated,... Out of Stock [Buy Now](https://www.adafruit.com/product/5426) [Related Guides to the Product](https://learn.adafruit.com/products/5426/guides) ### Adafruit QT Py ESP32-S2 WiFi Dev Board with STEMMA QT [Adafruit QT Py ESP32-S2 WiFi Dev Board with STEMMA QT](https://www.adafruit.com/product/5325) What has your favorite Espressif WiFi microcontroller, comes with [our favorite connector - the STEMMA QT](http://adafruit.com/stemma), a chainable I2C port, and has lots of Flash and RAM memory for your next IoT project? What will make your next IoT project flyyyyy? What a... Out of Stock [Buy Now](https://www.adafruit.com/product/5325) [Related Guides to the Product](https://learn.adafruit.com/products/5325/guides) ### Adafruit QT Py ESP32-S2 WiFi Dev Board with uFL Antenna Port [Adafruit QT Py ESP32-S2 WiFi Dev Board with uFL Antenna Port](https://www.adafruit.com/product/5348) What has your favorite Espressif WiFi microcontroller, comes with [our favorite connector - the STEMMA QT](http://adafruit.com/stemma), a chainable I2C port, and has lots of Flash and RAM memory for your next IoT project? What will make your next IoT project flyyyyy? What a... In Stock [Buy Now](https://www.adafruit.com/product/5348) [Related Guides to the Product](https://learn.adafruit.com/products/5348/guides) ### Adafruit MagTag - 2.9" Grayscale E-Ink WiFi Display [Adafruit MagTag - 2.9" Grayscale E-Ink WiFi Display](https://www.adafruit.com/product/4800) The Adafruit MagTag combines the ESP32-S2 wireless module and a 2.9" grayscale E-Ink display to make a low-power IoT display that can show data on its screen even when power is removed! The ESP32-S2 is great because it builds on the years of code and support for the ESP32 and also adds... In Stock [Buy Now](https://www.adafruit.com/product/4800) [Related Guides to the Product](https://learn.adafruit.com/products/4800/guides) ## Related Guides - [Adafruit HUZZAH32 - ESP32 Feather](https://learn.adafruit.com/adafruit-huzzah32-esp32-feather.md) - [Adafruit MagTag](https://learn.adafruit.com/adafruit-magtag.md) - [Adafruit FunHouse](https://learn.adafruit.com/adafruit-funhouse.md) - [Adafruit ESP32-S2 Feather](https://learn.adafruit.com/adafruit-esp32-s2-feather.md) - [Adafruit QT Py ESP32-S2 and QT Py ESP32-S2 with uFL Antenna](https://learn.adafruit.com/adafruit-qt-py-esp32-s2.md) - [Adafruit ESP32-S2 TFT Feather](https://learn.adafruit.com/adafruit-esp32-s2-tft-feather.md) - [Adafruit ESP32 Feather V2](https://learn.adafruit.com/adafruit-esp32-feather-v2.md) - [Adafruit QT Py ESP32-S3](https://learn.adafruit.com/adafruit-qt-py-esp32-s3.md) - [Adafruit ESP32-S3 TFT Feather](https://learn.adafruit.com/adafruit-esp32-s3-tft-feather.md) - [ESP-NOW in CircuitPython](https://learn.adafruit.com/esp-now-in-circuitpython.md) - [File Glider](https://learn.adafruit.com/file-glider.md) - [MagTag Case](https://learn.adafruit.com/magtag-case.md) - [Mini Weather Station ESP32-S3 TFT](https://learn.adafruit.com/mini-weather-station-esp32-s2-tft.md) - [FunHouse Mail Slot Detector](https://learn.adafruit.com/funhouse-mail-slot-detector.md) - [Holiday Lights: Easy DIY Christmas Wreath & Garland with WLED](https://learn.adafruit.com/holiday-garland-decor-app-control-with-no-coding.md) - [MagTag Progress Displays](https://learn.adafruit.com/magtag-progress-displays.md) - [ePaper Camera](https://learn.adafruit.com/epaper-camera.md) - [NextBus Transit Predictions for Adafruit MagTag](https://learn.adafruit.com/nextbus-transit-predictions-for-adafruit-magtag.md) - [MagTag IoT Menorah](https://learn.adafruit.com/magtag-iot-menorah.md) - [Sound Reactive Paper Lanterns with LedFx](https://learn.adafruit.com/sound-reactive-paper-lanterns-with-led-fx.md) - [Cheekmate - a Wireless Haptic Communication System](https://learn.adafruit.com/cheekmate-wireless-haptic-communication.md) - [FunHouse Motion Detecting Lights with LIFX Bulbs](https://learn.adafruit.com/funhouse-motion-detecting-lighting-for-lifx-bulbs.md) - [Blinka LED Sign](https://learn.adafruit.com/blinka-led-sign.md)