Practice: Gateway Protocol Translation

Start With the Story

This section: Start With the Story — The lab is a rehearsal for a real incident review: a source device sends a value, the gateway translates it, the target route reacts, and someone later asks whether the result can be trusted.

The lab is a rehearsal for a real incident review: a source device sends a value, the gateway translates it, the target route reacts, and someone later asks whether the result can be trusted. Build the first path slowly. Map one source sample, preserve its unit and source time, choose the route, then force a timeout so the bad-quality record is as visible as the successful telemetry.

Learning Objectives

This section: Learning Objectives

By the end of this lab, you should be able to:

• Build a source-to-target mapping record for a gateway translation path.
• Normalize source samples while preserving unit, timestamp, quality, and identity.
• Choose target routes and delivery expectations for telemetry, state, and command paths.
• Define queue behavior for ordinary messages, critical messages, stale messages, and malformed messages.
• Produce lab evidence for success, timeout, duplicate, replay, and target-unavailable scenarios.

Lab Scenario

This section: Lab Scenario — You are reviewing a gateway that bridges local equipment readings into a target event route.

You are reviewing a gateway that bridges local equipment readings into a target event route. The exact protocols can vary, but the lab uses a consistent evidence pattern:

The next choice in the “source sample”–“point map” decision depends on “Normalized msg”, a boundary shown in Figure 1. Inspect “Source sample”, then set it against “Point map”, before judging One spine — source sample, point map, normalized message, queue policy, target route, evidence record — carries a good reading, a state change, and a timeout to three different evidence records.

+

In Figure 1, notice how “Source sample” establishes the initial state; “Point map” supplies the next check. The move through “Normalized msg” reaches “Queue policy”, making One spine — source sample, point map, normalized message, queue policy, target route, evidence record — carries a good reading, a state change, and a timeout to three different evidence records observable. Return to the “source sample”–“point map” decision with “Queue policy”, and keep “Source sample” in the release record.

Your gateway receives three source samples:

Lab Workbench

This section: Lab Workbench — The lab workbench is a set of records, not a single tool.

The lab workbench is a set of records, not a single tool. You can complete it with a spreadsheet, notes, a local script, or a gateway configuration review.

Inspect Figure 2 with one question from the “source samples”–“unit=7 register=40017 raw=214” decision: how does “Source Samples” constrain “unit=7 register=40017 raw=214”? The answer supports Gateway translation lab workbench showing source samples, point map, normalized payload, target route, queue observation, and failure drill.

+

Notice how Figure 2 separates “Source Samples” from “unit=7 register=40017 raw=214”. Now move to “source time/result/quality” and finish at “timeout sample preserved”; that second step reveals why Gateway translation lab workbench showing source samples, point map, normalized payload, target route, queue observation, and failure drill. Apply the distinction when “timeout sample preserved” closes the record for the “source samples”–“unit=7 register=40017 raw=214” decision.

Prepare these artifacts:

1. Source sample sheet: raw address, raw value, source timestamp, quality indicator, and read result.
2. Point map: point name, unit, scale, target route, expected update rule, and owner.
3. Normalization rule: how raw fields become typed internal fields.
4. Queue rule: priority, maximum age, retry behavior, and dead-letter condition.
5. Verification record: ordinary sample, failure sample, expected output, actual output, and reviewer decision.

{
  "source": "line-2-meter-7",
  "address": "unit=7/register=40017",
  "raw_value": 214,
  "source_time": "observed-at-source",
  "quality": "good",
  "read_result": "ok"
}

Step 1: Build the Point Map

This section: Step 1: Build the Point Map — Start with the source samples and define the mapping.

Start with the source samples and define the mapping. Do not begin with the target dashboard or route name. The source meaning comes first.

• In the source sample sheet, select unit=7/register=40017 and read its raw value and quality before naming a route.
• In the point-map row, enter the point name, C unit, 0.1 scale, and the timeout quality rule.
• Check that register 40018 maps to state and 40019 to a missing-observation path, rather than reusing the temperature rule.
• A local Python calculation of the sample 214 * 0.1 returned 21.4 C; retain the raw value beside the mapped value.
• Mark the map version and owner so the subsequent message can identify the rule that produced it.

Example mapping row:

source: unit=7/register=40017
point: return_air_temperature_c
scale: raw_value * 0.1
target_route: site-a/mechanical/boiler-1/return-air-temperature
quality_rule: publish bad_quality event when read_result is timeout

Step 2: Normalize the Payload

This section: Step 2: Normalize the Payload — The normalized message is the gateway’s internal contract.

The normalized message is the gateway’s internal contract. It should be stable even if the source protocol or target route changes later.

• In the normalized-message record, copy the point identity, 21.4 C, source time, gateway time, quality, and mapping version into separate fields.
• Compare it with the source sheet; the source time must survive the translation instead of being replaced by gateway receipt time.
• For register 40019, write a bad-quality or missing-observation event with no fresh numeric value.
• The local Python check returned gateway timeout= bad_quality; no fresh value; this is a rule check, not a live gateway trace.
• Review the message against the mistakes below before using the animation’s Semantic translation view.

{
  "point": "return_air_temperature_c",
  "value": 21.4,
  "unit": "C",
  "source_time": "observed-at-source",
  "gateway_time": "received-at-gateway",
  "quality": "good",
  "source": "line-2-meter-7",
  "mapping_version": "bridge-map-01"
}

Check for these mistakes:

• The target only contains a raw register number.
• The target timestamp hides when the source was actually observed.
• Quality is dropped because the value looks valid.
• The mapping version is missing, so a future schema change cannot be traced.

