integrated environmental monitoring

Author: oetiker

CHANGES.md

@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### New
+- Added **UPS Environment** service for THS environmental sensor monitoring:
+  - Temperature monitoring (thsOneTempData - .1.3.6.1.4.1.44782.1.2.1.1.1.0)
+  - Humidity monitoring (thsOneHumiData - .1.3.6.1.4.1.44782.1.2.1.1.2.0)
+  - Configurable thresholds for both upper and lower limits
+  - Service auto-discovered only when THS sensor is connected
+- Added graphing metrics for environmental data (env_temperature, env_humidity)
+- Added environment-specific graphs (temperature, humidity, combined)
 
 ### Changed
 

README.md

@@ -1,223 +1,99 @@
 # CheckMK Wiseways UPS SNMP Plugin
 
-A comprehensive CheckMK SNMP plugin for monitoring Wiseways UPS devices (6000VA, 10kVA and compatible models).
-
-## Overview
-
-This plugin provides complete monitoring of Wiseways UPS systems via SNMP with 18 specialized services covering every aspect of UPS operation:
-
-- **System Information**: Model, serial number, firmware versions, maintenance schedules
-- **Battery Monitoring**: Individual services for charge, runtime, status, and alarms
-- **Power Monitoring**: Separate services for input/output/bypass/battery voltages
-- **Load Management**: Output load percentage, power consumption, and current monitoring
-- **Frequency Stability**: Individual monitoring for input/output/bypass frequencies
-- **Alarm System**: Comprehensive alarm detection and status reporting
+A CheckMK SNMP plugin for monitoring Wiseways UPS devices (6000VA, 10kVA and compatible models).
 
 ## Features
 
-- **18 Specialized Services**: Each monitoring aspect has its own dedicated service for granular control
-- **Automatic Data Normalization**: Converts SNMP values to standard units (decivolts→volts, minutes→seconds)
-- **Maintenance Monitoring**: Automatic warnings for expired maintenance and battery service schedules
-- **Smart Graph Organization**: Unit-based grouping for combined overview graphs
-- **Dynamic Thresholds**: Uses device configuration values as defaults when available
-- **Enterprise & Standard MIB Support**: Works with both RFC 1628 standard UPS MIB and Wiseways enterprise OIDs (44782)
+- 19 specialized services for granular monitoring and alerting
+- Automatic unit conversion (decivolts→volts, minutes→seconds)
+- Dynamic thresholds from device configuration when available
+- Maintenance expiration warnings
+- Support for RFC 1628 UPS MIB and Wiseways enterprise OIDs (44782)
+- THS environmental sensor support (temperature/humidity)
 
 ## Installation
 
