Updates files to included extensive inline documentation and TODOs

PDT.EssentialsPluginTemplate.EPI/EssentialsPluginTemplateFactory.cs

@@ -1,43 +1,92 @@
-using System;
-using System.Collections.Generic;
-using Crestron.SimplSharp;                          				// For Basic SIMPL# Classes
-using Crestron.SimplSharpPro;                       				// For Basic SIMPL#Pro classes
-
-using Newtonsoft.Json;
-using Newtonsoft.Json.Linq;
-
-using PepperDash.Essentials;
-using PepperDash.Essentials.Core;
-using PepperDash.Essentials.Core.Config;
+using System.Collections.Generic;
 using PepperDash.Core;
+using PepperDash.Essentials.Core;
 
-namespace EssentialsPluginTemplateEPI 
+namespace EssentialsPluginTemplate
 {
-    /// <summary>
-    /// This class contains the necessary properties and methods required to function as an Essentials Plugin
-    /// </summary>
-	public class EssentialsPluginFactory:EssentialsPluginDeviceFactory<EssentialsPluginTemplateDevice>
+	/// <summary>
+	/// Plugin device factory
+	/// </summary>
+	/// <remarks>
+	/// Rename the class to match the device plugin being developed
+	/// </remarks>
+	/// <example>
+	/// "EssentialsPluginFactoryTemplate" renamed to "SamsungMdcFactory"
+	/// </example>
+    public class EssentialsPluginFactoryTemplate : EssentialsPluginDeviceFactory<EssentialsPluginDeviceTemplate>
     {
-        public EssentialsPluginFactory()
+		/// <summary>
+		/// Plugin device factory constructor
+		/// </summary>
+		/// <remarks>
+		/// Update the MinimumEssentialsFrameworkVersion & TypeNames as needed when creating a plugin
+		/// </remarks>
+		/// <example>
+		/// <code>
+		/// // Set the minimum Essentials Framework Version
+		/// MinimumEssentialsFrameworkVersion = "1.5.5";
+		/// // In the constructor we initialize the list with the typenames that will build an instance of this device
+#pragma warning disable 1570
+		/// TypeNames = new List<string>() { "SamsungMdc", "SamsungMdcDisplay" };
+#pragma warning restore 1570
+		/// </code>
+		/// </example>
+        public EssentialsPluginFactoryTemplate()
         {
-            // This string is used to define the minimum version of the
-            // Essentials Framework required for this plugin
-            MinimumEssentialsFrameworkVersion = "1.6.1";
+            // Set the minimum Essentials Framework Version
+			// TODO [ ] Update the Essentials minimum framework version which this plugin has been tested against
+			MinimumEssentialsFrameworkVersion = "1.6.4";
 
-            //The strings defined in this list will be used in the configuration file to build the device in this plugin.
-            TypeNames = new List<string> {"essentialsPluginTemplateDevice"};
+            // In the constructor we initialize the list with the typenames that will build an instance of this device
+			// TODO [ ] Update the TypeNames for the plugin being developed
+            TypeNames = new List<string>() { "examplePluginDevice" };
+        }
+        
+		/// <summary>
+		/// Builds and returns an instance of EssentialsPluginDeviceTemplate
+		/// </summary>
+		/// <param name="dc">device configuration</param>
+		/// <returns>plugin device or null</returns>
+		/// <remarks>		
+		/// The example provided below takes the device key, name, properties config and the comms device created.
+		/// Modify the EssetnialsPlugingDeviceTemplate constructor as needed to meet the requirements of the plugin device.
+		/// </remarks>
+		/// <seealso cref="PepperDash.Core.eControlMethod"/>
+        public override EssentialsDevice BuildDevice(PepperDash.Essentials.Core.Config.DeviceConfig dc)
+        {
+            Debug.Console(1, "[{0}] Factory Attempting to create new device from type: {1}", dc.Key, dc.Type);	       
+
+			// get the plugin device properties configuration object & check for null 
+            var propertiesConfig = dc.Properties.ToObject<EssentialsPluginConfigObjectTemplate>();
+	        if (propertiesConfig == null)
+	        {
+		        Debug.Console(0, "[{0}] Factory: failed to read properties config for {1}", dc.Key, dc.Name);
+		        return null;
+	        }
+
+			// TODO [ ] Discuss with Andrew/Neil on recommended best practice 
+			
+			// Method 1
+			//var username = dc.Properties["control"].Value<TcpSshPropertiesConfig>("tcpSshProperties").Username;
+			//var password = dc.Properties["control"].Value<TcpSshPropertiesConfig>("tcpSshProperties").Password;
+			//var method = dc.Properties["control"].Value<string>("method");
+			
+			// Method 2 - Returns a JValue, has to be casted to string
+	        var username = (string)dc.Properties["control"]["tcpSshProperties"]["username"];
+			var password = (string)dc.Properties["control"]["tcpSshProperties"]["password"];
+	        var method = (string)dc.Properties["control"]["method"];
+	        
+			// build the plugin device comms & check for null
+			// TODO { ] As of PepperDash Core 1.0.41, HTTP and HTTPS are not valid eControlMethods and will throw an exception.
+			var comms = CommFactory.CreateCommForDevice(dc);
+			if (comms == null)
+			{
+				Debug.Console(0, "[{0}] Factory: failed to create comm for {1}", dc.Key, dc.Name);
+				return null;
+			}
+
+            return new EssentialsPluginDeviceTemplate(dc.Key, dc.Name, propertiesConfig, comms);
         }
 
-        #region Overrides of EssentialsDeviceFactory<EssentialsPluginTemplateDevice>
-
-        public override EssentialsDevice BuildDevice(DeviceConfig dc)
-        {
-            var config = dc.Properties.ToObject<EssentialsPluginTemplatePropertiesConfig>();
-			var newDevice = new EssentialsPluginTemplateDevice(dc.Key, dc.Name, config);
-			return newDevice;
-        }
-
-        #endregion
     }
-}
-
+}