PIO + VS Code: Help with Arduino Library Examples Needed

Libraries
1

Hello everyone :wave:

I’m new to PIO and this forum, but I have some experience with the Arduino IDE and VS Code.

I’ve been struggling to get library examples to work in VS Code with PIO, specifically the Heltec ESP32 LoRa V3 library. I need to get this working for a school project, so any assistance would be greatly appreciated. :innocent:

platformio.ini:

  • Platform = espressif32
  • Board = heltec_wifi_lora_32_V3
  • Framework = arduino
  • lib_ldf_mode = deep+

I successfully ran the traditional Arduino Blink example on this board (compiled and uploaded directly from PIO in VS Code). Next, I installed the “Heltec ESP32 LoRa V3” library using the PIO Library Manager and copied the example code from the SimpleDemo.ino file in the library examples into main.cpp in the src folder of my project.

Issues Encountered:

  1. Include Statements:
    In the Arduino IDE, I didn’t need to manually include some files (e.g., #include "SSD1306Wire.h"), but in PIO, I encountered the following error:

    fatal error: SSD1306Wire.h: No such file or directory

    Adding these lines fixed this issue (and similar errors):

    #include "SSD1306Wire.h"
#include <Wire.h>
#include "HotButton.h"

  2. Missing File (images.h):
    I’m still facing an issue with the images.h file included in the example:

    fatal error: images.h: No such file or directory

    This file is located in the example folder of the library (same folder as linked above), but I’m unsure how to correctly reference it in PIO.

Questions:

  1. Differences to Arduino:
    Why do I need to explicitly include "SSD1306Wire.h", <Wire.h>, etc., in PIO but not in the Arduino IDE?

  2. Library Dependencies:
    Does PIO automatically install all dependencies when a library is installed? (I read, that it does, but the described behavior shows otherwise…)

  3. Include Paths:
    Where does PIO save the library files? What is the correct syntax to include these files in the build so I can use them in my code?

  4. Library Folder Usage:
    How should I correctly include files like images.h from the example folder? Should I manually place them in the lib folder or reference them differently? When is it appropriate to use the lib folder in the project?

  5. JSON config:
    What role does library.json play? :thinking:

I hope you can point out where my misunderstanding of the PIO concept is. I’m trying to understand why the approach that works in the Arduino IDE isn’t working the same way in PIO.

I’d greatly appreciate any guidance, tutorials, or other reading recommendations, as I’m finding the official documentation overwhelming.

Thanks in advance! :smiling_face:
Max

(Perhaps my namesake @maxgerhardt can help me?)

2

Hi @max.w !

Regarding your Issues 1 & 2:

  1. It looks like you basicly missed to #include <Arduino.h>.
    See Convert Arduino file to C++ manually — PlatformIO latest documentation

  2. You also missed to copy the images.h from the example folder of the library to your projects src or include folder.

Regarding your questions:

  1. Should be fixed by #1 from above
  2. That depends on the library’s manifest (library.json).
    If there are dependencies declared, platformio will install them.
  3. a) <project folder>/.pio/libdeps/<library-name>
    b) #include <headerfilename.h>
    In this case: #include <heltec_unofficial.h> as it is done in the example code
  4. Should be fixed by #2 from above.
    This file belongs to the project, not to the library. Therefore you have to copy the file to your projects src or include folder.
  5. A detailed description can be found in the documentation.
    Please see library.json — PlatformIO latest documentation
1 Like
3

Dear Boris @sivar2311 , thank you so much for your help! :blush:

  1. I fixed the #include <Arduino.h>, and
  2. copied images.h to the include folder.

Now, everything is working! :tada: I think part of my confusion was that the .pio folder is usually hidden…

For my general understanding:
I’m used to integrating (example) files directly from the library to avoid redundancies. I tried:
#include "../.pio/libdeps/heltec_wifi_lora_32_V3/Heltec_ESP32_LoRa_v3/examples/display demos/SimpleDemo/images.h
(instead of copying the images.h file to the include folder) and it works as well.

:arrow_right_hook: Is this considered bad coding style in PIO and should be avoided, or is it just fine? Am I missing something?