Run it: Step the m2m-gateway animation below to see what a normalized message must preserve. Move through Decode the source, Preserve meaning, Rebuild delivery, and Check the boundary, and set the translation to Semantic so units and identity are preserved rather than Enriched, which adds gateway metadata. Watch the stage where the source unit, identity, and source time survive into the internal message — exactly the fields the normalized contract above must keep and the ones the mistake list warns are silently dropped.

Step 3: Choose the Target Route

This section: Step 3: Choose the Target Route — Target routes are a contract.

Target routes are a contract. A route should be stable, authorized, and specific enough for consumers to subscribe without broad catch-all filters.

• In the route ledger, assign the temperature point to the site/system/asset/point telemetry hierarchy.
• Keep the equipment-state transition on its state route; the previous state and event id help review duplicate decisions.
• Put a command request on a separate authorized route with requester identity, timeout, and audit id before any write is allowed.
• Review the target subscription scope and record the exact accepted route, rather than a broad wildcard alone.
• This is a route-design record here; verify delivery and authorization on your own gateway before claiming an operational bridge.

Step 4: Queue and Failure Drills

This section: Step 4: Queue and Failure Drills — Translation is not complete until failure behavior is visible.

Translation is not complete until failure behavior is visible.

• In the simulator’s Scenario control, run an ordinary sample first and retain its Adapt, Normalize, Route, and Buffer observations.
• For the target-unavailable case, inspect the Buffer stage and record queue depth before and after recovery.
• A local Python queue check produced queue depth= 1 while unavailable and queue depth= 0 after recovery; these are model results, not the browser simulator’s counters.
• The same local check accepted one target record from two copies of event m7; use the simulator to test its own duplicate behavior.
• If using a physical gateway, repeat the drills on your own hardware and retain source and target logs with timestamps.

Before deciding the “gateway under review”–“map, queue, publish, observe” decision, inspect “Gateway Under Review” in Figure 3 and compare it with “Map, queue, publish, observe”. That contrast matters because Gateway lab failure drills showing source timeout, malformed payload, duplicate message, target unavailable, replay, and operator evidence.

+

In Figure 3, notice how “Gateway Under Review” establishes the initial state; “Map, queue, publish, observe” supplies the next check. The move through “Source Timeout” reaches “No fresh reading”, making Gateway lab failure drills showing source timeout, malformed payload, duplicate message, target unavailable, replay, and operator evidence observable. Return to the “gateway under review”–“map, queue, publish, observe” decision with “No fresh reading”, and keep “Gateway Under Review” in the release record.

Run these drills:

1. Source timeout: confirm the gateway emits a missing or bad-quality state rather than a fresh-looking stale value.
2. Malformed source value: confirm the sample moves to an error path with raw context and rule id.
3. Duplicate event: confirm the gateway accepts, rejects, or idempotently updates according to the contract.
4. Target unavailable: confirm queue depth, oldest age, retry count, and drop or dead-letter behavior are visible.
5. Replay after recovery: confirm source timestamps are preserved and downstream side effects remain safe.

Run it: Run these failure drills against the multi-protocol gateway simulator below. Pick a Scenario and push traffic through the Adapt, Normalize, Route, and Buffer stages, then stress the path so the Buffer stage has to hold messages when the target is slow — the Target-unavailable drill made visible as queue growth. Watch how the simulator routes and protects mixed MQTT, AMQP, HTTP, and CoAP traffic under load, so you can record the queue depth, retry, and drop behavior each drill above asks you to prove.

Lab Review Record

This section: Lab Review Record — Your final deliverable is the review record.

Your final deliverable is the review record. It should fit on one page and link every decision to evidence.

Use Figure 4 with “Source” to inspect the next step in the “source”–“raw evidence” decision. The relationship between “Source” and “Raw evidence” is what makes Gateway protocol translation lab record showing source evidence, mapping evidence, delivery evidence, failure evidence, and release decision reviewable.

+

In Figure 4, notice how “Source” establishes the initial state; “Raw evidence” supplies the next check. The move through “Mapping” reaches “Rule evidence”, making Gateway protocol translation lab record showing source evidence, mapping evidence, delivery evidence, failure evidence, and release decision observable. Return to the “source”–“raw evidence” decision with “Rule evidence”, and keep “Source” in the release record.

Release Checklist

This section: Release Checklist

Before the lab is accepted, verify:

• Every source sample has a mapping row or an error path.
• Every normalized payload contains point, value, unit, source time, gateway time, quality, source identity, and mapping version.
• Every target route has an owner and an authorization boundary.
• Queue limits, retry limits, stale-message handling, and dead-letter behavior are written down.
• At least one ordinary sample and four failure samples were reviewed.
• The reviewer can reproduce the evidence without relying on memory or screenshots alone.

Knowledge Check: Release Evidence

This section: Knowledge Check: Release Evidence

Summary

This section: Summary — This lab turns protocol translation into a reproducible review.

This lab turns protocol translation into a reproducible review. The work starts with source samples, not tool configuration. A complete lab record shows the point map, normalized payload, target route, queue behavior, failure drills, and release decision. That evidence is what proves the gateway preserves meaning, timing, quality, and delivery intent.

Related Chapters

This section: Related Chapters

Key Takeaway

This section: Key Takeaway — A gateway lab should prove ingress, transformation, egress, and failure handling.

A gateway lab should prove ingress, transformation, egress, and failure handling. Capture payloads, logs, errors, and timing so the bridge can be reviewed as a system boundary.