mxaccesscli: read/write/subscribe System Platform tags via MxAccess

New tool wrapping ArchestrA.MxAccess.LMXProxyServerClass (the same COM proxy aaObjectViewer / WindowViewer use) as a CliFx CLI for LLM-driven debugging. Commands: - mxa info — loaded MxAccess assembly identity, supported value types, MxStatusCategory enum. - mxa read — fetch one or more tag values; subscribes briefly, captures first OnDataChange per tag, tears down. - mxa write — write a value with optional --type coercion; advises first to resolve the attribute type, then waits for OnWriteComplete with a per-call timeout. - mxa subscribe — stream OnDataChange events for --seconds; JSON Lines under --llm-json for piped agent consumption. - mxa diag — minimal smoke test on a private STA thread; bypasses the CliFx pipeline for diagnosing apartment / pump issues. Implementation notes documented in docs/api-notes.md (reverse-engineered because AVEVA does not publish a single canonical MxAccess reference): - Net48 / x86 / [STAThread] are non-negotiable. The CLI runs the entire CliFx pipeline on a dedicated STA thread. - COM events are dispatched as Win32 messages; AutoResetEvent.WaitOne alone does not pump them on this configuration. MxSession.WaitForUpdate loops Application.DoEvents() + drain + Sleep(20ms) instead. - Write requires the target attribute's type to be resolved first. WriteCommand advises and waits for the initial OnDataChange before calling LMXProxyServerClass.Write to avoid ArgumentException "Value does not fall within the expected range". - Errors carry the full MXSTATUS_PROXY[] from MxAccess (Success, Category, DetectedBy, Detail) so an agent can tell exactly which layer rejected a request. Verified against the live ZB galaxy with a writeable tag identified via grdb (TestChildObject.TestInt, mx_attribute_category=10): read: 99 (q=192, MxCategoryOk) write 7: round-tripped — read returned 7 — written back to 99 write str: TestChildObject.TestString round-tripped a timestamp subscribe: captured initial value plus subsequent change from a separate process The vendored ArchestrA.MxAccess.dll is gitignored — it is copied from C:\Program Files (x86)\ArchestrA\Framework\Bin\ on any System Platform install per the README. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 20:02:51 -04:00
parent 5a78ec5a76
commit ab202a1fa1
20 changed files with 1466 additions and 0 deletions
@@ -0,0 +1,58 @@
+using System;
+using ArchestrA.MxAccess;
+
+namespace MxAccess.Cli.Mx
+{
+    /// One AddItem-handle. Owns Advise/UnAdvise pairing so a Dispose tears
+    /// down the subscription cleanly even if the caller forgets.
+    public sealed class MxItem : IDisposable
+    {
+        private readonly MxSession _session;
+        private readonly LMXProxyServerClass _proxy;
+        private readonly int _hServer;
+        private bool _advised;
+        private bool _disposed;
+
+        public int Handle { get; }
+        public string Reference { get; }
+
+        internal MxItem(MxSession session, LMXProxyServerClass proxy, int hServer, int hItem, string reference)
+        {
+            _session  = session;
+            _proxy    = proxy;
+            _hServer  = hServer;
+            Handle    = hItem;
+            Reference = reference;
+        }
+
+        public void Advise()
+        {
+            if (_advised) return;
+            _proxy.Advise(_hServer, Handle);
+            _advised = true;
+        }
+
+        public void UnAdvise()
+        {
+            if (!_advised) return;
+            try { _proxy.UnAdvise(_hServer, Handle); } catch { /* best effort */ }
+            _advised = false;
+        }
+
+        /// `Write` blocks neither the caller nor the proxy — it queues a write and
+        /// returns. Use MxSession.WaitForUpdate() to await OnWriteComplete.
+        /// `userId = 0` means "unauthenticated"; OK for simple writes when galaxy
+        /// security allows it.
+        public void Write(object value, int userId = 0) =>
+            _proxy.Write(_hServer, Handle, value, userId);
+
+        public void Dispose()
+        {
+            if (_disposed) return;
+            _disposed = true;
+            try { UnAdvise(); } catch { }
+            try { _proxy.RemoveItem(_hServer, Handle); } catch { }
+            _session.RemoveItem(Handle);
+        }
+    }
+}