Managing a Multi-Environment ESP32 Project in PlatformIO Before Production Deployment

1

Hello everyone,

I’m currently developing an ESP32-based monitoring and control system using PlatformIO and VS Code. The project started as a simple prototype but has gradually grown into a larger codebase with multiple hardware variants, OTA updates, sensor interfaces, and a display subsystem.

As the project grows, I’m finding it increasingly difficult to keep the PlatformIO configuration clean while supporting different hardware revisions and deployment targets.

Current setup:

  • ESP32-WROOM

  • PlatformIO + VS Code

  • Multiple custom libraries

  • WiFi and Ethernet support

  • OTA firmware updates

  • TFT display interface

  • Sensor acquisition and data logging

At the moment I have separate build environments for:

  • Development hardware

  • Production hardware

  • Debug configuration

  • Manufacturing test firmware

While this works, the project structure is becoming increasingly difficult to maintain.

A few questions for developers managing larger PlatformIO projects:

  1. How do you organize multi-environment projects without ending up with duplicated configuration files?

  2. Do you prefer separate repositories for hardware revisions or a single repository with multiple PlatformIO environments?

  3. How are you managing version control for custom libraries that are shared across multiple embedded projects?

  4. Have you integrated automated testing or CI/CD pipelines with PlatformIO, and if so, what has worked well?

Hardware Design Question:

The firmware is approaching production readiness, and I’m now preparing a custom PCB that integrates the ESP32, power management, communication interfaces, and display connections. The board will likely be manufactured through PCBWay

For engineers who have transitioned from development boards to production hardware:

  • Need help with separating GND and Power Panels( How to Design an Efficient PCB Grounding System )?

  • What hardware issues appeared only after moving away from ESP32 development boards?

  • Are there PCB layout practices that significantly improve wireless performance and long-term reliability?

  • Have you found dedicated RF design reviews worthwhile before releasing a production board?

  • Which PCB fabrication or inspection options provided the most value during early production runs?

Wiring Harness and Connector Question:

