fix: add property to disable auto mode

src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombiner.cs

@@ -10,6 +10,13 @@ using System.Threading.Tasks;
 
 namespace PepperDash.Essentials.Core
 {
+    /// <summary>
+    /// Represents a device that manages room combinations by controlling partitions and scenarios.
+    /// </summary>
+    /// <remarks>The <see cref="EssentialsRoomCombiner"/> 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.</remarks>
     public class EssentialsRoomCombiner : EssentialsDevice, IEssentialsRoomCombiner
     {
         private EssentialsRoomCombinerPropertiesConfig _propertiesConfig;
@@ -18,6 +25,9 @@ namespace PepperDash.Essentials.Core
 
         private List<IEssentialsRoom> _rooms;
 
+        /// <summary>
+        /// Gets a list of rooms represented as key-name pairs.
+        /// </summary>
         public List<IKeyName> Rooms
         {
             get
@@ -28,6 +38,12 @@ namespace PepperDash.Essentials.Core
 
         private bool _isInAutoMode;
 
+        /// <summary>
+        /// Gets or sets a value indicating whether the system is operating in automatic mode.
+        /// </summary>
+        /// <remarks>Changing this property triggers an update event via
+        /// <c>IsInAutoModeFeedback.FireUpdate()</c>. Ensure that any event listeners are properly configured to handle
+        /// this update.</remarks>
         public bool IsInAutoMode
         {
             get
@@ -52,6 +68,19 @@ namespace PepperDash.Essentials.Core
 
         private Mutex _scenarioChange = new Mutex();
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EssentialsRoomCombiner"/> class, which manages room combination
+        /// scenarios and partition states.
+        /// </summary>
+        /// <remarks>The <see cref="EssentialsRoomCombiner"/> 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 <paramref name="props"/>
+        /// specifies otherwise.  After activation, the room combiner initializes partition state providers and sets up
+        /// the initial room configuration. Additionally, it subscribes to the <see
+        /// cref="DeviceManager.AllDevicesInitialized"/> event to ensure proper initialization of dependent devices
+        /// before determining or setting the room combination scenario.</remarks>
+        /// <param name="key">The unique identifier for the room combiner instance.</param>
+        /// <param name="props">The configuration properties for the room combiner, including default settings and debounce times.</param>
         public EssentialsRoomCombiner(string key, EssentialsRoomCombinerPropertiesConfig props)
             : base(key)
         {
@@ -246,8 +275,16 @@ namespace PepperDash.Essentials.Core
 
         #region IEssentialsRoomCombiner Members
 
+        /// <summary>
+        /// Occurs when the room combination scenario changes.
+        /// </summary>
+        /// <remarks>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.</remarks>
         public event EventHandler<EventArgs> RoomCombinationScenarioChanged;
 
+        /// <summary>
+        /// Gets the current room combination scenario.
+        /// </summary>
         public IRoomCombinationScenario CurrentScenario
         {
             get
@@ -256,10 +293,25 @@ namespace PepperDash.Essentials.Core
             }
         }
 
+        /// <summary>
+        /// Gets the feedback indicating whether the system is currently in auto mode.
+        /// </summary>
         public BoolFeedback IsInAutoModeFeedback { get; private set; }
 
+        /// <summary>
+        /// Enables auto mode for the room combiner and its partitions, allowing automatic room combination scenarios to
+        /// be determined.
+        /// </summary>
+        /// <remarks>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.</remarks>
         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();
         }
 
+        /// <summary>
+        /// Switches the system to manual mode, disabling automatic operations.
+        /// </summary>
+        /// <remarks>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.</remarks>
         public void SetManualMode()
         {
             IsInAutoMode = false;
@@ -280,6 +338,11 @@ namespace PepperDash.Essentials.Core
             }
         }
 
+        /// <summary>
+        /// Toggles the current mode between automatic and manual.
+        /// </summary>
+        /// <remarks>If the current mode is automatic, this method switches to manual mode.  If the
+        /// current mode is manual, it switches to automatic mode.</remarks>
         public void ToggleMode()
         {
             if (IsInAutoMode)
@@ -292,10 +355,22 @@ namespace PepperDash.Essentials.Core
             }
         }
 
+        /// <summary>
+        /// Gets the collection of room combination scenarios.
+        /// </summary>
         public List<IRoomCombinationScenario> RoomCombinationScenarios { get; private set; }
 
+        /// <summary>
+        /// Gets the collection of partition controllers managed by this instance.
+        /// </summary>
         public List<IPartitionController> Partitions { get; private set; }
 
+        /// <summary>
+        /// Toggles the state of the partition identified by the specified partition key.
+        /// </summary>
+        /// <remarks>If no partition with the specified key exists, the method performs no
+        /// action.</remarks>
+        /// <param name="partitionKey">The key of the partition whose state is to be toggled. This value cannot be null or empty.</param>
         public void TogglePartitionState(string partitionKey)
         {
             var partition = Partitions.FirstOrDefault((p) => p.Key.Equals(partitionKey));
@@ -306,6 +381,17 @@ namespace PepperDash.Essentials.Core
             }
         }
 
+        /// <summary>
+        /// Sets the room combination scenario based on the specified scenario key.
+        /// </summary>
+        /// <remarks>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.</remarks>
+        /// <param name="scenarioKey">The key identifying the room combination scenario to apply. This must match the key of an existing scenario.</param>
         public void SetRoomCombinationScenario(string scenarioKey)
         {
             if (IsInAutoMode)
@@ -354,13 +440,32 @@ namespace PepperDash.Essentials.Core
         #endregion
     }
 
