Add repository README
Orient new readers: project scope (read-only SDK, no native AVEVA dependency), operation status table, quick-start example, build/test commands, repository layout, doc hierarchy (AGENTS.md → CLAUDE.md → handoff.md → instructions.md), architecture overview, and the live-verified read + event chains end-to-end. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
dohertj2
@@ -0,0 +1,163 @@
|
||||
# histsdk
|
||||
|
||||
Pure managed .NET 10 client for AVEVA Historian's binary WCF protocol. The
|
||||
production SDK has no dependency on `aahClientManaged.dll`, `aahClient.dll`, or
|
||||
any other AVEVA native runtime — the wire protocol is reverse-engineered and
|
||||
re-implemented in C#.
|
||||
|
||||
Read-only by design. The required surface (per [`CLAUDE.md`](CLAUDE.md)):
|
||||
|
||||
| Operation | Status |
|
||||
|---|---|
|
||||
| `ProbeAsync` | live-verified |
|
||||
| `ReadRawAsync` | live-verified |
|
||||
| `ReadAggregateAsync` | live-verified (TimeWeightedAverage; other modes need fixtures) |
|
||||
| `ReadAtTimeAsync` | live-verified |
|
||||
| `ReadEventsAsync` | live-verified (typed event + 31-property property bag) |
|
||||
| `BrowseTagNamesAsync` | live-verified |
|
||||
| `GetTagMetadataAsync` | live-verified for 17 distinct native data-type codes |
|
||||
| `GetConnectionStatusAsync` | synthesized from authenticated probe (matches native semantic) |
|
||||
| `GetStoreForwardStatusAsync` | synthesized defaults (no SF sidecar to probe) |
|
||||
| `GetSystemParameterAsync` | live-verified via `Stat/GetSystemParameter` |
|
||||
|
||||
Out of scope: write-back, store-forward write, configuration changes.
|
||||
|
||||
## Quick start
|
||||
|
||||
```csharp
|
||||
using AVEVA.Historian.Client;
|
||||
using AVEVA.Historian.Client.Models;
|
||||
|
||||
await using HistorianClient client = new(new HistorianClientOptions
|
||||
{
|
||||
Host = "localhost",
|
||||
IntegratedSecurity = true,
|
||||
Transport = HistorianTransport.LocalPipe,
|
||||
});
|
||||
|
||||
DateTime endUtc = DateTime.UtcNow;
|
||||
DateTime startUtc = endUtc - TimeSpan.FromMinutes(10);
|
||||
|
||||
await foreach (HistorianSample sample in client.ReadRawAsync(
|
||||
"SysTimeSec", startUtc, endUtc, maxValues: 100))
|
||||
{
|
||||
Console.WriteLine($"{sample.TimestampUtc:o} {sample.NumericValue} Q={sample.Quality}");
|
||||
}
|
||||
```
|
||||
|
||||
For a remote Historian over Net.TCP set `Transport = HistorianTransport.RemoteTcpIntegrated`
|
||||
and `Host` to the server hostname. Remote-TCP plumbing exists but only `LocalPipe`
|
||||
has live verification in this checkout.
|
||||
|
||||
## Build & test
|
||||
|
||||
```powershell
|
||||
dotnet build .\Histsdk.slnx --no-restore
|
||||
dotnet test .\Histsdk.slnx --no-build --logger "console;verbosity=minimal"
|
||||
```
|
||||
|
||||
Run a single test class:
|
||||
|
||||
```powershell
|
||||
dotnet test .\Histsdk.slnx --no-build --filter "FullyQualifiedName~WcfDataQueryProtocolTests"
|
||||
```
|
||||
|
||||
Live integration tests (`tests/AVEVA.Historian.Client.Tests/HistorianClientIntegrationTests.cs`)
|
||||
are gated and skip cleanly without these env vars:
|
||||
|
||||
```powershell
|
||||
$env:HISTORIAN_HOST = 'localhost'
|
||||
$env:HISTORIAN_TEST_TAG = 'SysTimeSec' # any tag the server has data for
|
||||
# Optional for non-integrated auth:
|
||||
$env:HISTORIAN_USER, $env:HISTORIAN_PASSWORD
|
||||
$env:HISTORIAN_TAG_FILTER = 'Sys*' # or any LIKE-pattern
|
||||
```
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
src/AVEVA.Historian.Client/ Production SDK — pure managed .NET 10. No native AVEVA dependency.
|
||||
tests/ Unit tests (golden-byte / round-trip) + gated live integration tests.
|
||||
tools/ Reverse-engineering tooling (NOT shipped):
|
||||
AVEVA.Historian.ReverseEngineering/ .NET 10 CLI: WCF probes, dnlib IL inspection,
|
||||
IL-rewrite instrumentation (instrument-wcf-{write,read}message,
|
||||
instrument-openconnection*, instrument-startdataquery, etc.).
|
||||
AVEVA.Historian.NativeTraceHarness/ .NET Framework harness that loads aahClientManaged.dll for
|
||||
byte-for-byte parity testing against the native wrapper.
|
||||
AVEVA.Historian.NetFxWcfProbe/ .NET Framework WCF probe for ruling out .NET 10-only differences.
|
||||
AVEVA.Historian.ReverseInstrumentation/ Helper assembly injected into IL-rewritten wrapper copies.
|
||||
AVEVA.Historian.WcfCaptureServer/ Fake server for endpoint experiments.
|
||||
scripts/ PowerShell + Frida runners + Python decoders for capture analysis.
|
||||
fixtures/protocol/ Sanitized golden-byte fixtures.
|
||||
docs/reverse-engineering/ Sanitized handoff evidence; commit-safe summaries only.
|
||||
```
|
||||
|
||||
Native AVEVA binaries (`current/`, `aveva-install-x64/`, `aveva-install-x86/`) are
|
||||
**gitignored**. Each developer fetches their own copy from the AVEVA installer; we
|
||||
neither modify nor redistribute them.
|
||||
|
||||
## Documentation
|
||||
|
||||
Read in order before non-trivial work:
|
||||
|
||||
| Doc | Purpose |
|
||||
|---|---|
|
||||
| [`AGENTS.md`](AGENTS.md) | Standing project constraints and safety rules. |
|
||||
| [`CLAUDE.md`](CLAUDE.md) | Build commands, code architecture, the active protocol blocker (now resolved) and SDK surface. |
|
||||
| [`docs/reverse-engineering/handoff.md`](docs/reverse-engineering/handoff.md) | Decision record + decoded protocol evidence (binding shapes, descriptor layouts, Open2 v6 response, event-row wire format, property-bag value encoding). |
|
||||
| [`instructions.md`](instructions.md) | Original plan + decision record. |
|
||||
|
||||
## Architecture
|
||||
|
||||
Three intentionally decoupled subsystems under `src/AVEVA.Historian.Client/`:
|
||||
|
||||
- **`HistorianClient` + `HistorianClientOptions`** — public façade. Validates inputs;
|
||||
delegates reads to `Historian2020ProtocolDialect`; delegates probe / tag metadata /
|
||||
browse / status helpers to the WCF layer.
|
||||
- **`Wcf/`** — managed WCF/MDAS layer. Custom `MdasMessageEncoder` wraps SOAP 1.2 +
|
||||
WS-Addressing 1.0 in AVEVA's `application/x-mdas` framing. Three binding flavors
|
||||
via `HistorianWcfBindingFactory`: plain MDAS over Net.NamedPipe (local), MDAS +
|
||||
Windows transport (remote `/Hist-Integrated`), MDAS + certificate (remote
|
||||
`/HistCert`). Service contracts in `Wcf/Contracts/` mirror the server-side WCF
|
||||
surface (versioned per native interface — `IHistoryServiceContract`,
|
||||
`IRetrievalServiceContract2..4`, `IStatusServiceContract2`, etc.).
|
||||
- **`Protocol/`** — binary frame layer. `Historian2020ProtocolDialect` is the
|
||||
version-anchored bridge between the public façade and the WCF + frame layers.
|
||||
Methods without protocol evidence throw `ProtocolEvidenceMissingException` rather
|
||||
than guessing wire bytes.
|
||||
- **`Models/`** — public DTOs and enums. `HistorianSample`, `HistorianAggregateSample`,
|
||||
`HistorianEvent`, `HistorianTagMetadata`, `HistorianDataType`, `RetrievalMode`,
|
||||
`HistorianTransport`, etc.
|
||||
|
||||
Read flow end-to-end (live-verified against `localhost`):
|
||||
|
||||
```
|
||||
Hist.GetV → Hist.ValCl × N → Hist.Open2 → Retr.GetV → Retr.IsOriginalAllowed →
|
||||
Retr.StartQuery2 → loop Retr.GetNextQueryResultBuffer2 → typed HistorianSample rows
|
||||
```
|
||||
|
||||
Event flow end-to-end (live-verified):
|
||||
|
||||
```
|
||||
Hist.GetV → Hist.ValCl × N → Hist.Open2 → Hist.UpdC3 → 6× Stat.GetSystemParameter →
|
||||
Hist.RTag2 → Stat.GetSystemParameter(AllowRenameTags) → Trx.GetV → Stat.GetV →
|
||||
Retr.GetV → Hist.EnsT2(CmEventTagId) → Retr.StartEventQuery →
|
||||
loop Retr.GetNextEventQueryResultBuffer → typed HistorianEvent rows with
|
||||
property dictionary → Retr.EndEventQuery → Hist.Close2
|
||||
```
|
||||
|
||||
## Safety
|
||||
|
||||
- Production code under `src/` must remain pure managed .NET 10 with no native AVEVA
|
||||
reference. Reverse-engineering harnesses under `tools/` may reference native binaries.
|
||||
- Never commit credentials, hostnames, user names, customer tag names, or raw packet
|
||||
captures. `*.ndjson`, `current/`, `aveva-install-*/`, and `artifacts/` are gitignored
|
||||
precisely because they accumulate identity-bearing runtime data.
|
||||
- Methods without protocol evidence throw `ProtocolEvidenceMissingException`. Do not
|
||||
stub fake behavior — leave them throwing until evidence supports an implementation.
|
||||
|
||||
## Status
|
||||
|
||||
108 unit + live integration tests pass (`dotnet test --logger "console;verbosity=minimal"`).
|
||||
Full read-only SDK surface verified end-to-end against a local Historian. Remote-TCP
|
||||
transports and explicit-credentials path are wired but await live verification.
|
||||
Reference in New Issue
Block a user