Project structure · More
ESP32 with PlatformIO project structure
Opens with creditsFirmware for an ESP32-S3 plant monitor that reads soil moisture and temperature, publishes them over MQTT and serves a small web dashboard, built with PlatformIO and the Arduino framework. The layout follows the PlatformIO project conventions: firmware in src/, testable logic in private libraries under lib/, tests under test/ that run on your laptop and on the board, web files in data/ for LittleFS, and a custom partition table with two OTA slots. For students who have blinked an LED in the Arduino IDE and want to build firmware that survives in the field.
Curated by Tauseef FayyazIntermediate131 files and foldersPlatformIO Core 6.2, pioarduino platform-espressif32 55.03.312 (Arduino-ESP32 3.3.12 on ESP-IDF 5.5.5), ESP32-S3Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you17 files and folders
- 2GrowingWhat a real app with features and tests adds+53 files and folders
- ProductionWhat running it for real users adds+31 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+30 files and foldersOpens with credits
How it is organised
- platformio.ini is the single source of truth: board, platform version, libraries and build flags are pinned there, so every machine and CI builds the same firmware.
- Pin the platform and library versions. "Latest" on the platform line means your firmware can change under you on the next clean build.
- Keep src/ for the application and hardware glue, and move logic that does not need the ESP32 into private libraries in lib/. Those compile on your laptop, so they can be tested in a second without a board.
- Test in two places: many fast native tests for logic, and a few on-device tests for flash, NVS and sensors. Hardware-in-the-loop comes when field bugs demand it.
- Secrets never go in Git: secrets.h is gitignored for development, and production devices get credentials through provisioning into NVS.
- Plan flash from the start with your own partition table: two app slots for OTA, a LittleFS partition for web files, NVS for settings, and a core dump partition.
- Use FreeRTOS tasks and queues, not `delay()`, so slow network calls never block sensor sampling, and let a watchdog reset anything that hangs.
- Every OTA update travels over HTTPS with a checked certificate and is confirmed only after a healthy boot, so a bad release rolls back by itself.
At the top of the project
Open one in the explorer for the full story
- plant-monitor/
- .git/Git history, created by `git init`.
- .pio/PlatformIO's build folder: compiled firmware per environment and downloaded libraries.
- .vscode/VS Code files written by `--ide vscode`: recommended extensions, plus generated IntelliSense and debug files.3 inside
- data/Files uploaded to the LittleFS partition: the web dashboard and default settings.4 inside
- docs/Wiring, message formats, OTA and hardware notes, and later decisions and runbooks.2 inside
- include/Project-wide header files: board pins, configuration constants, secrets and certificates.5 inside
- lib/Private libraries: one folder per library, each with its own src/ and optional library.json.3 inside
- src/The firmware application: setup, tasks, networking, web server, OTA. PlatformIO compiles everything here.7 inside
- test/Unit tests run by `pio test`, one folder per test suite, using the Unity test framework.3 inside
- .clang-formatC++ formatting rules, applied on save by VS Code and checked in CI.
- .pre-commit-config.yamlRuns clang-format and basic whitespace checks before each commit.
- .gitignoreIgnores .pio and the generated VS Code files. Add include/secrets.h yourself.
- LICENSEThe license for the firmware and, if separate, the hardware files.
- README.mdWhat the device does, the board, how to wire it, build, flash and upload the web files.
- compile_commands.jsonA compilation database for clangd and other tools, made by `pio run -t compiledb`.
- platformio.iniThe project config: environments, board, platform version, framework, libraries, build flags, upload and test settings.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with ESP32 with PlatformIO.
- Roadmap· Arduino and ESP32Embedded systems and IoT roadmapC, microcontrollers, sensors, MQTT
- Roadmap· C++Programming foundations roadmapFirst language, Git, CS basics
- RoadmapLinux, terminal and Git roadmapShell, Git, SSH and your dev setup
- Cheat sheetEmbedded systems and IoT cheat sheetC, microcontrollers, sensors, MQTT.
- FYP idea· AdvancedSigned, Staged OTA Updates with Automatic Rollback for ESP32 Device FleetsBuild a self-hostable update system for small fleets of ESP32 devices that signs every firmware image, rolls updates out in stages, checks device health after each update and rolls back automatically when something goes wrong. Small IoT companies in Pakistan and elsewhere ship devices with no safe way to fix bugs in the field, or with update schemes that a single bad build can brick. The project applies the security ideas behind automotive update frameworks at a scale a startup can run.
- FYP idea· IntermediateLow-Cost Beehive Weight and Temperature Monitor for Migratory BeekeepersBuild a solar-powered hive scale and sensor node that records hive weight, inside temperature and humidity every few minutes, sends data over LoRa to a gateway at the apiary and alerts the beekeeper to swarming, a nectar flow ending, a hive tipped over or a colony losing weight. Beekeepers who move hives between flowering areas cannot inspect every box every day. The core is accurate weighing outdoors and turning weight curves into events.
- FYP idea· AdvancedSingle-Point Pressure Sensor for Household Water Leak and Tap DetectionBuild a device that screws onto one tap in a home, samples water pressure hundreds of times a second, and works out which fixture is in use, how much water it used and whether there is a hidden leak. The research behind the idea was done on pressurised mains plumbing; most South Asian homes run on rooftop tanks with low gravity pressure. Finding out whether and how it works there is the core of the project.
- FYP idea· IntermediateClassroom CO2 and Ventilation Monitor Network with a Raspberry Pi Gateway for SchoolsA final year project that builds a network of low-cost CO2 sensor nodes for classrooms, each with a traffic-light display, reporting to a Raspberry Pi gateway that runs its own MQTT broker, database and dashboard, even without internet. Teachers see at a glance when to open a window, and school leaders get a weekly report of which rooms are poorly ventilated and when.
- FYP idea· IntermediateIoT Sensor Readings Store with Bucketed Time Series in MongoDBBuild a temperature and humidity monitoring system for vaccine and medicine fridges in small clinics and pharmacies, storing millions of sensor readings in MongoDB. The core of the project is a measured comparison of the hand-built bucket pattern with native time series collections, plus TTL retention and live dashboards built from aggregation pipelines.
See 8 moreShow fewer
- QuestionShould I start embedded systems with Arduino, ESP32, STM32 or Raspberry Pi?Start with Arduino and ESP32 if you want quick, cheap wins and connected projects, STM32 if you want industry-style firmware and a real debugger, and Raspberry Pi if your project needs Linux, a camera or a gateway. Pick one, go deep for a few months, and the others become easy later.
- QuestionHow do I become an embedded systems engineer as a computer or electrical engineering student?Learn C properly, enough electronics to wire safely, one microcontroller in depth, the UART, I2C and SPI buses, an RTOS and a debugger, then finish one real device with measured results. Employers hire embedded engineers on evidence that you can make hardware work, so your projects and write-ups matter more than certificates.
- QuestionWhat projects should I build in my first year of university?Build small, finished projects that solve problems you or people around you actually have: a script that automates a chore, a command line tool, a simple website for a society or family business. First year is about finishing things and using Git, not about impressive ideas.
- Resource· GuideESP-IDF Programming GuideEspressif's official documentation for ESP-IDF, the development framework for ESP32 chips: setup, API reference for Wi-Fi, Bluetooth, peripherals, FreeRTOS, OTA and power management, plus debugging guides. Essential once you go beyond the Arduino functions on an ESP32. Free and open source.
- Resource· GuideArduino DocumentationArduino's official documentation: the language reference, Arduino IDE 2 guides, board pages with pinouts and specs, and step-by-step tutorials. It is the first place to look when you write a sketch for an Uno, a Nano ESP32 or any official board, and it is free.
- Resource· GuideFreeRTOS DocumentationThe official documentation for FreeRTOS, the widely used open source real-time kernel for microcontrollers: concepts, the full kernel API for tasks, queues, semaphores, mutexes and timers, and the free book Mastering the FreeRTOS Real Time Kernel. MIT licensed and already built into ESP-IDF and STM32Cube.
- Resource· GuideMQTT EssentialsHiveMQ's free MQTT Essentials series explains the protocol behind most IoT systems one idea at a time: publish and subscribe, clients and brokers, topics and wildcards, QoS levels, persistent sessions, retained messages, Last Will and keep alive, plus a separate MQTT 5 series.
- Resource· BookMaking Embedded Systems, 2nd EditionElecia White's book on building embedded software that survives real hardware: architecture, inputs and timers, interrupts, peripherals, debugging, connected devices, optimisation, maths, power and motors. The second edition (O'Reilly, 2024) adds IoT, motors and data handling. A practical bridge from tutorials to professional firmware.
Checked against 17 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- PlatformIO: pio project init
- PlatformIO: Project configuration file
- PlatformIO: Library Dependency Finder
- PlatformIO: Unit testing
- PlatformIO: Static code analysis
- PlatformIO: Advanced scripting
- PlatformIO: Espressif 32 platform
- platformio/platform-espressif32 releases
- pioarduino/platform-espressif32
- Arduino-ESP32 documentation
- ESP-IDF: Partition tables
- ESP-IDF: Over the air updates (OTA)
- ESP-IDF: Core dump
- ESP-IDF: ESP-MQTT
- ArduinoJson documentation
- ESP32Async/ESPAsyncWebServer
- Unity test framework (ThrowTheSwitch)
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com