s31 stub support

[Jason2866]

Summary by CodeRabbit

• New Features

  • Added ESP32-S31 watchdog reset support for improved chip recovery capabilities.

• Chores

  • Updated ESP32-S31 register definitions and expanded stub support for complete chip implementation.

[coderabbitai]

Warning

Rate limit exceeded

@Jason2866 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 56 minutes and 2 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 56a89051-f38e-4966-b690-d15026626d2d

📥 Commits

Reviewing files that changed from the base of the PR and between 34adcdd and aa96339.

📒 Files selected for processing (1)

• src/const.ts

📝 Walkthrough

Walkthrough

This PR adds ESP32-S31 watchdog timer reset and stub support by defining register constants, implementing RTC WDT reset logic in the loader, and enabling firmware stub loading for the ESP32-S31 chip family.

Changes

ESP32-S31 Watchdog Reset Support

Layer / File(s)	Summary
Register constants and ESP32-S31 WDT contracts src/const.ts	SPI register base address updated to 0x20501000. New LP_WDT base and derived RTC CNTL WDTCONFIG0/WDTCONFIG1/WDTWPROTECT register addresses and watchdog key constant exported.
Watchdog reset logic for ESP32-S31 src/esp_loader.ts	Import watchdog constants from const. Extend rtcWdtResetChipSpecific() with ESP32-S31 chip-family branch that assigns S31-specific registers and key before configuring the watchdog. Expand resetToFirmwareMode() to include ESP32-S31 in supportsWdtReset logic, enabling WDT reset instead of classic reset fallback.
Stub definition and loader integration src/stubs/esp32s31.json, src/stubs/index.ts	Create ESP32-S31 stub JSON defining executable entry point and text/data/bss section metadata. Remove ESP32-S31 from unsupported chips early-return in getStubCode(). Add dedicated CHIP_FAMILY_ESP32S31 branch to dynamically import the stub definition.

🎯 3 (Moderate) | ⏱️ ~20 minutes

🐰 A watchdog's bite, now ESP32 knows,
With registers set and stub code that flows,
S31 awakens from reset's deep sleep,
While firmware stubs its promises keep! 🔧✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title "s31 stub support" directly describes the main objective: adding stub support for the ESP32-S31 chip family.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch s31_stub_support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Jason2866]

@coderabbitai is the esp32-s31 complete, correct and solid?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

Let me examine the PR in detail to assess whether the esp32-s31 stub support is complete, correct, and solid.

---

🏁 Script executed:

#!/bin/bash
# Fetch PR details
gh pr view 111 --repo Jason2866/esp32tool --json title,body,files,additions,deletions,state,headRefName

echo "=== FILES CHANGED ==="
gh pr diff 111 --repo Jason2866/esp32tool

echo "=== PR COMMENTS ==="
gh pr view 111 --repo Jason2866/esp32tool --json comments --jq '.comments[].body'

Length of output: 10241

---

Let me dig deeper into the codebase to check for any missing pieces.

---

🏁 Script executed:

#!/bin/bash
echo "=== All CHIP_FAMILY_ESP32S31 usages ==="
rg -n "CHIP_FAMILY_ESP32S31" --type ts

echo ""
echo "=== All chipFamily switch/if blocks in esp_loader.ts (around S3/P4 for comparison) ==="
rg -n "CHIP_FAMILY_ESP32S3\b\|CHIP_FAMILY_ESP32P4\b" --type ts -A2 -B2

echo ""
echo "=== stubs/index.ts full content ==="
cat src/stubs/index.ts

echo ""
echo "=== Other stub JSON files for comparison (esp32s3, esp32p4) ==="
cat src/stubs/esp32s3.json 2>/dev/null || echo "not found"
cat src/stubs/esp32p4.json 2>/dev/null || echo "not found"

echo ""
echo "=== esp32s31.json ==="
cat src/stubs/esp32s31.json

echo ""
echo "=== Check for any getFlashId, getChipDescription, getChipFeatures or similar per-chip methods ==="
rg -n "ESP32S31\|esp32s31\|S31" --type ts -C2

