Deploy to a real board

Deploy compiles the sketch in the editor for the real chip and uploads it to the board plugged into your computer. It uses arduino-cli, Arduino's free command-line tool, which the app can download for you.

Not yet tested on a real board

In Circuit Lab 1.0.0, Deploy has been tested against a stand-in for arduino-cli, not yet against a real board. The Windows app has not been run on Windows yet, and uploading from inside the snap has not been tried. The library projects have only been run in the simulator, so the real compiler may find something to fix. If Deploy does not work for you, export the program and upload it with the Arduino IDE, and please report what happened on the issues page.

Where Deploy works

Where	Deploy
Linux and Windows apps	Yes
The website, circuitlab.dhivalabs.com	No: a web page cannot compile or reach a USB port. The Deploy dialog says so.
A web build served from your own computer with tool/serve.dart	Yes, through that local server

It works for every board except the Raspberry Pi 4 / 5, which is a Linux computer: its script is copied over and run there. See Raspberry Pi 4 and 5.

One-time setup

1. Open a project and select Deploy at the top. The Deploy to your board dialog opens.

2. If arduino-cli is not found, the dialog shows One-time setup. Select Install the add-on.

   The app downloads arduino-cli from Arduino, about 30 MB, into its own folder. Nothing else on the computer changes. When it is done, the dialog says The deploy add-on is installed.

3. On Linux, if your user may not open serial ports yet, the dialog shows this command. Run it once in a terminal, then log out and back in:

   sudo usermod -aG dialout $USER

If you would rather install arduino-cli yourself, open Or install it yourself in the dialog for the command, then select Check again.

The add-on is kept in ~/.local/share/circuit_lab/addons on Linux and %LOCALAPPDATA%\circuit_lab\addons on Windows. It is not part of Circuit Lab: it is licensed by Arduino under GPL 3.0.

Upload a sketch

1. Plug the board in with a USB cable that carries data. Some cables only charge.

2. Open the project and select Deploy.

3. Pick the board's Port. A port where arduino-cli recognises a board shows the board's name, and is picked first. If the list is empty, check the cable and select the refresh button (Look for boards again).

4. Select Deploy.

The dialog shows each step and the tool's output as it goes:

1. Checking the tools.
2. Installing support for this board: a one-time download of the board's compiler, the first time you deploy to a new kind of board. For an ESP32 it is large and can take a few minutes.
3. Installing the Servo library or Installing the ESP32Servo library, if the sketch uses a servo and the library is missing.
4. Compiling for the real chip.
5. Uploading to the port.

When it works, the dialog says Uploaded. The sketch is running on the board. Select Stop to cancel at any point, and Deploy again to repeat.

If the sketch does not compile, the dialog says the real compiler is stricter than the simulator: read the first error: line in the log to see what to fix.

Circuit Lab has no serial monitor for a real board. To see what the board prints, use the Serial Monitor in the Arduino IDE at 115200 baud.

Connecting each board

The dialog's Connecting the section has these tips for the board you are using. On Windows, a board that does not show up usually needs the driver for its USB chip: CH340 for most clones, CP210x for many ESP boards.

Board	Tips
ESP32-S3 DevKitC-1	Use the USB-C port marked COM (or UART). If the upload cannot connect, hold BOOT, press and release RST, let go of BOOT and deploy again.
ESP32 DevKit V1	Use a micro-USB data cable. If the upload cannot connect, hold BOOT when the log says Connecting and let go once it starts writing.
NodeMCU (ESP8266)	The same, with the FLASH button.
Arduino Uno R3, Mega 2560	Plug in the USB-B cable. Leave pins 0 and 1 free: they carry the upload.
Arduino Nano	Mini-USB on the classic Nano, USB-C on many clones. If the first upload fails, the app tries again for clones with the old bootloader.
Raspberry Pi Pico	The first time, hold BOOTSEL while you plug it in, so it appears as a drive called RPI-RP2. Pick No port: the board shows up as a USB drive and deploy. After that, pick its port as usual.

When the upload fails

The dialog explains the common failures:

Message	What to do
Your user may not open the serial port	On Linux, run sudo usermod -aG dialout $USER, then log out and back in
Another program has the port open	Close any serial monitor or other IDE and try again
The port is in use or gone	Close any serial monitor, check the cable and try again
The board did not enter upload mode	Hold its BOOT (or FLASH) button while the upload starts
The board did not answer	Check the port, the board and that the cable carries data
Unplug the Pico, hold BOOTSEL	Plug it back in so it appears as a USB drive, then deploy again

Raspberry Pi 4 and 5

A Raspberry Pi 4 / 5 project has Run on the Pi where other boards have Deploy. It opens Run it on your Raspberry Pi, with these steps:

1. Put Raspberry Pi OS on a microSD card with Raspberry Pi Imager. In its settings, set a user name and password, your Wi-Fi, and turn on SSH. Start the Pi and give it two minutes.

2. Wire the circuit with the Pi switched off. The pins work at 3.3 V only: never connect 5 V to a GPIO pin.

3. Select Save and the script's name to save the Python script on your computer.

4. Copy it to the Pi, from the folder you saved it in, using your user name in place of pi. For a project called Traffic light:

   scp traffic-light.py pi@raspberrypi.local:~/

5. Log in to the Pi and run it. Ctrl + C stops it.

   ssh pi@raspberrypi.local
   python3 traffic-light.py

If raspberrypi.local is not found, the Pi and your computer must be on the same network. Look up the Pi's address in your router and use it instead, for example pi@192.168.1.42. The script uses the gpiozero library, which comes with Raspberry Pi OS.

Deploy from the web build

A web page cannot run a compiler, so the web build deploys through a small server on your own computer. From a clone of the repository, with Flutter installed:

flutter build web --release
dart run tool/serve.dart

Open the address it prints, http://127.0.0.1:8765/. Deploy then asks that local server to run arduino-cli. The server listens on your own computer only and refuses requests from other sites.

Use your own arduino-cli

The app looks for arduino-cli in this order:

1. The program named in the CIRCUIT_LAB_ARDUINO_CLI environment variable.
2. An addons folder beside the app's program file.
3. The add-on the app downloaded.
4. Your PATH, then usual install folders such as ~/.local/bin.

What is downloaded

Circuit Lab sends nothing about you or your project. When you ask for it, the app downloads arduino-cli from Arduino, and arduino-cli downloads compilers and libraries from Arduino and the board makers, such as Espressif.

Next steps

• Export and import
• Boards and the datasheet
• Troubleshooting and FAQ