Safe NFC image transfers
Keep the phone in place from identification through the final result. The app must use the sequence below for both text and image updates. These are app behaviors to expect, not commands to enter manually.
Identify and prepare
Read Metadata and confirm display part, width, height, color count, pixel format, and required image length. Prepare the complete canvas in that format. The app must give each new image transfer a new nonzero transfer identity and validate the encoded image's integrity.
Do not force a guessed geometry or palette. Never reuse one transfer identity for different image content.
Wait for readiness
The app begins the upload and consumes the initial OK + receiving response. It must then wait for and consume the separate ready event matching that Begin exchange before sending the first image chunk.
The documented app readiness window is bounded at 20 seconds. This is a preparation/recovery limit, not a promised total update time. If the Begin exchange or readiness wait expires, the app must handle any stale response, check Image Status, and begin a complete new transfer when re-upload is required. It must never send image data based only on the initial receiving response.
Send and verify the entire image
The app sends image chunks in order, waiting until each mailbox message has been consumed before writing the next. It must never overwrite an occupied mailbox.
Accepted chunks and exact duplicates do not produce individual app responses. A lack of per-chunk responses is expected; polling between chunks is not the correct progress check.
After the final chunk, the app checks Image Status for loaded, the exact required byte count, and the complete chunk count. Only then should it commit the same image for refresh.
Wait quietly through refresh
The app consumes OK + refresh_pending from Commit. The device then waits through a five-second preparation interval before physical refresh. Keep the NFC field active and send no commands during that interval or refresh.
Wait for the automatic completion event matching the Commit exchange. If event delivery is lost, the app may recover with Image Status after the expected refresh window, using a bounded timeout. Do not repeatedly poll while the display is refreshing. No universal end-to-end update duration is confirmed here.
Interpret the outcome
| Status and state | Meaning and action |
|---|---|
| OK + complete | The update succeeded. Do not request another physical refresh for the same successful transfer. |
| DISPLAY_CLEANUP_FAILED + complete | The visible refresh succeeded, but cleanup failed. Report the fault; do not retry the refresh. |
| REFRESH_START_FAILED + refresh_retryable | The app may retry the matching Commit while the loaded image remains valid. This is not a new image upload. |
| Any result with reupload_required | Start a complete new upload with a new transfer identity and every chunk from the beginning. Do not resume from a remembered percentage or sequence. |
| BUSY + refreshing | Wait for completion; do not start another transfer. |
For a retryable refresh-start failure, the documented retained-image window is 30 seconds, with at most three physical refresh attempts for one loaded image. The app must respect those limits. If the window or attempts are exhausted, a complete re-upload is required.
Power loss or a reset invalidates the loaded image even if the screen still shows content. Missing, corrupt, or out-of-order data also requires a complete re-upload when reported by the device.
Use troubleshooting for the next step when an update fails. Production apps must not use Display Fill, and text must be composed into the image rather than sent through Display Text.