Feature Request: WebRelay Integration for Automated Physical Alarm Annunciation with Selectable Alarm Decision Source

[tyronechrisharris]

Related Issue: github.com/Botts-Innovative-Research/osh-oakridge-buildnode/issues/46

1. Summary:

This feature request proposes the integration of the WebRelay Quad (https://controlbyweb.com/original-webrelay-quad/) network-enabled relay device into the Oscar system, allowing for automated triggering of physical alarm annunciators and lights for radiation portal monitors. Crucially, this feature will include a selectable option during administration to determine the source of the alarm decision: either relying on Oscar's internal alarm algorithms (including EML) or directly passing through the alarm decisions generated internally by the radiation portal monitor itself. This provides flexibility in how physical alarms are triggered based on operational needs.

2. User Story:

As a security administrator utilizing Oscar with radiation portal monitors, I need the ability to:

• Automate Physical Alarms based on Oscar or RPM Decisions: Have Oscar automatically trigger physical alarms based on either alarm decisions made by Oscar's internal algorithms (like EML) or alarm signals directly from the radiation portal monitor (RPM).
• Select Alarm Decision Source: Choose, during system administration, whether to use Oscar's internal alarm logic or the RPM's internal alarm logic to control the WebRelay and physical alarms.
• Configure WebRelay Integration: Easily configure Oscar to communicate with and control a WebRelay Quad device connected to the radiation portal monitor's alarm system.
• Define Alarm Duration: Set a user-defined duration for the physical alarm to sound (with a default duration provided).
• Control Alarm by Occupancy: Choose an option where the physical alarm continues to sound and light until the radiation portal monitor area is no longer occupied by the alarming item.
• Utilize Standard Protocols: Have Oscar communicate with the WebRelay Quad using documented standard protocols such as XML Control or Modbus, as supported by the device.
• Centralized Alarm Control: Manage both system-level (GUI) alarms and physical alarms through the integrated Oscar platform, providing a unified alarm response system.

3. Detailed Feature Description:

This feature will implement integration with the ControlByWeb WebRelay Quad device and introduce a selectable alarm decision source, allowing users to tailor the physical alarm triggering mechanism.

Key functionalities to be implemented include:

• WebRelay Quad Communication:

  • Protocol Support: Implement communication with the WebRelay Quad using its supported protocols: XML Control and/or Modbus TCP (as documented in https://controlbyweb.com/wp-content/uploads/2024/09/webrelay-quad_um_v2.5.pdf). Initially, XML Control may be a simpler starting point.
  • Network Connectivity: Oscar will need to be able to communicate with the WebRelay Quad over the network.

• Configuration Interface:

  • Enhanced WebRelay Configuration Panel: Create a configuration panel within the Oscar GUI (within the Administration section) to allow users to:
    • Enter the IP address or hostname of the WebRelay Quad device.
    • Select the communication protocol (XML Control or Modbus).
    • Configure the specific output relay on the WebRelay Quad connected to the radiation portal monitor alarm system.
    • Select Alarm Decision Source: Provide a selectable option (e.g., a dropdown menu or radio buttons) to choose the alarm decision source:
      • "Oscar EML Algorithm": Oscar will use its internal alarm detection algorithms (including EML if applicable) to determine when to trigger the WebRelay.
      • "Radiation Portal Monitor Internal Alarm": Oscar will directly monitor an alarm signal from the radiation portal monitor. When the RPM's internal alarm is active, Oscar will trigger the WebRelay.
  • Duration Control Settings: Implement settings to control the duration of the physical alarm, including:
    • User-Defined Duration: Allow users to configure a fixed duration (e.g., in seconds, with a default of 3 seconds) for the WebRelay activation.
    • Occupancy-Based Duration (Optional): Implement an option where the WebRelay output remains active as long as the "alarming occupancy" condition persists (when using Oscar's EML algorithm as the decision source) or as long as the RPM's internal alarm signal is active (when using the RPM internal alarm as the source).

• Alarm Trigger Logic:

  • Decision Source Selection: Oscar will use the configured "Alarm Decision Source" to determine when to trigger the WebRelay.
    • Oscar EML Algorithm Mode: Oscar's internal alarm logic (including EML) will trigger the WebRelay when an "alarming occupancy" is detected.
    • RPM Internal Alarm Mode: Oscar will monitor the selected input source for an alarm signal from the radiation portal monitor. When this signal is active, Oscar will trigger the WebRelay.
  • WebRelay Output Activation and Control: Based on the chosen decision source and configured duration, Oscar will send commands to the WebRelay Quad to activate the designated output relay and control its duration (either fixed or occupancy-based).

• Status Monitoring (Optional): Consider displaying the status of the WebRelay connection, selected alarm decision source, and output relay status in the Oscar GUI.

4. Benefits:

• Automated Physical Alarm Annunciation: Provides immediate and direct physical indication of alarms, enhancing operator awareness.
• Flexibility in Alarm Triggering: Administrators can choose the most appropriate alarm decision source (Oscar's algorithms or RPM internal alarms) based on operational requirements and confidence in each system's detection capabilities.
• Faster Alarm Response: Automating physical alarm triggers and offering direct RPM alarm pass-through can speed up response times.
• Redundancy and Layered Security: Provides a layered approach to alarms with both system-level and physical annunciation.
• Integration with Existing Infrastructure: Utilizes WebRelay hardware and integrates with existing RPM alarm systems.
• Centralized Control via Oscar: Maintains centralized management of alarms through the Oscar platform.

5. Technical Considerations:

• Protocol Implementation (XML/Modbus): Development for WebRelay communication and protocol handling.
• Network Communication: Robust network communication and error handling.
• Configuration UI Enhancements: Development of the configuration panel with the new alarm decision source selection.
• Testing and Validation: Thorough testing of both alarm decision source modes, duration control, and WebRelay integration.

6. Acceptance Criteria:

• Users can successfully configure WebRelay Quad parameters and select the Alarm Decision Source (Oscar EML Algorithm or RPM Internal Alarm) within the Oscar administration panel.
• Oscar can successfully communicate with the WebRelay Quad in both alarm decision source modes.
• In "Oscar EML Algorithm" mode: Oscar triggers the WebRelay and physical alarm based on its internal alarm logic.
• In "Radiation Portal Monitor Internal Alarm" mode: Oscar triggers the WebRelay and physical alarm when the RPM's internal alarm signal is active.
• Users can configure and control the duration of the physical alarm in both modes (fixed duration and optional occupancy-based duration).
• The WebRelay integration and alarm decision source selection are stable and reliable.

7. Conclusion:

By integrating WebRelay Quad with a selectable alarm decision source, Oscar will become a more versatile and adaptable security platform. This feature will provide users with greater control over physical alarm annunciation and allow them to tailor the system to their specific operational context and security protocols. We recommend prioritizing the development of this enhanced WebRelay integration.