Start with the connected display
An image update begins with device metadata, not a guessed screen size. The current app integration guide requires the app to read the display part, width, height, color count, pixel-format ID, and required image byte length before encoding.
Use the app and phone supported by your exact product, and follow its power and positioning instructions throughout the update.
Compose one complete canvas
Fit the artwork to the metadata dimensions. Decide on cropping and orientation deliberately so the app does not stretch a label or cut off important text. Compose text and graphics together, then convert the whole image to the supported palette.
Text is rasterized by the app. The production firmware does not provide a separate Display Text rendering service. The reference text document includes a small bitmap test font, but a different font can be rasterized into the same canvas. Check every required character before sending the image.
Review the converted result at its native dimensions. Look for clipped letters, lost strokes, ambiguous digits, and colors that collapsed into the same output value. Meaningful color should have a text or shape cue too.
Encode the selected format
The display-format document defines three formats. The app must choose the one returned by metadata, not infer it from a folder name.
| Format | Display palette | Image encoding |
|---|---|---|
| 0 | BW | Row-major, most-significant-bit first; 0 is black, 1 is white |
| 1 | BWYR | Four pixels per byte; 00 black, 01 white, 10 yellow, 11 red |
| 2 | BWR | Complete active-low black plane, then complete active-low red plane |
For format 0, each row occupies ceil(width / 8) bytes. Unused low bits at the end of a row must be white. The 122 × 250 profile therefore requires 4,000 bytes, including row padding. Multiplying the visible pixel count and dividing by eight is not sufficient for that canvas.
For format 2, a white pixel leaves both plane bits at 1. Black clears only the black-plane bit; red clears only the red-plane bit. The combination with both bits cleared is reserved. The 152 × 296 profile uses 5,624 bytes per plane and 11,248 bytes for the complete image.
Calculate the full-image CRC32 over the final encoded bytes sent in the image chunks, not the original photo, text, or logical canvas. Check the result’s byte length against metadata.
Distinguish preparation, transfer, and completion
The app sends Image Begin and consumes its response, then waits for the matching ready event before sending chunk zero. The initial acknowledgement alone does not mean the display is ready for image data.
During transfer, chunks are sent in order. The app waits for the current RF mailbox message to be consumed before writing another; accepted chunks do not produce individual app responses. After the chunks, Image Status must confirm the loaded image and its expected byte and sequence counts.
Image Commit is a separate step. After consuming the accepted commit response, the app waits through preparation and physical refresh for the automatic completion event. A successful upload is not yet a completed display update. The documented successful terminal result is OK + complete; elapsed time alone is not evidence of success.
If the device reports reupload_required, the app restarts the complete image with a new transfer ID. It must not guess a sequence from which to resume. The integration guide also distinguishes retryable refresh-start failures and cleanup faults; applications must interpret both status and image state rather than blindly repeating a physical refresh.
Keep the scope clear
The guide requires the RF field to remain active during the relevant update stages and defines bounded waits and recovery behavior. This is an integration contract, not a refresh-speed or universal NFC-compatibility claim. Follow the device and app’s verified instructions for a real update.
If you are still choosing a canvas, start with screen size and display palette.
Source notes
Based on docs/mobile-app/DISPLAY_FORMATS.md, APP_INTEGRATION.md, and TEXT_RENDERING.md, read together on 30 September 2026. See our source policy. Format numbers and byte counts describe the current firmware profiles.