How to Design MQTT Topics for an Oilfield Fleet

Back to Blog

Order Levels From Broad to Specific

A topic is a path, and the value of MQTT wildcards depends entirely on that path going broad to specific. Put the widest grouping first and narrow at each level: enterprise, then region or field, then the site, then the device or asset, then the specific measurement. With that order, a single-level wildcard cleanly selects every device in a site, or the plus wildcard selects one measurement across every site in a field.

Get the order wrong - measurement before site, say - and no wildcard gives you a useful slice, because the thing you want to select by is buried mid-path. The wildcard rules that make this pay off are covered in the MQTT topic hierarchy and wildcards; design the tree so those rules work in your favor.

Give Each Level One Real Dimension

Each level should represent exactly one dimension of the fleet, not two smashed together. A level like well-pad-north-pumpjack-3 combines location and asset and defeats wildcarding on either. Split them: a site level and a device level. One dimension per level keeps every wildcard slice meaningful and keeps the tree readable when someone new opens it a year later.

Use stable identifiers, not descriptions that change. A site's legal name or a lease number is stable; a nickname is not. If a value in the path can be renamed by an operator, it will be, and every retained message and subscription tied to the old string becomes an orphan. Stable identifiers also make a fleet-wide tag naming discipline portable - see the SCADA tag naming convention.

Design the Tree for Access Control

Broker access control is granted per topic branch, so the tree is also your security boundary. If each field or operating region is its own second-level branch, you can grant a contractor or a regional team publish and subscribe rights to just their branch with one rule. A flat tree forces per-device rules that no one maintains, and the fleet ends up over-permissioned.

Decide the security boundaries before the tree is final, because they may add a level. If you need to isolate a joint-venture partner's sites, a partner or tenant level near the top makes that a single clean grant. Retrofitting an isolation level after devices publish means re-provisioning every device on the wrong side of the boundary.

Reserve Branches for State and Commands

Keep telemetry, device state, and commands in clearly separate branches rather than mixing them under the same device node. A common pattern gives each device a data branch for measurements, a state branch for birth and death and status, and a command branch for writes. Separation lets you subscribe a dashboard to data only, an availability monitor to state only, and gate the command branch behind tighter access control.

Reserve a place for last-will and status now, because a device offline-detection scheme depends on a predictable status topic per device. If a device announces itself and its departure on a known status topic, the fleet's availability view is a single wildcard subscription. Plan that alongside the MQTT last will and testament.

Verify the Design Before Deployment

Before any device publishes, write down the exact wildcard subscriptions your applications will use and confirm each one selects precisely the topics intended against your planned tree. If a real subscription you need cannot be expressed as a clean wildcard, the tree is wrong and this is the cheap moment to fix it. Test the access rules the same way: one grant per intended role.

Then pilot with a handful of sites publishing real topics and confirm the dashboards, the availability monitor, and the access rules all behave before you roll to the whole fleet. A topic tree proven on ten sites scales to hundreds; one never tested against real subscriptions fails at scale when it is most expensive to change.

Common Mistakes

The costliest mistake is a flat or specific-first tree that no wildcard can slice usefully, discovered only after hundreds of devices publish to it. The second is combining two dimensions in one level, which quietly breaks wildcarding on both.

Another is embedding renameable descriptions in the path, guaranteeing orphaned topics the first time an operator relabels a site. And do not mix commands into the telemetry branch - it forces you to over-grant access and makes a dashboard subscription accidentally see command traffic. Separate the branches from the start.

Frequently Asked Questions