<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Nahiyan Al Mahmood</title>
    <description>The latest articles on DEV Community by Nahiyan Al Mahmood (@shadowbit24).</description>
    <link>https://dev.to/shadowbit24</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4254736%2F488ec827-51b2-46cf-aa70-28059ecbec46.jpg</url>
      <title>DEV Community: Nahiyan Al Mahmood</title>
      <link>https://dev.to/shadowbit24</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/shadowbit24"/>
    <language>en</language>
    <item>
      <title>I Stopped Eyeballing Serial Logs and Gave My ESP32 Boards a Health Score Instead</title>
      <dc:creator>Nahiyan Al Mahmood</dc:creator>
      <pubDate>Fri, 20 Nov 2026 03:48:17 +0000</pubDate>
      <link>https://dev.to/shadowbit24/i-stopped-eyeballing-serial-logs-and-gave-my-esp32-boards-a-health-score-instead-5a81</link>
      <guid>https://dev.to/shadowbit24/i-stopped-eyeballing-serial-logs-and-gave-my-esp32-boards-a-health-score-instead-5a81</guid>
      <description>&lt;p&gt;Validating an ESP32 board by opening a serial monitor and reading the boot log works exactly once. It does not repeat, it does not scale to the next board on the bench, and when a board fails it leaves no evidence you can hand to anyone.&lt;/p&gt;

&lt;p&gt;I know because board validation was the second half of a longer fight. The first half was three boards that flashed and verified perfectly and never ran a line of application code, a fault I eventually isolated to a bounded domain in the boot chain (I wrote that investigation up separately). The lesson that stuck was not really about those boards. It was that manual checking produces opinions, and what I wanted was the same run, the same evidence, and the same report every time. So I built a framework to do the checking for me.&lt;/p&gt;

&lt;h2&gt;
  
  
  How it works
&lt;/h2&gt;

&lt;p&gt;There are two halves.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;On the board&lt;/strong&gt;, an Arduino test firmware runs seven tests and reports structured JSON records over a small serial protocol:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Serial communication&lt;/li&gt;
&lt;li&gt;Heap behaviour&lt;/li&gt;
&lt;li&gt;Chip information&lt;/li&gt;
&lt;li&gt;A structured board inventory&lt;/li&gt;
&lt;li&gt;Wi-Fi scan&lt;/li&gt;
&lt;li&gt;NVS write and read integrity&lt;/li&gt;
&lt;li&gt;GPIO output&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;strong&gt;On the host&lt;/strong&gt;, a Python runner does the rest:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;It discovers the attached board, and refuses to guess when several are attached.&lt;/li&gt;
&lt;li&gt;It triggers the test suite and validates every record the board sends against the run summary, so a truncated or garbled record fails loudly instead of passing silently.&lt;/li&gt;
&lt;li&gt;It analyzes the boot log, classifying what it finds with a severity, the likely causes, and recommended actions.&lt;/li&gt;
&lt;li&gt;It runs esptool diagnostics: chip ID, flash ID, and flash status.&lt;/li&gt;
&lt;li&gt;It scores the board's health from 0 to 100, using weights that are published in the guide rather than hidden in the code.&lt;/li&gt;
&lt;li&gt;It writes timestamped JSON and Markdown reports, with the raw serial log preserved, so any result can be re-examined later.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There is also a 13-test offline regression suite with mocked serial and esptool, so changes to the host code can be verified with no hardware attached at all. It passes as shipped.&lt;/p&gt;

&lt;h2&gt;
  
  
  The board that scored 15 out of 100
&lt;/h2&gt;

&lt;p&gt;The framework earned its keep on the first real board I pointed it at: an ESP32-D0WD-V3 with 4 MB of flash.&lt;/p&gt;

&lt;p&gt;The run came back with a health score of &lt;strong&gt;15 out of 100&lt;/strong&gt;. The interesting part was the split. Every flash diagnostic passed. Chip ID, flash ID, flash status, all clean. But the application on the board was dead, and the boot log analysis classified the boot as an invalid image.&lt;/p&gt;

&lt;p&gt;A board that passes its flash checks and still cannot run is exactly the pattern from my earlier investigation, so the next step was the eFuse audit. The board's flash encryption state was enabled, and the images being written to it were plaintext. A mismatch between the board's security state and the form of the image is a configuration fault, not a hardware death sentence.&lt;/p&gt;

