---
title: "ValueWrapper Template Class"
description: "A templated class for managing values with threshold-based notifications through Modbus"
keywords: "ValueWrapper, Modbus, threshold, notification, embedded systems, ESP32"
---

## ValueWrapper

**Path**: [`src/modbus/ValueWrapper.h`](../src/modbus/ValueWrapper.h)

**Revision History**: Initial documentation

A template class that wraps values of any type with threshold-based update notifications through Modbus. This class monitors changes in a value and sends notifications to the owner component when changes exceed specified thresholds, using different comparison modes. It helps reduce network traffic by only sending updates when significant changes occur.

## REQUIREMENTS

- An owning Component instance that receives notifications
- A Modbus address space for notifications
- Function code configuration for the Modbus messages

## PROVIDES

- `ValueWrapper<T>` - Template class for wrapping values of any type
- `ThresholdMode` enumeration:
  - `DIFFERENCE` - Triggers when absolute difference between old and new values exceeds threshold
  - `INTERVAL_STEP` - Triggers when values cross step boundaries defined by the threshold

- Macros:
  - `DEFAULT_VW_POST_NOTIFY_LAMBDA` - Helper for creating standard post-notification logging lambdas
  - `INIT_COMPONENT_VALUE_WRAPPER` - Simplifies ValueWrapper initialization

## FEATURES

- Wraps any data type, including enums, with transparent type conversion
- Provides automatic threshold-based notifications through Modbus
- Supports different threshold modes for different types of data
- Handles both arithmetic types and enumerations correctly
- Provides callbacks when notifications are sent
- Automatic typecasting for Modbus message values

## DEPENDENCIES

- [`Component.h`](../src/Component.md)
- [`modbus/ModbusTypes.h`](../src/modbus/ModbusTypes.md)
- [`enums.h`](../src/enums.md)
- [`Logger.h`](../src/Logger.md)

```mermaid
graph TD
    ValueWrapper --> Component
    ValueWrapper --> ModbusTypes
    ValueWrapper --> enums
    ValueWrapper --> Logger
```

## BEHAVIOUR

The ValueWrapper monitors changes to a value and sends notifications when thresholds are exceeded.

```mermaid
stateDiagram-v2
    [*] --> Initialized: Constructor
    Initialized --> Comparing: update(newValue)
    Comparing --> ThresholdNotMet: Below threshold
    Comparing --> ThresholdExceeded: Above threshold
    ThresholdNotMet --> ValueUpdated: Update value without notification
    ThresholdExceeded --> NotifyOwner: Send Modbus update
    NotifyOwner --> CallbackExecution: Execute post-notification callback
    CallbackExecution --> ValueUpdated: Value updated
    ValueUpdated --> Initialized: Ready for next update
```

## TODOS

### PERFORMANCE

- Consider providing specialized implementations for common types to avoid template instantiation overhead
- Investigate using std::variant for better type safety and potentially reduced memory footprint
- Add an optional hysteresis parameter to prevent rapid oscillations around threshold values

### SECURITY

- Add bounds checking for Modbus addresses to prevent accidental overwrites
- Consider adding validation callbacks to ensure values remain within acceptable ranges

### COMPLIANCE

- Ensure all Modbus messages conform to the Modbus specification requirements
- Consider adding support for additional Modbus function codes as needed

### RECOMMENDATIONS

- Use the `INIT_COMPONENT_VALUE_WRAPPER` macro to simplify instance creation
- Choose appropriate threshold values to balance responsiveness and network traffic
- For enum types, use threshold value of 1 to notify on any state change
- For float values, consider the INTERVAL_STEP mode to create logical boundaries for notifications