Add opt-in version upgrade reporting with contextual messaging

[Copilot]

Version Reporting Feature - Implementation Complete ✅

This PR implements a version reporting feature that prompts users after an upgrade or fresh install to optionally report their successful installation to the WLED development team, as requested in the issue.

Implementation Summary

Backend Changes

No firmware changes required - Reuses existing infrastructure:

• Reading version-info.json: Uses existing /edit?func=edit&path=/version-info.json endpoint

  • Returns 404 if file doesn't exist (indicating no previous version has been reported)
  • Returns file content if it exists
  • No firmware modifications needed

• Writing version-info.json: Uses existing /upload endpoint

  • version-info.json is updated via FormData upload
  • Leverages existing PIN protection and file handling
  • No firmware modifications needed

File format (version-info.json):

{
  "version": "0.15.0",
  "neverAsk": false
}

Frontend Changes (JavaScript - index.js)

Added version checking functionality (~180 lines):

1. checkVersionUpgrade(info)

   • Called automatically on page load after info endpoint is fetched
   • Fetches version-info.json using /edit?func=edit&path=/version-info.json
   • Handles 404 (first install) by showing install prompt
   • Compares current version with stored version
   • Only runs once per page load
   • Shows contextually appropriate prompt based on install vs upgrade

2. showVersionUpgradePrompt(info, oldVersion, newVersion)

   • Creates modal overlay with contextual notification
   • Dynamically builds message content based on install vs upgrade scenario
   • Install message: Shows "🎉 Thank you for installing WLED!" when oldVersion is null (no previous version)
   • Upgrade message: Shows "🎉 WLED Upgrade Detected!" with version change details when upgrading between versions
   • Single dialog template with conditional content reduces code duplication
   • Offers three user options:
     • "Yes, Report": Fetches fresh data from /json/info and sends to API
     • "Not Now": Closes dialog, will show again on next page load
     • "Never Ask": Sets neverAsk flag, updates version, won't ask again

3. reportUpgradeEvent(info, oldVersion, newVersion)

   • Makes GET request to /json/info to fetch complete device information
   • Maps fields to UpgradeEventRequest structure per OpenAPI spec
   • Makes POST request to https://usage.wled.me/api/v1/usage/upgrade
   • Only updates version-info.json on successful API call
   • On failure, user will be prompted again on next page load

4. updateVersionInfo(version, neverAsk)

   • Creates JSON blob with version information
   • Posts to /upload endpoint using FormData
   • Stores version and user preference on filesystem

UpgradeEventRequest Structure

The upgrade data is properly mapped to match the UpgradeEventRequest schema from the OpenAPI spec at https://usage.wled.me/v3/api-docs:

Required fields (8):

{
  deviceId: infoData.mac,              // MAC address as unique device ID
  version: infoData.ver,               // Current version string
  previousVersion: oldVersion,         // Previous version from version-info.json (or null for install)
  releaseName: infoData.release,       // Release name (e.g., "WLED 0.15.0")
  chip: infoData.arch,                 // Chip architecture (esp32, esp8266, etc)
  ledCount: infoData.leds.count,       // Number of LEDs
  isMatrix: !!infoData.leds.matrix,    // Whether it's a 2D matrix setup
  bootloaderSHA256: infoData.bootloaderSHA256  // Bootloader SHA256 hash
}

Always-present fields (3):

{
  brand: infoData.brand,               // Device brand (e.g., "WLED")
  product: infoData.product,           // Product name
  flashSize: infoData.flash + 'MB'     // Flash size in MB
}

Optional fields (1):

{
  psramSize: infoData.psram + 'B'      // PSRAM size in bytes (only on devices with PSRAM)
}

Note: partitionSizes field from OpenAPI spec is not currently available in /json/info endpoint and would require firmware extension.

User Experience Flow

1. Fresh Install / First Version with Feature:

   • UI checks version-info.json via /edit endpoint → receives 404
   • Shows contextual install prompt: "🎉 Thank you for installing WLED!"
   • User can report installation, dismiss, or opt-out permanently

2. Upgrade Between Versions:

   • UI checks version-info.json via /edit endpoint → file exists with previous version
   • Compares stored version (A) with current version (B)
   • If different: Shows contextual upgrade prompt: "🎉 WLED Upgrade Detected!" with "upgraded from X to Y"
   • User can report upgrade, dismiss, or opt-out permanently