The final product will include several external sensors, communication ports, and power connections, so I’m evaluating custom wiring harnesses(https://www.unikeyic.com/blog/wiring-harness-connector-types.html) with locking connectors instead of individual cable assemblies.

For those building commercial embedded products:

  • What connector systems have worked best for ESP32-based products?

  • Have connector or harness-related failures been a major source of field issues?

  • Is it worth outsourcing harness manufacturing for low-to-medium production volumes?

  • How much attention do you typically give to strain relief and serviceability during the design phase?

Mechanical Enclosure Question:

The prototype currently operates on an open bench, but the final product will require a custom enclosure that accommodates the PCB, display, wiring harnesses, antennas, and external connectors.

I’m considering CNC-machined and rapid-prototyped enclosure options through Justway.

For those who have moved from prototype to production:

  • What enclosure design mistakes caused the most rework?

  • How do you account for antenna placement and RF performance inside a custom enclosure?

  • Have thermal issues appeared after moving ESP32-based products into sealed housings?

  • Any recommendations regarding enclosure materials, mounting methods, or long-term maintainability?

I’d appreciate hearing how others are managing PlatformIO-based projects as they transition from development prototypes to production-ready products.

2

Hi,

From my recent experience of a simple Temperature and Humidity measurement and display project using a DHT21 and Whadda TFT display, putting the project into a sealed enclosure with the 5v regulated power supply did cause thermal problems. At a certain point the temperature built up in the enclosure and the TFT saturated to a white screen, where I assume the actual display board exceeded its thermal specification limits quoted as:

display mode full-colour mode (Idle mode OFF) . 262 000 colour (selectable colour depth mode by software) reduced colour mode (Idle mode ON)… 8-colour operating temperature… -40 °C to +85 °C

Though I find it hard to believe it was anywhere near +85 °C.

Opening up the case (I was in Spain at the time) resolved the issue. I’m currently looking to put a separate sensor inside to verify the thermal limit when I return. It’s been working fine at home so far without issue.

3

To: jovelyngentallan02
First, I want to let you know that some of your questions are not directly related to PlatformIO.
Please check the purpose of this community (https://community.platformio.org/about).
However, since you’ve taken the time to post, I will answer as much as I can.

The system I was commissioned to develop uses an ESP32-S3, which is slightly different from your system, but it has the following features, so it may be helpful.
Please note that I may not be able to answer all your questions.

[Configuration of the equipment I was in charge of]
・SoC: ESP32-S3-WROOM-1-N16
・Software development environment: PlatformIO + VS Code + Windows 10/11
・Libraries: I used many public libraries, but I modified and improved some of them
(there was clearly incorrect code).
・Flash memory file system: I used LittleFS. Also the system partitions are adjusted to
system requirements.
・WiFi: Connected to the main PC processing system via MQTT.
(The system is isolated from the internet, and the broker is installed on the PC.)
・OTA : Performed using the main PC in maintenance mode. The necessary servers are
pre-installed.
・Display : LED dot matrix displays.
・Analog : Load cell I/F (amplifier and 24-bit ADC) IC with I2C.

[Development Environment]
Development was carried out as follows. These are general procedures.

Stage 1: For functional verification, DevKit-C is implemented on a general-purpose board,
and each hardware component is added step-by-step for individual functional verification.
The software build environment is updated each time hardware is added.

Stage 2: All hardware and DevKit-C are newly implemented on a general-purpose board,
and full-scale system development is carried out.
Once it is confirmed that there are no problems with the main functions, the circuit design
is finalized and reflected in the design of the mass-production prototype board.
From this stage, the software build environment is reset and fixed thereafter.
At this stage, ensure that a means of connection for loading and maintaining the
initial program is secured.
In my case, I included a USB connector and, for good measure, a UART connector.
To allow for simultaneous initial program writing to multiple boards during mass production,
the documentation was created assuming the use of Espressif’s Flash Download Tool.

Stage 3: Once the mass-production prototype board is complete, software development continues
using it.
The build environment remains unchanged from Stage 2.
The firmware includes a factory mode with a command interface via USB or WiFi TCP socket.
After board manufacturing, the factory mode is used to
(1) obtain the MAC address and reflect it in the DHCP server’s lease table, and
(2) perform analog system calibration and write that information to the file system.

Stage 4: If changes are made to the board, they are reflected in the final version.
In my case, there were two places where changes to the schematic were not reflected,
and one place where there was an error in the bill of materials.
These were corrected on the prototype board using jumper wires and component replacements.

[Answers to your questions regarding hardware design]
Regarding the ESP32, if you carefully read Espressif’s official hardware design guidelines
https://docs.espressif.com/projects/esp-hardware-design-guidelines/en/latest/esp32/esp-hardware-design-guidelines-en-master-esp32.pdf ,
your concerns regarding power supply/GND and layout for improving wireless performance/
long-term reliability should be resolved. It is clearly stated in the guidelines.

Furthermore, there is a wealth of discussion and technical explanations regarding analog and
digital power and GND accumulated worldwide, and information like the link you provided is
readily available. Almost all of it is the same.
For example, please refer to
https://www.analog.com/en/resources/analog-dialogue/articles/what-are-the-basic-guidelines-for-layout-design-of-mixed-signal-pcbs.html).
Espressif’s guidelines also state similar things regarding circuit board design.

[Answer to your question regarding the enclosure]
Regarding the temperature inside the enclosure, I first assembled the evaluation set into a
temporary enclosure and ran the test program (this test program consumes approximately twice
the estimated power consumption during operation).
Afterward, I installed it in an environmental test machine and conducted temperature cycling tests.
After confirming that it operated under the required conditions, we proceeded with the overall
enclosure design.
I think this is a typical development procedure.
Development is complete already, and I no longer have it in my possession, but I have not
received any reports of thermal problems in the field.

I hope this was helpful.

4

You never ever have to write duplicate config / platformio.ini file contents with the extends (inheritance), extra_configs (inclusion) and interpolation feature. Also you can split large config files into smaller ones, e.g., one for each hardware platform or firmware variant.

See docs

An example of a project using that is the 3D printer firmware Marlin:

5

I was reluctant initially, but I am glad I posted it here. It’s a lot of info to absorb, please give me some time and I get back with the updates.