-### Standard Installation (Recommended)
-
-1. Download the latest MKP package from [GitHub Releases](https://github.com/oposs/cmk-oposs_wiseways_ups/releases)
-
-2. Install the MKP in CheckMK:
-   ```bash
-   cmk -P install oposs_wiseways_ups-<version>.mkp
-   ```
-
-3. Run service discovery on your UPS hosts:
-   ```bash
-   cmk -II <hostname>
-   ```
+### From MKP Package (Recommended)
 
-### Manual Installation (Developers)
+```bash
+# Download from https://github.com/oposs/cmk-oposs_wiseways_ups/releases
+cmk -P install oposs_wiseways_ups-<version>.mkp
+cmk -II <hostname>
+```
 
-For development or manual installation:
+### Manual Installation
 
-1. Copy the plugin files to your CheckMK site:
-   ```bash
-   cp -r local/* ~/local/
-   ```
+```bash
+cp -r local/* ~/local/
+cmk -R
+cmk -II <hostname>
+```
 
-2. Reload CheckMK to recognize the new plugin:
-   ```bash
-   cmk -R
-   ```
-
-3. Run service discovery on your UPS hosts:
-   ```bash
-   cmk -II <hostname>
-   ```
-
-## Configuration
-
-### SNMP Setup
-
-Ensure your Wiseways UPS is accessible via SNMP:
+## SNMP Setup
 
 1. Configure SNMP community string on the UPS
 2. Add the UPS as a host in CheckMK with SNMP monitoring enabled
 3. Set the appropriate SNMP community in CheckMK host properties
 
-### Service Discovery
-
-The plugin will automatically discover up to 18 services per UPS:
-
-#### Information Services
-- **UPS System Info**: Model, serial, firmware, maintenance dates
-- **UPS Battery Status**: Battery state and alarms (without charge/runtime)
-- **UPS Power Status**: Power source, operational mode, line failures
-- **UPS Alarm Status**: System-wide alarm monitoring
-
-#### Battery Monitoring Services
-- **UPS Battery Charge**: Battery charge percentage
-- **UPS Battery Runtime**: Remaining runtime in seconds
-- **UPS Battery Voltage**: DC battery voltage
-- **UPS Battery Current**: Charging/discharging current
-- **UPS Battery Temperature**: Battery temperature monitoring
-
-#### Voltage Monitoring Services  
-- **UPS Input Voltage**: AC input voltage
-- **UPS Output Voltage**: AC output voltage
-- **UPS Bypass Voltage**: Bypass line voltage (when available)
-
-#### Frequency Monitoring Services
-- **UPS Input Frequency**: Input frequency stability
-- **UPS Output Frequency**: Output frequency stability
-- **UPS Bypass Frequency**: Bypass frequency (when available)
-
-#### Load and Power Services
-- **UPS Output Load**: Load percentage monitoring
-- **UPS Output Power**: Power consumption in watts
-- **UPS Output Current**: Output current monitoring
-
-### Threshold Configuration
-
-Configure monitoring thresholds in CheckMK under "Setup" > "Services" > "Service monitoring rules" > "OPOSS Wiseways UPS":
-
-All thresholds can be configured through a single unified ruleset that applies to all relevant services:
-
-#### Battery Thresholds
-- **Battery Charge** (`battery_charge_lower`): Warning at 20%, Critical at 10%
-- **Battery Runtime** (`battery_runtime_lower`): Warning at 10 minutes, Critical at 5 minutes
-- **Battery Voltage** (`battery_voltage_lower`): Warning at 180V, Critical at 170V
-- **Battery Temperature** (`temp_upper/temp_lower`): Warning at 40°C/10°C, Critical at 45°C/5°C
-
-#### Voltage Thresholds
-- **Input Voltage** (`input_voltage_upper/lower`): Warning at 250V/210V, Critical at 260V/200V
-- **Output Voltage** (`output_voltage_upper/lower`): Warning at 250V/210V, Critical at 260V/200V
-- **Bypass Voltage** (`bypass_voltage_upper/lower`): Warning at 250V/210V, Critical at 260V/200V
-
-#### Frequency Thresholds
-- **All Frequencies** (`frequency_upper/lower`): Warning at 51Hz/49Hz, Critical at 52Hz/48Hz
-
-#### Load and Power Thresholds
-- **Output Load** (`load_upper`): Warning at 80%, Critical at 90%
-- **Output Current** (`output_current_upper`): Configurable, no default
-- **Output Power** (`power_upper`): Configurable, no default
-
-Note: The plugin uses device-reported configuration values as dynamic defaults when available (e.g., input voltage limits from the UPS configuration).
-
-## Metrics and Graphs
-
-### Graph Organization
-
-The plugin provides two types of graphs:
-
-#### Service-Specific Graphs
-Each service displays its own dedicated graph with relevant metrics and thresholds.
-
-#### Combined Overview Graphs (Host Level)
-These graphs combine metrics from multiple services for comparative analysis:
-
-1. **UPS All Voltages**: All voltages (input, output, bypass, battery) on one graph
-2. **UPS AC Voltages**: AC voltages only (input, output, bypass)
-3. **UPS Frequencies**: All frequencies (input, output, bypass) together
-4. **UPS Currents**: Output and battery currents combined
-5. **UPS Battery Time**: Runtime and time-on-battery metrics
-
-### Metric Units
-
-All metrics use base SI units for consistency:
-- **Time**: seconds (converted from minutes in SNMP)
-- **Voltage**: volts (converted from decivolts or string format)
-- **Frequency**: hertz (converted from centihertz or string format)
-- **Temperature**: degrees Celsius
-- **Power**: watts
-- **Current**: amperes
-- **Charge**: percentage
-- **Load**: percentage
-
-## Supported OIDs
-
-The plugin monitors both standard RFC 1628 UPS MIB OIDs and Wiseways enterprise-specific OIDs:
-
-### Standard MIB (.1.3.6.1.2.1.33)
-- UPS identification and status
-- Battery metrics
-- Input/output electrical parameters
-- Bypass parameters
-
-### Enterprise OIDs
-- `.1.3.6.1.4.1.935` - Enhanced battery metrics
-- `.1.3.6.1.4.1.44782` - Wiseways-specific high-precision values
+## Services and Thresholds
+
+Configure thresholds under "Setup" > "Services" > "Service monitoring rules" > "OPOSS Wiseways UPS".
+
+| Service | Description | Default Thresholds (Warn/Crit) |
+|---------|-------------|-------------------------------|
+| **UPS System Info** | Model, serial, firmware, maintenance dates | Warns on expired maintenance |
+| **UPS Battery Status** | Battery state and alarms | — |
+| **UPS Power Status** | Power source, mode, line failures | — |
+| **UPS Alarm Status** | System-wide alarm monitoring | — |
+| **UPS Battery Charge** | Battery charge % | Lower: 20%/10% |
+| **UPS Battery Runtime** | Remaining runtime | Lower: 10min/5min |
+| **UPS Battery Voltage** | DC battery voltage | Lower: 180V/170V |
+| **UPS Battery Current** | Charging/discharging current | — |
+| **UPS Battery Temperature** | Battery temperature | Upper: 40°C/45°C, Lower: 10°C/5°C |
+| **UPS Input Voltage** | AC input voltage | Upper: 250V/260V, Lower: 210V/200V |
+| **UPS Output Voltage** | AC output voltage | Upper: 250V/260V, Lower: 210V/200V |
+| **UPS Bypass Voltage** | Bypass line voltage | Upper: 250V/260V, Lower: 210V/200V |
+| **UPS Input Frequency** | Input frequency | Upper: 51Hz/52Hz, Lower: 49Hz/48Hz |
+| **UPS Output Frequency** | Output frequency | Upper: 51Hz/52Hz, Lower: 49Hz/48Hz |
+| **UPS Bypass Frequency** | Bypass frequency | Upper: 51Hz/52Hz, Lower: 49Hz/48Hz |
+| **UPS Output Load** | Load percentage | Upper: 80%/90% |
+| **UPS Output Power** | Power consumption (W) | — |
+| **UPS Output Current** | Output current (A) | — |
+| **UPS Environment** | THS sensor temp/humidity | Temp: 35°C/40°C (upper), 10°C/5°C (lower); Humidity: 70%/80% (upper), 20%/10% (lower) |
+
+Services marked "—" have no default thresholds but can be configured. Bypass and Environment services only appear when hardware is present.
+
+## Graphs
+
+Each service has its own graph. Additional combined graphs at host level:
+
+- **UPS All Voltages** / **UPS AC Voltages**: Compare voltage sources
+- **UPS Frequencies**: All frequencies together
+- **UPS Currents**: Output and battery currents
+- **UPS Battery Time**: Runtime and time-on-battery
+- **UPS Environment**: Temperature and humidity
 
 ## Requirements
 
 - CheckMK 2.3 or later
 - SNMP v1/v2c access to the UPS
-- Wiseways UPS with SNMP support (tested with 6000VA model)
+- Wiseways UPS with SNMP support
 
 ## Troubleshooting
 
-### No Services Discovered
-
-1. Verify SNMP connectivity:
-   ```bash
-   snmpwalk -v2c -c <community> <ups_ip> .1.3.6.1.2.1.33.1.1.5.0
-   ```
-   This should return a string containing "Wiseway3" for compatible devices.
-
-2. Check SNMP configuration in CheckMK host settings
-
-3. Ensure the UPS supports standard UPS MIB and/or Wiseways enterprise OIDs
-
-4. Run manual discovery:
-   ```bash
-   cmk -vvI --detect-plugins=oposs_wiseways_ups <hostname>
-   ```
+**No services discovered:**
+```bash
+# Verify SNMP connectivity (should return string containing "Wiseway3")
+snmpwalk -v2c -c <community> <ups_ip> .1.3.6.1.2.1.33.1.1.5.0
 
-### Fewer Than 18 Services
+# Debug discovery
+cmk -vvI --detect-plugins=oposs_wiseways_ups <hostname>
+```
 
-Not all services may be discovered depending on UPS capabilities:
-- Bypass services only appear if bypass voltage/frequency data is available
-- Battery current may not be available on all models
-- Some older models may not report all metrics
+**Fewer than 19 services:** Normal - bypass, environment, and some battery metrics only appear when supported by hardware.
 
-### Incorrect Values
-
-- The plugin automatically converts enterprise string format values (e.g., "231.9") to floats
-- Minutes are converted to seconds for all time-based metrics
-- Special value -99998 indicates unavailable data and is handled gracefully
-
-### Missing Graphs
-
-- Individual service graphs appear with their respective services
-- Combined overview graphs appear at the host level (not under specific services)
-- This is the intended behavior for cross-service visualization
+**Incorrect values:** The plugin handles enterprise string formats and special value -99998 (unavailable data) automatically.
 
 ## License
 
 This plugin is provided as-is for monitoring Wiseways UPS devices in CheckMK environments.
-
-## Support
-
-For issues or feature requests, please refer to the project documentation or contact your system administrator.

local/lib/python3/cmk_addons/plugins/oposs_wiseways_ups/agent_based/oposs_wiseways_ups.py

@@ -251,6 +251,12 @@ class OIDDefinition:
                   "output_load_up_config", converter=identity_float),
     OIDDefinition("battery_volt_low_config", "4.1.44782.1.1.3.7.0", "upsBatteryVoltLowConfig",
                   "battery_volt_low_config", converter=identity_float),
