wwtools/mbproxy/README.md

mbproxy

A .NET 10 Windows Service that sits inline as a Modbus TCP proxy in front of a fleet of AutomationDirect DirectLOGIC DL205/DL260 controllers, rewriting BCD-encoded registers bidirectionally so upstream clients can read and write them as plain integers. Since Phase 11, the proxy also offers an opt-in per-tag response cache (default OFF) for FC03/FC04 reads with bounded operator-configured staleness — see docs/design.md → "Response cache (Phase 11)" before enabling it.

Hard constraints / prerequisites

• Windows 10 / Server 2019 or later, 64-bit. No Linux or Docker support — the service uses Microsoft.Extensions.Hosting.WindowsServices and the Windows Event Log.
• Modbus TCP backends reachable from the proxy host on port 502 (or the port configured per PLC). The H2-ECOM100 module caps simultaneous connections at 4 per PLC — a fifth upstream client will fail to connect.
• Admin rights to install the service (install.ps1 requires elevation).
• No COM dependency — this is a pure .NET 10 socket-level proxy (unlike the .NET Framework 4.8 / x86 siblings in this repo).
• Python 3.10+ on the test machine to run the pymodbus-backed E2E simulator (not needed to run the service in production).

Layout

src/Mbproxy/          Main C# project (net10.0, Microsoft.NET.Sdk.Worker)
tests/Mbproxy.Tests/  xUnit v3 test project (314 unit + 48 E2E tests)
install/              PowerShell install/uninstall scripts and config template
docs/                 Design document, phase plans, and operations runbook
DL260/                DL205/DL260 reference material and pymodbus simulator profile

Resource index

Task	Go to
Full architecture, schema, log events, status counters, test strategy	docs/design.md
Phase-by-phase implementation plan	docs/plan/README.md
Install, upgrade, config, logs, troubleshooting	docs/operations.md
DL205/DL260 Modbus quirks (BCD, CDAB, octal V-memory, FC limits)	DL260/dl205.md
pymodbus simulator profile (register seeds for E2E tests)	DL260/dl205.json
Agent-oriented coding guide (architecture bullets, device quirks, phase context)	CLAUDE.md

Detailed documentation

The docs/ tree is organized by topic. Start with docs/design.md for the canonical end-to-end design; jump to the focused pages below when you need depth on one area.

Architecture

• Architecture/Overview.md — Listener topology, request flow, per-PLC isolation.
• Architecture/ConnectionModel.md — Single backend connection per PLC, TxId multiplexing, request-timeout watchdog, disconnect cascade.
• Architecture/ReadCoalescing.md — In-flight FC03/FC04 deduplication via InFlightByKeyMap.
• Architecture/ResponseCache.md — Opt-in per-tag response cache with bounded operator-configured staleness.

Features

• Features/BcdRewriting.md — BCD codec, CDAB word order, FC03/04/06/16 scope, partial-overlap policy.
• Features/HotReload.md — IOptionsMonitor-driven config reload with per-change-kind reconcile rules.

Operations

• Operations/Configuration.md — Full appsettings.json reference: every Mbproxy:* key, default, and validation rule.
• Operations/StatusPage.md — Admin endpoint surface (/, /status.json) with every JSON field documented.
• Operations/Troubleshooting.md — Diagnosis playbook keyed to log events and status counters.

Reference

• Reference/LogEvents.md — Stable mbproxy.* event catalog (28 events across 7 categories).

Testing

• Testing/Simulator.md — pymodbus DL205 fixture, skip policy, and the load-bearing pymodbus 3.13 framer quirk.

Build and run

Build (Debug, multi-file — fast for iteration):

dotnet build Mbproxy.slnx -c Debug

Publish (Release, single-file self-contained, win-x64):

dotnet publish src/Mbproxy/Mbproxy.csproj -c Release -r win-x64 --self-contained true -o C:\build\mbproxy-publish

The published output is a single Mbproxy.exe (~100 MB). The self-contained publish bundles the full .NET 10 + ASP.NET Core runtime. No .NET installation is required on the target machine.

Run tests:

dotnet test Mbproxy.slnx -c Debug                    # all tests
dotnet test Mbproxy.slnx -c Debug --filter Category=Unit   # unit tests only (no Python required)
dotnet test Mbproxy.slnx -c Debug --filter Category=E2E    # E2E tests (require Python + pymodbus)

Run interactively (without installing as a service):

cd src/Mbproxy
dotnet run --configuration Debug

Edit src/Mbproxy/appsettings.json to configure PLCs before running. The admin status page will be at http://localhost:8080/ by default.

Install

Full detail is in docs/operations.md. Quick path:

# 1. Publish
dotnet publish src/Mbproxy/Mbproxy.csproj -c Release -r win-x64 --self-contained true -o C:\build\mbproxy-publish

# 2. Install (elevated PowerShell)
.\install\install.ps1 -PublishOutput C:\build\mbproxy-publish -Start

# 3. Edit the config that was placed at %ProgramData%\mbproxy\appsettings.json

# 4. Verify
Invoke-WebRequest http://localhost:8080/ -UseBasicParsing

Maintenance

Documentation doctrine for this repo: ../DOCS-GUIDE.md.

• This README routes to deep docs — it does not duplicate them.
• Design decisions: docs/design.md is the source of truth.
• When the service's public surface or task→tool mapping changes, update this README and the root ../CLAUDE.md index row.