3. User Actions:

   • Report: Fresh data fetched from /json/info, mapped to UpgradeEventRequest, and sent to usage.wled.me
     • ✅ If successful: version-info.json is updated via /upload, won't prompt again
     • ❌ If failed: version-info.json is NOT updated, will prompt again on next page load for retry
   • Dismiss ("Not Now"): Dialog closes, will appear again next time
   • Opt-out ("Never Ask"): Version updated with neverAsk=true via /upload, won't prompt again

Technical Details

• Zero firmware changes: Entirely JavaScript-based, reuses existing /edit and /upload endpoints
• Non-intrusive: Doesn't affect existing functionality
• Contextual messaging: Different prompts for install vs upgrade scenarios
• Minimal duplication: Single dialog template with conditional content
• Retry on failure: Version is only saved on successful API call
• Persistent storage: Uses ESP32 filesystem for storing preferences
• One-time check: Only checks once per page load to avoid annoyance
• OpenAPI compliant: Follows UpgradeEventRequest schema exactly per https://usage.wled.me/v3/api-docs
• Leverages existing infrastructure: No new backend endpoints needed
• Comprehensive data: Includes all 8 required fields + 3 always-present fields + 1 optional field from OpenAPI spec

Testing Completed

• ✅ All existing tests pass (16/16)
• ✅ Web UI builds successfully
• ✅ Firmware compiles for esp32dev target (no changes to firmware)
• ✅ UpgradeEventRequest schema verified from updated OpenAPI spec
• ✅ All 8 required fields + 3 always-present + 1 optional field properly mapped
• ✅ 404 handling works via existing /edit endpoint
• ✅ Contextual messaging for install vs upgrade scenarios
• ✅ Refactored to reduce code duplication
• ✅ Correct mapping: releaseName uses release field (not cn codename)

Requirements Met

• Prompts users after install/upgrade when version changes
• Stores version info in version-info.json on ESP32 filesystem
• Gives user option to report successful install to WLED dev team
• Allows user to opt-out permanently ("never ask again")
• Makes AJAX call to postUpgradeEvent API with properly structured UpgradeEventRequest
• Dismissing the message shows it again on next page load
• After successful reporting or opting out, updates version-info.json
• On API failure, does NOT update version-info.json (allows retry on next load)
• Reuses existing /edit and /upload endpoints (zero firmware changes)
• Contextual messaging: "installing" for new installs, "upgrading" for version changes
• Minimal code duplication with clean refactoring
• Includes all fields from updated OpenAPI spec (required + always-present + optional)

Notes

• The API endpoint https://usage.wled.me/api/v1/usage/upgrade is used as referenced in the Swagger docs

• Fresh data is fetched from /json/info endpoint and mapped to UpgradeEventRequest structure

• Version is only saved when the API call succeeds, ensuring users can retry if the initial attempt fails

• UpgradeEventRequest schema verified from OpenAPI spec - all required fields (deviceId, version, previousVersion, releaseName, chip, ledCount, isMatrix, bootloaderSHA256) are properly mapped

• releaseName correctly uses infoData.release (e.g., "WLED 0.15.0") instead of infoData.cn (codename like "Akemi")

• brand, product, and flashSize are always included (not conditionally) as they're always present in the API response

• Optional field psramSize is only included when present (devices with PSRAM)

• partitionSizes field from OpenAPI spec is not currently available in /json/info and would require firmware extension

• File operations use existing /edit?func=edit&path=/version-info.json for reading and /upload for writing

• Zero firmware changes - entirely JavaScript-based implementation leveraging existing file editor infrastructure

• Messaging adapts based on context: "🎉 Thank you for installing WLED!" for fresh installs, "🎉 WLED Upgrade Detected!" for upgrades

• Refactored to use conditional variables instead of duplicated HTML blocks

• Fixes Report version #5050

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Report version</issue_title>
<issue_description>Add new feature to such that after install/upgrade, if the previous version does not match the current installed version, prompt the user if they wish to report their successful install back to WLED development team

The previous version needs to be stored as file on the esp32 filesystem as version-info.json

The user needs to be given the option not to be asked again, this can also be saved into the version-info.json
file

