====================================================================
LINTRONIC NETWORK MONITOR (v4.3) - DOCUMENTATION & SETUP GUIDE
====================================================================

A lightweight Windows background monitor designed to track the
availability, network stability, and host resource usage of a
Home Assistant instance (running in Oracle VirtualBox or on
dedicated hardware).


--------------------------------------------------------------------
1. KEY FEATURES
--------------------------------------------------------------------
* SMART LOGGING:
  Runs quietly when everything is healthy (logs a status heartbeat
  + 30-minute min/avg/max statistics every 30 minutes) and switches
  to high-frequency logging (every 30 seconds) if Home Assistant
  stops responding.

* AUTOMATIC STARTUP & OUTAGE DIAGNOSTICS:
  Automatically inspects VirtualBox VM state, top CPU/RAM processes,
  network adapters, Link Speed, power management settings, Windows
  Event Logs, and VBox.log on startup and whenever an outage occurs.

* LINK SPEED & IP CHANGE DETECTION:
  Instantly logs if a network adapter changes IP address or drops
  its physical link speed (e.g., from 1000 Mbps down to 100 Mbps).

* NETWORK POWER MANAGEMENT AUDIT:
  Checks whether Windows is allowed to turn off your network adapter
  to save power (MSPower_DeviceEnable) and inspects driver registry
  keys for Energy-Efficient Ethernet (EEE) and Green Ethernet.

* EXTERNAL CONFIGURATION (config.ini):
  All paths, IP addresses, and thresholds can be customized without
  recompiling the application.


--------------------------------------------------------------------
2. INSTALLATION & SETUP
--------------------------------------------------------------------
1. RUN THE APPLICATION ONCE:
   Launch HA Network Monitor.exe (preferably "Run as administrator").

2. AUTOMATIC FOLDER & CONFIG CREATION:
   On first launch, the application automatically creates the working
   directory:
      C:\LinTronic\NetworkMonitor\

   Inside this folder, it generates a default config.ini file, this
   README.txt file, and starts writing timestamped log files:
      networklog_YYYY-MM-DD_HH-mm-ss.txt

3. CUSTOMIZE config.ini:
   Open C:\LinTronic\NetworkMonitor\config.ini in Notepad, adjust
   the values to match your setup, save the file, and restart the
   monitor.


--------------------------------------------------------------------
3. CONFIGURATION REFERENCE (config.ini)
--------------------------------------------------------------------
[VirtualBox]
VmName          = Exact name of your VirtualBox VM. (Optional if
                  running Home Assistant on dedicated hardware).
VmFolder        = Path to your VirtualBox VM folder containing the
                  Logs\VBox.log file.
VBoxManagePath  = Full path to VBoxManage.exe.

[Network]
HaIpAddress     = Local IPv4 address of your Home Assistant instance
                  (used for ICMP ping checks).
HaWebUrl        = Full URL to the Home Assistant web interface
                  (used for HTTP status checks, e.g.
                  http://192.168.1.72 or http://192.168.1.72:8123).
RouterIpAddress = Local gateway/router IP to verify local LAN
                  connectivity during an outage.
ExternalDnsIp   = External IP (e.g., 8.8.8.8) to verify internet
                  connectivity during an outage.

[Monitoring]
LogFolder                  = Directory where log files are saved.
TimerIntervalMs            = Background check interval in milliseconds
                             (10000 = 10 seconds).
CpuWarningThreshold        = Host CPU percentage threshold that
                             triggers a high-CPU warning.
CpuConsecutiveHitsRequired = Number of consecutive high-CPU checks
                             required before logging a warning.
MinFreeDiskSpaceGB         = Minimum free space on C: before logging
                             a critical low-disk warning.


--------------------------------------------------------------------
4. IMPORTANT NOTES & RECOMMENDED HOST SETTINGS
--------------------------------------------------------------------
* RUN AS ADMINISTRATOR:
  To allow the monitor to read Windows PnP power management settings
  (MSPower_DeviceEnable) and the System Event Log, right-click the
  executable and select "Run as administrator" (or configure it to
  run with highest privileges in Windows Task Scheduler).

* RECOMMENDED SETTINGS FOR 24/7 WINDOWS HOSTS:
  If the startup diagnostic reports:
    - "Windows allowed to turn off device (PnP): TRUE"
    - or active EEE / GreenEthernet driver keys (value not 0)
  consider disabling them in:
    Device Manager -> Network Adapters -> Properties ->
    Power Management / Advanced
  to prevent brief connection drops. Also set the Windows Power Plan
  to "High Performance".
====================================================================