+    /// <summary>
+    /// Provides a factory for creating instances of <see cref="EssentialsRoomCombiner"/> devices.
+    /// </summary>
+    /// <remarks>This factory is responsible for constructing <see cref="EssentialsRoomCombiner"/> devices
+    /// based on the provided configuration. It supports the type name "essentialsroomcombiner" for device
+    /// creation.</remarks>
     public class EssentialsRoomCombinerFactory : EssentialsDeviceFactory<EssentialsRoomCombiner>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EssentialsRoomCombinerFactory"/> class.
+        /// </summary>
+        /// <remarks>This factory is used to create instances of room combiners with the specified type
+        /// names. By default, the factory includes the type name "essentialsroomcombiner".</remarks>
         public EssentialsRoomCombinerFactory()
         {
             TypeNames = new List<string> { "essentialsroomcombiner" };
         }
 
+        /// <summary>
+        /// Creates and initializes a new instance of the <see cref="EssentialsRoomCombiner"/> device.
+        /// </summary>
+        /// <remarks>This method uses the provided device configuration to extract the properties and
+        /// create an  <see cref="EssentialsRoomCombiner"/> device. Ensure that the configuration contains valid 
+        /// properties for the device to be created successfully.</remarks>
+        /// <param name="dc">The device configuration containing the key and properties required to build the device.</param>
+        /// <returns>A new instance of <see cref="EssentialsRoomCombiner"/> initialized with the specified configuration.</returns>
         public override EssentialsDevice BuildDevice(PepperDash.Essentials.Core.Config.DeviceConfig dc)
         {
             Debug.LogMessage(LogEventLevel.Debug, "Factory Attempting to create new EssentialsRoomCombiner Device");

src/PepperDash.Essentials.Core/Room/Combining/EssentialsRoomCombinerPropertiesConfig.cs

@@ -1,10 +1,4 @@
-
+using System.Collections.Generic;
-
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using Crestron.SimplSharp;
 
 using PepperDash.Core;
 
@@ -17,6 +11,13 @@ namespace PepperDash.Essentials.Core
     /// </summary>
     public class EssentialsRoomCombinerPropertiesConfig
     {
+        /// <summary>
+        /// Gets or sets a value indicating whether the system operates in automatic mode.
+        /// <remarks>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.</remarks>
+        /// </summary>
+        public bool DisableAutoMode { get; set; }
+
         /// <summary>
         /// The list of partitions that device the rooms
         /// </summary>
@@ -47,6 +48,9 @@ namespace PepperDash.Essentials.Core
         [JsonProperty("defaultScenarioKey")]
         public string defaultScenarioKey { get; set; }
 
+        /// <summary>
+        /// Gets or sets the debounce time, in seconds, for scenario changes.
+        /// </summary>
         [JsonProperty("scenarioChangeDebounceTimeSeconds")]
         public int ScenarioChangeDebounceTimeSeconds { get; set; }
     }
@@ -56,9 +60,15 @@ namespace PepperDash.Essentials.Core
     /// </summary>
     public class PartitionConfig : IKeyName
     {
+        /// <summary>
+        /// Gets or sets the unique key associated with the object.
+        /// </summary>
         [JsonProperty("key")]
         public string Key { get; set; }
 
+        /// <summary>
+        /// Gets or sets the name associated with the object.
+        /// </summary>
         [JsonProperty("name")]
         public string Name { get; set; }
 
@@ -80,12 +90,21 @@ namespace PepperDash.Essentials.Core
     /// </summary>
     public class RoomCombinationScenarioConfig : IKeyName
     {
+        /// <summary>
+        /// Gets or sets the key associated with the object.
+        /// </summary>
         [JsonProperty("key")]
         public string Key { get; set; }
 
+        /// <summary>
+        /// Gets or sets the name associated with the object.
+        /// </summary>
         [JsonProperty("name")]
         public string Name { get; set; }
 
+        /// <summary>
+        /// Gets or sets the collection of partition states.
+        /// </summary>
         [JsonProperty("partitionStates")]
         public List<PartitionState> PartitionStates { get; set; }
 
@@ -95,9 +114,15 @@ namespace PepperDash.Essentials.Core
         [JsonProperty("uiMap")]
         public Dictionary<string, string> UiMap { get; set; }
 
+        /// <summary>
+        /// Gets or sets the list of actions to be performed during device activation.
+        /// </summary>
         [JsonProperty("activationActions")]
         public List<DeviceActionWrapper> ActivationActions { get; set; }
 
+        /// <summary>
+        /// Gets or sets the list of actions to be performed when a device is deactivated.
+        /// </summary>
         [JsonProperty("deactivationActions")]
         public List<DeviceActionWrapper> DeactivationActions { get; set; }    
     }
@@ -107,9 +132,15 @@ namespace PepperDash.Essentials.Core
     /// </summary>
     public class PartitionState
     {
+        /// <summary>
+        /// Gets or sets the partition key used to group and organize data within a storage system.
+        /// </summary>
         [JsonProperty("partitionKey")]
         public string PartitionKey { get; set; }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether a partition is currently present.
+        /// </summary>
         [JsonProperty("partitionSensedState")]
         public bool PartitionPresent { get; set; }
     }