&lt;p&gt;The recovery was to write the board's boot chain in encrypted form to match its recorded security state. The procedure writes no eFuses and does not enable encryption; it works with the state the board already has. After the recovery, the same framework ran the same suite on the same board and scored it &lt;strong&gt;100 out of 100&lt;/strong&gt;, with all seven firmware tests and all three flash diagnostics passing.&lt;/p&gt;

&lt;p&gt;That pair of reports, 15 and 100, from the same board and the same tool, is the whole argument for automated validation. Nothing about the board was assessed by feel. The evidence before and after sits in two timestamped reports that anyone can read.&lt;/p&gt;

&lt;h2&gt;
  
  
  The honest limits
&lt;/h2&gt;

&lt;p&gt;A scoring framework invites overconfidence, so the limits matter as much as the features:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The framework was exercised on one ESP32-D0WD-V3 board with 4 MB flash. The included flash profile (DOUT, 40 MHz, custom partitions) must be verified for other boards before you trust a run.&lt;/li&gt;
&lt;li&gt;The health score is a diagnostic heuristic, not a certification. It tells you where to look next, not whether a board is "good" in any absolute sense.&lt;/li&gt;
&lt;li&gt;The GPIO test confirms software toggling, not electrical soundness. A pin can toggle in software and still be wrong on the wire.&lt;/li&gt;
&lt;li&gt;The Wi-Fi scan result is environment-dependent. A quiet RF environment and a faulty radio can look similar from one scan.&lt;/li&gt;
&lt;li&gt;The recovery described above fixed one board with one specific failure mode. It is a documented case study, not a general fix, and it has not been replicated across a batch.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why bother, for a handful of boards
&lt;/h2&gt;

&lt;p&gt;If you validate one board once, a serial monitor is fine. The moment you validate the same board twice, or a second board ever, the framework pays for itself: identical procedure, comparable numbers, and a paper trail. That is true on a hobby bench and it is doubly true anywhere a result has to survive a reviewer's questions.&lt;/p&gt;

&lt;p&gt;The framework, the guide, the test plan and results templates, and the full worked example are packaged here: &lt;a href="https://nahiyan8.gumroad.com/l/esp32-automated-validation-framework" rel="noopener noreferrer"&gt;ESP32 Automated Validation Framework&lt;/a&gt; ($29). If your problem is earlier in the chain, a board that will not boot at all, start with the free &lt;a href="https://nahiyan8.gumroad.com/l/esp32-bring-up-checklist" rel="noopener noreferrer"&gt;ESP32 Bring-Up Checklist&lt;/a&gt; or the &lt;a href="https://nahiyan8.gumroad.com/l/esp32-boot-failure-debugging-pack" rel="noopener noreferrer"&gt;debugging pack&lt;/a&gt; built on the three-board investigation. The framework code and investigation live on my GitHub: &lt;a href="https://github.com/ShadowBit24/esp32-automated-test" rel="noopener noreferrer"&gt;esp32-automated-test&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;How do you validate boards on your bench? I am genuinely interested in what other people score, check, or simply refuse to trust.&lt;/p&gt;

</description>
      <category>esp32</category>
      <category>embedded</category>
      <category>python</category>
      <category>testing</category>
    </item>
    <item>
      <title>Your ESP32 Flashes and Verifies Fine but Never Boots. Here Is How to Find the Failing Stage.</title>
      <dc:creator>Nahiyan Al Mahmood</dc:creator>
      <pubDate>Fri, 20 Nov 2026 02:47:37 +0000</pubDate>
      <link>https://dev.to/shadowbit24/your-esp32-flashes-and-verifies-fine-but-never-boots-here-is-how-to-find-the-failing-stage-52n1</link>
      <guid>https://dev.to/shadowbit24/your-esp32-flashes-and-verifies-fine-but-never-boots-here-is-how-to-find-the-failing-stage-52n1</guid>
      <description>&lt;p&gt;It is one of the most misleading faults in embedded work. You flash your ESP32, esptool reports the write succeeded and the hash verified, you reset the board, and the application never runs. The ROM bootloader prints something like this instead:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;invalid header: 0x8e465484
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Most people respond the same way: reflash, swap the USB cable, change the port, reflash again. I know, because I did all of that too, on three ESP32 DevKit V1 boards from a single purchase batch that all behaved exactly this way. What finally moved the investigation forward was not another reflash. It was accepting one uncomfortable idea and testing the boot chain in order.&lt;/p&gt;

