feat: Add camera control interfaces and messenger classes

This commit introduces new interfaces in `CameraControl.cs` for various camera functionalities, including muting, panning, tilting, zooming, and auto modes. The `IHasCameras` interface is expanded to manage camera lists and selections, with the addition of `CameraSelectedEventArgs` for event handling.

In `CameraBaseMessenger.cs`, a new `IHasCamerasMessenger` class is created to facilitate communication for devices implementing the `IHasCameras` interface, along with the `IHasCamerasStateMessage` class to represent the state of camera devices. These changes enhance the overall camera control capabilities and improve interaction management within the application.

.gitignore

@@ -393,4 +393,5 @@ essentials-framework/Essentials Interfaces/PepperDash_Essentials_Interfaces/Pepp
 /._PepperDash.Essentials.sln
 .vscode/settings.json
 _site/
-api/
+api/
+*.DS_Store

src/PepperDash.Essentials.Core/DeviceTypeInterfaces/IHasScreensWithLayouts.cs

@@ -17,6 +17,13 @@ namespace PepperDash.Essentials.Core.DeviceTypeInterfaces
         /// A dictionary of screens, keyed by screen ID, that contains information about each screen and its layouts.
         /// </summary>
         Dictionary<uint, ScreenInfo> Screens { get; }
+
+        /// <summary>
+        /// Applies a specific layout to a screen based on the provided screen ID and layout index.
+        /// </summary>
+        /// <param name="screenId"></param>
+        /// <param name="layoutIndex"></param>
+        void ApplyLayout(uint screenId, uint layoutIndex);
     }
 
     /// <summary>

src/PepperDash.Essentials.Core/Devices/LevelControlListItem.cs

