Phosphor.Adapter.HwMon 0.3.1

phosphor-adapter-hwmon

Hardware sensor adapter for the Phosphor real-time operational visualization platform. Reads temperatures, fan speeds, voltages, power draw, clock speeds, and S.M.A.R.T. data from local hardware and publishes it to the Phosphor message bus as normalized telemetry envelopes.

What It Does

This adapter bridges physical hardware sensors into the Phosphor pipeline. It reads data that operating system metric exporters (Prometheus node_exporter, windows_exporter) don't cover — Super I/O chip sensors, per-component fan RPM, VRM temperatures, individual GPU thermals, NVMe drive temps, and more.

It also emits structural events describing the hardware topology (CPU, GPU, motherboard, drives, fans) so that phosphor-scene-generator can auto-assemble a 3D model of the machine from discovered components.

Data Path

Hardware Sensors (Super I/O, CPU, GPU, NVMe, S.M.A.R.T.)
    ↓
LibreHardwareMonitorLib
    ↓
phosphor-adapter-hwmon
    ↓ publish
NATS (:4222)
    ↓ subscribe
phosphor-core → gRPC → Unreal Engine 5 (3D visualization)

Supported Hardware

The Windows implementation uses LibreHardwareMonitor, which supports:

Linux support (lm_sensors / /sys/class/hwmon) is planned via a swappable provider interface.

Requirements

• .NET 8 SDK
• Windows (Linux provider is a stub for now)
• Administrator privileges — required for ring-0 kernel driver access to Super I/O chips
• NATS server running locally or accessible on the network
• Phosphor.Core.Sdk NuGet package

Quick Start

# Clone
git clone https://github.com/phosphor-unreal/phosphor-adapter-hwmon.git
cd phosphor-adapter-hwmon

# Build
dotnet build src/Phosphor.Adapter.HwMon/

# Run (as administrator)
dotnet run --project src/Phosphor.Adapter.HwMon/ -- --config config/hwmon-config.yaml

The adapter will discover all available hardware sensors, emit structural events describing the hardware topology, and begin publishing sensor readings to NATS.

Configuration

adapter:
  name: "hwmon"
  hostname: "auto"                     # auto-detect or override

connection:
  nats_url: "nats://localhost:4222"

polling:
  interval_ms: 2000                    # sensor poll rate
  stale_threshold_ms: 10000            # mark sensor stale if no update

sensors:
  provider: "librehardwaremonitor"     # or "lm_sensors" on Linux

  include_types:                       # optional allowlist
    - Temperature
    - Fan
    - Voltage
    - Power
    - Load
    - Clock

  exclude_patterns:                    # optional blocklist
    - "*/Bus Speed"

structural:
  emit_topology: true                  # structural events for scene auto-assembly
  discovery_interval_ms: 30000         # re-scan for hot-plugged hardware

normalization:
  temperature:
    min: 20.0
    max: 100.0
  fan_rpm:
    min: 0
    max: 3000
  voltage:
    normalize: false                   # publish raw values

NATS Subjects

All subjects follow the Phosphor naming convention: domain.category.source.metric

hwmon.temp.{hostname}.{sensor_path}          — temperature (°C)
hwmon.fan.{hostname}.{sensor_path}           — fan speed (RPM)
hwmon.voltage.{hostname}.{sensor_path}       — voltage (V)
hwmon.power.{hostname}.{sensor_path}         — power draw (W)
hwmon.load.{hostname}.{sensor_path}          — utilization (%)
hwmon.clock.{hostname}.{sensor_path}         — clock speed (MHz)
hwmon.throughput.{hostname}.{sensor_path}    — data rate (B/s)
hwmon.storage.{hostname}.{sensor_path}       — S.M.A.R.T. attributes

Sensor paths are derived from the LibreHardwareMonitor hardware tree, sanitized for NATS compatibility. For example: cpu0.core0, gpu.nvidia.0, motherboard.ite.fan1, nvme.samsung.0.temp.

Payload Format

{
  "metric": "hwmon.temp.workstation1.cpu0.core0",
  "value": 62.5,
  "normalized": 0.53,
  "unit": "°C",
  "timestamp": 1709571234567,
  "labels": {
    "hostname": "workstation1",
    "hardware_type": "CPU",
    "hardware_name": "Intel Core i9-10980XE",
    "sensor_type": "Temperature",
    "sensor_name": "CPU Core #0"
  }
}

Both raw value and normalized (0-1) are included in every reading. The normalized value maps directly to Phosphor visual channels (color gradients, pulse rates, etc.) in Unreal Engine.

Structural Events

On startup and periodically during operation, the adapter emits structural events:

{
  "event_type": "node_appeared",
  "entity_id": "hwmon.workstation1.cpu0",
  "labels": {
    "type": "CPU",
    "manufacturer": "Intel",
    "model": "Core i9-10980XE",
    "parent": "hwmon.workstation1.motherboard"
  }
}

These events enable phosphor-scene-generator to auto-assemble a 3D model of the machine — spawning actors for each component, linking parent-child relationships, and grouping by hardware type.

Development

Debugging (VS Code)

LibreHardwareMonitor requires administrator privileges to access ring-0 kernel drivers (Super I/O chips, certain GPU sensors, S.M.A.R.T.). Without elevation the adapter will run but return incomplete or empty sensor data.

Two debug configurations are provided in .vscode/launch.json:

Tip: On Windows, right-click the VS Code shortcut and choose "Run as administrator" for the simplest full-sensor debug experience.

Architecture

src/Phosphor.Adapter.HwMon/
├── Program.cs                          # Host builder, DI setup
├── HwMonAdapter.cs                     # IPhosphorAdapter + IStructuralAdapter
├── Configuration/
│   └── HwMonConfig.cs                  # Strongly-typed config model
├── Providers/
│   ├── IHardwareSensorProvider.cs      # Backend abstraction
│   ├── LibreHardwareMonitorProvider.cs  # Windows implementation
│   └── LmSensorsProvider.cs            # Linux stub
├── Models/
│   ├── SensorReading.cs                # Internal reading model
│   └── HardwareNode.cs                 # Hardware tree node
└── Mapping/
    ├── SubjectMapper.cs                # Sensor → NATS subject
    └── NormalizationService.cs         # Raw → 0-1 with configurable ranges

The IHardwareSensorProvider interface abstracts the sensor backend so that the core adapter logic is platform-independent. On Windows, LibreHardwareMonitorProvider wraps the LibreHardwareMonitorLib NuGet package. On Linux, LmSensorsProvider will read from /sys/class/hwmon and lm_sensors.

How It Fits in the Phosphor Platform

This adapter is complementary to phosphor-adapter-prometheus:

Together, they provide complete observability of a machine — both what the OS sees and what the hardware reports.

Downstream Consumers

• phosphor-core — routes hwmon data to gRPC consumers
• phosphor-unreal-plugin — binds sensor values to material parameters, animation speeds
• phosphor-scene-generator — uses structural events to auto-build the 3D hardware model
• phosphor-adapter-computed — references hwmon metrics in derived rules (e.g., thermal risk scoring)
• phosphor-adapter-claude — AI interpretation of hardware health patterns

License

Apache 2.0 — see LICENSE.

Part of the Phosphor Platform

Phosphor translates operational telemetry into real-time 3D visualizations using Unreal Engine 5. Learn more at github.com/phosphor-unreal.