&lt;h2&gt;
  
  
  Flashing and booting are different paths
&lt;/h2&gt;

&lt;p&gt;Here is the core idea the whole method hangs on. Flashing exercises the ROM downloader path: host-driven, host-paced, host-checked. Booting exercises the ROM's own read of the same flash, under boot parameters, with no host involved. The two paths share silicon and pins and almost nothing else that matters. A fault can live in exactly one of them.&lt;/p&gt;

&lt;p&gt;So "it flashed and verified" tells you the downloader path works. It tells you nothing about the boot path. In my three boards, one path was flawless and the other was broken on every unit.&lt;/p&gt;

&lt;p&gt;The boot chain you are always testing, whether you say so or not:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Power / Reset → ROM Bootloader → SPI Flash Read → Image Header Parse → Application Startup
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Your job is to find which arrow fails, and to prove it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Capture the symptom exactly, before changing anything
&lt;/h2&gt;

&lt;p&gt;Record the exact ROM output at reset. "It still fails" is not an observation. "Fails with &lt;code&gt;invalid header: 0x8e465484&lt;/code&gt;" is an observation.&lt;/p&gt;

&lt;p&gt;In the case study, the header values never repeated across resets: &lt;code&gt;0x3ffea272&lt;/code&gt;, &lt;code&gt;0xd610e111&lt;/code&gt;, &lt;code&gt;0x8e465484&lt;/code&gt;, &lt;code&gt;0x5691acba&lt;/code&gt;. That turned out to be the single most valuable clue in the investigation. A valid image header starts with magic byte &lt;code&gt;0xE9&lt;/code&gt;. Fixed corruption returns the same wrong value every time. Non-repeating wrong values point at the transfer, not the content.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2: Verify each subsystem independently
&lt;/h2&gt;

&lt;p&gt;Cheapest and most discriminating tests first. USB enumeration, power indication, UART communication, download mode entry, flash identification:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;esptool flash-id
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each subsystem you close is a fault domain eliminated. On my boards all of these passed, which felt like bad news and was actually progress: the elimination list is what makes the final conclusion defensible.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Never trust a write. Read back and validate.
&lt;/h2&gt;

&lt;p&gt;Dump the flash and validate the dump:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;esptool read-flash 0 0x400000 flash_dump.bin
esptool image-info flash_dump.bin
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the checksum is valid and the validation hash is valid, the stored image is structurally sound, and you can stop suspecting your build, your partition table, and your flashing process in one move.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: Audit the security state early
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;espefuse summary
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Do this before anything writes to the device, because eFuse state cannot be captured retroactively once it changes. On unfamiliar or suspect boards, the security state is part of the board's identity.&lt;/p&gt;

&lt;p&gt;My boards were not factory virgin: &lt;code&gt;FLASH_CRYPT_CNT = 1&lt;/code&gt;, &lt;code&gt;FLASH_CRYPT_CONFIG = 15&lt;/code&gt;, &lt;code&gt;RD_DIS = 1&lt;/code&gt;, download decrypt disabled, JTAG disabled. A standard erase refused to run, reporting active security features. A forced erase completed:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;esptool erase-flash          &lt;span class="c"&gt;# refused on these boards&lt;/span&gt;
esptool erase-flash --force  &lt;span class="c"&gt;# completed&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The security state and the erase behaviour corroborated each other. That is a free probe, and it reframed the whole investigation.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5: Change one variable at a time, and record every result
&lt;/h2&gt;

&lt;p&gt;With the stored image proven valid, I swept SPI mode and clock individually and logged the symptom after each change:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Configuration&lt;/th&gt;
&lt;th&gt;Observed header at boot&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;DIO at 80 MHz&lt;/td&gt;
&lt;td&gt;0xd610e111&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DIO at 40 MHz&lt;/td&gt;
&lt;td&gt;0x8e465484&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DOUT at 40 MHz&lt;/td&gt;
&lt;td&gt;0x5691acba&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The stored data was constant. The header, still invalid, changed with interface settings. The corruption is introduced in the boot-time transfer, not present in the stored content. That one table moved the fault out of the content domain and into the interface domain.&lt;/p&gt;

&lt;p&gt;Changing two settings at once would have destroyed that signal. Change one variable, record, repeat.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 6: Replicate across units before concluding anything
&lt;/h2&gt;

