The first and most basic program you can upload to your Arduino is the classic Blink sketch. This takes something on the board and makes it, well, blink! On and off. It's a great way to make sure everything is working and you're uploading your sketch to the right board and right configuration.
When all else fails, you can always come back to Blink!
Now traditionally you would use an onboard LED to make a blink occur. However, this board does not have an onboard single-color LED, so we will 'mimic' the same blink sketch but instead of using a digital output pin, we will use NeoPixel support to blink the onboard RGB LED!
Pre-Flight Check: Get Arduino IDE & Hardware Set Up
This lesson assumes you have Arduino IDE set up. This is a generalized checklist, some elements may not apply to your hardware. If you haven't yet, check the previous steps in the guide to make sure you:
- Install the very latest Arduino IDE for Desktop (not all boards are supported by the Web IDE so we don't recommend it)
- Install any board support packages (BSP) required for your hardware. Some boards are built in defaults on the IDE, but lots are not! You may need to install plug-in support which is called the BSP.
- Get a Data/Sync USB cable for connecting your hardware. A significant amount of problems folks have stem from not having a USB cable with data pins. Yes, these cursed cables roam the land, making your life hard. If you find a USB cable that doesn't work for data/sync, throw it away immediately! There is no need to keep it around, cables are very inexpensive these days.
- Install any drivers required - If you have a board with a FTDI or CP210x chip, you may need to get separate drivers. If your board has native USB, it probably doesn't need anything. After installing, reboot to make sure the driver sinks in.
- Connect the board to your computer. If your board has a power LED, make sure its lit. Is there a power switch? Make sure its turned On!
Start up Arduino IDE and Select Board/Port
OK, now you are prepared! Open the Arduino IDE on your computer. Now you have to tell the IDE what board you are using, and how you want to connect to it.
In the IDE find the Tools menu. You will use this to select the board. If you switch boards, you must switch the selection! So always double-check before you upload code in a new session.
Install NeoPixel Library
Despite their popularity, NeoPixel RGB LEDs are not supported 'out of the box' in Arduino IDE! You will need to add support by installing the library. Good news it is very easy to do it. Go to the Library Manager here
Search for and install the Adafruit NeoPixel library. It might not be first in the list so make sure you get the name matched up right!
Then in the new window, copy and paste this text:
#include <Adafruit_NeoPixel.h>
// How many internal neopixels do we have? some boards have more than one!
#define NUMPIXELS 1
Adafruit_NeoPixel pixels(NUMPIXELS, PIN_NEOPIXEL, NEO_GRB + NEO_KHZ800);
// the setup routine runs once when you press reset:
void setup() {
Serial.begin(115200);
#if defined(NEOPIXEL_POWER)
// If this board has a power control pin, we must set it to output and high
// in order to enable the NeoPixels. We put this in an #if defined so it can
// be reused for other boards without compilation errors
pinMode(NEOPIXEL_POWER, OUTPUT);
digitalWrite(NEOPIXEL_POWER, HIGH);
#endif
pixels.begin(); // INITIALIZE NeoPixel strip object (REQUIRED)
pixels.setBrightness(20); // not so bright
}
// the loop routine runs over and over again forever:
void loop() {
// say hi
Serial.println("Hello!");
// set color to red
pixels.fill(0xFF0000);
pixels.show();
delay(500); // wait half a second
// turn off
pixels.fill(0x000000);
pixels.show();
delay(500); // wait half a second
}
One note you'll see is that we reference the LED with the constant PIN_NEOPIXEL rather than a number. That's because each board could have the built in NeoPixels on a different pin and this makes the code a little more portable!
Verify (Compile) Sketch
OK now you can click the Verify button to convert the sketch into binary data to be uploaded to the board.
Note that Verifying a sketch is the same as Compiling a sketch - so these terms will be used interchangeably.
During verification/compilation, the computer will do a bunch of work to collect all the libraries and code and the results will appear in the bottom window of the IDE.
If something went wrong with compilation, you will get red warning/error text in the bottom window letting you know what the error was. It will also highlight the line with an error.
For example, here I had the wrong board selected - and the selected board does not have a built-in NeoPixel pin defined!
Here's another common error, in my haste I forgot to add a ; at the end of a line. The compiler warns me that it's looking for one - note that the error is actually a few lines up!
On success you will see something like this white text output and the message Done compiling. in the message area.
Upload Sketch
Once the code is verified/compiling cleanly you can upload it to your board. Click the Upload button:
The IDE will try to compile the sketch again for good measure, then it will try to connect to the board and upload a the file.
This is actually one of the hardest parts for beginners because it's where a lot of things can go wrong.
However, start with what it looks like: success! Here's what your board upload process looks like when it goes right:
Often times you will get a warning like this, which is kind of vague:
No device found on COM66 (or whatever port is selected)An error occurred while uploading the sketch
This could be a few things.
First up, check again that you have the correct board selected! Many electronics boards have very similar names or look, and often times folks grab a board different from what they thought.
If you're positive the right board is selected, we recommend the next step is to put the board into manual bootloading mode.
Native USB and manual bootloading
Historically, microcontroller boards contained two chips: the main micro chip (say, ATmega328 or ESP8266 or ESP32) and a separate chip for USB interface that would be used for bootloading (a CH430, FT232, CP210x, etc). With these older designs, the microcontroller is put into a bootloading state for uploading code by the separate chip. It allows for easier uploading but is more expensive as two chips are needed, and also the microcontroller can't act like a keyboard or disk drive.
Modern chips often have 'native' USB - that means that there is no separate chip for USB interface. It's all in one! Great for cost savings, simplicity of design, reduced size and more control. However, it means the chip must be self-aware enough to be able to put itself into bootload/upload mode on its own. That's fine 99% of the time but is very likely you will at some point get the board into an odd state that makes it too confused to bootload.
Before continuing we really really suggest turning on Verbose Upload messages, it will help in this process because you will be able to see what the IDE is trying to do. It's a checkbox in the Preferences menu.
Enter Manual Bootload Mode
OK now you know it's probably time to try manual bootloading. No problem! Here is how you do that for this board:
Entering the ROM bootloader is easy. Complete the following steps.
Before you start, make sure your QT Py ESP32-S3 is plugged into USB port to your computer using a data/sync cable. Charge-only cables will not work!
To enter the bootloader:
- Press and hold the Boot button down. Don't let go of it yet!
- Press and release the Reset button. You should still have the Boot button pressed while you do this.
- Now you can release the Boot button.
No USB drive will appear when you've entered the ROM bootloader. This is normal!
Once you are in manual bootload mode, go to the Tools menu, and make sure you have selected the bootloader serial port. It is almost certain that the serial port has changed now that the bootloader is enabled.
Now you can try uploading again!
This time, you should have success!
After uploading this way, be sure to click the reset button - it sort of makes sure that the board got a good reset and will come back to life nicely.
It's also a good idea to try to re-upload the sketch again now that you've performed a manual bootload to get the chip into a good state. It should perform an auto-reset the second time, so you don't have to manually bootload again.
Once you've finished the re-upload, don't forget to press RESET and then select the old Port again!
Page last edited December 19, 2024
Text editor powered by tinymce.
