Firmware release notes: shipping updates to devices you don’t control

Most release notes ride along with software the reader can quit, reinstall, or roll back. Firmware notes don’t. They describe an update to a physical object — a router, a thermostat, a camera, a door lock, a hearing aid — that is often doing a job the household or the business depends on, has no screen of its own, and may not support rolling back at all. The reader of firmware release notes is deciding whether to let a thing on their wall rewrite itself overnight. That makes these the highest-stakes release notes in software, and the ones where vagueness costs the most trust.

This guide covers writing update notes for embedded and IoT products: what the two very different readers need, what counts as breaking when the interface is a device, why the known-issues section is mandatory here, and the anti-patterns that teach people to refuse updates forever.

Two readers: the homeowner and the fleet

Firmware notes serve two audiences with almost nothing in common.

The homeowner has one device and three questions: will it still work with my setup, what will look or behave differently, and how long will it be offline while it updates. They read the notes (if at all) inside a companion app’s update prompt, mid-task, deciding between “Update now” and “Remind me later.” Everything in release notes for non-technical users applies double: name symptoms, not subsystems.

The fleet operator or integrator has forty units in a building — or forty thousand in the field — plus scripts talking to the device’s local API, a hub that has its own minimum-version requirements, and a change-control process. They read notes in bulk before scheduling a rollout window, and they care about exactly the things the homeowner skips: protocol changes, default resets, certificate updates, and whether the update can be staged or deferred.

Write one entry that serves both, in that order: consumer-visible changes first, in plain language, then a clearly-headed section (“For integrations” / “Local API”) with the technical detail. Neither reader should have to wade through the other’s material to find their answer.

What counts as breaking on a device

On hardware, the API surface is bigger than the API. Treat all of these as breaking changes that lead the entry — not footnotes:

  • Local API and protocol changes. Home-automation setups, monitoring scripts, and third-party hubs talk to your device directly. A renamed endpoint, a changed payload, a dropped protocol version, or newly-required authentication breaks integrations the moment the device reboots — and the person who wired them up may not even know an update happened.
  • Settings that reset or change defaults. An update that quietly re-enables a setting someone turned off — telemetry, cloud connectivity, LED brightness, standby behavior — reads as betrayal, not oversight. If the update resets anything, say exactly what.
  • Removed or degraded features. The “my device got worse after an update” story is its own genre, and every incident in it was a silent removal. More below — this one is the trust cliff.
  • New minimum versions elsewhere. Firmware that requires a newer hub, bridge, or companion app version makes the update a coordinated event, not a tap. Name the minimum versions in the entry, first line, not in a support article discovered afterward.
  • Power and battery behavior. On battery-powered devices, a change to polling frequency or radio behavior is a change users will physically notice weeks later. An honest “battery life improves/decreases by roughly …” line beats a mystery.
  • Hardware-revision splits. The day revision A stops getting updates while revision B continues is a breaking change for revision A owners — announce it as loudly as any API removal, with dates, per the breaking-changes playbook.

Write for the device that spent the winter unplugged

On phones and desktops the version-skipper is a special case. In firmware they’re the norm: devices live in drawers, holiday homes, and network closets, and come back online three, five, ten versions behind. Two consequences:

Entries must stand alone. “Fixes the pairing regression from 2.3.1” means nothing to someone jumping 2.1 → 2.6. Name the symptom (“fixed: device dropped off Wi-Fi after 24 hours idle”) so any reader can tell whether it affects them.

Show the span. Most update dialogs show only the latest version’s notes, even when the device is about to jump six versions. Link the full history — a canonical page the dialog can point at — and for big jumps, lead with one line that summarizes the span: “Since 2.1: new scheduling engine, Matter support, and 40+ fixes.” The same convention as desktop update dialogs, with higher stakes.

Rollback is not a given — so the notes carry the whole decision

Desktop users can usually reinstall the old version. Firmware often can’t go back: bootloader changes, new partition layouts, or security fuses make downgrades unsupported or physically impossible. When the update is a one-way door, the release notes are the only place the reader can weigh the decision — which obligates three things:

  • Say whether rollback is possible. One line: “Rollback: supported via the app” or “Rollback: not supported for this release.” Fleet operators schedule around this line.
  • Publish known issues with the release, not after. A known-issues section is optional courtesy elsewhere; here it’s mandatory kindness. “Known: Zigbee re-pairing may be required on hubs with 50+ devices” lets exactly the right people defer.
  • Never silently re-release a version. If 2.4.0 shipped broken and you rebuilt it, the new build is 2.4.1 with an honest entry — per the hotfix communication playbook. Two different binaries with one version number is how fleet operators lose a weekend, and devices can’t clear their caches.

Security fixes: precise impact, vague mechanism

Unattended devices are exactly what attackers scan for, and fleets patch slowly. That combination sets the rule: the ship-day entry states precise impact — severity word, affected versions and hardware revisions, whether exploitation requires local network access — and stays vague about mechanism until the fleet has had time to update. The full account belongs in an advisory published on its own clock; the security advisory vs changelog guide covers the two-document sequence.

What you cannot do is label a CVE fix “stability improvements.” Operators prioritize update windows by what’s in the notes; a hidden security fix means the people most willing to patch fast are the last to know they should. Say “Security: fixes a high-severity vulnerability in the local web interface; update promptly” — that sentence gives attackers little and defenders everything they need to schedule tonight instead of next quarter.

Removed features are the trust cliff

