What is Key frame in OPC UA?

Glossary · PubSub

Key frame

In OPC UA PubSub, a key frame is a DataSetMessage carrying every field of the PublishedDataSet rather than only the changed ones. It is what lets a subscriber build or resynchronise complete state, and the DataSetWriter's KeyFrameCount decides how many messages pass between one key frame and the next.

Why a late subscriber sees nothing

PubSub has no request and no retained state. A subscriber that starts mid-stream, or comes back after a restart or a burst of packet loss, receives delta frames it cannot resolve because it holds no baseline. It shows nothing, or a partial dataset, until the next key frame arrives. With KeyFrameCount set to 10 on a one-second WriterGroup that is up to ten seconds of blank screen after every reconnect, which reads as a broken subscriber rather than as configuration.

KeyFrameCount 1 is the safe default

Setting KeyFrameCount to 1 makes every message a full snapshot. Frames become constant size, subscribers become stateless, packet loss costs you exactly one cycle instead of an unbounded stretch, and a new consumer is correct on its first message. That is why deterministic Ethernet and TSN deployments almost always run key frames only. Raise the count only when you have measured the bandwidth problem you are solving.

Key frames are not metadata

A key frame carries all the values; a DataSetMetaData message carries the schema those values are indexed against. A subscriber needs both, and they arrive on different schedules - on MQTT usually on different topics with their own update rate. A subscriber that has values but no metadata decodes nothing; a subscriber that has metadata but has not yet seen a key frame decodes nothing either. The symptom is identical, the fix is not.

Example

KeyFrameCount 4 - what a subscriber that joins at message 6 actually gets

msg 1  KEY    Force=812.4  Position=41.0  CycleCount=90211
msg 2  DELTA  Force=813.1
msg 3  DELTA  Force=812.9
msg 4  DELTA  Force=811.7  CycleCount=90212
msg 5  KEY    Force=810.2  Position=41.0  CycleCount=90212
msg 6  DELTA  Force=809.8            <- subscriber starts here: one field, no baseline
msg 7  DELTA  Force=808.1            <- still nothing usable
msg 8  DELTA  Force=806.6
msg 9  KEY    Force=805.0  Position=40.8  CycleCount=90213   <- first complete picture

The mistake people make: Expecting PubSub to behave like an MQTT retained message or a Sparkplug birth certificate. There is no last-known-value store in UADP over UDP, so a dashboard or historian fed from PubSub must either run KeyFrameCount 1 or explicitly tolerate an empty dataset for up to KeyFrameCount publishing intervals after every restart.

Defined in: Part 14 - PubSub, DataSetMessage types.

Related concepts

Delta frame DataSetWriter DataSetReader UADP Sparkplug B PublishedDataSet

Status codes you will meet

BadDecodingError BadWaitingForInitialData

Last verified 7 September 2026 against OPC UA 1.05.07. OPC UA Connect is an educational resource and is not affiliated with the OPC Foundation.