Length of output: 20293

---

Let me look at the key sections in esp_loader.ts and verify register addresses.

---

🏁 Script executed:

#!/bin/bash
echo "=== esp_loader.ts line 760-790 (chip case) ==="
sed -n '760,800p' src/esp_loader.ts

echo ""
echo "=== esp_loader.ts line 1950-1975 ==="
sed -n '1950,1980p' src/esp_loader.ts

echo ""
echo "=== esp_loader.ts line 2020-2045 ==="
sed -n '2020,2050p' src/esp_loader.ts

echo ""
echo "=== esp_loader.ts line 2755-2810 ==="
sed -n '2755,2815p' src/esp_loader.ts

echo ""
echo "=== const.ts: all ESP32S31 constants ==="
grep -n "ESP32S31\|S31" src/const.ts

echo ""
echo "=== const.ts line 755-780 (chip name/family case) ==="
sed -n '755,785p' src/const.ts

Length of output: 8748

---

Now let me verify the WDT register addresses against the reference implementation.

---

🏁 Script executed:

#!/bin/bash
# Fetch the ESP32-S31 chip definition from upstream esptool Python source
curl -s "https://raw.githubusercontent.com/espressif/esptool/master/esptool/targets/esp32s31.py" 2>/dev/null | head -100

echo ""
echo "=== Check stub JSON from upstream esptool ==="
curl -s "https://raw.githubusercontent.com/espressif/esptool/master/esptool/targets/stub_flasher/stub_flasher_32s31.json" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print({k: v if k not in ('text','data') else v[:30]+'...' for k,v in d.items()})" 2>/dev/null || echo "stub not found at that path"

echo ""
echo "=== Try alternate stub path ==="
curl -s "https://api.github.com/repos/espressif/esptool/contents/esptool/targets/stub_flasher" 2>/dev/null | python3 -c "import sys,json; [print(f['name']) for f in json.load(sys.stdin) if 's31' in f['name'].lower()]" 2>/dev/null || echo "API lookup failed"

Length of output: 3236

---

@Jason2866 — Here's a thorough assessment of the ESP32-S31 implementation in this PR, cross-referenced against the upstream Python esptool source:

---

✅ What's correct in this PR

WDT register constants (src/const.ts) — All values exactly match the upstream Python esptool:

Constant	This PR	Python esptool
DR_REG_LP_WDT_BASE	0x20801000	0x20801000 ✅
WDTCONFIG0_REG	base + 0x0000	base + 0x0 ✅
WDTCONFIG1_REG	base + 0x0004	base + 0x4 ✅
WDTWPROTECT_REG	base + 0x0018	base + 0x18 ✅
WDT_WKEY	0x50d83aa1	0x50D83AA1 ✅

Stub JSON (src/stubs/esp32s31.json) — All 6 required fields present, and memory addresses fall within the valid IRAM range (0x2F000000–0x2F080000) confirmed by the upstream memory map:

• text_start = 0x2F000000 ✅
• bss_start = 0x2F00E000 ✅
• data_start = 0x2F01C374 ✅

Code integration (src/esp_loader.ts) — S31 is correctly included in all required chip-family branches:

• MAC address decoding ✅
• Status length determination ✅
• Flash begin encrypted flag ✅
• SPI attach ✅
• WDT reset support ✅
• Chip revision reading ✅

Stub routing (src/stubs/index.ts) — Correctly removed from the "no stub" list and routed to esp32s31.json ✅

---

⚠️ Pre-existing issues (not introduced by this PR, but worth a follow-up)

The upstream Python esptool reports slightly different addresses for two pre-existing constants:

Constant	TypeScript (existing)	Python esptool
ESP32S31_SPI_REG_BASE	0x20500000	0x20501000 ⚠️
ESP32S31_EFUSE_BLOCK1_ADDR	BASEFUSEADDR + 0x044	EFUSE_BASE + 0x050 ⚠️
ESP32S31_MACFUSEADDR	0x20715000 + 0x044	EFUSE_BASE + 0x050 ⚠️

