Build: compiling instructions - plan-d-io/P1-dongle GitHub Wiki

Instructions on how to setup the Arduino IDE to edit and compile the firmware on your own.

Prerequisites

This guide is aimed towards Windows users, but the instructions are general enough to be useful for users of other OS'es as well.

  • Arduino IDE 1.8.19
  • arduino-esp32 core 2.0.14
  • GitHub CLI or Desktop

This guide uses Github CLI

Get the firmware code

  • Install the latest version of Github CLI. Click on Show all assets to find the binary for your OS. Be sure to add git to your PATH.

Windows users, you can also use git-scm (recommended)

  • When prompted, select main as the name for the main branch. The rest of the installer options may remain default.
  • Verify git works by opening a terminal or command prompt and typing the git version command
  • In the terminal or prompt, navigate to a folder to store the firmware code in
  • Execute the command git clone https://github.com/plan-d-io/P1-dongle.git. You now have a local copy of this repository.
  • If you want to update the local repository to the latest version, use git pull -p from inside this folder

This repository has multiple branches. main and develop are the most active. You might want to switch to develop for the latest firmware by using the command git checkout develop.

Setup your the Arduino IDE

  • Install Arduino IDE 1.8.19 (scroll down to Legacy IDE)
  • Open Arduino, go to File>Preferences. Add https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json to the Additional Boards Managers URLs field.
  • While you are here, also tick the compilation and upload options for verbose output, set compiler warnings to default and tick Display line numbers. Save.
  • Go to Tools>Boards>Boards Manager. Search for esp32. Install esp32 by Espressif Systems version 2.0.14.
  • Go to Sketch>Include Library>Manage Libraries. Search for and install the following libraries
    • M5Atom by M5Stack (and all dependencies)
    • HttpClient by Adrian McEwen
    • PubSubClient by Nick O'Leary
    • ArduinoJSon by Benoit Blanchon
    • elapsedMillis by Peter Feerick
    • UUID by Rob Tillaart
  • Download the following libraries
  • In the Arduino IDE, go to Sketch>Include Library>Add .zip Library and select the libraries you’ve just downloaded
  • Install the ESP32 LittleFS Filesystem Uploader

Compiling the firmware

  • Restart the Arduino IDE
  • Open the P1-dongle.ino file in this repository
  • Go to Tools>Board>ESP32 Arduino and select M5Stack-ATOM
  • Go to Tools>Upload Speed and select 115200
  • Go to Tools>Partition Scheme and select Minimal SPIFFS (Large APPS with OTA)
  • Connect the dongle through USB
  • Go to Tools>Port and select the COM port of your dongle
  • Compile and upload the firmware to the dongle

Depending on your installation, you might get compile errors due to missing libraries. Add them through the library manager of the Arduino IDE.

  • When upload has finished, go to Tools>ESP32 Sketch Data Upload
  • You can now open a serial monitor to view debug output. Don't forget to set the baud rate of serial monitor to 115200.

Compatibility with OTA updates

As of ESP32-arduino core 2.07, a coredump partition is reserved to store core crash debug dumps. This modifies the space available to the SPIFFS partition, making it incompatible with firmware developed on previous versions of the ESP core, like this repository. This means that, if you compile the firmware yourself, it might crash when updating OTA with precompiled binaries released on this repository.

If you selected the Minimal SPIFFS partition table (see above), a modified partition table (included in this repository) is used by the build process and compatibility with future OTA updates is assured. If you roll your own partition table, be sure it is formatted like below.

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x5000,
otadata,  data, ota,     0xe000,  0x2000,
app0,     app,  ota_0,   0x10000, 0x1E0000,
app1,     app,  ota_1,   0x1F0000,0x1E0000,
spiffs,   data, spiffs,  0x3D0000,0x30000,