@@ -9,10 +9,15 @@ using PepperDash.Essentials.Core.Devices;
 
 namespace PepperDash.Essentials.Core
 {
+    /// <summary>
+    /// Represents a level control item in a list, which can be used to control volume or mute functionality.
+    /// </summary>
     public class LevelControlListItem : AudioControlListItemBase
     {
 
-
+        /// <summary>
+        /// A reference to the IBasicVolumeWithFeedback device for control.
+        /// </summary>
         [JsonIgnore]
         public IBasicVolumeWithFeedback LevelControl
         {
@@ -55,7 +60,7 @@ namespace PepperDash.Essentials.Core
         {
             get
             {
-                if(string.IsNullOrEmpty(ItemKey)) return ParentDeviceKey;
+                if (string.IsNullOrEmpty(ItemKey)) return ParentDeviceKey;
                 else
                 {
                     return DeviceManager.AllDevices.
@@ -70,13 +75,39 @@ namespace PepperDash.Essentials.Core
         [JsonProperty("type")]
         [JsonConverter(typeof(Newtonsoft.Json.Converters.StringEnumConverter))]
         public eLevelControlType Type { get; set; }
+
+
+        /// <summary>
+        /// Indicates if the item is a mic or not.
+        /// </summary>
+        [JsonProperty("isMic", NullValueHandling = NullValueHandling.Ignore)]
+        public bool? IsMic { get; set; }
+
+        /// <summary>
+        /// Indicates if the item should show the raw level in the UI.
+        /// </summary>
+        [JsonProperty("showRawLevel", NullValueHandling = NullValueHandling.Ignore)]
+        public bool? ShowRawLevel { get; set; }
     }
 
+    /// <summary>
+    /// Indicates the type of level control item.
+    /// </summary>
     [Flags]
     public enum eLevelControlType
     {
+        /// <summary>
+        /// Indicates that the item is a level control only
+        /// </summary>
         Level = 1,
+        /// <summary>
+        /// Indicates that the item is a mute control only
+        /// </summary>
         Mute = 2,
+        /// <summary>
+        /// Indicates that the item is both a level and mute control
+        /// </summary>
         LevelAndMute = Level | Mute,
     }
+
 }

src/PepperDash.Essentials.Core/Devices/SourceListItem.cs

@@ -10,7 +10,18 @@ namespace PepperDash.Essentials.Core
     /// </summary>
     public enum eSourceListItemType
     {
-        Route, Off, Other, SomethingAwesomerThanThese
+        /// <summary>
+        /// Represents a typical route.
+        /// </summary>
+        Route,
+        /// <summary>
+        /// Represents an off route.
+        /// </summary>
+        Off,
+        /// <summary>
+        /// Represents some other type of route
+        /// </summary>
+        Other,
     }
 
     /// <summary>
@@ -18,6 +29,9 @@ namespace PepperDash.Essentials.Core
     /// </summary>
     public class SourceListItem
     {
+        /// <summary>
+        /// The key of the source item, which is used to identify it in the DeviceManager
+        /// </summary>
         [JsonProperty("sourceKey")]
         public string SourceKey { get; set; }
 
@@ -117,6 +131,9 @@ namespace PepperDash.Essentials.Core
 		[JsonProperty("disableRoutedSharing")]
         public bool DisableRoutedSharing { get; set; }
 
+        /// <summary>
+        /// 
+        /// </summary>
         [JsonProperty("destinations")]
         public List<eSourceListItemDestinationTypes> Destinations { get; set; }
         /// <summary>
@@ -149,31 +166,56 @@ namespace PepperDash.Essentials.Core
         [JsonProperty("disableSimpleRouting")]
         public bool DisableSimpleRouting { get; set; }
 
+        /// <summary>
+        /// Default constructor for SourceListItem, initializes the Icon to "Blank"
+        /// </summary>
         public SourceListItem()
         {
             Icon = "Blank";
         }
 
+        /// <summary>
+        /// Returns a string representation of the SourceListItem, including the SourceKey and Name
+        /// </summary>
+        /// <returns></returns>
         public override string ToString()
         {
             return $"{SourceKey}:{Name}";
         }
     }
 
+    /// <summary>
+    /// Represents a route in a source list item, which defines the source and destination keys and the type of signal being routed
+    /// </summary>
     public class SourceRouteListItem
     {
+        /// <summary>
+        /// The key of the source device to route from
+        /// </summary>
         [JsonProperty("sourceKey")]
         public string SourceKey { get; set; }
 
+        /// <summary>
+        /// The key of the source port to route from
+        /// </summary>
         [JsonProperty("sourcePortKey")]
         public string SourcePortKey { get; set; }
 
+        /// <summary>
+        /// The key of the destination device to route to
+        /// </summary>
         [JsonProperty("destinationKey")]
         public string DestinationKey { get; set; }
 
+        /// <summary>
+        /// The key of the destination port to route to
+        /// </summary>
         [JsonProperty("destinationPortKey")]
         public string DestinationPortKey { get; set; }
 
+        /// <summary>
+        /// The type of signal being routed, such as audio or video
+        /// </summary>
         [JsonProperty("type")]
         public eRoutingSignalType Type { get; set; }
     }
@@ -183,15 +225,85 @@ namespace PepperDash.Essentials.Core
     /// </summary>
     public enum eSourceListItemDestinationTypes
     {
+        /// <summary>
+        /// Default display, used for the main video output in a room
+        /// </summary>
         defaultDisplay,
+        /// <summary>
+        /// Left display
+        /// </summary>
         leftDisplay,
+        /// <summary>
+        /// Right display
+        /// </summary>
         rightDisplay,
+        /// <summary>
+        /// Center display
+        /// </summary>
         centerDisplay,
+        /// <summary>
+        /// Program audio, used for the main audio output in a room
+        /// </summary>
         programAudio,
+        /// <summary>
+        /// Codec content, used for sharing content to the far end in a video call
+        /// </summary>
         codecContent,
+        /// <summary>
+        /// Front left display, used for rooms with multiple displays
+        /// </summary>
         frontLeftDisplay,
+        /// <summary>
+        /// Front right display, used for rooms with multiple displays
+        /// </summary>
         frontRightDisplay,
+        /// <summary>
+        /// Rear left display, used for rooms with multiple displays
+        /// </summary>
         rearLeftDisplay,
+        /// <summary>
+        /// Rear right display, used for rooms with multiple displays
+        /// </summary>
         rearRightDisplay,
+        /// <summary>
+        /// Auxiliary display 1, used for additional displays in a room
+        /// </summary>
+        auxDisplay1,
+        /// <summary>
+        /// Auxiliary display 2, used for additional displays in a room
+        /// </summary>
+        auxDisplay2,
+        /// <summary>
+        /// Auxiliary display 3, used for additional displays in a room
+        /// </summary>
+        auxDisplay3,
+        /// <summary>
+        /// Auxiliary display 4, used for additional displays in a room
+        /// </summary>
+        auxDisplay4,
+        /// <summary>
+        /// Auxiliary display 5, used for additional displays in a room
+        /// </summary>
+        auxDisplay5,
+        /// <summary>
+        /// Auxiliary display 6, used for additional displays in a room
+        /// </summary>
+        auxDisplay6,
+        /// <summary>
+        /// Auxiliary display 7, used for additional displays in a room
+        /// </summary>
+        auxDisplay7,
+        /// <summary>
+        /// Auxiliary display 8, used for additional displays in a room
+        /// </summary>
+        auxDisplay8,
+        /// <summary>
+        /// Auxiliary display 9, used for additional displays in a room
+        /// </summary>
+        auxDisplay9,
+        /// <summary>
+        /// Auxiliary display 10, used for additional displays in a room
+        /// </summary>
+        auxDisplay10,
     }
 }

src/PepperDash.Essentials.Core/Routing/IRoutingSink.cs

@@ -7,8 +7,14 @@
     {        
     }
 
+    /// <summary>
+    /// For fixed-source endpoint devices with an input port
+    /// </summary>
     public interface IRoutingSinkWithInputPort :IRoutingSink
     {
+        /// <summary>
+        /// Gets the current input port for this routing sink.
+        /// </summary>
         RoutingInputPort CurrentInputPort { get; }
     }
     /*/// <summary>

src/PepperDash.Essentials.Devices.Common/Cameras/CameraControl.cs

@@ -3,29 +3,60 @@ using System.Collections.Generic;
 using System.Linq;
 using System.Text;
 using Crestron.SimplSharp;
-
+using PepperDash.Core;
 using PepperDash.Essentials.Core;
 
 namespace PepperDash.Essentials.Devices.Common.Cameras
 {
+    /// <summary>
+    /// Enum for camera control modes
+    /// </summary>
     public enum eCameraControlMode
-    {       
+    {
+        /// <summary>
+        /// Manual control mode, where the camera is controlled directly by the user or system
+        /// </summary>
         Manual = 0,
+        /// <summary>
+        /// Off control mode, where the camera is turned off or disabled
+        /// </summary>
         Off,
+        /// <summary>
+        ///  Auto control mode, where the camera automatically adjusts settings based on the environment or conditions
+        /// </summary>
         Auto
     }
 
 
-    public interface IHasCameras
+    /// <summary>
+    /// Interface for devices that have cameras
+    /// </summary>
+    public interface IHasCameras : IKeyName
     {
+        /// <summary>
+        /// Event that is raised when a camera is selected
+        /// </summary>
         event EventHandler<CameraSelectedEventArgs> CameraSelected;
 
+        /// <summary>
+        /// List of cameras on the device.  This should be a list of CameraBase objects
+        /// </summary>
         List<CameraBase> Cameras { get; }
 
+        /// <summary>
+        /// The currently selected camera.  This should be a CameraBase object
+        /// </summary>
         CameraBase SelectedCamera { get; }
 
+        /// <summary>
+        /// Feedback that indicates the currently selected camera
+        /// </summary>
         StringFeedback SelectedCameraFeedback { get; }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="key"></param>
         void SelectCamera(string key);
     }
 
@@ -42,7 +73,14 @@ namespace PepperDash.Essentials.Devices.Common.Cameras
     /// </summary>
     public interface IHasCameraOff
     {
+        /// <summary>
+        /// Feedback that indicates whether the camera is off
+        /// </summary>
         BoolFeedback CameraIsOffFeedback { get; }
+
+        /// <summary>
+        /// Turns the camera off, blanking the near end video
+        /// </summary>
         void CameraOff();
     }
 
@@ -51,31 +89,71 @@ namespace PepperDash.Essentials.Devices.Common.Cameras
     /// </summary>
     public interface IHasCameraMute
     {
+        /// <summary>
+        /// Feedback that indicates whether the camera is muted
+        /// </summary>
         BoolFeedback CameraIsMutedFeedback { get; }
+
+        /// <summary>
+        /// Mutes the camera video, preventing it from being sent to the far end
+        /// </summary>
         void CameraMuteOn();
+
+        /// <summary>
+        /// Unmutes the camera video, allowing it to be sent to the far end
+        /// </summary>
         void CameraMuteOff();
+
+        /// <summary>
+        /// Toggles the camera mute state. If the camera is muted, it will be unmuted, and vice versa.
+        /// </summary>
         void CameraMuteToggle();
     }
 
+    /// <summary>
+    /// Interface for devices that can mute and unmute their camera video, with an event for unmute requests
+    /// </summary>
     public interface IHasCameraMuteWithUnmuteReqeust : IHasCameraMute
     {
+        /// <summary>
+        /// Event that is raised when a video unmute is requested, typically by the far end
+        /// </summary>
         event EventHandler VideoUnmuteRequested;
     }
 
+    /// <summary>
+    /// Event arguments for the CameraSelected event
+    /// </summary>
     public class CameraSelectedEventArgs : EventArgs
     {
+        /// <summary>
+        /// The selected camera
+        /// </summary>
         public CameraBase SelectedCamera { get; private set; }
 
+        /// <summary>
+        /// Constructor for CameraSelectedEventArgs
+        /// </summary>
+        /// <param name="camera"></param>
         public CameraSelectedEventArgs(CameraBase camera)
         {
             SelectedCamera = camera;
         }
     }
 
+    /// <summary>
+    /// Interface for devices that have a far end camera control
+    /// </summary>
     public interface IHasFarEndCameraControl
     {
+        /// <summary>
+        /// Gets the far end camera, which is typically a CameraBase object that represents the camera at the far end of a call
+        /// </summary>
         CameraBase FarEndCamera { get; }
 
+        /// <summary>
+        /// Feedback that indicates whether the far end camera is being controlled
+        /// </summary>
         BoolFeedback ControllingFarEndCameraFeedback { get; }
 
     }
@@ -88,6 +166,9 @@ namespace PepperDash.Essentials.Devices.Common.Cameras
 
     }
 
+    /// <summary>
+    /// Interface for devices that have camera controls
+    /// </summary>
     public interface IHasCameraControls
     {
     }
@@ -108,8 +189,19 @@ namespace PepperDash.Essentials.Devices.Common.Cameras
     /// </summary>
     public interface IHasCameraPanControl : IHasCameraControls
     {
+        /// <summary>
+        /// Pans the camera left
+        /// </summary>
         void PanLeft();
+
+        /// <summary>
+        /// Pans the camera right
+        /// </summary>
         void PanRight();
+
+        /// <summary>
+        /// Stops the camera pan movement
+        /// </summary>
         void PanStop();
     }
 
@@ -118,8 +210,19 @@ namespace PepperDash.Essentials.Devices.Common.Cameras
     /// </summary>
     public interface IHasCameraTiltControl : IHasCameraControls
     {
+        /// <summary>
+        /// Tilts the camera down
+        /// </summary>
         void TiltDown();
+
+        /// <summary>
+        /// Tilts the camera up
+        /// </summary>
         void TiltUp();
+
+        /// <summary>
+        /// Stops the camera tilt movement
+        /// </summary>
         void TiltStop();
     }
 
@@ -128,8 +231,19 @@ namespace PepperDash.Essentials.Devices.Common.Cameras
     /// </summary>
     public interface IHasCameraZoomControl : IHasCameraControls
     {
+        /// <summary>
+        /// Zooms the camera in
+        /// </summary>
         void ZoomIn();
+
+        /// <summary>
+        /// Zooms the camera out
+        /// </summary>
         void ZoomOut();
+
+        /// <summary>
+        /// Stops the camera zoom movement
+        /// </summary>
         void ZoomStop();
     }
 
@@ -138,25 +252,71 @@ namespace PepperDash.Essentials.Devices.Common.Cameras
     /// </summary>
     public interface IHasCameraFocusControl : IHasCameraControls
     {
+        /// <summary>
+        /// Focuses the camera near
+        /// </summary>
         void FocusNear();
+
+        /// <summary>
+        /// Focuses the camera far
+        /// </summary>
         void FocusFar();
+
+        /// <summary>
+        /// Stops the camera focus movement
+        /// </summary>
         void FocusStop();
 
+        /// <summary>
+        /// Triggers the camera's auto focus functionality, if available.
+        /// </summary>
         void TriggerAutoFocus();
     }
 
+    /// <summary>
+    /// Interface for devices that have auto focus mode control
+    /// </summary>
     public interface IHasAutoFocusMode
     {
+        /// <summary>
+        /// Sets the focus mode to auto or manual, or toggles between them.
+        /// </summary>
         void SetFocusModeAuto();
+
+        /// <summary>
+        /// Sets the focus mode to manual, allowing for manual focus adjustments.
+        /// </summary>
         void SetFocusModeManual();
+
+        /// <summary>
+        /// Toggles the focus mode between auto and manual.
+        /// </summary>
         void ToggleFocusMode();
     }
 
+    /// <summary>
+    /// Interface for devices that have camera auto mode control
+    /// </summary>
     public interface IHasCameraAutoMode : IHasCameraControls
     {
+        /// <summary>
+        /// Enables or disables the camera's auto mode, which may include automatic adjustments for focus, exposure, and other settings.
+        /// </summary>
         void CameraAutoModeOn();
+
+        /// <summary>
+        /// Disables the camera's auto mode, allowing for manual control of camera settings.
+        /// </summary>
         void CameraAutoModeOff();
+
+        /// <summary>
+        /// Toggles the camera's auto mode state. If the camera is in auto mode, it will switch to manual mode, and vice versa.
+        /// </summary>
         void CameraAutoModeToggle();
+
+        /// <summary>
+        /// Feedback that indicates whether the camera's auto mode is currently enabled.
+        /// </summary>
         BoolFeedback CameraAutoModeIsOnFeedback { get; }
     }
 

src/PepperDash.Essentials.Devices.Common/Codec/Cisco/IPresenterTrack.cs

@@ -48,7 +48,7 @@ namespace PepperDash.Essentials.Devices.Common.Codec.Cisco
         BoolFeedback PresenterTrackAvailableFeedback { get; }
 
         /// <summary>
-        /// Feedback indicateing the current status of Presenter Track is off
+        /// Feedback indicating the current status of Presenter Track is off
         /// </summary>
         BoolFeedback PresenterTrackStatusOffFeedback { get; }
 

src/PepperDash.Essentials.MobileControl.Messengers/Messengers/CameraBaseMessenger.cs

@@ -6,11 +6,14 @@ using System.Collections.Generic;
 
 namespace PepperDash.Essentials.AppServer.Messengers
 {
+    /// <summary>
+    /// Messenger for a CameraBase device
+    /// </summary>
     public class CameraBaseMessenger : MessengerBase
     {
         /// <summary>
         /// Device being bridged
-        /// </summary>
+        /// </summary>  
         public CameraBase Camera { get; set; }
 
         /// <summary>
@@ -45,6 +48,9 @@ namespace PepperDash.Essentials.AppServer.Messengers
             );
         }
 
+        /// <summary>
+        /// Registers the actions for this messenger.  This is called by the base class
+        /// </summary>
         protected override void RegisterActions()
         {
             base.RegisterActions();

src/PepperDash.Essentials.MobileControl.Messengers/Messengers/IHasCamerasMessenger.cs

@@ -0,0 +1,104 @@
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using PepperDash.Essentials.Devices.Common.Cameras;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace PepperDash.Essentials.AppServer.Messengers
+{
+    /// <summary>
+    /// Messenger for devices that implement the IHasCameras interface.
+    /// </summary>
+    public class IHasCamerasMessenger : MessengerBase
+    {
+        /// <summary>
+        /// Device being bridged that implements IHasCameras interface.
+        /// </summary>
+        public IHasCameras CameraController { get; private set; }
+
+        /// <summary>
+        /// Messenger for devices that implement IHasCameras interface.
+        /// </summary>
+        /// <param name="key"></param>
+        /// <param name="cameraController"></param>
+        /// <param name="messagePath"></param>
+        /// <exception cref="ArgumentNullException"></exception>
+        public IHasCamerasMessenger(string key, IHasCameras cameraController, string messagePath)
+            : base(key, messagePath, cameraController)
+        {
+            CameraController = cameraController ?? throw new ArgumentNullException("cameraController");
+            CameraController.CameraSelected += CameraController_CameraSelected;
+        }
+
+        private void CameraController_CameraSelected(object sender, CameraSelectedEventArgs e)
+        {
+            PostStatusMessage(new IHasCamerasStateMessage
+            {
+                SelectedCamera = e.SelectedCamera
+            });
+        }
+
+        /// <summary>
+        /// Registers the actions for this messenger.
+        /// </summary>
+        /// <exception cref="ArgumentException"></exception>
+        protected override void RegisterActions()
+        {
+            base.RegisterActions();
+
+            AddAction("/fullStatus", (id, context) =>
+            {
+                SendFullStatus();
+            });
+
+            AddAction("/selectCamera", (id, content) =>
+            {
+                var cameraKey = content?.ToObject<string>();
+
+                if (!string.IsNullOrEmpty(cameraKey))
+                {
+                    CameraController.SelectCamera(cameraKey);
+                }
+                else
+                {
+                    throw new ArgumentException("Content must be a string representing the camera key");
+                }
+            });
+        }
+
+        private void SendFullStatus()
+        {
+            var state = new IHasCamerasStateMessage
+            {
+                CameraList = CameraController.Cameras,
+                SelectedCamera = CameraController.SelectedCamera
+            };
+
+            PostStatusMessage(state);
+        }
+
+
+    }
+
+    /// <summary>
+    /// State message for devices that implement the IHasCameras interface.
+    /// </summary>
+    public class IHasCamerasStateMessage : DeviceStateMessageBase
+    {
+        /// <summary>
+        /// List of cameras available in the device.
+        /// </summary>
+        [JsonProperty("cameraList", NullValueHandling = NullValueHandling.Ignore)]
+        public List<CameraBase> CameraList { get; set; }
+
+        /// <summary>
+        /// The currently selected camera on the device.
+        /// </summary>
+        [JsonProperty("selectedCamera", NullValueHandling = NullValueHandling.Ignore)]
+        public CameraBase SelectedCamera { get; set; }
+
+    }
+}