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; }
}