firmware-base/docs-c/core/ValueWrapper.md

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

ValueWrapper

Path: 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
• modbus/ModbusTypes.h
• enums.h
• Logger.h

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.

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