From 4de4548fd28ada3afc086f2eb69ee26f84d4817c Mon Sep 17 00:00:00 2001 From: Trevor Payne Date: Wed, 13 May 2020 22:45:05 -0500 Subject: [PATCH] New Documentation : GenericComm; RelayOutput; DigitalInput --- Bridging-To-Hardware-Resources.md | 13 + DigitalInput.md | 171 ++++++++++++++ GenericComm.md | 381 ++++++++++++++++++++++++++++++ RelayOutput.md | 164 +++++++++++++ _Sidebar.md | 4 + 5 files changed, 733 insertions(+) create mode 100644 Bridging-To-Hardware-Resources.md create mode 100644 DigitalInput.md create mode 100644 GenericComm.md create mode 100644 RelayOutput.md diff --git a/Bridging-To-Hardware-Resources.md b/Bridging-To-Hardware-Resources.md new file mode 100644 index 0000000..43b6051 --- /dev/null +++ b/Bridging-To-Hardware-Resources.md @@ -0,0 +1,13 @@ +# Bridging to Hardware and Network Resources + +One of the most powerful features of Essentials is the ability to bridge SIMPL to and hardware resource to any piece of equipment instantiated inside of essentials. You can bridge directly to a comport on the processor just as easily as you can to the comport of an instantiated DM device. A simple change in the connection location of a display can be made with just a few keystrokes. This isn't restricted to comports either. Devices and direct connections can be linked to Digital Inputs, IR Ports, Relays, Comports, SSH, TCP/IP, UDP, and Cresnet resources. + +## Examples + +Follow the links below for examples of bridging to hardware and network resources. + +**[GenericComm Bridging](GenericComm)** + +**[RelayOutput Bridging](RelayOutput)** + +**[Digital Input Bridging](DigitalInput)** diff --git a/DigitalInput.md b/DigitalInput.md new file mode 100644 index 0000000..8c4b16d --- /dev/null +++ b/DigitalInput.md @@ -0,0 +1,171 @@ +# DigitalInput + +Digital Inputs can be bridged directly to SIMPL from any device that is both inlcuded within essentials and has a relay. + +Consider the following example. + +```JSON +{ + "template": { + "roomInfo": [ + {} + ], + "devices": [ + { + "key": "processor", + "uid": 0, + "type": "pro3", + "name": "pro3", + "group": "processor", + "supportedConfigModes": [ + "compliance", + "essentials" + ], + "supportedSystemTypes": [ + "hudType", + "presType", + "vtcType", + "custom" + ], + "supportsCompliance": true, + "properties": {} + }, + { + "key": "DigitalInput-1", + "uid": 3, + "name": "Digital Input 1", + "group": "api", + "type": "digitalInput", + "properties": { + "portDeviceKey" : "processor", + "portNumber" : 1, + "disablePullUpResistor" : true + } + }, + { + "key": "DigitalInput-2", + "uid": 3, + "name": "Digital Inptut 2", + "group": "api", + "type": "digitalInput", + "properties": { + "portDeviceKey" : "processor", + "portNumber" : 2, + "disablePullUpResistor" : true + } + }, + { + "key": "deviceBridge", + "uid": 4, + "name": "BridgeToDevices", + "group": "api", + "type": "eiscapiadv", + "properties": { + "control": { + "tcpSshProperties": { + "address": "127.0.0.2", + "port": 0 + }, + "ipid": "03", + "method": "ipidTcp" + }, + "devices": [ + { + "deviceKey": "DigitalInput-1", + "joinStart": 1 + }, + { + "deviceKey": "DigitalInput-2", + "joinStart": 2 + } + ] + } + } + ] + } +} +``` + +## RelayOutput Configuration Explanation + +This configuration is meant for a Pro3 device, and instantiates two relay ports and links them to an eisc bridge to another processor slot on ipid 3. Let's break down the ```DigitalInput-1``` device. + +```JSON +{ + "key": "DigitalInput-1", + "uid": 3, + "name": "Digital Input 1", + "group": "api", + "type": "digitalInput", + "properties": { + "portDeviceKey" : "processor", + "portNumber" : 1, + "disablePullUpResistor" : true + } +} +``` + +**```Key```** + +The Key is a unique identifier for essentials. The key allows the device to be linked to other devices also defined by key. All Keys MUST be unique, as every device is added to a globally-accessible dictionary. If you have accidentally utilized the same key twice, Essentials will notify you during startup that there is an issue with the device. + +**```Uid```** + +The Uid is reserved for use with an PepperDash internal config generation tool, and is not useful to Essentials in any way. + +**```Name```** + +The Name a friendly name assigned to the device. Many devices pass this data to the bridge for utilization in SIMPL. + +**```Group```** + +Utilized in certain Essentials devices. In this case, the value is unimportant. + +**```Type```** + +The Type is the identifier for a specific type of device in Essentials. A list of all valid types can be reported by using the consolecommand ```gettypes``` in Essentials. In this case, the type is ```digitalInput```. This type is valid for any instance of a Relay Output. + +**```Properties```** + +These are the properties essential to the instantiation of the identified type. + +### Properties + +There are two properties relevant to the instantiation of a relay device. + +**```portDeviceKey```** + +This property maps to the ```key``` of the device upon which the relay resides. + +**```portNumber```** + +This property maps to the number of the relay on the device you have mapped the relay device to. Even if the device has only a single relay, ```portNumber``` must be defined. + +**```disablePullUpResistor```** + +This is a boolean value, therefore it is a case-sensitive ```true``` or ```false``` utilized to determine if the pullup resistor on the digital input will be disabled or not. + +### The JoinMap + +The joinmap for a ```digitalInput``` device is comprised of a single digital join. + +```cs +namespace PepperDash.Essentials.Core.Bridges +{ + public class IDigitalInputJoinMap : JoinMapBaseAdvanced + { + + [JoinName("InputState")] + public JoinDataComplete InputState = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 }, + new JoinMetadata() { Label = "Room Email Url", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital }); + + + public IDigitalInputJoinMap(uint joinStart) + : base(joinStart, typeof(IDigitalInputJoinMap)) + { + } + } +} +``` + +```InputState``` is a digital join that represents the feedback for the associated Digital Input Device. Its join is set to 1. diff --git a/GenericComm.md b/GenericComm.md new file mode 100644 index 0000000..b4abee4 --- /dev/null +++ b/GenericComm.md @@ -0,0 +1,381 @@ +# GenericComm + +One of the most common scenarios in control system development is utilizing RS232 to connect to a device. Essentials doesn't restrict you to connecting a native essentials device or plugin to the comport. You can directly access the comport, and even set baudrates on the fly if you so desire. + +Similarly you can instantiate one of several socket types in this manner and bridge them directly to SIMPL. + +Consider the following example. + +```JSON +{ + "template": { + "roomInfo": [ + {} + ], + "devices": [ + { + "key": "processor", + "uid": 0, + "type": "pro3", + "name": "pro3", + "group": "processor", + "supportedConfigModes": [ + "compliance", + "essentials" + ], + "supportedSystemTypes": [ + "hudType", + "presType", + "vtcType", + "custom" + ], + "supportsCompliance": true, + "properties": {} + }, + { + "key": "Comport-1", + "uid": 3, + "name": "Comport 1", + "group": "api", + "type": "genericComm", + "properties": { + "control": { + "method": "com", + "comParams": { + "hardwareHandshake": "None", + "parity": "None", + "protocol": "RS232", + "baudRate": 115200, + "dataBits": 8, + "softwareHandshake": "None", + "stopBits": 1 + }, + "controlPortNumber": 1, + "controlPortDevKey": "processor", + } + } + }, + { + "key": "Comport-2", + "uid": 3, + "name": "Comport 2", + "group": "api", + "type": "genericComm", + "properties": { + "control": { + "method": "ssh", + "tcpSshProperties": { + "address": "192.168.1.57", + "port": 22, + "username": "", + "password": "", + "autoReconnect": true, + "autoReconnectIntervalMs": 10000 + } + } + } + }, + { + "key": "deviceBridge", + "uid": 4, + "name": "BridgeToDevices", + "group": "api", + "type": "eiscapiadv", + "properties": { + "control": { + "tcpSshProperties": { + "address": "127.0.0.2", + "port": 0 + }, + "ipid": "03", + "method": "ipidTcp" + }, + "devices": [ + { + "deviceKey": "Comport-1", + "joinStart": 1 + }, + { + "deviceKey": "Comport-2", + "joinStart": 3 + } + ] + } + } + ] + } +} +``` + +## GenericComm Configuration Explanation + +This configuration is meant for a Pro3 device, and instantiates one comport and one SSH session and links them to an eisc bridge to another processor slot on ipid 3. Let's break down the ```Comport-1``` device. + +```JSON +{ + "key": "Comport-1", + "uid": 3, + "name": "Comport 1", + "group": "comm", + "type": "genericComm", + "properties": { + "control": { + "comParams": { + "hardwareHandshake": "None", + "parity": "None", + "protocol": "RS232", + "baudRate": 115200, + "dataBits": 8, + "softwareHandshake": "None", + "stopBits": 1 + }, + "controlPortNumber": 1, + "controlPortDevKey": "processor", + "method": "com" + } + } +} +``` + +**```Key```** + +The Key is a unique identifier for essentials. The key allows the device to be linked to other devices also defined by key. All Keys MUST be unique, as every device is added to a globally-accessible dictionary. If you have accidentally utilized the same key twice, Essentials will notify you during startup that there is an issue with the device. + +**```Uid```** + +The Uid is reserved for use with an PepperDash internal config generation tool, and is not useful to Essentials in any way. + +**```Name```** + +The Name a friendly name assigned to the device. Many devices pass this data to the bridge for utilization in SIMPL. + +**```Group```** + +Utilized in certain Essentials devices. In this case, the value is unimportant. + +**```Type```** + +The Type is the identifier for a specific type of device in Essentials. A list of all valid types can be reported by using the consolecommand ```gettypes``` in Essentials. In this case, the type is ```genericComm```. This type is valid for any instance of a serial-based communications channel such as a Serial Port, SSH, UDP, or standard TCP/IP Socket. + +**```Properties```** + +These are the properties essential to the instantiation of the identified type. + +#### Control + +The properties within this property are dependant on the type of genericComm you wish to instantiate. There is one common property for control of any type, and that is ```method```. The ```method``` property requires a string that maps to the following enumerations in Essentials : + +```cs +namespace PepperDash.Core +{ + // Summary: + // Crestron Control Methods for a comm object + public enum eControlMethod + { + None = 0, + Com = 1, + IpId = 2, + IpidTcp = 3, + IR = 4, + Ssh = 5, + Tcpip = 6, + Telnet = 7, + Cresnet = 8, + Cec = 9, + Udp = 10, + } +} +``` + +These enumerations are not case sensitive. Not all methods are valid for a ```genericComm``` device. For a comport, the only valid type would be ```Com```. For a direct network socket, valid options are ```Ssh```, ```Tcpip```, ```Telnet```, and ```Udp```. + +##### ComParams + +A ```Com``` device requires a ```comParams``` object to set the propeties of the comport. The values of all proeprties are case-insensitive. + +```JSON +{ +"comParams": { + "hardwareHandshake": "None", + "parity": "None", + "protocol": "RS232", + "baudRate": 115200, + "dataBits": 8, + "softwareHandshake": "None", + "stopBits": 1 +} +``` + +**Valid ```hardwareHandshake``` values are as follows** + +```sh +"None" +"Rts" +"Cts" +"RtsCts" +``` + +**Valid ```parity``` values are as follows** + +```sh +"None" +"Even" +"Odd" +"Mark" +``` + +**Valid ```protocol``` values are as follows** + +```sh +"RS232" +"RS422" +"RS485" +``` + +**Valid ```baudRate``` values are as follows** + +```sh +300 +600 +1200 +1800 +2400 +3600 +4800 +7200 +9600 +14400 +19200 +28800 +38400 +57600 +115200 +``` + +**Valid ```dataBits``` values are as follows** + +```sh +7 +8 +``` + +**Valid ```softwareHandshake``` values are as follows** + +```sh +"None" +"XON" +"XONT" +"XONR" +``` + +**Valid ```stopBits``` values are as follows** + +```sh +1 +2 +``` + +Additionally, a ```control``` object for a physical hardware port needs to map to that physical port. This is accomplished by utilizing the ```controlPortDevKey``` and ```port``` properties. + +**```controlPortDevKey```** + +This property maps to the ```key``` of the device upon which the port resides. + +**```port```** + +This property maps to the number of the port on the device you have mapped the relay device to. Even if the device has only a single port, ```port``` must be defined. + +##### TcpSshParams + +A ```Ssh```, ```TcpIp```, or ```Udp``` device requires a ```tcpSshProperties``` object to set the propeties of the socket. + +```Json +{ + "tcpSshProperties": { + "address": "192.168.1.57", + "port": 22, + "username": "", + "password": "", + "autoReconnect": true, + "autoReconnectIntervalMs": 10000 + } +} +``` + +**```address```** + +This is the IP address, hostname, or FQDN of the resource you wish to open a socket to. In the case of a UDP device, you can set either a single whitelist address with this data, or an appropriate broadcast address. + +**```port```** + +This is the port you wish to utilize for the socket connection. Certain protocols require certain ports - ```Ssh``` being ```22``` and ```Telnet``` being ```23```. + +**```username```** + +This is the username (if required) for authentication to the device you are connecting to. Typcally only required for ```Ssh``` connections. + +**```password```** + +This is the password (if required) for authentication to the device you are connecting to. Typcally only required for ```Ssh``` connections. + +**```autoreconnect```** + +This is a boolean value, therefore it is a case-sensitive ```true``` or ```false``` utilized to determine if the socket will attempt to reconnect upon loss of connection. + +**```autoReconnectIntervalMs```** + +This is the duration of time, in Miliseconds, that the socket will wait before discrete connection attempts if ```autoreconnect``` is set to true. + +##### The JoinMap + +The join map for a generic comms device is fairly simple. + +```cs +namespace PepperDash.Essentials.Core.Bridges +{ + public class IBasicCommunicationJoinMap : JoinMapBaseAdvanced + { + [JoinName("TextReceived")] + public JoinDataComplete TextReceived = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 }, + new JoinMetadata() { Label = "Text Received From Remote Device", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Serial }); + + [JoinName("SendText")] + public JoinDataComplete SendText = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 }, + new JoinMetadata() { Label = "Text Sent To Remote Device", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Serial }); + + [JoinName("SetPortConfig")] + public JoinDataComplete SetPortConfig = new JoinDataComplete(new JoinData() { JoinNumber = 2, JoinSpan = 1 }, + new JoinMetadata() { Label = "Set Port Config", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Serial }); + + [JoinName("Connect")] + public JoinDataComplete Connect = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 }, + new JoinMetadata() { Label = "Connect", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital }); + + [JoinName("Connected")] + public JoinDataComplete Connected = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 }, + new JoinMetadata() { Label = "Connected", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital }); + + [JoinName("Status")] + public JoinDataComplete Status = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 }, + new JoinMetadata() { Label = "Status", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Analog }); + + + public IBasicCommunicationJoinMap(uint joinStart) + : base(joinStart, typeof(IBasicCommunicationJoinMap)) + { + } + } +} +``` + +```TextReceived``` is a stream of strings received **FROM** the connected device. + +```SendText``` is for any strings you wish to send **TO** the connected device. + +```Connect``` connects to a remote socket device on the rising edge of the signal. + +```Connected``` represents the current connection state. High for Connected, low for Disconnected. + +```Status``` is an analog value that is representative of the connection states as reported by the SIMPL TCP/IP socket symbol. + +All of the preceeding joins are set to join ```1```. The second serial input join is reserved for ```2```. It allows you to send a ```comparams``` json object as a string, utilizing the same format mentioned previously in this document. Doing so will override the configured comport specifications. diff --git a/RelayOutput.md b/RelayOutput.md new file mode 100644 index 0000000..f2a5608 --- /dev/null +++ b/RelayOutput.md @@ -0,0 +1,164 @@ +# RelayOutput + +Relays can be bridged directly to SIMPL from any device that is both inlcuded within essentials and has a relay. + +Consider the following example. + +```JSON +{ + "template": { + "roomInfo": [ + {} + ], + "devices": [ + { + "key": "processor", + "uid": 0, + "type": "pro3", + "name": "pro3", + "group": "processor", + "supportedConfigModes": [ + "compliance", + "essentials" + ], + "supportedSystemTypes": [ + "hudType", + "presType", + "vtcType", + "custom" + ], + "supportsCompliance": true, + "properties": {} + }, + { + "key": "Relay-1", + "uid": 3, + "name": "Relay 1", + "group": "api", + "type": "relayOutput", + "properties": { + "portDeviceKey" : "processor", + "portNumber" : 1 + } + }, + { + "key": "Relay-2", + "uid": 3, + "name": "Relay 2", + "group": "api", + "type": "relayOutput", + "properties": { + "portDeviceKey" : "processor", + "portNumber" : 2 + } + }, + { + "key": "deviceBridge", + "uid": 4, + "name": "BridgeToDevices", + "group": "api", + "type": "eiscapiadv", + "properties": { + "control": { + "tcpSshProperties": { + "address": "127.0.0.2", + "port": 0 + }, + "ipid": "03", + "method": "ipidTcp" + }, + "devices": [ + { + "deviceKey": "Relay-1", + "joinStart": 1 + }, + { + "deviceKey": "Relay-2", + "joinStart": 2 + } + ] + } + } + ] + } +} +``` + +## RelayOutput Configuration Explanation + +This configuration is meant for a Pro3 device, and instantiates two relay ports and links them to an eisc bridge to another processor slot on ipid 3. Let's break down the ```Relay-1``` device. + +```JSON +{ + "key": "Relay-1", + "uid": 3, + "name": "Relay 1", + "group": "api", + "type": "relayOutput", + "properties": { + "portDeviceKey" : "processor", + "portNumber" : 1 + } +} +``` + +**```Key```** + +The Key is a unique identifier for essentials. The key allows the device to be linked to other devices also defined by key. All Keys MUST be unique, as every device is added to a globally-accessible dictionary. If you have accidentally utilized the same key twice, Essentials will notify you during startup that there is an issue with the device. + +**```Uid```** + +The Uid is reserved for use with an PepperDash internal config generation tool, and is not useful to Essentials in any way. + +**```Name```** + +The Name a friendly name assigned to the device. Many devices pass this data to the bridge for utilization in SIMPL. + +**```Group```** + +Utilized in certain Essentials devices. In this case, the value is unimportant. + +**```Type```** + +The Type is the identifier for a specific type of device in Essentials. A list of all valid types can be reported by using the consolecommand ```gettypes``` in Essentials. In this case, the type is ```relayOutput```. This type is valid for any instance of a Relay Output. + +**```Properties```** + +These are the properties essential to the instantiation of the identified type. + +### Properties + +There are two properties relevant to the instantiation of a relay device. + +**```portDeviceKey```** + +This property maps to the ```key``` of the device upon which the relay resides. + +**```portNumber```** + +This property maps to the number of the relay on the device you have mapped the relay device to. Even if the device has only a single relay, ```portNumber``` must be defined. + +### The JoinMap + +The joinmap for a ```relayOutput``` device is comprised of a single digital join. + +```cs +namespace PepperDash.Essentials.Core.Bridges +{ + public class GenericRelayControllerJoinMap : JoinMapBaseAdvanced + { + + [JoinName("Relay")] + public JoinDataComplete Relay = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 }, + new JoinMetadata() { Label = "Device Relay State Set / Get", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital }); + + + public GenericRelayControllerJoinMap(uint joinStart) + : base(joinStart, typeof(GenericRelayControllerJoinMap)) + { + } + } +} +``` + +```Relay``` is a digital join that represents both the trigger and the feedback for the associated relay device. Its join is set to 1. diff --git a/_Sidebar.md b/_Sidebar.md index 3b3c384..351e6ad 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -9,6 +9,10 @@ * [Standalone Use](Standalone-Use) * [SIMPL Windows Bridging](SIMPL-Bridging) * [Join Maps](JoinMaps) + * [Bridging to Hardware Resources](Bridging-To-Hardware-Resources) + * [GenericComm Bridging](GenericComm) + * [RelayOutput Bridging](RelayOutput) + * [Digital Input Bridging](DigitalInput) **Technical documentation** * [Essentials Architecture](Arch-summary)