Every product category has its cautionary tales; connected hardware’s are the devices that lost features after purchase — a cloud service ended, an integration dropped, a capability moved behind a subscription — announced only by users noticing. People bought the physical object partly for that capability, and an update took it away.

Sometimes removals are genuinely forced: a partner API shuts down, a certificate authority sunsets, maintaining an old protocol becomes a security risk. The removal isn’t the trust failure — the silence is. If firmware removes or degrades anything: announce it ahead of the release with dates, explain the why in one honest sentence, ship it in a dedicated entry (never bundled into “bug fixes”), and leave the entry standing in the history. An unbroken, honest changelog — visible before purchase — is itself a buying signal in a category where “will this still work in three years?” is a real question shoppers ask.

A firmware entry template

## 2.4.1 — 2026-07-12

Devices: Hub v2 (hardware rev B and later) · Update size: ~12 MB
Device restarts during update (~90 seconds; sensors offline briefly).
Rollback: not supported for this release.

Updating from 2.1 or earlier? You also get Matter support and the
new scheduling engine — see the full changelog: <url>

### Fixed
- Device dropped off Wi-Fi after ~24 hours idle (affected mesh networks)
- Schedules ran an hour late in half-hour-offset time zones

### Changed
- Motion sensitivity default: Medium → Low on rev C hardware
  (existing custom settings are kept)

### For integrations
- Local API: /v1/status now includes "battery_pct"; nothing removed
- Requires companion app 4.2+ for the new schedule editor

### Known issues
- Zigbee re-pairing may be required on hubs with 50+ paired devices

Every line answers a decision question: which hardware, how long offline, can I go back, what breaks, what’s known-broken. A reader with one thermostat and a reader with four hundred can both act on it.

Where the notes live

The device usually has no screen, so the notes live everywhere else — which without a plan means nowhere:

  • The companion app’s update prompt is the most-read surface, and it shows the latest version only. Treat it like the app-store “What’s New” box: first line carries the decision, link to the full history.
  • A canonical hosted page with per-version permalinks is the anchor everything else points at: support replies, community-forum threads, resellers’ update advisories, the app prompt. Firmware discussions live for years in forums — permalinks mean the right information gets cited instead of screenshots and rumor.
  • Feeds for the fleet. Operators who manage many devices script their awareness: an RSS or JSON feed of firmware entries plugs into their monitoring — the machine-readable changelog guide covers the formats. Publishing a feed is the difference between operators discovering updates and being ambushed by them.
  • Beta rings get their own stream. Early-access firmware channels follow the beta release notes rules: publish the stability contract first, keep beta churn out of the stable feed.

Staged rollouts — standard for OTA, since a bad update can brick a fleet — follow the same dating rule as everywhere else: the entry is dated and published at first availability, with a note (“rolling out over two weeks”) so the reader whose device hasn’t offered the update yet knows nothing is wrong.

Anti-patterns

  • “Stability and performance improvements” as the entire history. For an object someone let into their home, a changelog of nothing is a statement: we don’t owe you an explanation. Refusing the next update is a rational response.
  • Silent feature removal. The single fastest way to convert customers into people who warn others away from your brand. Dedicated entry, advance notice, honest reason — every time.
  • One changelog for five hardware revisions with no map. “Does this apply to my device?” is the first question; if the entry doesn’t name revisions, every reader guesses. Name them per entry, or keep separate streams per product line.
  • Notes that exist only inside the mobile app. Unlinkable, unsearchable, invisible to the operator with a laptop and forty units. The app prompt is a teaser; the canonical page is the record.
  • Version soup across regions and SKUs. When the same behavior ships as 2.4.1 in one region and 2.4.3 in another, support threads become archaeology. If builds must differ, the changelog is exactly where the mapping belongs.
  • The forced update announced afterward. If a critical fix must auto-install, the notes ship with it, not in the apology later. Mandatory plus undocumented is the combination that ends up in the news.

Where Wakelog fits

Wakelog gives firmware teams the canonical layer: a hosted changelog page with per-version permalinks your support team and forum mods can cite, tags to make security and breaking entries loud, RSS and JSON feeds fleet operators can point their monitoring at, and drafts plus scheduled publishing so the entry goes live at rollout start — written back when the build was signed. Posting is one curl from the same CI job that signs the image, so the notes can’t drift from the binary. Honest caveat: Wakelog doesn’t host firmware images or run your OTA infrastructure — it’s the announcement layer that sits beside it, and your history stays exportable as a portable changelog.md.

Give your firmware notes a permanent home   Next: security advisories vs changelog →

Related guides

  • Desktop app release notes: writing for the update dialog
    The update prompt is the most-read changelog surface you’ll ever own: your notes and a Restart button in the same window. How to write release notes that earn the restart — for Sparkle, Electron, and everything that ships an installer.
  • Driver release notes: writing updates for hardware someone already owns
    A driver update sits between someone’s computer and hardware they already paid for — and unlike firmware, the reader chooses when to install and can roll back. That choice is the whole job: driver notes exist so the game-day upgrader, the crash troubleshooter, the don’t-touch-my-studio professional, and the fleet admin can each decide correctly. What to write so they can.
  • Network upgrade notes: announcing protocol changes you can’t deploy for anyone
    Most release notes describe software somebody can deploy. A protocol upgrade only happens if enough independent operators adopt it before an activation moment — and whoever misses it falls off the network. How to write upgrade notes that coordinate strangers: heights and dates together, a version table per client, consequences stated as physics, and a campaign instead of a single post.

Last updated 2026-07-28 · All guides