Merge pull request #13 from PepperDash/feature/clarify-device-creation-cases

Clarify device creation cases

Author: andrew-welker

PDT.EssentialsPluginTemplate.EPI/EssentialsPluginTemplateCrestronDevice.cs

@@ -0,0 +1,99 @@
+// For Basic SIMPL# Classes
+// For Basic SIMPL#Pro classes
+
+using Crestron.SimplSharpPro.DeviceSupport;
+using Crestron.SimplSharpPro;
+using PepperDash.Core;
+using PepperDash.Essentials.Core;
+using PepperDash.Essentials.Core.Bridges;
+
+namespace EssentialsPluginTemplate
+{
+	/// <summary>
+	/// Plugin device
+	/// </summary>
+	/// <remarks>
+	/// Rename the class to match the device plugin being developed.
+	/// </remarks>
+	/// <example>
+	/// "EssentialsPluginDeviceTemplate" renamed to "SamsungMdcDevice"
+	/// </example>
+	public class EssentialsPluginTemplateCrestronDevice : CrestronGenericBridgeableBaseDevice
+    {
+        /// <summary>
+        /// It is often desirable to store the config
+        /// </summary>
+        private EssentialsPluginConfigObjectTemplate _config;
+
+
+        #region Constructor for Devices without IBasicCommunication.  Remove if not needed
+        /// <summary>
+        /// Plugin device constructor for Crestron devices
+        /// </summary>
+        /// <param name="key"></param>
+        /// <param name="name"></param>
+        /// <param name="config"></param>
+        /// <param name="hardware"></param>
+        public EssentialsPluginTemplateCrestronDevice(string key, string name, EssentialsPluginConfigObjectTemplate config, GenericBase hardware)
+            : base(key, name, hardware)
+        {
+            Debug.Console(0, this, "Constructing new {0} instance", name);
+
+            // The base class takes care of registering the hardware device for you
+
+            // TODO [ ] Update the constructor as needed for the plugin device being developed
+
+            _config = config;
+        }
+
+        #endregion
+
+
+        #region Overrides of EssentialsBridgeableDevice
+
+        /// <summary>
+        /// Links the plugin device to the EISC bridge
+        /// </summary>
+        /// <param name="trilist"></param>
+        /// <param name="joinStart"></param>
+        /// <param name="joinMapKey"></param>
+        /// <param name="bridge"></param>
+        public override void LinkToApi(BasicTriList trilist, uint joinStart, string joinMapKey, EiscApiAdvanced bridge)
+        {
+            var joinMap = new EssentialsPluginBridgeJoinMapTemplate(joinStart);
+
+            // This adds the join map to the collection on the bridge
+            if (bridge != null)
+            {
+                bridge.AddJoinMap(Key, joinMap);
+            }
+
+            var customJoins = JoinMapHelper.TryGetJoinMapAdvancedForDevice(joinMapKey);
+
+            if (customJoins != null)
+            {
+                joinMap.SetCustomJoinData(customJoins);
+            }
+
+            Debug.Console(1, "Linking to Trilist '{0}'", trilist.ID.ToString("X"));
+            Debug.Console(0, "Linking to Bridge Type {0}", GetType().Name);
+
+            // TODO [ ] Implement bridge links as needed
+
+            // links to bridge
+            trilist.SetString(joinMap.DeviceName.JoinNumber, Name);
+
+            trilist.OnlineStatusChange += (o, a) =>
+            {
+                if (!a.DeviceOnLine) return;
+
+                trilist.SetString(joinMap.DeviceName.JoinNumber, Name);
+            };
+        }
+
+
+        #endregion
+
+    }
+}
+

PDT.EssentialsPluginTemplate.EPI/EssentialsPluginTemplateDevice.cs