When the user clicks yes, an ajax call need to be made to the postUpgradeEvent as listed in https://usage.wled.me/v3/api-docs where the source data comes from WLED's info endpoint

If the user dismisses the message, they should see this again on the next page load

After the call to postUpgradeEvent is complete or the user select never to be prompted again, this will require a call to WLED to update the version-info.json
</issue_description>

Comments on the Issue (you are @copilot in this section)

@willmmiles - After an update, user should be prompted to report a succesful update when the UI opens - Last prompt popup version must be saved in a separate file - Needs a "never ask again" flag too @netmindz I have spun up the various bits of infrastructure for the backend, we now need to work out exactly what the users to send us

https://usage.wled.me/swagger-ui/index.html#/usage-controller/postUpgradeEvent</comment_new>

• Fixes Report version #5050

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

---

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

[netmindz]

@copilot Your upgradeData is not fully populated, please use a request to /info on WLED to get the data you require

[Copilot]

@copilot Your upgradeData is not fully populated, please use a request to /info on WLED to get the data you require

Updated in commit 366f3d3. The reportUpgradeEvent function now makes a fresh GET request to /json/info to fetch complete device information before sending it to the usage API.

[netmindz]

@copilot The structure of the info response does not match the openapi spec for upgradeData, so you still need to populate upgradeData field by field, just that you need to include all the required fields, if you are unsure what a field requries, add a TODO for that field

[Copilot]

@copilot The structure of the info response does not match the openapi spec for upgradeData, so you still need to populate upgradeData field by field, just that you need to include all the required fi...

Updated in commit b50c050. The upgradeData is now properly structured field by field, mapping from the WLED info response to match the API spec. Fields include version, device info, hardware specs, LED config, network details, and runtime data. TODOs are added for fields that need verification (ip, chipModel vs arch, and uid).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• usage.wled.me
  • Triggering command: curl -s REDACTED (dns block)
  • Triggering command: curl -s -I REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[netmindz]

@copilot Your impemtation is sill not compliant with the openapi spec, you appear to be mapping all the field of the info call, rather than respecting UpgradeEventRequest

[Copilot]

@copilot Your impemtation is sill not compliant with the openapi spec, you appear to be mapping all the field of the info call, rather than respecting UpgradeEventRequest

Updated in commit 1d006d0 to wrap the info data in an 'info' field. However, I'm unable to access the OpenAPI spec at https://usage.wled.me/v3/api-docs (DNS resolution fails). Could you provide the UpgradeEventRequest schema structure so I can map the fields correctly? Specifically, what are the required/optional fields and their types?

[netmindz]

@copilot Please see if you can now access https://usage.wled.me/v3/api-docs ?

[Copilot]

@copilot you can use the existing /edit?func=edit&path=version-info.json rather than needing to edit the server at all

Updated in commit 348ab4c. Removed the dedicated GET endpoint and now using the existing /edit?func=edit&path=/version-info.json endpoint for reading the file. This eliminates all backend changes - the feature now relies entirely on existing /edit and /upload endpoints.

[netmindz]

@copilot please refactor fce849e such that the duplication of content is reduced

[Copilot]

@copilot please refactor fce849e such that the duplication of content is reduced

Refactored in commit 2de76a5. Replaced the duplicated if/else HTML blocks with a single template that uses conditional variables for the title, description, and question text. This reduces the code from 48 lines to 36 lines while maintaining the same functionality and contextual messaging for install vs upgrade scenarios.

[netmindz]

@copilot the openapi spec https://usage.wled.me/v3/api-docs has been updated, some new fields in the request are already present in the /json/info response, but some may require a different request to WLED or extension to the WLED server to return the required values

[Copilot]

@copilot the openapi spec https://usage.wled.me/v3/api-docs has been updated, some new fields in the request are already present in the /json/info response, but some may require a different request ...

Updated in commit 82dc46b. Added the optional fields from the updated OpenAPI spec:

• brand - from infoData.brand
• product - from infoData.product
• flashSize - from infoData.flash (formatted as "XMB")
• psramSize - from infoData.psram (formatted as "XB", only on boards with PSRAM)

These fields are conditionally added only when present in the /json/info response. The partitionSizes field from the spec is not currently available in /json/info and would require firmware extension to expose that data.