Controller Development Environment
This guide will explain how to install and configure VSCode for use with arduino-cli. It assumes the Arduino plug-in has already been installed in VSCode.
Installing and Configuring arduino-cli
Using arduino-cli is more flexible and reliable than the IDE.
Install Arduino CLI
Instructions are available at https://arduino.github.io/arduino-cli/latest/. Essentially:
brew update
brew install arduino-cliPost Installation
Initialize the installation:
arduino-cli config initEnable unsafe installation so that local zip files can be installed:
arduino-cli config set library.enable_unsafe_install trueUpdating Arduino CLI
To update an existing installation of Arduino CLI:
brew update
brew upgrade arduino-cliInstalling and Updating ESP Core
Install
Add the ESP32 board manager packages:
arduino-cli config set board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.jsonUpdate the index:
arduino-cli core update-indexInstall ESP32 core, version 2.0.11:
arduino-cli core install esp32:esp32@2.0.11Verify the installation was successful, and optionally remove any other cores:
arduino-cli core listExpect:
| ID | Installed | Latest | Name |
|---|---|---|---|
| esp32:esp32 | 2.0.11 | 2.0.11 | esp32 |
Updating
Uninstall the current ESP core:
arduino-cli core uninstall esp32:esp32Specify the version number to upgrade the ESP to 2.0.11:
arduino-cli core install esp32:esp32@2.0.11Installing and Configuring Libraries
Check the libraries to ensure no libraries are installed:
arduino-cli lib listExpect:
No libraries installed.If there are any installed libraries, uninstall them before proceeding.
Download required libraries
Download each library below as a zip file or download from GitHub.
Install each library above using the following command:
arduino-cli lib install --zip-path /my/downloads/directory/library_name.zipINFO
Versions must also be changed in the GitHub actions.
Add Symlink for boards.local.txt
The boards.local.txt file must be placed adjacent to the other boards.txt file provided by ESP32 core.
Steps:
Close Visual Studio Code
Create a symlink adjacent to the main boards file. Example for ESP Core version 2.0.11:
ln -s ./FireFly-Controller/boards.local.txt ~/Library/Arduino15/packages/esp32/hardware/esp32/2.0.11/boards.local.txtOpen Visual Studio Code. Select the board labeled
ESP32 Wrover Moduleand select the 16MB partition scheme. This will allow the solution to compile. However, the partitions will not be respected and may inaccurately reflect the amount of space remaining.For new boards only, ensure the option
Hardware-Registration-and-Configurationis set toEnabled. Subsequent flashes of that chip should be set toDisabled.Flash the Hardware-Registration-and-Configuration.ino project.
Visual Studio IDE Configuration
To use Visual Studio Code to compile FireFly-Controller, several files must be modified, all of which are located in /.vscode/. The folder may be hidden, but the file should be created automatically by VSCode.
c_cpp_properties.json
No changes should be required for this file, as it is generated automatically.
settings.json
{
"arduino.commandPath": "arduino-cli",
"arduino.useArduinoCli": true,
"arduino.path": "/usr/local/bin/",
"arduino.logLevel": "info",
"arduino.defaultTimestampFormat": "%H:%m:%S.%L "
}arduino.json
Contents of this file control the data sent to the compiler, and do not affect IntelliSense. IntelliSense is updated automatically from the compiler's output.
Example File Contents:
{
"sketch": "Hardware-Registration-and-Configuration.ino",
"configuration": "FlashFreq=80,PartitionScheme=default,UploadSpeed=921600,DebugLevel=none,EraseFlash=none",
"board": "esp32:esp32:firefly_controller",
"buildPreferences": [
[
"build.extra_flags",
"-DASYNCWEBSERVER_REGEX -DPRODUCT_HEX=0x08062305 -DESP32 -DCORE_DEBUG_LEVEL=3 -DDISABLE_ALL_LIBRARY_WARNINGS -I~/GitHub/P5Software/FireFly-Controller"
]
],
"port": "/dev/tty.SLAB_USBtoUART",
"output": "../.cache",
"programmer": "esptool"
}board
Defines the custom board configured in the Custom Boards section, above: esp32:esp32:firefly_controller
build.extra_flags
ASYNCWEBSERVER_REGEX Allows regex paths in the URL.
PRODUCT_HEX This configuration indicates the hardware product ID expressed as a hexadecimal and is required. If it is not included, the compiler will trigger an error. Change the 0x08062305 value in the example shown above to match the actual hardware product ID, with 0x prefixed. This allows for a product ID beginning with zero.
ESP32 The hardware type must also be set for the Adafruit libraries to be configured correctly. Use -DESP32 flag to set the hardware to ESP32. Without it, you can expect to receive errors such as fatal error: util/delay.h: No such file or directory
CORE_DEBUG_LEVEL To show or quiet the debug outputs. Additional libraries are slaved to these values in hardware.h:
0= None1= Error2= Warn3= Info4= Debug5= Verbose
DISABLE_ALL_LIBRARY_WARNINGS Will quiet progra messages from the FOTA library.
You must also include the parent directory of FireFly-Controller using the -I/my/path/to/project/FireFly-Controller parameter. Note that abbreviated file paths using ~ (for instance, ~/project/FireFly-Controller) will not work properly.
The folder structure should look like this:
/my/path/to/project/FireFly-Controller
-> .vscode
-> boards.local.txt
-> Controller
---> Controller.ino
---> ...
-> Hardware-Registration-and-Configuration
---> www
-----> auxillary_data.json
-----> ...
---> Hardware-Registration-and-Configuration.ino
---> swagger.yaml
---> ...
-> common
---> hardware.h
---> externalEEPROM.h
---> ...Troubleshooting
Uploads won't work
If the upload function does not work, but the application compiles correctly, re-select the port on the bottom right side of the screen.
Partitions
FireFly Controller uses a custom partition, partitions.csv, adjacent to the .ino file.
See more information about partitions.
Flashing www partition with 16MB Chip
Size (see table above) = 0x2E0000. To create the image:
~/Library/Arduino15/packages/esp32/tools/mklittlefs/3.0.0-gnu12-dc7f933/mklittlefs -s 0x2E0000 -c ~/GitHub/P5Software/FireFly-Controller/Hardware-Registration-and-Configuration/www ~/GitHub/P5Software/FireFly-Controller/Hardware-Registration-and-Configuration/www.binLocation (see table above) = 0xD10000. To flash the image:
~/Library/Arduino15/packages/esp32/tools/esptool_py/4.5.1/esptool --chip esp32 --port "/dev/tty.SLAB_USBtoUART" --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size 16MB 0xD10000 ~/GitHub/P5Software/FireFly-Controller/Hardware-Registration-and-Configuration/www.binFlashing config partition with 16MB Chip
DATA LOSS MAY OCCUR
This will destory any user-defined configuration!
Size (see table above) = 0x80000. To create the image:
~/Library/Arduino15/packages/esp32/tools/mklittlefs/3.0.0-gnu12-dc7f933/mklittlefs -s 0x80000 -c ~/GitHub/P5Software/FireFly-Controller/Hardware-Registration-and-Configuration/config ~/GitHub/P5Software/FireFly-Controller/Hardware-Registration-and-Configuration/config.binLocation (see table above) = 0xC90000. To flash the image:
~/Library/Arduino15/packages/esp32/tools/esptool_py/4.5.1/esptool --chip esp32 --port "/dev/tty.SLAB_USBtoUART" --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size 16MB 0xC90000 ~/GitHub/P5Software/FireFly-Controller/Hardware-Registration-and-Configuration/config.binAdding a new hardware version
Hardware configurationsk are abstracted from the main applications to allow for compilation with minimal hardware-specific design considerations. Each hardware model is defined in hardware.h.
Additionally, the peripheral information must be added to ./www/auxillary_data.json file. Adding the product HEX and the product ID to the auxillary_data.json file will add it to the Product ID drop down in the Identification area of the configuration.
Filter Large JSON documents
The Controller filters large JSON documents in order to conserve memory and protect future upgradeability.