hiveops-guide/backend/src/main/resources/content/agent/xfs/claude.md at ee94f94fa1118a8fa2f962868c9eb99dd23e36b7

Files

T

johannes ee94f94fa1 docs(guide): XFS hardware-events coverage (EPIC hiveops-agent#102)

New agent.xfs module (architect/internal/claude tabs) documenting native
CEN/XFS hardware monitoring via the 32-bit helper, framed built-on-develop
/ ships-dark / not-yet-enabled. Adds hiveops.hardware.events to the Kafka
topic catalog, and hardware-events pointers to technical.agent /
.devices / .incident / .agent-proxy overviews. coverage-reconcile green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-23 11:05:18 -04:00

2.2 KiB

Raw Blame History

module, title, tab, order, audience

module	title	tab	order	audience
agent.xfs	XFS Device — native CEN/XFS hardware monitoring (MoniManager replacement)	Claude	10	bcos

Read this to act. Built on develop, ships DARK (xfs.enabled=false, not in the agent JAR). Full design: hiveops-agent/docs/xfs-integration.md + docs/hardware-events-pipeline.md. Epic hiveops-agent#102.

What it does

On-ATM module that reads Nautilus Hyosung ATM hardware natively via CEN/XFS (through a 32-bit helper process), and POSTs device faults into the hardware-events pipeline so they become incidents. Replaces MoniManager's hardware monitoring.

Key files

hiveops-agent/hiveops-module-xfs/ — XfsModule (poller), XfsHelperClient, HardwareEvent, HardwareEventClient.
hiveops-agent/native/hiveops-xfs/ — xfs_helper.c, xfs_min.h, build scripts, README.

To test the helper on an ATM (read-only, safe)

Lab ATM AT000999 (NHAdministrator@192.168.200.43) has the helper at C:\hiveops-agent\native\hiveops-xfs.exe. That box points at PROD — startup/open/status are read-only and emit nothing to the backend, but do NOT run the agent module against it.

hiveops-xfs.exe startup                    # negotiate CEN/XFS version
hiveops-xfs.exe open CardReader            # open a service provider
hiveops-xfs.exe status CardReader 201      # read device state (online/offline/hwerror)

To simulate the backend pipeline (no ATM needed)

Produce a HardwareEvent JSON to hiveops.hardware.events, or POST to devices /api/internal/atms/hardware-events (header X-Internal-Secret). A fault deviceState (offline/hwerror/nodevice/fraud) raises an incident; online resolves it. See [technical.incident].

Gotchas

Ships dark — enabling requires un-darking the module (add to hiveops-app) + xfs.enabled=true.
The EVENT lines from the helper's monitor mode carry dwEventID, not device state — decoding them needs the CEN/XFS SDK; the module uses status polling for the MVP.
32-bit helper only (the fielded msxfs.dll is x86). Cross-build with MinGW-i686.
Never issue a PIN/EPP command (PCI). See the Architect tab for the four native-bridge facts.

2.2 KiB Raw Blame History