96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
---
|
|
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 |