Your TRMNL keeps its own firmware up to date over WiFi, so most of the time you never have to think about it. This guide covers when an update installs, how to check which version you're on, how to turn updates off, and what to do on the rare occasion an update gets stuck.
How over-the-air updates work
Each time your device wakes to fetch a new screen it checks in with us, and if a newer firmware release exists for your model, our reply tells the device to update. You'll see "Firmware update available! Starting now..." while the device downloads and installs the new firmware, followed by "Firmware update success. Device will restart..." once it's done.
An update installs at the first check-in after we release it, which means the timing depends on your refresh rate. A device on a long refresh rate or in sleep mode won't hear about it until it next wakes up.
There are a few situations where we hold the update back:
The battery is low. Below 10% and not charging, the device skips the update. Charge it and the update follows at the next check-in.
OTA updates are off for the device, which we cover below.
We paused the release. Your device stays on its current version until we resume it or ship a new one.
Check your firmware version
Open your device's settings page and look under Device Info, where Current firmware shows the version your device reported at its last check-in.
To compare against the latest release, head over to the firmware releases on GitHub, or open the Flash Assistant, which lists the versions it can install for your model with the newest at the top.
Turn automatic updates on or off
On your device's settings page, open Firmware, where the row reads either "Updates enabled" or "Updates disabled". Inside you'll find the OTA Updates Enabled toggle, which controls automatic updates and is on by default, so remember to click Save after you change it.
We recommend turning it off only when you want to stay on a specific version, for example one you flashed yourself. While it's off the device keeps whatever firmware it has, and once you turn it back on the device moves to the latest stable release at its next check-in.
One exception worth knowing: TRMNL hardware on firmware older than 1.5.2 still updates with the toggle off.
Firmware Early Release
If you have Developer Edition, the Firmware page adds a Firmware Early Release toggle, which gets you new firmware before other users. When there's no early release available, your device gets the stable release instead. The same page shows your current version next to the latest Stable and Staging versions, so you can see exactly where you stand.
If our support team sets your device to a specific build for troubleshooting, the page shows Pinned firmware, and your device stays on that build until support removes the pin.
When an update stalls
If the download or install fails, the device shows an error and keeps its current firmware. Recent firmware then waits 24 hours before trying again, so your TRMNL doesn't get stuck in a loop of restarting over and over.
If your device is still on the old version two days after we first offered the update, we stop offering it, and your device settings show "Firmware update stalled after repeated failed attempts." along with a Retry update button.
Click Retry update and we'll offer the update again at your device's next check-in, although if the last attempt failed less than 24 hours ago, the device waits out the rest of that day first. If you'd rather do nothing, that works too, since we offer the update again on our own about a week after the first attempt.
For the scripting crowd, the TRMNL API has the same retry, listed as "Retry a stalled firmware update".
BYOD and DIY devices
Over-the-air updates are not supported for BYOD devices, so most of them have no Firmware section in their settings at all. Boards with the same 7.5" black and white panel as TRMNL OG do show the section for its display options, but the OTA toggle is locked.
To update a BYOD device, flash a compatible version from the Flash Assistant.
When to flash manually
Most people never need to, but flashing by hand makes sense when:
You run a BYOD device.
An update stalls and Retry update doesn't help.
You want a specific older version, for example to roll back after a problem.
The device doesn't start and can't check in at all.
Follow Manually flash firmware, and if you want to stay on the version you flash, turn off OTA Updates Enabled first, otherwise we'll replace it at the next check-in. You'll need a USB-C cable that carries data (not one that only charges), and Chrome or Edge on a Mac or Windows PC works best.
Troubleshooting
"Firmware update failed. Device will restart..." The download or install didn't finish, so move the device closer to your router and leave it on, and it will try again after 24 hours.
"WiFi connected, could not get firmware update from api." The device reached your WiFi but couldn't download the firmware. If you use a firewall or a DNS filter, check DNS and Network Requests for Firewall Whitelists.
"WiFi connected but signal is weak" The device couldn't hold a connection long enough to download the update, so move it closer to your router.
Current firmware hasn't changed. The version updates when the device next checks in, so give it a cycle, then confirm the battery is above 10% or charging and that OTA Updates Enabled is on.
The device stopped responding during an update. Start with Troubleshooting an Unresponsive Device, and if it still won't start, put it in flashing mode and flash it by hand.
Have a TRMNL X? Our troubleshooter walks you through the most common problems in a couple of minutes.
Related