+
+    # Environmental sensor data (THS One)
+    OIDDefinition("env_temperature", "4.1.44782.1.2.1.1.1.0", "thsOneTempData",
+                  "env_temperature", converter=identity_float),
+    OIDDefinition("env_humidity", "4.1.44782.1.2.1.1.2.0", "thsOneHumiData",
+                  "env_humidity", converter=identity_float),
 ]
 
 
@@ -1198,4 +1204,68 @@ def check_oposs_wiseways_ups_system_info(section: Dict[str, Any]) -> CheckResult
     sections=["oposs_wiseways_ups"],
     discovery_function=discover_oposs_wiseways_ups_system_info,
     check_function=check_oposs_wiseways_ups_system_info,
+)
+
+
+# Check plugin for UPS Environment (THS sensor)
+def discover_oposs_wiseways_ups_environment(section: Dict[str, Any]) -> DiscoveryResult:
+    # Discover only if environmental sensor data is present
+    env_temp = section.get("env_temperature", 0)
+    env_humi = section.get("env_humidity", 0)
+    if section and (env_temp > 0 or env_humi > 0):
+        yield Service()
+
+
+def check_oposs_wiseways_ups_environment(
+    params: Mapping[str, Any], section: Dict[str, Any]
+) -> CheckResult:
+    if not section:
+        yield Result(state=State.UNKNOWN, summary="No data")
+        return
+
+    env_temp = section.get("env_temperature", 0)
+    env_humi = section.get("env_humidity", 0)
+
+    # Check if sensor data is available
+    if env_temp <= 0 and env_humi <= 0:
+        yield Result(state=State.UNKNOWN, summary="No environmental sensor data")
+        return
+
+    # Temperature check
+    if env_temp > 0:
+        yield from check_levels(
+            env_temp,
+            levels_upper=params.get("env_temp_upper", ("fixed", (35.0, 40.0))),
+            levels_lower=params.get("env_temp_lower", ("fixed", (10.0, 5.0))),
+            metric_name="env_temperature",
+            label="Temperature",
+            render_func=lambda v: f"{v:.1f}°C",
+        )
+
+    # Humidity check
+    if env_humi > 0:
+        yield from check_levels(
+            env_humi,
+            levels_upper=params.get("env_humidity_upper", ("fixed", (70.0, 80.0))),
+            levels_lower=params.get("env_humidity_lower", ("fixed", (20.0, 10.0))),
+            metric_name="env_humidity",
+            label="Humidity",
+            render_func=lambda v: f"{v:.0f}%",
+            boundaries=(0, 100),
+        )
+
+
+check_plugin_oposs_wiseways_ups_environment = CheckPlugin(
+    name="oposs_wiseways_ups_environment",
+    service_name="UPS Environment",
+    sections=["oposs_wiseways_ups"],
+    discovery_function=discover_oposs_wiseways_ups_environment,
+    check_function=check_oposs_wiseways_ups_environment,
+    check_ruleset_name="oposs_wiseways_ups",
+    check_default_parameters={
+        "env_temp_upper": ("fixed", (35.0, 40.0)),
+        "env_temp_lower": ("fixed", (10.0, 5.0)),
+        "env_humidity_upper": ("fixed", (70.0, 80.0)),
+        "env_humidity_lower": ("fixed", (20.0, 10.0)),
+    },
 )