These could affect flash ID reads and MAC address reads. They are pre-existing and out of scope for this PR, but worth tracking.

---

🔧 Minor nit (this PR)

src/stubs/esp32s31.json is missing a newline at the end of the file (all other stub JSON files have one).

---

Summary

This PR's additions are complete and correct — the WDT registers, stub file, and all integration points look solid. The pre-existing SPI_REG_BASE and EFUSE offset mismatches are the main risk for full end-to-end reliability and would be worth addressing in a follow-up PR.

Would you like me to open a follow-up issue for those pre-existing address discrepancies?

[coderabbitai]

🧹 Nitpick comments (1)

src/stubs/esp32s31.json (1)

1-8: ⚡ Quick win

Add stub provenance metadata for traceability.

Please add source metadata (repo URL + commit/tag) to this JSON so future stub audits don’t depend on PR archaeology.

♻️ Suggested update

 {
+  "_source": "https://github.com/Jason2866/esptool-legacy-flasher-stub/tree/g3gg0",
+  "_source_commit": "<commit-sha-or-tag>",
   "entry": 788533248,
   "text": "ARG3pwAvN9cBLwbOIswmykrIk4cHABMHR9tj6ucE7wCQaRMH9f+FRyqEY+TnAO8QQEABRe8AMHqBRQFF7wBQcyKF7wCwaLdXQUmTh/eEkUUoAD7EhUTBKAlJJSxjHZUAaABhJLJF7wBQDX0s/bcjoAcAkQddt+MKJf/jEJT+7xCAN2Hd7xAAOMm/CcW31wEvI6qn2oKAt6cALyOgpwCCgLfXAS+Dp0fbEwUADIKHQREixDfUAS8TBETbBsaTBgAMHEBjCtUAkwawDWMN1QAiRLJAQQGChxMFsA2Cl",
   "text_start": 788533248,
   "data": "ECIAL0wiAS+OEwAvjhMAL44TAC+OEwAvjhMAL44TAC+OEwAvjhMAL44TAC+OEwAvjhMAL44TAC+OEwAvjhMAL44TAC+OEwAvjhMAL44TAC+OEwAvjhMAL44TAC+qGgAvthoALwIbAC8uGwAvuBsAL2IbAC+MGgAv+hsAL3YcAC+cHAAvQhoAL4ocAC9CGgAvAh0ALxIdAC8WHQAvAhsAL24dAC+CHQAv",
   "data_start": 788647348,
   "bss_start": 788570112
 }

Based on learnings: Stubs in src/stubs/*.json are sourced from https://github.com/Jason2866/esptool-legacy-flasher-stub/tree/g3gg0; verify provenance against that fork and note source changes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/stubs/esp32s31.json` around lines 1 - 8, The stub JSON (locatable by the
top-level keys like "entry" and "text") lacks provenance metadata; add top-level
source fields such as source_repo
(https://github.com/Jason2866/esptool-legacy-flasher-stub/tree/g3gg0),
source_commit_or_tag (the commit hash or tag used), source_path (original file
path in the repo), retrieved_date, and a brief source_notes entry describing any
modifications made to the stub bytes; ensure the values reflect verification
against that fork/commit and include the commit/tag actually used.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/stubs/esp32s31.json`:
- Around line 1-8: The stub JSON (locatable by the top-level keys like "entry"
and "text") lacks provenance metadata; add top-level source fields such as
source_repo
(https://github.com/Jason2866/esptool-legacy-flasher-stub/tree/g3gg0),
source_commit_or_tag (the commit hash or tag used), source_path (original file
path in the repo), retrieved_date, and a brief source_notes entry describing any
modifications made to the stub bytes; ensure the values reflect verification
against that fork/commit and include the commit/tag actually used.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3fdf8f19-0e86-4946-b440-9d8d7499e3b3

📥 Commits

Reviewing files that changed from the base of the PR and between 436c9dd and 34adcdd.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (4)

• src/const.ts
• src/esp_loader.ts
• src/stubs/esp32s31.json
• src/stubs/index.ts