From 1a9e1087de4a58a3ac59cd833c534faa9ad45e13 Mon Sep 17 00:00:00 2001 From: Andrew Welker Date: Fri, 27 Jun 2025 10:32:21 -0400 Subject: [PATCH] fix: add property to disable auto mode --- .../Room/Combining/EssentialsRoomCombiner.cs | 105 ++++++++++++++++++ .../EssentialsRoomCombinerPropertiesConfig.cs | 45 ++++++-- 2 files changed, 143 insertions(+), 7 deletions(-) diff --git a/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombiner.cs b/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombiner.cs index f0fb5e98..681f8810 100644 --- a/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombiner.cs +++ b/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombiner.cs @@ -10,6 +10,13 @@ using System.Threading.Tasks; namespace PepperDash.Essentials.Core { + /// + /// Represents a device that manages room combinations by controlling partitions and scenarios. + /// + /// The allows for dynamic configuration of room + /// combinations based on partition states and predefined scenarios. It supports both automatic and manual modes + /// for managing room combinations. In automatic mode, the device determines the current room combination scenario + /// based on partition sensor states. In manual mode, scenarios can be set explicitly by the user. public class EssentialsRoomCombiner : EssentialsDevice, IEssentialsRoomCombiner { private EssentialsRoomCombinerPropertiesConfig _propertiesConfig; @@ -18,6 +25,9 @@ namespace PepperDash.Essentials.Core private List _rooms; + /// + /// Gets a list of rooms represented as key-name pairs. + /// public List Rooms { get @@ -28,6 +38,12 @@ namespace PepperDash.Essentials.Core private bool _isInAutoMode; + /// + /// Gets or sets a value indicating whether the system is operating in automatic mode. + /// + /// Changing this property triggers an update event via + /// IsInAutoModeFeedback.FireUpdate(). Ensure that any event listeners are properly configured to handle + /// this update. public bool IsInAutoMode { get @@ -52,6 +68,19 @@ namespace PepperDash.Essentials.Core private Mutex _scenarioChange = new Mutex(); + /// + /// Initializes a new instance of the class, which manages room combination + /// scenarios and partition states. + /// + /// The class is designed to handle dynamic room + /// combination scenarios based on partition states. It supports both automatic and manual modes for managing + /// room combinations. By default, the instance starts in automatic mode unless the + /// specifies otherwise. After activation, the room combiner initializes partition state providers and sets up + /// the initial room configuration. Additionally, it subscribes to the event to ensure proper initialization of dependent devices + /// before determining or setting the room combination scenario. + /// The unique identifier for the room combiner instance. + /// The configuration properties for the room combiner, including default settings and debounce times. public EssentialsRoomCombiner(string key, EssentialsRoomCombinerPropertiesConfig props) : base(key) { @@ -246,8 +275,16 @@ namespace PepperDash.Essentials.Core #region IEssentialsRoomCombiner Members + /// + /// Occurs when the room combination scenario changes. + /// + /// This event is triggered whenever the configuration or state of the room combination + /// changes. Subscribers can use this event to update their logic or UI based on the new scenario. public event EventHandler RoomCombinationScenarioChanged; + /// + /// Gets the current room combination scenario. + /// public IRoomCombinationScenario CurrentScenario { get @@ -256,10 +293,25 @@ namespace PepperDash.Essentials.Core } } + /// + /// Gets the feedback indicating whether the system is currently in auto mode. + /// public BoolFeedback IsInAutoModeFeedback { get; private set; } + /// + /// Enables auto mode for the room combiner and its partitions, allowing automatic room combination scenarios to + /// be determined. + /// + /// Auto mode allows the room combiner to automatically adjust its configuration based on + /// the state of its partitions. If auto mode is disabled in the configuration, this method logs a warning and + /// does not enable auto mode. public void SetAutoMode() { + if(_propertiesConfig.DisableAutoMode) + { + this.LogWarning("Auto mode is disabled for this room combiner. Cannot set to auto mode."); + return; + } IsInAutoMode = true; foreach (var partition in Partitions) @@ -270,6 +322,12 @@ namespace PepperDash.Essentials.Core DetermineRoomCombinationScenario(); } + /// + /// Switches the system to manual mode, disabling automatic operations. + /// + /// This method sets the system to manual mode by updating the mode state and propagates + /// the change to all partitions. Once in manual mode, automatic operations are disabled for the system and its + /// partitions. public void SetManualMode() { IsInAutoMode = false; @@ -280,6 +338,11 @@ namespace PepperDash.Essentials.Core } } + /// + /// Toggles the current mode between automatic and manual. + /// + /// If the current mode is automatic, this method switches to manual mode. If the + /// current mode is manual, it switches to automatic mode. public void ToggleMode() { if (IsInAutoMode) @@ -292,10 +355,22 @@ namespace PepperDash.Essentials.Core } } + /// + /// Gets the collection of room combination scenarios. + /// public List RoomCombinationScenarios { get; private set; } + /// + /// Gets the collection of partition controllers managed by this instance. + /// public List Partitions { get; private set; } + /// + /// Toggles the state of the partition identified by the specified partition key. + /// + /// If no partition with the specified key exists, the method performs no + /// action. + /// The key of the partition whose state is to be toggled. This value cannot be null or empty. public void TogglePartitionState(string partitionKey) { var partition = Partitions.FirstOrDefault((p) => p.Key.Equals(partitionKey)); @@ -306,6 +381,17 @@ namespace PepperDash.Essentials.Core } } + /// + /// Sets the room combination scenario based on the specified scenario key. + /// + /// This method manually adjusts the partition states according to the specified + /// scenario. If the application is in auto mode, the operation will not proceed, and a log message will be + /// generated indicating that the mode must be set to manual first. If the specified scenario key does not + /// match any existing scenario, a debug log message will be generated. For each partition state in the + /// scenario, the corresponding partition will be updated to either "Present" or "Not Present" based on the + /// scenario's configuration. If a partition key in the scenario cannot be found, a debug log message will be + /// generated. + /// The key identifying the room combination scenario to apply. This must match the key of an existing scenario. public void SetRoomCombinationScenario(string scenarioKey) { if (IsInAutoMode) @@ -354,13 +440,32 @@ namespace PepperDash.Essentials.Core #endregion } + /// + /// Provides a factory for creating instances of devices. + /// + /// This factory is responsible for constructing devices + /// based on the provided configuration. It supports the type name "essentialsroomcombiner" for device + /// creation. public class EssentialsRoomCombinerFactory : EssentialsDeviceFactory { + /// + /// Initializes a new instance of the class. + /// + /// This factory is used to create instances of room combiners with the specified type + /// names. By default, the factory includes the type name "essentialsroomcombiner". public EssentialsRoomCombinerFactory() { TypeNames = new List { "essentialsroomcombiner" }; } + /// + /// Creates and initializes a new instance of the device. + /// + /// This method uses the provided device configuration to extract the properties and + /// create an device. Ensure that the configuration contains valid + /// properties for the device to be created successfully. + /// The device configuration containing the key and properties required to build the device. + /// A new instance of initialized with the specified configuration. public override EssentialsDevice BuildDevice(PepperDash.Essentials.Core.Config.DeviceConfig dc) { Debug.LogMessage(LogEventLevel.Debug, "Factory Attempting to create new EssentialsRoomCombiner Device"); diff --git a/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombinerPropertiesConfig.cs b/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombinerPropertiesConfig.cs index 745f303f..cd6f3f17 100644 --- a/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombinerPropertiesConfig.cs +++ b/src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombinerPropertiesConfig.cs @@ -1,10 +1,4 @@ - - -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using Crestron.SimplSharp; +using System.Collections.Generic; using PepperDash.Core; @@ -17,6 +11,13 @@ namespace PepperDash.Essentials.Core /// public class EssentialsRoomCombinerPropertiesConfig { + /// + /// Gets or sets a value indicating whether the system operates in automatic mode. + /// Some systems don't have partitions sensors, and show shouldn't allow auto mode to be turned on. When this is true in the configuration, + /// auto mode won't be allowed to be turned on. + /// + public bool DisableAutoMode { get; set; } + /// /// The list of partitions that device the rooms /// @@ -47,6 +48,9 @@ namespace PepperDash.Essentials.Core [JsonProperty("defaultScenarioKey")] public string defaultScenarioKey { get; set; } + /// + /// Gets or sets the debounce time, in seconds, for scenario changes. + /// [JsonProperty("scenarioChangeDebounceTimeSeconds")] public int ScenarioChangeDebounceTimeSeconds { get; set; } } @@ -56,9 +60,15 @@ namespace PepperDash.Essentials.Core /// public class PartitionConfig : IKeyName { + /// + /// Gets or sets the unique key associated with the object. + /// [JsonProperty("key")] public string Key { get; set; } + /// + /// Gets or sets the name associated with the object. + /// [JsonProperty("name")] public string Name { get; set; } @@ -80,12 +90,21 @@ namespace PepperDash.Essentials.Core /// public class RoomCombinationScenarioConfig : IKeyName { + /// + /// Gets or sets the key associated with the object. + /// [JsonProperty("key")] public string Key { get; set; } + /// + /// Gets or sets the name associated with the object. + /// [JsonProperty("name")] public string Name { get; set; } + /// + /// Gets or sets the collection of partition states. + /// [JsonProperty("partitionStates")] public List PartitionStates { get; set; } @@ -95,9 +114,15 @@ namespace PepperDash.Essentials.Core [JsonProperty("uiMap")] public Dictionary UiMap { get; set; } + /// + /// Gets or sets the list of actions to be performed during device activation. + /// [JsonProperty("activationActions")] public List ActivationActions { get; set; } + /// + /// Gets or sets the list of actions to be performed when a device is deactivated. + /// [JsonProperty("deactivationActions")] public List DeactivationActions { get; set; } } @@ -107,9 +132,15 @@ namespace PepperDash.Essentials.Core /// public class PartitionState { + /// + /// Gets or sets the partition key used to group and organize data within a storage system. + /// [JsonProperty("partitionKey")] public string PartitionKey { get; set; } + /// + /// Gets or sets a value indicating whether a partition is currently present. + /// [JsonProperty("partitionSensedState")] public bool PartitionPresent { get; set; } }