And one last question about PIO behavior:
In Arduino, there is a library and board manager. I think I’m now familiar with the basics of how PIO handles libraries, and I guess that the board selection in the PIO project menu is the equivalent of the Arduino Board Manager. In the Arduino IDE, I can see where the board library comes from and which version it is:

photo arduino
photo arduino522×578 18.5 KB

:arrow_right_hook: Where can I find the equivalent ‘function’ or ‘menu’ (of the Arduino Board Manager) in PIO, and how can I, for example, change the version? :slightly_smiling_face:

I am now working on converting some of my Arduino code to C++. Your link was very helpful — I hadn’t considered the slight differences…

Have a great weekend!

4

This is bad practice.

In contrast to the ArduinoIDE, the libraries are not installed globally but per project. You have to get used to this at first. This allows you to use different versions of the same library for different projects.

The libraries are downloaded from the respective source (e.g. PlatformIO Registry, GitHub etc.) into the .pio/libdeps/<environment>/<library-name> folder as required.

There are several causes that can delete this folder. The libraries are then downloaded again and your changes are gone.

The projects are designed to be reproducible. If you share a project, you usually do not share the .pio folder. The required libraries are handled by the platformio.ini. Here too, your changes are no longer included.

Furthermore, the “Example” folder is not part of the library source code. It contains example projects. The files are intended for you to use in your project and are therefore part of the project - not the library.

Click on the PIO icon / Libraries and select the Installed tab at the top.
You’ll see a list of your Projects and which libraries are installed to that project.
Remember, libraries are installed per project.

image
image1223×389 26.9 KB

You can also specify the version of a library in the platformio.ini:

lib_deps = 
  bblanchon/ArduinoJson @ 7.0.1

See Dependency Management — PlatformIO latest documentation

The more you work with PlatformIO, the less you will use the GUI and the more you will edit the platformio.ini directly or use the CLI commands.

5

Dear @sivar2311,

First, thank you once again for your previous help! I know I’ve been quiet over the past few weeks due to other commitments, but I’ve picked up the project again and have a few follow-up questions. :slightly_smiling_face:

Your guidance has really helped me understand how PIO handles libraries, and I now feel confident using the Library Manager and specifying dependencies directly in the platformio.ini file. However, I’m still trying to fully understand how PIO manages boards compared to the Arduino IDE:

Boards(1)-min
In Arduino IDE, the Board Manager and Library Manager are clearly separate. I found the equivalent for libraries in PIO, but I’m curious about boards. Specifically, does adding the following line in platformio.ini:

[env:heltec_wifi_lora_32_V3]
board = heltec_wifi_lora_32_V3

automatically include the necessary files and dependencies (like those found here), or do I need to manually include this as a separate “normal” library as well?

Lastly, I have a question regarding configuration options. In the Arduino IDE, we usually set parameters like port, upload speed, and other options through the “Tools” menu (see image below). How can I configure these in PIO? Is there an equivalent way to set these parameters within the platformio.ini file?

Tools-min
Tools-min794×498 6.01 KB

Looking forward to your advice and thanks again for your patience and assistance! :blush:

Best regards,
Max

6

In PlatformIO boards are parts of the platform.

If you install the Espressif32 platform, all supported boards are installed with that Platform to your system.

Check the path C:\Users\<username>\.platformio\platforms\espressif32\boards
There you should see a heltec_wifi_lora_32_V3.json where you can find the basic settings for this board.

The ArduinoIDE creates all the settings for the board from the boards.txt file.
The settings for your boards starts in line 24677.

It’s a bit tricky and hard for me to explain how this works.

The most important line seems to be line 24816.

Here you can see how the macros are generated.

Example:
To set the LoRaWAN settings to match your ArduinoIDE settings (screenshot from above):

build_flags = 
  -DLORAWAN_DEVEUI_AUTO=0
  -DLORAWAN_PREAMBLE_LENGTH=8
  -DREGION_EU868
  -DACTIVE_REGION=LORAMAC_REGION_EU868
  -DLoRaWAN_DEBUG_LEVEL=0
  -DSLOW_CLK_TPYE=0