-
Notifications
You must be signed in to change notification settings - Fork 79
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.
{
"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
}
]
}
}
]
}
}
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.
{
"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.
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 :
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
.
A Com
device requires a comParams
object to set the propeties of the comport. The values of all proeprties are case-insensitive.
{
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 115200,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
}
Valid hardwareHandshake
values are as follows
"None"
"Rts"
"Cts"
"RtsCts"
Valid parity
values are as follows
"None"
"Even"
"Odd"
"Mark"
Valid protocol
values are as follows
"RS232"
"RS422"
"RS485"
Valid baudRate
values are as follows
300
600
1200
1800
2400
3600
4800
7200
9600
14400
19200
28800
38400
57600
115200
Valid dataBits
values are as follows
7
8
Valid softwareHandshake
values are as follows
"None"
"XON"
"XONT"
"XONR"
Valid stopBits
values are as follows
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.
A Ssh
, TcpIp
, or Udp
device requires a tcpSshProperties
object to set the propeties of the socket.
{
"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 join map for a generic comms device is fairly simple.
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.