Tools

Coert Vonk

Describes the development environment for the OPNpool interface as described in VSCode-starters ESP32, consisting of

  • GNU toolchain
  • Espressif IoT Development Framework (ESP-IDF)
  • Microsoft Visual Code Studio IDE
  • Git version control

Git

We use git with a repository hosted on GitHub.

  1. Make sure that you can ssh to github.com. On Windows, you may have to install the Windows OpenSSH Client.
  2. Clone the repository and its submodules to a local directory. Note the --recursive flag. 
    git clone --recursive git@github.com:cvonk/OPNpool.git

EAGLE

The schematics and layout of the printed circuit board were created using Autodesk EAGLE. If you wish to edit these files, you will need to install the software.

Remember

In Windows, you need to specify the EAGLE_HOME environment variable that points to the your EAGLE directory. Inside EAGLE it is known as $HOME and is used in Control Panel » Options » Directories.

The schematic and board layouts are available in the hardware directory. Custom parts such as the Wemos LOLIN-D32, DC/DC converter, JTAG, RS-485 connector can be found in the hardware/libraries/OPNpool.lbr library.

Go to Options then Directories, and add the absolute path of `OPNpool/hardware/libraries` to the libraries.

ESP Toolchain

These instructions are for Windows, the paths will be slightly different on other operating systems.

Before you start, make sure that Git is installed and that you can call git from the command line.

VScode ESP-IDF plugin

If you haven’t already, install Microsoft Visual Studio Code (VSCode).

From within VSCode:

  1. Add the Microsoft’s C/C++ extension
  2. Add the Espressif IDF 1.4.0 extension.
  3. Install the tools and configure the Espressif IDF extension.
    • F1 » ISP-IDF: Configure ESP-IDF
    • Select Advanced mode
    • ESP-IDF 4.4 in C:/espressif (goes to subdir esp-idf)
    • GNU Tools in C:/espressif/bin
    • Choose “Download ESP-IDF Tools”
  4. To speed up compile times, disable Windows Defender’s real-time scanning of C:/espressif. If you get an “You’ll need a new app to open this WindowsDefender link” prompt, then issue Get-AppxPackage Microsoft.SecHealthUI -AllUsers | Reset-AppxPackage from an elevated PowerShell terminal.

If you prefer to use a ESP-IDF beta version or the master branch, refer to VSCode starter for ESP32.

Start humble

  1. From Visual Studio Code, change to an empty folder and copy a simple example project such as blink.
    • F1 » ESP-IDF: Show ESP-IDF Example Projects
      • Get-started » Blink
      • Click on “Create project using example Blink”.
  2. Connect an ESP32 board to your computer. It will show up as a Serial Port device in the Windows device manager.
  3. Select the serial port in Visual Studio Code
    • F1 » ESP-IDF: Device configuration
      • Device Target = ESP32
      • Device Port = COM4
      • Baud Rate = 115200
  4. Start a compile-flash-monitor cycle
    1. F1 » ESP-IDF: Build, flash and monitor, or use ^e d.
    2. Flash using the “UART”.

In case you encounter warnings or errors, refer to the table below.

Message Explanation
esptool.py failed with exit code 2 Hints that the baud rate is to high. Try a different/shorter cable.
no such option: -b Change idf.py monitor line in .vscode\tasks.json so that the command Monitor” is behind the options.
CMake Error: Unable to open check cache file for write. The directory for the cache file doesn’t exist. Create it by hand.
IDF_PATH environment variable is different from inferred IDF_PATH.. Likely because $IDF_PATH is not set in Windows’ system/user environment. Ignore.
Could NOT find Git (missing: GIT_EXECUTABLE) Odd because ${env:PATH} does include C:\Program Files\Git\cmd [build system]

Compiling

You should now be able to compile and link e.g. the “factory” application.

Start Visual Studio Code (vscode), in the directory OPNpool\factory.

  1. Connect an ESP32 board to your computer. In Device Manager, the UART (COM) will show up under the Serial Ports. Select this port in Visual Studio Code:
    • F1 » ESP-IDF: Device configuration
      • Device Target = ESP32
      • Device Port = COM6
      • Baud Rate = 115200
  2. Start a compile-flash-monitor cycle
    1. F1 » ESP-IDF: Build, flash and monitor, or using ^e d.
    2. Flash using the “UART”.

Android Studio

The OPNpool provisioning application is available on the Play Store. The Deploying chapter of this document describes the process in more detail.

If you prefer to build it yourself, download and install Google Android Studio and its SDK. We’d recommend trying to build one of the example projects before you building the OPNpool provisioning app.

Build

Open Android Studio in the android directory and start the build process. Enable Developer mode on you Android device, and enable Wireless Debugging. Your phone should now be listed as a test device. Click the button to run the app on your phone.

Note that the app targets API 30 (Android 11), but builds with API 31. This is so that we can request BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions for Android 12 devices. For details refer to the Android 12 Behavior Changes document

Continue reading to learn about the debugging methods.