@@ -9,31 +9,41 @@
 namespace EssentialsPluginTemplate
 {
 	/// <summary>
-	/// Plugin device
+	/// Plugin device template for third party devices that use IBasicCommunication
 	/// </summary>
 	/// <remarks>
 	/// Rename the class to match the device plugin being developed.
 	/// </remarks>
 	/// <example>
 	/// "EssentialsPluginDeviceTemplate" renamed to "SamsungMdcDevice"
 	/// </example>
-	public class EssentialsPluginDeviceTemplate : EssentialsBridgeableDevice
-	{
-		// TODO [ ] Add, modify, remove properties and fields as needed for the plugin being developed
+	public class EssentialsPluginTemplateDevice : EssentialsBridgeableDevice
+    {
+        /// <summary>
+        /// It is often desirable to store the config
+        /// </summary>
+        private EssentialsPluginConfigObjectTemplate _config;
+
+        #region IBasicCommunication Properties and Constructor.  Remove if not needed.
+
+        // TODO [ ] Add, modify, remove properties and fields as needed for the plugin being developed
 		private readonly IBasicCommunication _comms;
 		private readonly GenericCommunicationMonitor _commsMonitor;
 
 		// _comms gather for ASCII based API's
 		// TODO [ ] If not using an ASCII based API, delete the properties below
 		private readonly CommunicationGather _commsGather;
+
+        /// <summary>
+        /// Set this value to that of the delimiter used by the API (if applicable)
+        /// </summary>
 		private const string CommsDelimiter = "\r";
 
 		// _comms byte buffer for HEX/byte based API's
 		// TODO [ ] If not using an HEX/byte based API, delete the properties below
 		private byte[] _commsByteBuffer = { };
 
 
-		private EssentialsPluginConfigObjectTemplate _config;
 
 		/// <summary>
 		/// Connects/disconnects the comms of the plugin device
@@ -75,13 +85,13 @@ public bool Connect
 		public IntFeedback StatusFeedback { get; private set; }
 
 		/// <summary>
-		/// Plugin device constructor
+		/// Plugin device constructor for devices that need IBasicCommunication
 		/// </summary>
 		/// <param name="key"></param>
 		/// <param name="name"></param>
 		/// <param name="config"></param>
 		/// <param name="comms"></param>
-		public EssentialsPluginDeviceTemplate(string key, string name, EssentialsPluginConfigObjectTemplate config, IBasicCommunication comms)
+		public EssentialsPluginTemplateDevice(string key, string name, EssentialsPluginConfigObjectTemplate config, IBasicCommunication comms)
 			: base(key, name)
 		{
 			Debug.Console(0, this, "Constructing new {0} instance", name);
@@ -103,79 +113,28 @@ public EssentialsPluginDeviceTemplate(string key, string name, EssentialsPluginC
 				// device comms is IP **ELSE** device comms is RS232
 				socket.ConnectionChange += socket_ConnectionChange;
 				Connect = true;
-			}
-
-			// _comms gather for ASCII based API's
-			// TODO [ ] If not using an ASCII based API, delete the properties below
-			_commsGather = new CommunicationGather(_comms, CommsDelimiter);
-			AddPostActivationAction(() => _commsGather.LineReceived += Handle_LineRecieved);
-
-			// _comms byte buffer for HEX/byte based API's
-			// TODO [ ] If not using an HEX/byte based API, delete the properties below
-			_comms.BytesReceived += Handle_BytesReceived;
-			AddPostActivationAction(() => _comms.BytesReceived += Handle_BytesReceived);
-		}
+            }
 
-		#region Overrides of EssentialsBridgeableDevice
+            #region Communication data event handlers.  Comment out any that don't apply to the API type
 
-		/// <summary>
-		/// Links the plugin device to the EISC bridge
-		/// </summary>
-		/// <param name="trilist"></param>
-		/// <param name="joinStart"></param>
-		/// <param name="joinMapKey"></param>
-		/// <param name="bridge"></param>
-		public override void LinkToApi(BasicTriList trilist, uint joinStart, string joinMapKey, EiscApiAdvanced bridge)
-		{
-			var joinMap = new EssentialsPluginBridgeJoinMapTemplate(joinStart);
+            // Only one of the below handlers should be necessary.  
 
-			// This adds the join map to the collection on the bridge
-			if (bridge != null)
-			{
-				bridge.AddJoinMap(Key, joinMap);
-			}
-
-			var customJoins = JoinMapHelper.TryGetJoinMapAdvancedForDevice(joinMapKey);
-
-			if (customJoins != null)
-			{
-				joinMap.SetCustomJoinData(customJoins);
-			}
-
-			Debug.Console(1, "Linking to Trilist '{0}'", trilist.ID.ToString("X"));
-			Debug.Console(0, "Linking to Bridge Type {0}", GetType().Name);
-
-			// TODO [ ] Implement bridge links as needed
-
-			// links to bridge
-			trilist.SetString(joinMap.DeviceName.JoinNumber, Name);
-
-			trilist.SetBoolSigAction(joinMap.Connect.JoinNumber, sig => Connect = sig);
-			ConnectFeedback.LinkInputSig(trilist.BooleanInput[joinMap.Connect.JoinNumber]);
+            // _comms gather for any API that has a defined delimiter
+			// TODO [ ] If not using an ASCII based API, remove the line below
+			_commsGather = new CommunicationGather(_comms, CommsDelimiter);
+			_commsGather.LineReceived += Handle_LineRecieved;
 
-			StatusFeedback.LinkInputSig(trilist.UShortInput[joinMap.Status.JoinNumber]);
-			OnlineFeedback.LinkInputSig(trilist.BooleanInput[joinMap.IsOnline.JoinNumber]);
+			// _comms byte buffer for HEX/byte based API's with no delimiter
+            // TODO [ ] If not using an HEX/byte based API, remove the line below
+			_comms.BytesReceived += Handle_BytesReceived;
 
-			UpdateFeedbacks();
+            // _comms byte buffer for HEX/byte based API's with no delimiter
+            // TODO [ ] If not using an HEX/byte based API, remove the line below
+            _comms.TextReceived += Handle_TextReceived;
 
-			trilist.OnlineStatusChange += (o, a) =>
-			{
-				if (!a.DeviceOnLine) return;
+            #endregion
+        }
 
-				trilist.SetString(joinMap.DeviceName.JoinNumber, Name);
-				UpdateFeedbacks();
-			};
-		}
-
-		private void UpdateFeedbacks()
-		{
-			// TODO [ ] Update as needed for the plugin being developed
-			ConnectFeedback.FireUpdate();
-			OnlineFeedback.FireUpdate();
-			StatusFeedback.FireUpdate();
-		}
-
-		#endregion
 
 		private void socket_ConnectionChange(object sender, GenericSocketStatusChageEventArgs args)
 		{
@@ -186,20 +145,28 @@ private void socket_ConnectionChange(object sender, GenericSocketStatusChageEven
 				StatusFeedback.FireUpdate();
 		}
 
-		// TODO [ ] If not using an ASCII based API, delete the properties below
+		// TODO [ ] If not using an API with a delimeter, delete the method below
 		private void Handle_LineRecieved(object sender, GenericCommMethodReceiveTextArgs args)
 		{
 			// TODO [ ] Implement method 
 			throw new System.NotImplementedException();
 		}
 
-		// TODO [ ] If not using an HEX/byte based API, delete the properties below
+        // TODO [ ] If not using an HEX/byte based API with no delimeter,  delete the method below
 		private void Handle_BytesReceived(object sender, GenericCommMethodReceiveBytesArgs args)
 		{
 			// TODO [ ] Implement method 
 			throw new System.NotImplementedException();
 		}
 
+        // TODO [ ] If not using an ASCII based API with no delimeter, delete the method below
+        void Handle_TextReceived(object sender, GenericCommMethodReceiveTextArgs e)
+        {
+            // TODO [ ] Implement method 
+            throw new System.NotImplementedException();
+        }
+
+
 		// TODO [ ] If not using an ACII based API, delete the properties below
 		/// <summary>
 		/// Sends text to the device plugin comms
@@ -239,8 +206,74 @@ public void SendBytes(byte[] bytes)
 		public void Poll()
 		{
 			// TODO [ ] Update Poll method as needed for the plugin being developed
+            // Example: SendText("getstatus");
 			throw new System.NotImplementedException();
-		}
-	}
+        }
+
+        #endregion
+
+
+        #region Overrides of EssentialsBridgeableDevice
+
+        /// <summary>
+        /// Links the plugin device to the EISC bridge
+        /// </summary>
+        /// <param name="trilist"></param>
+        /// <param name="joinStart"></param>
+        /// <param name="joinMapKey"></param>
+        /// <param name="bridge"></param>
+        public override void LinkToApi(BasicTriList trilist, uint joinStart, string joinMapKey, EiscApiAdvanced bridge)
+        {
+            var joinMap = new EssentialsPluginBridgeJoinMapTemplate(joinStart);
+
+            // This adds the join map to the collection on the bridge
+            if (bridge != null)
+            {
+                bridge.AddJoinMap(Key, joinMap);
+            }
+
+            var customJoins = JoinMapHelper.TryGetJoinMapAdvancedForDevice(joinMapKey);
+
+            if (customJoins != null)
+            {
+                joinMap.SetCustomJoinData(customJoins);
+            }
+
+            Debug.Console(1, "Linking to Trilist '{0}'", trilist.ID.ToString("X"));
+            Debug.Console(0, "Linking to Bridge Type {0}", GetType().Name);
+
+            // TODO [ ] Implement bridge links as needed
+
+            // links to bridge
+            trilist.SetString(joinMap.DeviceName.JoinNumber, Name);
+
+            trilist.SetBoolSigAction(joinMap.Connect.JoinNumber, sig => Connect = sig);
+            ConnectFeedback.LinkInputSig(trilist.BooleanInput[joinMap.Connect.JoinNumber]);
+
+            StatusFeedback.LinkInputSig(trilist.UShortInput[joinMap.Status.JoinNumber]);
+            OnlineFeedback.LinkInputSig(trilist.BooleanInput[joinMap.IsOnline.JoinNumber]);
+
+            UpdateFeedbacks();
+
+            trilist.OnlineStatusChange += (o, a) =>
+            {
+                if (!a.DeviceOnLine) return;
+
+                trilist.SetString(joinMap.DeviceName.JoinNumber, Name);
+                UpdateFeedbacks();
+            };
+        }
+
+        private void UpdateFeedbacks()
+        {
+            // TODO [ ] Update as needed for the plugin being developed
+            ConnectFeedback.FireUpdate();
+            OnlineFeedback.FireUpdate();
+            StatusFeedback.FireUpdate();
+        }
+
+        #endregion
+
+    }
 }