&lt;p&gt;One failing board supports "this board is defective." Three boards from one batch failing identically supports "this batch has a property." The experiments worth running are different in those two worlds, and so is the disposition. Unit-level defect means component isolation on one board. Batch-level property means quarantine and a fault domain report.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 7: Stop at the boundary your instruments can defend
&lt;/h2&gt;

&lt;p&gt;Nine of my ten test groups passed. The only failing behaviour was application execution. The conclusion the evidence supports is a bounded fault domain:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;ROM Bootloader → SPI Flash Interface → Flash Security / Configuration → Application Startup
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The next discriminating steps need a logic analyzer on the SPI bus and a known-good control board, neither of which I had. So the investigation closed with a fault domain, high confidence in the domain, and the next experiments defined. Not a best guess dressed as a root cause. An investigation that claims one step more than its evidence teaches everyone to discount all of its steps.&lt;/p&gt;

&lt;h2&gt;
  
  
  The decision flow, condensed
&lt;/h2&gt;

&lt;p&gt;Work these in order. The first four cost minutes and close most real-world cases.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;ROM output on serial?&lt;/strong&gt; No: power, USB, UART path. Yes: continue.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Download mode reachable?&lt;/strong&gt; You want &lt;code&gt;boot:0x3 (DOWNLOAD_BOOT)&lt;/code&gt; and "waiting for download". No: strapping or GPIO0 fault. Yes: continue.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Flash ID sane?&lt;/strong&gt; No: flash device or SPI wiring. Yes: continue.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Readback image valid?&lt;/strong&gt; No: write-path fault. Yes: continue.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;eFuse state normal for a new board?&lt;/strong&gt; Abnormal: you are in the configuration domain. Normal: continue.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Does an SPI sweep change the symptom?&lt;/strong&gt; Changes: interface domain. Constant: re-examine your content and configuration.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Does it replicate on other units?&lt;/strong&gt; Yes: batch property. No: unit defect.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  One more thing: when the security state is the fault
&lt;/h2&gt;

&lt;p&gt;There is a related case worth knowing about. If your eFuse summary shows flash encryption already enabled (for example &lt;code&gt;FLASH_CRYPT_CNT = 1&lt;/code&gt;) and the images you are flashing were built and written as plaintext, the board can show this exact symptom while every host diagnostic passes. In one documented case, a board like this was recovered by writing its boot chain in encrypted form to match its recorded security state, with no eFuses written by the procedure itself. It went from a validation score of 15 out of 100 to 100 out of 100, with all firmware tests passing.&lt;/p&gt;

&lt;p&gt;The honest limit: that is a single board result, not a general fix. If your eFuse state does not show encryption enabled, that procedure does not apply to you, and the method above is how you find out where your fault actually lives.&lt;/p&gt;

&lt;h2&gt;
  
  
  Get the checklist free
&lt;/h2&gt;

&lt;p&gt;I turned the ordered checklist from this investigation into a free download, the same one I now run on any new board from first power-on to application execution:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;a href="https://nahiyan8.gumroad.com/l/esp32-bring-up-checklist" rel="noopener noreferrer"&gt;ESP32 Bring-Up Checklist, free on Gumroad&lt;/a&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If you want the full method with the complete case study, the command reference, the fault investigation and test log templates, and the recovery chapter, that is the &lt;a href="https://nahiyan8.gumroad.com/l/esp32-boot-failure-debugging-pack" rel="noopener noreferrer"&gt;ESP32 Bring-Up and Boot Failure Debugging Pack&lt;/a&gt; ($15). And if you would rather automate the whole validation run, the &lt;a href="https://nahiyan8.gumroad.com/l/esp32-automated-validation-framework" rel="noopener noreferrer"&gt;ESP32 Automated Validation Framework&lt;/a&gt; is the Python host runner and test firmware I built to do it repeatably.&lt;/p&gt;

&lt;p&gt;The investigation itself, including the evidence package and the final fault domain analysis, is public on my GitHub: &lt;a href="https://github.com/ShadowBit24/esp32-boot-failure-investigation" rel="noopener noreferrer"&gt;esp32-boot-failure-investigation&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;If you have fought this fault before, I would like to hear where yours turned out to live.&lt;/p&gt;

</description>
      <category>esp32</category>
      <category>embedded</category>
      <category>iot</category>
      <category>tutorial</category>
    </item>
  </channel>
</rss>
