# Module 16: Capstone: Real Device Integration

> Bring a real or simulated device online with a reviewable evidence package.

**Phase:** Capstone  
**Estimated time:** 8 min  
**Release status:** Published  
**Content version:** 1.0.0  
**Source:** https://learnmodbus.studioseventeen.io/lesson/capstone-real-device-integration

## What you'll be able to do
- Plan an integration from spec to first reliable poll.
- Build an evidence package another engineer can review.
- Hand off a register map with units, scales, and verification notes.

## Three things people get wrong
1. **Skipping the pre-flight read.** Before any write, do a complete read sweep and snapshot the device's pre-state.
2. **Treating 'works in the lab' as done.** Field cabling, baud limits, and gateway behavior re-test in production — budget for it.
3. **Not versioning the register map.** Treat the map as code. Pin a version with the firmware revision it was verified against.

## From the field
**The handover that survived a rebadge**

An integrator left a tidy package: register map, capture file, scaling notes, and a one-page test script. Two years later the device was rebadged by a competitor. The same package, with two register addresses changed, brought the new unit online in an afternoon. Documentation is the deliverable.

## References
- [Modbus Application Protocol V1.1b3](https://www.modbus.org/file/secure/modbusprotocolspecification.pdf)
- [Synthetic device spec — Stratos VFD 7.2](https://learnmodbus.studioseventeen.io/devices/stratos-vfd-72)

## Lesson

# Module 16 Lesson: Capstone Real Device Integration
## Learner Outcome

By the end of this module, learners can turn a synthetic or reviewed register map into a documented Modbus integration package with correct requests, decoded values, polling plan, troubleshooting evidence, safety notes, and a reusable normalized handoff structure.

## Key Concepts

- A register map is not an integration until its assumptions are tested.
- Every point needs both the source-facing reference and the protocol request actually sent.
- Address base, table, function code, Unit Identifier or serial server address, quantity, type, word order, scale, unit, access, and validity conditions must be explicit.
- Start with read-only evidence; write-capable points are boundaries unless the lab is simulated or formally approved.
- Normalization turns vendor-specific raw points into consistent tags, values, quality, and context.
- The final package should be repeatable by another learner or integrator without hidden assumptions.

## Key Terms

- Source intake: the recorded source map, manual, fixture, or evidence used to start the integration.
- Normalized tag: a stable internal name for a decoded point.
- Evidence package: the set of source rows, requests, responses, decoded values, assumptions, and review notes that prove the integration work.
- Reviewed vendor map: a named vendor source with revision, firmware/applicability, and license/source notes checked.
- Commissioning handoff: the final package another reviewer can use to understand what was proven and what remains unresolved.
- Modmapper-ready: structured enough for later import/export review after tool behavior is verified.

## Source-Grounded Explanation

### The Capstone Is Evidence Work

The capstone combines the course skills into one workflow:

1. Identify the exact transport path: RTU, ASCII, TCP, Modbus Security, or gateway.
2. Select a source map: the synthetic course map by default, or a reviewed vendor map after source/license review.
3. Convert documented references into function code, table, PDU address, and quantity.
4. Poll read-only points first.
5. Decode raw values into engineering meaning with type, signedness, word order, scale, unit, state, and freshness.
6. Classify and resolve or explicitly defer at least two troubleshooting cases.
7. Review safety and security boundaries before any write-capable point is tested.
8. Package a normalized, reusable integration artifact.

The grading target is not "the dashboard looks nice." The target is a defensible integration package: someone else can read it, repeat the tests, and understand what is proven, what is assumed, and what remains unresolved.

### Required Evidence Per Point

Each selected point should include:

| Field | Purpose |
|---|---|
| Source label | Synthetic course map, reviewed vendor manual, official rule, tool behavior, field note, or needs verification. |
| Raw/vendor label | Preserves the original wording from the source map. |
| Normalized tag | Creates a stable internal name such as `meter.voltage.l1_l2`. |
| Transport and responder | TCP Unit Identifier, serial server address, or gateway route. |
| Function code and table | Separates coil/discrete/input/holding register assumptions. |
| Documented address | What the source says. |
| PDU address | What the request sends. |
| Quantity | Number of coils/registers requested. |
| Data meaning | Type, signedness, word order, scale, unit, enum, bitfield, sentinel, state, quality. |
| Expected response | Normal response shape and likely exception/failure mode. |
| Evidence | Saved bytes, simulator output, tool log, source note, screenshot, or reviewer note. |

### Track A: Synthetic No-Hardware Capstone

This is the default track until a simulator/toolchain is pinned and real vendor maps are reviewed. It uses `release/synthetic-course-device-map.md` and course-authored saved response examples. The learner must label synthetic behavior clearly and must not present it as a real device.

Required minimum:

- At least six normalized points.
- At least one value from each category: bitfield/status, 16-bit scaled value, 32-bit value, enum/state, quality/sentinel/freshness, and write boundary.
- Two troubleshooting cases from Module 14, such as off-by-one wrong value plus reserved-gap exception or unresolved source row.
- One safety/security note from Module 15.
- One commissioning-report excerpt.

### Track B: Reviewed Vendor-Map Extension

Use this only after source and license review. The learner must record:

- Vendor, model, document title, revision, firmware/applicability.
- Source/license notes.
- Configuration assumptions.
- Any vendor-specific behavior, such as word order, read limits, local/remote mode, cache/freshness, or write workflow.
- Evidence that vendor-specific behavior was not taught as a generic Modbus rule.

### Optional Modmapper-Ready Thinking After Tool Verification

The capstone should separate raw protocol evidence from reusable tags:

```text
Source row -> request fields -> raw response -> decoded value -> normalized tag -> quality/state -> evidence
```

A Modmapper-ready package should preserve enough structure to be imported, reviewed, validated, and reused later after import/export behavior and licensing are verified:

- Stable tag names.
- Source labels.
- Request fields.
- Decode rules.
- Quality and validity rules.
- Evidence and unresolved assumptions.

## Practical Example: Synthetic Energy Meter Package

Scenario: learners use the synthetic course energy meter map.

| Item | Value |
|---|---|
| Transport | Modbus TCP |
| Unit Identifier | `1` for the synthetic simulator track |
| Point | Line voltage L1-L2 |
| Function code | `03` Read Holding Registers |
| Documented register | `40010` |
| Actual PDU address | `0x0009` |
| Quantity | `1` register |
| Data type | unsigned 16-bit |
| Scale/unit | raw `/10 V` |
| Expected normal response | Function `03`, byte count `2`, data `09 C4` |
| Expected decoded value | `250.0 V` |
| Likely failure mode | Off-by-one wrong value if PDU address `0x000A` is used; exception `02` in the synthetic fixture when the server reports an illegal data address |

Evidence row:

| Tag | Evidence |
|---|---|
| `meter.voltage.l1_l2` | Synthetic map row plus response `03 02 09 C4`; PDU address `0x0009`; decode `0x09C4 = 2500`, scale `/10 V = 250.0 V`. |

The learner should also include an "assumption overturned by evidence." Example: the source row `40010` did not mean PDU address `40010`; it meant holding-register table with first PDU address `9` when using one-based `40001` notation.

## Common Pitfalls

- Copying a vendor table without proving address base and function code.
- Treating a dashboard screenshot as enough evidence.
- Hiding word-order guesses.
- Polling across reserved gaps because it is convenient.
- Ignoring quality, sentinel, stale, or state context.
- Including write-capable points without a safety boundary.
- Treating synthetic behavior as product behavior.
- Using a vendor map without document revision, firmware/applicability, or license notes.
- Packaging only final settings and omitting troubleshooting evidence.

## Instructor Flow

1. Show the capstone brief and rubric before learners start.
2. Require a source intake row and normalized map excerpt.
3. Review one point together from documented address to decoded telemetry.
4. Require two troubleshooting cases and one safety/security stop.
5. Grade evidence quality, source labeling, and reusability more heavily than visual polish.

## Check-Your-Understanding

1. What fields must another integrator see to reproduce a Modbus read?
2. Why does the capstone start read-only?
3. What evidence proves an address-base assumption?
4. What evidence proves word order?
5. What makes a normalized tag different from a raw vendor register label?

## Source Notes

- Official protocol basis: Modbus Application Protocol Specification for data model, function codes, PDU fields, normal/exception responses, and quantity limits.
- Official TCP basis: Modbus Messaging on TCP/IP Implementation Guide for MBAP, Unit Identifier, and TCP behavior.
- Official serial basis: Modbus over Serial Line Specification and Implementation Guide if a serial or gateway extension is selected.
- Official citation targets: [official-citation-map.md](https://learnmodbus.studioseventeen.io/resource/official-citation-map) rows for four primary logical data tables, addressing model and zero-based PDU addresses, public function-code categories, normal response vs exception response, exception codes and exception response PDU shape, relevant function quantity rows, MBAP header fields, Unit Identifier and gateway routing, RTU/ASCII frame fields, serial server address range and broadcast address where the selected capstone path uses those transports, and Modbus Security TLS wrapping if the secure track remains listed.
- Internal synthetic basis: `release/synthetic-course-device-map.md` and Module 5-16 draft packages.
- Vendor-specific basis: real-device capstone work requires reviewed vendor map source, document revision, firmware/applicability, and source/license notes.
- Tool behavior: simulator, Node-RED, screenshots, packet captures, Modmapper import/export, and decoder/test harness output require version-pinned verification before learner release.

## Completion Checkpoint

Before completing the course, learners should assemble a synthetic no-hardware evidence package with source intake, normalized rows, request/response evidence, decoded values, troubleshooting cases, safety notes, unresolved assumptions, and a reviewer-ready handoff.

## Reusable Assets

- [Capstone brief and rubric](https://learnmodbus.studioseventeen.io/resource/capstone-brief)
- [Capstone integration lab](https://learnmodbus.studioseventeen.io/lesson/capstone-real-device-integration?page=lab-1)
- [Sample evidence package](https://learnmodbus.studioseventeen.io/resource/sample-evidence-package)
- [Commissioning report template](https://learnmodbus.studioseventeen.io/resource/commissioning-report-template)
- [Normalized register map template](https://learnmodbus.studioseventeen.io/resource/normalized-register-map-template)
- [Module 16 quiz](https://learnmodbus.studioseventeen.io/lesson/capstone-real-device-integration?page=quiz)

## Labs

### Lab 1

# Lab 32: Capstone Integration Package
## Learner Outcome

Learners produce a reusable Modbus integration package from the synthetic course map or a reviewed vendor map, proving address conversion, request fields, data decoding, troubleshooting, safety boundaries, and normalized handoff structure.

## Prerequisites

- Modules 1-4: message model, data tables, function codes, and exceptions.
- Modules 5-8: addressing, register maps, data types, scaling, quality, and telemetry meaning.
- Modules 9-13: serial, RTU/ASCII, TCP, and gateway evidence.
- Module 14: troubleshooting workflow and evidence log.
- Module 15: defensive security and write-safety stop.

## Safety And Scope

Track A is no-hardware and uses synthetic data. Do not connect to production systems, scan networks, or write to real devices. Track B uses a real/vendor map only after source and license review. Optional hardware work is read-only by default and requires instructor approval before any write.

## Track A: Synthetic No-Hardware Capstone

Use:

- [Synthetic course device map](https://learnmodbus.studioseventeen.io/resource/synthetic-course-device-map)
- [Normalized register map template](https://learnmodbus.studioseventeen.io/resource/normalized-register-map-template)
- [Troubleshooting evidence log](https://learnmodbus.studioseventeen.io/resource/troubleshooting-evidence-log)
- [Commissioning report template](https://learnmodbus.studioseventeen.io/resource/commissioning-report-template)
- [Write-safety checklist](https://learnmodbus.studioseventeen.io/resource/write-safety-checklist)
- [Sample evidence package](https://learnmodbus.studioseventeen.io/resource/sample-evidence-package)

## Required Deliverables

| Deliverable | Minimum Standard |
|---|---|
| Source summary | Identifies synthetic map or reviewed vendor map, source label, transport, Unit Identifier/server address, and safety scope. |
| Normalized map | At least six points with documented address, PDU address, function, quantity, type, scale/unit, access, validity, evidence, and assumptions. |
| Request evidence | Saved bytes, simulator output, or tool log for at least four read-only points and one simulated write boundary. |
| Decode notes | Shows raw-to-typed-to-engineering-value conversion for at least one 16-bit and one 32-bit value. |
| Polling plan | Splits reads around reserved gaps and groups by function/table/update need. |
| Troubleshooting log | Includes at least two no-response, exception, wrong-value, unresolved-source, polling-gap, or write-safety cases with evidence and resolution or explicit deferral. |
| Safety/security notes | Identifies write boundary, write-safety stop, monitoring concern, and any unresolved risk. |
| Handoff package | Includes commissioning report excerpt and Modmapper-ready normalized tags. |

## Synthetic Required Points

| Tag | Source Row | Required Evidence |
|---|---|---|
| `meter.status.word` | Device status word `40001` | FC03, PDU `0x0000`, U16 bitfield, response `03 02 00 03`, running plus warning. |
| `meter.voltage.l1_l2` | Line voltage `40010` | FC03, PDU `0x0009`, U16, scale `/10 V`, response `03 02 09 C4`, `250.0 V`. |
| `meter.frequency.ac` | AC frequency `30021` | FC04, PDU `0x0014`, U16, scale `/100 Hz`, response `04 02 17 70`, `60.00 Hz`. |
| `meter.energy.import.wh` | Total energy import `40031` | FC03, PDU `0x001E`, quantity `2`, U32 high-word-first, response `03 04 00 01 86 A0`, `100000 Wh`. |
| `meter.mode.operating` | Operating mode `40093` | FC03, PDU `0x005C`, U16 enum, response `03 02 00 02`, `Remote`. |
| `meter.temperature.sensor` | Lab temperature reading `40094` (Module 8 `lab_temperature_reading`) | FC03, PDU `0x005D`, S16, scale `/10 deg C`, sentinel `0x7FFF`; response `03 02 7F FF` publishes `null` with quality `invalid`. |
| `meter.temperature.undocumented` | Temperature (undocumented) `Offset 60` | Mark table/function/address base unresolved unless additional evidence is supplied. |
| `meter.command.word` | Command word `40101` | Simulated write boundary only; do not send real writes. Record FC06/FC16 response shape and independent-status requirement. |

## Procedure

1. Create a source summary with transport, Unit Identifier, address convention, safety scope, and source label.
2. Normalize at least six points into the template.
3. For each point, record function code, documented address, PDU address, quantity, data type, scale/unit, and expected response.
4. Decode at least one 16-bit scaled value and one 32-bit value from raw response bytes, and apply sentinel/quality handling to at least one value — for example, publish `null` with quality `invalid` when `meter.temperature.sensor` reads the `0x7FFF` sentinel instead of scaling it into a fake temperature.
5. Build a polling plan that avoids the reserved `40050-40059` gap.
6. Classify at least two troubleshooting cases:
   - off-by-one wrong value,
   - exception `02` from a map gap,
   - wrong table/function,
   - unresolved `Offset 60`,
   - or write-safety stop for `command_word`.
7. Complete the commissioning report excerpt.
8. Complete the safety/security notes.
9. Compare the package against the rubric.

## Answer Key / Instructor Notes

Strong packages should:

- Preserve `40010` as the documented reference and `0x0009` as the PDU address.
- Use function `04` for `30021` input register evidence.
- Decode `03 04 00 01 86 A0` as high-word-first U32 `100000 Wh`.
- Mark `Offset 60` unresolved instead of inventing table/function/address base.
- Apply the `0x7FFF` sentinel on `meter.temperature.sensor` before scaling, publishing `null`/invalid rather than a fabricated temperature.
- Avoid contiguous reads across `40050-40059`.
- Treat `40101` as a simulated write boundary and require independent status feedback.
- Include at least one explicit source label per row.
- Include one assumption overturned by evidence.
- Include two troubleshooting entries, with at least one resolved by changing evidence-backed assumptions rather than guessing.

## Expected Observations

- A strong package keeps documented references, PDU addresses, function codes, data types, scale/unit, and source labels visible in the same evidence trail.
- Reserved gaps and unresolved source rows should cause split reads or explicit deferral, not guessed values.
- Troubleshooting entries should distinguish no response, exception response, wrong-but-valid values, and unresolved source evidence.
- Simulated write boundaries should remain simulator-only and should require independent status feedback before any real-device extension.

## Troubleshooting Notes

- If a learner reads across `40050-40059`, split the polling plan and record the reserved-gap evidence.
- If `Offset 60` is normalized without table/function/address-base evidence, mark the row unresolved and request a better source.
- If a wrong value is plausible, test address base, table/function, data type, scale, and word order one at a time with evidence.
- If a command word is included, stop at the safety gate unless authorization, reviewed device source, rollback, and independent feedback evidence exist.

## Optional Track B: Reviewed Vendor Map

Only add a real/vendor map when:

- Source/license review is complete.
- Product, model, firmware/applicability, document title, and revision are recorded.
- Optional hardware is isolated and read-only by default.
- Any vendor-specific word order, read limit, gateway behavior, cache/freshness, write workflow, or safety interlock is labeled product-specific.

## Check Questions

1. Which points are safe read-only evidence points?
2. Which point must remain unresolved until table/function/address base are proven?
3. Which read should be split to avoid reserved gaps?
4. What proves that `meter.energy.import.wh` uses high-word-first word order?
5. What makes the final package reusable by another integrator?

## Source Notes

- Synthetic source: all Track A values are course-authored fixtures from the synthetic course map.
- Official protocol source: Modbus Application Protocol Specification for function codes, addressing, response shape, and exception behavior.
- Internal course source: Module 5-16 packages, capstone brief, normalized map template, commissioning report template, troubleshooting log, and write-safety checklist.
- Release gate: simulator output, Node-RED/dashboard screenshots, Modmapper import/export behavior, and real/vendor map track remain pending.

## Knowledge check

# Module 16 Quiz: Capstone Real Device Integration
## Questions

1. Which capstone evidence is required to reproduce a Modbus read?
   A. Dashboard color and title only.
   B. Function code, documented address, PDU address, quantity, responder, data type, scale/unit, and source evidence.
   C. Vendor logo only.
   D. The final scaled value only.

2. A source map lists line voltage at `40010` using one-based `40001` notation. What PDU address should the capstone try first?
   A. `40010`
   B. `10`
   C. `9`
   D. `0`

3. The synthetic source row says `Offset 60` for temperature but does not prove table, function code, or address base. What should the learner do?
   A. Invent a holding-register address.
   B. Mark the point as unresolved until evidence is available.
   C. Treat it as a coil.
   D. Use it as proof of simulator failure.

4. Why should a capstone avoid reading one large block across `40050-40059` in the synthetic map?
   A. Reserved gaps may make a contiguous read fail even when documented points outside the gap are valid.
   B. Modbus never allows more than one register.
   C. TCP cannot carry register reads.
   D. Scaling requires one request per bit.

5. A write response echoes a command value for `40101`. What must the capstone also include?
   A. Independent status or simulator-state evidence and a write-safety boundary.
   B. A production write test.
   C. A claim that the process changed physically.
   D. No additional evidence.

6. What is the difference between a raw vendor label and a normalized tag?
   A. A raw vendor label preserves source wording; a normalized tag gives the integration a stable internal name and context.
   B. They are always identical.
   C. Normalized tags replace evidence.
   D. Vendor labels prove word order.

7. What must be true before using a real vendor map for Track B?
   A. The map is interesting.
   B. Source/license review, model, revision, firmware/applicability, and vendor-specific caveats are recorded.
   C. The learner hides document assumptions.
   D. The device is on the production network.

8. Which capstone grading principle is most important?
   A. Evidence quality and source labeling matter more than visual polish.
   B. The most colorful dashboard wins.
   C. Any copied vendor table is complete.
   D. Unresolved assumptions should be removed from the submission.

## Answer Key

1. B. Reproducible reads require both source-facing and wire-level request fields plus data meaning and evidence.
2. C. If `40001` is the first holding register, documented `40010` maps to PDU address `9`.
3. B. Unclear source rows should be labeled unresolved, not invented.
4. A. Reserved gaps are a common polling-plan hazard.
5. A. A write echo is not physical proof; capstones need safety boundaries and independent confirmation.
6. A. Normalization turns source-specific labels into reusable project tags without losing evidence.
7. B. Real/vendor tracks require source and applicability review before use.
8. A. The capstone is graded on defensible evidence and reusable handoff quality.

## Distractor Review Notes

| Question | Correct | Why The Distractors Are Wrong |
|---:|---|---|
| 1 | B | A/C/D are presentation or partial-result details that cannot reproduce a Modbus read. |
| 2 | C | A sends documentation notation, B uses a one-based item number as the PDU address, and D is the first holding-register offset, not `40010`. |
| 3 | B | A invents a table and address, C changes the data model without evidence, and D blames the simulator before resolving the source row. |
| 4 | A | B falsely limits register reads, C denies TCP register reads, and D confuses scaling with request grouping. |
| 5 | A | B is unsafe, C overclaims physical effect, and D ignores the safety and independent-verification evidence required after a write echo. |
| 6 | A | B erases the distinction, C removes evidence, and D treats a label as proof of word order. |
| 7 | B | A is insufficient source qualification, C hides assumptions, and D violates the no-production-default course boundary. |
| 8 | A | B rewards presentation over evidence, C overtrusts copied tables, and D hides uncertainty instead of labeling it. |

## Instructor Notes

- Use questions 2 and 3 to check whether learners preserve address uncertainty.
- Use question 5 to connect Module 16 back to Module 15.
- Add tool or dashboard-specific questions only after simulator and UI evidence are verified.

## Source Notes

- Official citation targets: [official-citation-map.md](https://learnmodbus.studioseventeen.io/resource/official-citation-map) rows for four primary logical data tables, addressing model and zero-based PDU addresses, public function-code categories, relevant function-specific rows, normal response vs exception response, exception codes and exception response PDU shape, write single register shape and echo boundary, MBAP header fields, Unit Identifier and gateway routing, RTU/ASCII frame fields, and serial server address range and broadcast address where the selected capstone path uses those transports.
- Real/vendor capstone tracks require source/license review, model, revision, firmware/applicability, and source-specific caveats before publication.

---
_Learn Modbus · learnmodbus.studioseventeen.io · Module 16/16 · v1.0.0 · Exported for offline / agent use._