pepperdash/Essentials
1
0
Fork 0
mirror of https://github.com/PepperDash/Essentials.git synced 2026-01-11 19:44:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Changes to Deprecated & Current Pages with status

Trevor Payne
2020-05-13 14:29:46 -05:00
parent 2a19d82696
commit 4582a0cb3e
7 changed files with 769 additions and 761 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
Plugins-Deprecated.md Normal file

@@ -0,0 +1,74 @@
# Deprecated
**Note : this entry is out of date - please see [Plugins](Plugins)**
## What are Essentials Plugins?
Plugins are SIMPL# Pro libraries that reference the Essentials Framework and can be loaded into an Essentials Application at runtime to extend functionality beyond what the Essentials Framework provides on its own.
## Why Use Plugins?
Plugins are a way to extend or add new functionality to the Essentials Application without having to modify the actual Framework. In most cases, a plugin can be written to support a new device or behavior. Using plugins also limits the scope of understanding needed to work within the Essentials Framework.
## Should I use a Plugin?
Essentials is meant to be a lightweight framework and an extensible basis for development. While some devices are included in the framework, mostly for the purposes of providing examples and developing and prototyping new device types, the bulk of new development is intended to take place in Plugins. Once a plugin adds new functionality that may be of benefit if shared across multiple plugins, it may make sense to port that common logic (base classes and/or interfaces) back into the framework to make it available to others. The thrust of future Essentials development is targeted towards building a library of plugins.
## How do Plugins Work?
One or more plugins can be loaded to the /user/ProgramX/plugins as .dlls or .cplz packages. When the Essentials Application starts, it looks for any .cplz files, unzips them and then iterates any .dll assemblies in that folder and loads them. Once the plugin assemblies are loaded the Essentials Application will then attempt to load a configuration file and construct items as defined in the file. Those items can be defined in either the Essentials Framework or in any of the loaded plugin assemblies.
![Architecture drawing](https://pepperdash.github.io/Essentials/Plugin%20Load%20Sequence.png)
## What Must be Implemented in a Plugin for it to Work?
All plugin assemblies must contain a static method called LoadPlugin():
```cs
public class SomeDevice : Device , IBridge //IBridge only needs to be implemented if using a bridge
{
// This string is used to define the minimum version of the
// Essentials Framework required for this plugin
public static string MinimumEssentialsFrameworkVersion = "1.4.23";
// This method gets called by the Essentials Framework when the application starts.
// It is intended to be used to load the new Device type(s) specified in the plugin
public static void LoadPlugin()
{
DeviceFactory.AddFactoryForType("typeName", FactoryMethod);
// typeName should be the unique string that identifies the type of device to build,
// FactoryMethod represents the method that takes a DevicConfig object as and argument
// and returns an instance of the desired device type
}
// This is a factory method to construct a device and return it to be
// added to the DeviceManager
public static Device FactoryMethod(DeviceConfig dc)
{
return new SomeDevice(dc.key, dc.name, dc);
}
#region IBridge
// This method is called by an EiscApi bridge instance and should call an extension method
// defined in your plugin. Required for implementing IBridge
public void LinkToApi(BasicTriList trilist, uint joinStart, string joinMapKey)
{
this.LinkToApiExt(trilist, joinStart, joinMapKey);
}
#endregion
}
```
## SIMPL Bridging
Optionally, if your plugin device needs to be able to bridge to a SIMPL program over EISC, and there isn't already an existing bridge class in the Essentials Framework, you can write a new bridge class in your plugin. However, in order for the Essentials Application to be able to us that new bridge, the bridge must implement the IBridge interface with the required LinkToApi() Extension method.
Often though, you may find that a bridge class already exists in the Essentials Framework that you can leverage. For example, if you were writing a plugin to support a new display model that isn't already in the Essentials Framework, you would define a class in your plugin that inherits from PepperDash.Essentials.Core.DisplayBase. If you're only implementing the standard display control functions such as power/input/volume control, then the existing bridge class `DisplayControllerBridge` can be used. If you needed to add additional functions to the bridge, then you would need to write your own bridge in the plugin.
For additional info see the [SIMPL-Bridging article](SIMPL-Bridging).
## Template Essentials Plugin Repository
Fork this repository when starting a new plugin. The template repository uses the essentials-builds repository as a submodule. This allows the plugin to reference a specific build version of Essentials. You must make sure that you checkout the correct build of the Essentials-Builds repo that contains any dependencies that your plugin may rely on.
[Essentials Plugin Template Repository](https://github.com/PepperDash/EssentialsPluginTemplate)

123
Plugins-Updated.md

@@ -1,123 +0,0 @@
# What are Essentials Plugins?
Plugins are SIMPL# Pro libraries that reference the Essentials Framework and can be loaded into an Essentials Application at runtime to extend functionality beyond what the Essentials Framework provides on its own.
## Why Use Plugins?
Plugins are a way to extend or add new functionality to the Essentials Application without having to modify the actual Framework. In most cases, a plugin can be written to support a new device or behavior. Using plugins also limits the scope of understanding needed to work within the Essentials Framework.
## Should I use a Plugin?
Essentials is meant to be a lightweight framework and an extensible basis for development. While some devices are included in the framework, mostly for the purposes of providing examples and developing and prototyping new device types, the bulk of new development is intended to take place in Plugins. Once a plugin adds new functionality that may be of benefit if shared across multiple plugins, it may make sense to port that common logic (base classes and/or interfaces) back into the framework to make it available to others. The thrust of future Essentials development is targeted towards building a library of plugins.
## How do Plugins Work?
One or more plugins can be loaded to the /user/ProgramX/plugins as .dlls or .cplz packages. When the Essentials Application starts, it looks for any .cplz files, unzips them and then iterates any .dll assemblies in that folder and loads them. Once the plugin assemblies are loaded the Essentials Application will then attempt to load a configuration file and construct items as defined in the file. Those items can be defined in either the Essentials Framework or in any of the loaded plugin assemblies.
![Architecture drawing](https://pepperdash.github.io/Essentials/Plugin%20Load%20Sequence.png)
## What Must be Implemented in a Plugin for it to Work?
All plugin assemblies must contain a class which inherits from ```EssentialsPluginDeviceFactory<T>```, where ```<T>``` is a class which inherits from ```PepperDash.Essentials.Core.EssentialsDevice```
Within this class, we will define some metadata for the plugin and define which constructor to use
for instantiating each class as defined by type.
Note that multiple types can be loaded from the same plugin.
```cs
using System;
using Crestron.SimplSharp;
using Crestron.SimplSharpPro;
using PepperDash.Essentials.Core;
using PepperDash.Essentials.Core.Config;
using PepperDash.Core;
using System.Collections.Generic;
namespace MyPlugin
{
public class SomeDeviceFactory : EssentialsPluginDeviceFactory<SomeDevice>
{
// This method defines metadata for the devices in the plugin
public SomeDeviceFactory()
{
// This string is used to define the minimum version of the
// Essentials Framework required for this plugin
MinimumEssentialsFrameworkVersion = "1.5.0";
// This string is used to define all valid type names for
// this plugin. This string is case insensitive
TypeNames = new List<string> { "SomeDevice" , "ThisNewDevice" };
}
// This method instantiates new devices for the defined type
// within the plugin
public override EssentialsDevice BuildDevice(DeviceConfig dc)
{
// Deserialize the json properties for the loaded type to a new object
var props = dc.Properties.ToObject<SomeDeviceProperties>();
// Return a newly instantiated device using the desired constructor
// If no valid property data exists, return null with console print
// describing the failure.
if (props == null)
{
Debug.Console(0, "No valid property data for 'SomeDevice' - Verify Configuration.");
Debug.Console(0, dc.Properties.ToString());
return null;
}
return new SomeDevice(dc.Key, dc.Name, props);
}
}
public class OtherDeviceFactory : EssentialsPluginDeviceFactory<OtherDevice>
{
// This method defines metadata for the devices in the plugin
public OtherDeviceFactory()
{
// This string is used to define the minimum version of the
// Essentials Framework required for this plugin
MinimumEssentialsFrameworkVersion = "1.5.0";
// This string is used to define all valid type names for
// this plugin. This string is case insensitive
TypeNames = new List<string> { "OtherDevice", "ThisOtherDevice" };
}
// This method instantiates new devices for the defined type
// within the plugin
public override EssentialsDevice BuildDevice(DeviceConfig dc)
{
// Deserialize the json properties for the loaded type to a new object
var props = dc.Properties.ToObject<OtherDeviceProperties>();
// Return a newly instantiated device using the desired constructor
// If no valid property data exists, return null with console print
// describing the failure.
if (props == null)
{
Debug.Console(0, "No valid property data for 'OtherDevice' - Verify Configuration.");
Debug.Console(0, dc.Properties.ToString());
return null;
}
return new OtherDevice(dc.Key, dc.Name, props);
}
}
}
```
## SIMPL Bridging
Optionally, if your plugin device needs to be able to bridge to a SIMPL program over EISC, and there isn't already an existing bridge class in the Essentials Framework, you can write a new bridge class in your plugin. However, in order for the Essentials Application to be able to us that new bridge, the bridge must implement the ```IBridgeAdvanced``` interface with the required ```LinkToApi()``` Extension method.
If you are writing code for a bridgeable device, you should be inheriting from ```EssentialsBridgeableDevice```, which inherits from the already-required ```EssentialsDevice``` and implements ```IBridgeAdvanced```.
Often though, you may find that a bridge class already exists in the Essentials Framework that you can leverage. For example, if you were writing a plugin to support a new display model that isn't already in the Essentials Framework, you would define a class in your plugin that inherits from PepperDash.Essentials.Core.DisplayBase. If you're only implementing the standard display control functions such as power/input/volume control, then the existing bridge class `DisplayControllerBridge` can be used. If you needed to add additional functions to the bridge, then you would need to write your own bridge in the plugin.
For additional info see the [SIMPL-Bridging article](SIMPL-Bridging).
## Template Essentials Plugin Repository
Fork this repository when starting a new plugin. The template repository uses the essentials-builds repository as a submodule. This allows the plugin to reference a specific build version of Essentials. You must make sure that you checkout the correct build of the Essentials-Builds repo that contains any dependencies that your plugin may rely on.
[Essentials Plugin Template Repository](https://github.com/PepperDash/EssentialsPluginTemplate)

107
Plugins.md

@@ -1,6 +1,6 @@
# What are Essentials Plugins?
**Note : this entry is out of date - please see [Plugins - Updated](Plugins-Updated)**
**Note : this entry updates a deprecated method - for information related to that deprecated method, see [Plugins - Deprecated](Plugins-Deprecated)**
Plugins are SIMPL# Pro libraries that reference the Essentials Framework and can be loaded into an Essentials Application at runtime to extend functionality beyond what the Essentials Framework provides on its own.
@@ -20,46 +20,99 @@ One or more plugins can be loaded to the /user/ProgramX/plugins as .dlls or .cpl
## What Must be Implemented in a Plugin for it to Work?
All plugin assemblies must contain a static method called LoadPlugin():
All plugin assemblies must contain a class which inherits from ```EssentialsPluginDeviceFactory<T>```, where ```<T>``` is a class which inherits from ```PepperDash.Essentials.Core.EssentialsDevice```
Within this class, we will define some metadata for the plugin and define which constructor to use
for instantiating each class as defined by type.
Note that multiple types can be loaded from the same plugin.
```cs
public class SomeDevice : Device , IBridge //IBridge only needs to be implemented if using a bridge
using System;
using Crestron.SimplSharp;
using Crestron.SimplSharpPro;
using PepperDash.Essentials.Core;
using PepperDash.Essentials.Core.Config;
using PepperDash.Core;
using System.Collections.Generic;
namespace MyPlugin
{
// This string is used to define the minimum version of the
// Essentials Framework required for this plugin
public static string MinimumEssentialsFrameworkVersion = "1.4.23";
// This method gets called by the Essentials Framework when the application starts.
// It is intended to be used to load the new Device type(s) specified in the plugin
public static void LoadPlugin()
public class SomeDeviceFactory : EssentialsPluginDeviceFactory<SomeDevice>
{
DeviceFactory.AddFactoryForType("typeName", FactoryMethod);
// typeName should be the unique string that identifies the type of device to build,
// FactoryMethod represents the method that takes a DevicConfig object as and argument
// and returns an instance of the desired device type
// This method defines metadata for the devices in the plugin
public SomeDeviceFactory()
{
// This string is used to define the minimum version of the
// Essentials Framework required for this plugin
MinimumEssentialsFrameworkVersion = "1.5.0";
// This string is used to define all valid type names for
// this plugin. This string is case insensitive
TypeNames = new List<string> { "SomeDevice" , "ThisNewDevice" };
}
// This method instantiates new devices for the defined type
// within the plugin
public override EssentialsDevice BuildDevice(DeviceConfig dc)
{
// Deserialize the json properties for the loaded type to a new object
var props = dc.Properties.ToObject<SomeDeviceProperties>();
// Return a newly instantiated device using the desired constructor
// If no valid property data exists, return null with console print
// describing the failure.
if (props == null)
{
Debug.Console(0, "No valid property data for 'SomeDevice' - Verify Configuration.");
Debug.Console(0, dc.Properties.ToString());
return null;
}
return new SomeDevice(dc.Key, dc.Name, props);
}
}
// This is a factory method to construct a device and return it to be
// added to the DeviceManager
public static Device FactoryMethod(DeviceConfig dc)
public class OtherDeviceFactory : EssentialsPluginDeviceFactory<OtherDevice>
{
return new SomeDevice(dc.key, dc.name, dc);
}
// This method defines metadata for the devices in the plugin
public OtherDeviceFactory()
{
// This string is used to define the minimum version of the
// Essentials Framework required for this plugin
MinimumEssentialsFrameworkVersion = "1.5.0";
#region IBridge
// This method is called by an EiscApi bridge instance and should call an extension method
// defined in your plugin. Required for implementing IBridge
public void LinkToApi(BasicTriList trilist, uint joinStart, string joinMapKey)
{
this.LinkToApiExt(trilist, joinStart, joinMapKey);
// This string is used to define all valid type names for
// this plugin. This string is case insensitive
TypeNames = new List<string> { "OtherDevice", "ThisOtherDevice" };
}
// This method instantiates new devices for the defined type
// within the plugin
public override EssentialsDevice BuildDevice(DeviceConfig dc)
{
// Deserialize the json properties for the loaded type to a new object
var props = dc.Properties.ToObject<OtherDeviceProperties>();
// Return a newly instantiated device using the desired constructor
// If no valid property data exists, return null with console print
// describing the failure.
if (props == null)
{
Debug.Console(0, "No valid property data for 'OtherDevice' - Verify Configuration.");
Debug.Console(0, dc.Properties.ToString());
return null;
}
return new OtherDevice(dc.Key, dc.Name, props);
}
}
#endregion
}
```
## SIMPL Bridging
Optionally, if your plugin device needs to be able to bridge to a SIMPL program over EISC, and there isn't already an existing bridge class in the Essentials Framework, you can write a new bridge class in your plugin. However, in order for the Essentials Application to be able to us that new bridge, the bridge must implement the IBridge interface with the required LinkToApi() Extension method.
Optionally, if your plugin device needs to be able to bridge to a SIMPL program over EISC, and there isn't already an existing bridge class in the Essentials Framework, you can write a new bridge class in your plugin. However, in order for the Essentials Application to be able to us that new bridge, the bridge must implement the ```IBridgeAdvanced``` interface with the required ```LinkToApi()``` Extension method.
If you are writing code for a bridgeable device, you should be inheriting from ```EssentialsBridgeableDevice```, which inherits from the already-required ```EssentialsDevice``` and implements ```IBridgeAdvanced```.
Often though, you may find that a bridge class already exists in the Essentials Framework that you can leverage. For example, if you were writing a plugin to support a new display model that isn't already in the Essentials Framework, you would define a class in your plugin that inherits from PepperDash.Essentials.Core.DisplayBase. If you're only implementing the standard display control functions such as power/input/volume control, then the existing bridge class `DisplayControllerBridge` can be used. If you needed to add additional functions to the bridge, then you would need to write your own bridge in the plugin.

477
SIMPL-Bridging-Deprecated.md Normal file

@@ -0,0 +1,477 @@
# Deprecated
**Note : this entry is out of date - please see [SIMPL Windows Bridging](SIMPL-Bridging)**
## SIMPL Windows Bridging - Deprecated
Essentials allows for devices defined within the SIMPL# Pro application to be bridged to a SIMPL Windows application over Ethernet Intersystem Communication (EISC). This allows a SIMPL Windows program to take advantage of some of the features of the SIMPL# Pro environment, without requiring the entire application to be written in C#.
Some of the main advantages are:
1. The ability to instantiate devices from configuration.
1. The ability to leverage C# concepts to handle data intensive tasks (Serialization/Deserialization of JSON/XML, cyrptography, etc.).
1. The ability to reuse the same compiled SIMPL Windows program (regardless of target processor type) by offloading all the variables that may be room or hardware specific to Essentials.
1. The ability to handle multiple communciation types generically without changing the SIMPL Program (TCP/UDP/SSH/HTTP/HTTPS/CEC, etc.)
1. Much faster development cycle
1. Reduced processor overhead
1. Ability to easily share devices defined in Essentials between multiple other programs
## Implementation
Bridges are devices that are defined within the devices array in the config file. They are unique devices with a specialized purpose; to act as a bridge between Essentials Devices and applications programmed traditionally in Simpl Windows. This is accomplished by instantiating a Three Series Intersystem Communication symbol within the bridge device, and linking its Boolean/Ushort/String inputs and outputs to actions on one or multiple Essentials device(s). The definition for which joins map to which actions is defined within the device to be bridged to in a class that derives from JoinMapBase.
Let's consider the following Essentials Configuration:
```JSON
{
"template": {
"roomInfo": [
{}
],
"devices": [
{
"key": "processor",
"uid": 1,
"type": "pro3",
"name": "PRO3 w/o cards",
"group": "processor",
"supportedConfigModes": [
"essentials"
],
"supportedSystemTypes": [
"hudType",
"presType",
"vtcType",
"custom"
],
"supportsCompliance": true,
"properties": {
"numberOfComPorts": 6,
"numberOfIrPorts": 8,
"numberOfRelays": 8,
"numberOfDIOPorts": 8
}
},
{
"key": "panasonicDisplay01",
"type": "PanasonicThefDisplay",
"name": "Main Display",
"group": "displays",
"uid": 2,
"properties": {
"id": "01",
"inputNumber": 1,
"outputNumber": 1,
"control": {
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 9600,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
},
"controlPortNumber": 1,
"controlPortDevKey": "processor",
"method": "com"
}
}
},
{
"key": "vtcComPort",
"uid": 3,
"name": "VTC Coms",
"group": "comm",
"type": "genericComm",
"properties": {
"control": {
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 38400,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
},
"controlPortNumber": 2,
"controlPortDevKey": "processor",
"method": "com"
}
}
},
{
"key": "deviceBridge",
"uid": 4,
"name": "BridgeToDevices",
"group": "api",
"type": "eiscApi",
"properties": {
"control": {
"tcpSshProperties": {
"address": "127.0.0.2",
"port": 0
},
"ipid": "03",
"method": "ipidTcp"
},
"devices": [
{
"deviceKey": "panasonicDisplay01",
"joinStart": 1
},
{
"deviceKey": "vtcComPort",
"joinStart": 51
}
]
}
}
]
}
}
```
We have four Essentials Devices configured:
1. Pro3 with a Key of "processor"
1. Panasonic Display with a Key of "panasonicDisplay01"
1. Com port with a Key of "vtcComPort"
1. Bridge with a Key of "deviceBridge"
We want to have access to the com port for VTC Control from Simpl Windows and we want to control the display from Simpl Windows. To accomplish this, we have created a bridge device and added the devices to be bridged to the "devices" array on the bridge. As you can see we define the device key and the join start, which will determine which joins we will use on the resulting EISC to interact with the devices. In the Bridge control properties we defined ipid 03, and we will need a corresponding Ethernet System Intercommunication in the Simpl Windows program at ipid 03.
Now that our devices have been built, we can refer to the device join maps to see which joins correspond to which actions.
See below:
```cs
namespace PepperDash.Essentials.Bridges
{
public class DisplayControllerJoinMap : JoinMapBase
{
#region Digitals
/// <summary>
/// Turns the display off and reports power off feedback
/// </summary>
public uint PowerOff { get; set; }
/// <summary>
/// Turns the display on and repots power on feedback
/// </summary>
public uint PowerOn { get; set; }
/// <summary>
/// Indicates that the display device supports two way communication when high
/// </summary>
public uint IsTwoWayDisplay { get; set; }
/// <summary>
/// Increments the volume while high
/// </summary>
public uint VolumeUp { get; set; }
/// <summary>
/// Decrements teh volume while high
/// </summary>
public uint VolumeDown { get; set; }
/// <summary>
/// Toggles the mute state. Feedback is high when volume is muted
/// </summary>
public uint VolumeMute { get; set; }
/// <summary>
/// Range of digital joins to select inputs and report current input as feedback
/// </summary>
public uint InputSelectOffset { get; set; }
/// <summary>
/// Range of digital joins to report visibility for input buttons
/// </summary>
public uint ButtonVisibilityOffset { get; set; }
/// <summary>
/// High if the device is online
/// </summary>
public uint IsOnline { get; set; }
#endregion
#region Analogs
/// <summary>
/// Analog join to set the input and report current input as feedback
/// </summary>
public uint InputSelect { get; set; }
/// <summary>
/// Sets the volume level and reports the current level as feedback
/// </summary>
public uint VolumeLevel { get; set; }
#endregion
#region Serials
/// <summary>
/// Reports the name of the display as defined in config as feedback
/// </summary>
public uint Name { get; set; }
/// <summary>
/// Range of serial joins that reports the names of the inputs as feedback
/// </summary>
public uint InputNamesOffset { get; set; }
#endregion
public DisplayControllerJoinMap()
{
// Digital
IsOnline = 50;
PowerOff = 1;
PowerOn = 2;
IsTwoWayDisplay = 3;
VolumeUp = 5;
VolumeDown = 6;
VolumeMute = 7;
ButtonVisibilityOffset = 40;
InputSelectOffset = 10;
// Analog
InputSelect = 11;
VolumeLevel = 5;
// Serial
Name = 1;
InputNamesOffset = 10;
}
public override void OffsetJoinNumbers(uint joinStart)
{
var joinOffset = joinStart - 1;
IsOnline = IsOnline + joinOffset;
PowerOff = PowerOff + joinOffset;
PowerOn = PowerOn + joinOffset;
IsTwoWayDisplay = IsTwoWayDisplay + joinOffset;
ButtonVisibilityOffset = ButtonVisibilityOffset + joinOffset;
Name = Name + joinOffset;
InputNamesOffset = InputNamesOffset + joinOffset;
InputSelectOffset = InputSelectOffset + joinOffset;
InputSelect = InputSelect + joinOffset;
VolumeUp = VolumeUp + joinOffset;
VolumeDown = VolumeDown + joinOffset;
VolumeMute = VolumeMute + joinOffset;
VolumeLevel = VolumeLevel + joinOffset;
}
}
}
```
We know that the Panasonic Display uses the DisplayControllerJoinMap class and can see the join numbers that will give us access to functionality in the Device.
IsOnline = 50
PowerOff = 1
PowerOn = 2
IsTwoWayDisplay = 3
VolumeUp = 5
VolumeDown = 6
VolumeMute = 7
```cs
namespace PepperDash.Essentials.Bridges
{
public class IBasicCommunicationJoinMap : JoinMapBase
{
#region Digitals
/// <summary>
/// Set High to connect, Low to disconnect
/// </summary>
public uint Connect { get; set; }
/// <summary>
/// Reports Connected State (High = Connected)
/// </summary>
public uint Connected { get; set; }
#endregion
#region Analogs
/// <summary>
/// Reports the connections status value
/// </summary>
public uint Status { get; set; }
#endregion
#region Serials
/// <summary>
/// Data back from port
/// </summary>
public uint TextReceived { get; set; }
/// <summary>
/// Sends data to the port
/// </summary>
public uint SendText { get; set; }
/// <summary>
/// Takes a JSON serialized string that sets a COM port's parameters
/// </summary>
public uint SetPortConfig { get; set; }
#endregion
public IBasicCommunicationJoinMap()
{
TextReceived = 1;
SendText = 1;
SetPortConfig = 2;
Connect = 1;
Connected = 1;
Status = 1;
}
public override void OffsetJoinNumbers(uint joinStart)
{
var joinOffset = joinStart - 1;
TextReceived = TextReceived + joinOffset;
SendText = SendText + joinOffset;
SetPortConfig = SetPortConfig + joinOffset;
Connect = Connect + joinOffset;
Connected = Connected + joinOffset;
Status = Status + joinOffset;
}
}
}
```
TextReceived = 1
SendText = 1
SetPortConfig = 2
Connect = 1
Connected = 1
Status = 1
Considering our Bridge config, we can see that the display controls will start at join 1, and the VTC Com port will start at join 51. The result is a single EISC that allows us to interact with our Essentials devices.
To control diplay power from Simpl Windows, we would connect Digital Signals to joins 1 & 2 on the EISC to control Display Power On & Off.
To utilize the com port device, we would connect Serial Signals (VTC_TX$ and VTC_RX$) to join 51 on the EISC.
You can refer to our [Simpl Windows Bridging Example](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for a more complex example.
Example device config: <https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Example%20Configuration/SIMPLBridging/SIMPLBridgeExample_configurationFile.json>
## Notes
1. It is important to realize that there are no safety checks (yet) when assigning joinStarts in bridge configurations. If you were to put two devices on a bridge with overlapping joins, the most recently bridged join would overwrite previously bridged joins. For now it is on the programmer to ensure there are no conflicting join maps.
1. There is _no_ limit to the amount of times a device may be bridged to. You may have the same device on multiple bridges across multiple applications without problem. That being said, we recommend using common sense. Accessing a single com port for VTC control via multiple bridges may not be wise...
1. A bridge need not only bridge between applications on the same processor. A bridge may bridge to an application on a completely separate processor; simply define the ip address in the Bridge control properties accordingly.
1. For devices included in Essentials, you will be able to find defined join maps below. If you are building your own plugins, you will need to build the join map yourself. It would be beneficial to review the wiki entry on the [Feedback Class](https://github.com/PepperDash/Essentials/wiki/Feedback-Classes) for this.
1. When building plugins, we highly recommend reusing JoinMaps, as this will make code more easily interchangeable. For example; if you were to build a display plugin, we'd recommend you use/extend the existing DisplayControllerJoinMap. This way, you can swap plugins without needing any change on the Simpl Windows side. This is extremely powerful when maintaining Simpl Windows code bases for large deployments that may utilize differing equipment per room. If you can build a Simpl Windows program that interacts with established join maps, you can swap out the device via config without any change needed to Simpl Windows.
1. Related to item 5, you can use the same paradigm with respect to physical device communication. If you were to have a DSP device in some rooms communicating over RS232 and some via SSH, it would be trival to swap the device from a Com port to an SSH client in the Essentials Devicee Config and update the Bridge Config to brigde to the desired communication method. Again this would require no change on the Simpl Windows side as long as you maintain the same join Start in the Bridge Device Configuration.
## Common Use Cases
1. There are 10 conference rooms that all operate the same, but have hardware differences that are impossible to account for in SIMPL Windows. For example, each room might have a DM-MD8X8 chassis, but the input and output cards aren't all in the same order, or they might be different models but function the same. You can use Essentials with a unique configuration file for each hardware configuration.
1. You have a floor of conference rooms that all share some centralized hardware like DSP, AV Routing and a shared CEN-GWEXER gateway with multiple GLS-OIR-CSM-EX-BATT occupancy sensors. All the shared hardware can be defined in the Essentials configuration and bridged over an EISC to each program that needs access. The same device can even be exposed to multiple programs over different EISCs.
1. You have a SIMPL program that works for many room types, but because some rooms have different models of processors than others (CP3/CP3N/AV3/PRO3/DMPS3 variants), you have to maintain several versions of the program, compiled for each processor model to maintain access to features like the System Monitor slot. You can use Essentials running in a slot on a processor to expose the System Monitor and many other features of the processor, regardless of model. Now you only need to maintain a single SIMPL program defined for your most complex processor application (ex. PRO3)
## Device Type Join Maps
### AirMediaController
> supports: AM-200, AM-300
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/AirMediaControllerJoinMap.cs>
### AppleTvController
> supports: IR control of Apple TV
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/AppleTvJoinMap.cs>
### CameraControlBase
> supports: any camera that derives from CameraBase
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/CameraControllerJoinMap.cs>
### DisplayController
> supports: IR controlled displays, any two way display driver that derives from PepperDash.Essentials.Core.DisplayBase
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DisplayControllerJoinMap.cs>
### DmChasisController
> supports: All DM-MD-8x8/16x16/32x32 chassis, with or w/o DM-CPU3 Card
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmChassisControllerJoinMap.cs>
### DmRmcController
> supports: All DM-RMC devices
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmRmcControllerJoinMap.cs>
### DmTxController
> supports: All Dm-Tx devices
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmTxControllerJoinMap.cs>
### DmpsAudioOutputController
> supports: Program, Aux1, Aux2 outputs of all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmpsAudioOutputControllerJoinMap.cs>
### DmpsRoutingController
> supports: Av routing for all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmpsRoutingControllerJoinMap.cs>
### GenericRelayController
> supports: Any relay port on a Crestron Control System or Dm Endpoint
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/GenericRelayControllerJoinMap.cs>
### GenericLightingJoinMap
> supports: Devices derived from PepperDash.Essentials.Core.Lighting.LightingBase
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/GenericLightingJoinMap.cs>
### GlsOccupancySensorBase
> supports: Any Crestron GLS-Type Occupancy sensor - single/dual type
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/GlsOccupancySensorBaseJoinMap.cs>
### HdMdxxxCEController
> supports: HD-MD-400-C-E, HD-MD-300-C-E, HD-MD-200-C-E, HD-MD-200-C-1G-E-B/W
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/HdMdxxxCEControllerJoinMap.cs>
### IBasicCommunication
> supports: Any COM Port on a Control System or Dm Endpoint device, TCP Client, SSH Client, or UDP Server
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/IBasicCommunicationJoinMap.cs>
### IDigitalInput
> supports: Any Digital Input on a Control System, or DM Endpoint device
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/IDigitalInputJoinMap.cs>
### SystemMonitorController
> supports: Exposing the system monitor slot for any Control System
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/SystemMonitorJoinMap.cs>
## Example SIMPL Windows Program
We've provided an [example program](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for SIMPL Windows that works with the provided example Essentials configuration file [SIMPLBridgeExample_configurationFile.json](https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Example%20Configuration/SIMPLBridging/SIMPLBridgeExample_configurationFile.json). Load Essentials and the example SIMPL program to two slots on the same processor and you can get a better idea of how to take advantage of SIMPL Windows bridging.
Next: [Essentials architecture](Arch-summary)

407
SIMPL-Bridging-Updated.md

@@ -1,407 +0,0 @@
# SIMPL Windows Bridging
Essentials allows for devices defined within the SIMPL# Pro application to be bridged to a SIMPL Windows application over Ethernet Intersystem Communication (EISC). This allows a SIMPL Windows program to take advantage of some of the features of the SIMPL# Pro environment, without requiring the entire application to be written in C#.
Some of the main advantages are:
1. The ability to instantiate devices from configuration.
2. The ability to leverage C# concepts to handle data intensive tasks (Serialization/Deserialization of JSON/XML, cyrptography, etc.).
3. The ability to reuse the same compiled SIMPL Windows program (regardless of target processor type) by offloading all the variables that may be room or hardware specific to Essentials.
4. The ability to handle multiple communciation types generically without changing the SIMPL Program (TCP/UDP/SSH/HTTP/HTTPS/CEC, etc.)
5. Much faster development cycle
6. Reduced processor overhead
7. Ability to easily share devices defined in Essentials between multiple other programs
## Implementation
Bridges are devices that are defined within the devices array in the config file. They are unique devices with a specialized purpose: to act as a bridge between Essentials Devices and applications programmed traditionally in SIMPL Windows. This is accomplished by instantiating a Three Series Intersystem Communication symbol within the bridge device, and linking its Boolean/Ushort/String inputs and outputs to actions on one or multiple Essentials device(s). The definition for which joins map to which actions is defined within the device to be bridged to in a class that derives from JoinMapBase.
Let's consider the following Essentials Configuration:
```JSON
{
"template": {
"roomInfo": [
{}
],
"devices": [
{
"key": "processor",
"uid": 1,
"type": "pro3",
"name": "PRO3 w/o cards",
"group": "processor",
"supportedConfigModes": [
"essentials"
],
"supportedSystemTypes": [
"hudType",
"presType",
"vtcType",
"custom"
],
"supportsCompliance": true,
"properties": {
"numberOfComPorts": 6,
"numberOfIrPorts": 8,
"numberOfRelays": 8,
"numberOfDIOPorts": 8
}
},
{
"key": "panasonicDisplay01",
"type": "PanasonicThefDisplay",
"name": "Main Display",
"group": "displays",
"uid": 2,
"properties": {
"id": "01",
"inputNumber": 1,
"outputNumber": 1,
"control": {
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 9600,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
},
"controlPortNumber": 1,
"controlPortDevKey": "processor",
"method": "com"
}
}
},
{
"key": "vtcComPort",
"uid": 3,
"name": "VTC Coms",
"group": "comm",
"type": "genericComm",
"properties": {
"control": {
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 38400,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
},
"controlPortNumber": 2,
"controlPortDevKey": "processor",
"method": "com"
}
}
},
{
"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": "panasonicDisplay01",
"joinStart": 1
},
{
"deviceKey": "vtcComPort",
"joinStart": 51
}
]
}
}
]
}
}
```
We have four Essentials Devices configured:
1. Pro3 with a Key of "processor"
1. Panasonic Display with a Key of "panasonicDisplay01"
1. Com port with a Key of "vtcComPort"
1. Bridge with a Key of "deviceBridge"
We want to have access to the com port for VTC Control from SIMPL Windows and we want to control the display from SIMPL Windows. To accomplish this, we have created a bridge device and added the devices to be bridged to the "devices" array on the bridge. As you can see we define the device key and the join start, which will determine which joins we will use on the resulting EISC to interact with the devices. In the Bridge control properties we defined ipid 03, and we will need a corresponding Ethernet System Intercommunication in the SIMPL Windows program at ipid 03.
Now that our devices have been built, we can refer to the device join maps to see which joins correspond to which actions.
See below:
```cs
namespace PepperDash.Essentials.Core.Bridges
{
public class DisplayControllerJoinMap : JoinMapBaseAdvanced
{
[JoinName("Name")]
public JoinDataComplete Name = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Name", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Serial });
[JoinName("PowerOff")]
public JoinDataComplete PowerOff = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Power Off", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital });
[JoinName("PowerOn")]
public JoinDataComplete PowerOn = new JoinDataComplete(new JoinData() { JoinNumber = 2, JoinSpan = 1 },
new JoinMetadata() { Label = "Power On", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("IsTwoWayDisplay")]
public JoinDataComplete IsTwoWayDisplay = new JoinDataComplete(new JoinData() { JoinNumber = 3, JoinSpan = 1 },
new JoinMetadata() { Label = "Is Two Way Display", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeUp")]
public JoinDataComplete VolumeUp = new JoinDataComplete(new JoinData() { JoinNumber = 5, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Up", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeLevel")]
public JoinDataComplete VolumeLevel = new JoinDataComplete(new JoinData() { JoinNumber = 5, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Level", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Analog });
[JoinName("VolumeDown")]
public JoinDataComplete VolumeDown = new JoinDataComplete(new JoinData() { JoinNumber = 6, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Down", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeMute")]
public JoinDataComplete VolumeMute = new JoinDataComplete(new JoinData() { JoinNumber = 7, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Mute", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeMuteOn")]
public JoinDataComplete VolumeMuteOn = new JoinDataComplete(new JoinData() { JoinNumber = 8, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Mute On", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeMuteOff")]
public JoinDataComplete VolumeMuteOff = new JoinDataComplete(new JoinData() { JoinNumber = 9, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Mute Off", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("InputSelectOffset")]
public JoinDataComplete InputSelectOffset = new JoinDataComplete(new JoinData() { JoinNumber = 11, JoinSpan = 10 },
new JoinMetadata() { Label = "Input Select", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("InputNamesOffset")]
public JoinDataComplete InputNamesOffset = new JoinDataComplete(new JoinData() { JoinNumber = 11, JoinSpan = 10 },
new JoinMetadata() { Label = "Input Names Offset", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Serial });
[JoinName("InputSelect")]
public JoinDataComplete InputSelect = new JoinDataComplete(new JoinData() { JoinNumber = 11, JoinSpan = 1 },
new JoinMetadata() { Label = "Input Select", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Analog });
[JoinName("ButtonVisibilityOffset")]
public JoinDataComplete ButtonVisibilityOffset = new JoinDataComplete(new JoinData() { JoinNumber = 41, JoinSpan = 10 },
new JoinMetadata() { Label = "Button Visibility Offset", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.DigitalSerial });
[JoinName("IsOnline")]
public JoinDataComplete IsOnline = new JoinDataComplete(new JoinData() { JoinNumber = 50, JoinSpan = 1 },
new JoinMetadata() { Label = "Is Online", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital });
public DisplayControllerJoinMap(uint joinStart)
: base(joinStart, typeof(CameraControllerJoinMap))
{
}
}
}
```
We know that the Panasonic Display uses the DisplayControllerJoinMap class and can see the join numbers that will give us access to functionality in the Device.
IsOnline = 50
PowerOff = 1
PowerOn = 2
IsTwoWayDisplay = 3
VolumeUp = 5
VolumeDown = 6
VolumeMute = 7
```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))
{
}
}
}
```
Considering our Bridge config, we can see that the display controls will start at join 1, and the VTC Com port will start at join 51. The result is a single EISC that allows us to interact with our Essentials devices.
To control diplay power from SIMPL Windows, we would connect Digital Signals to joins 1 & 2 on the EISC to control Display Power On & Off.
To utilize the com port device, we would connect Serial Signals (VTC_TX$ and VTC_RX$) to join 51 on the EISC.
You can refer to our [SIMPL Windows Bridging Example](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for a more complex example.
Example device config: <https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Example%20Configuration/SIMPLBridging/SIMPLBridgeExample_configurationFile.json>
## Notes
1. It is important to realize that there are no safety checks (yet) when assigning joinStarts in bridge configurations. If you were to put two devices on a bridge with overlapping joins, the most recently bridged join would overwrite previously bridged joins. For now it is on the programmer to ensure there are no conflicting join maps.
2. There is _no_ limit to the amount of times a device may be bridged to. You may have the same device on multiple bridges across multiple applications without problem. That being said, we recommend using common sense. Accessing a single com port for VTC control via multiple bridges may not be wise...
3. A bridge need not only bridge between applications on the same processor. A bridge may bridge to an application on a completely separate processor; simply define the ip address in the Bridge control properties accordingly.
4. For devices included in Essentials, you will be able to find defined join maps below. If you are building your own plugins, you will need to build the join map yourself. It would be beneficial to review the wiki entry on the [Feedback Class](https://github.com/PepperDash/Essentials/wiki/Feedback-Classes) for this.
5. When building plugins, we highly recommend reusing JoinMaps, as this will make code more easily interchangeable. For example; if you were to build a display plugin, we'd recommend you use/extend the existing `DisplayControllerJoinMap`. This way, you can swap plugins without needing any change on the SIMPL Windows side. This is extremely powerful when maintaining SIMPL Windows code bases for large deployments that may utilize differing equipment per room. If you can build a SIMPL Windows program that interacts with established join maps, you can swap out the device via config without any change needed to SIMPL Windows.
6. Related to item 5, you can use the same paradigm with respect to physical device communication. If you were to have a DSP device in some rooms communicating over RS232 and some via SSH, it would be trival to swap the device from a Com port to an SSH client in the Essentials Devicee Config and update the Bridge Config to brigde to the desired communication method. Again this would require no change on the SIMPL Windows side as long as you maintain the same join Start in the Bridge Device Configuration.
## Common Use Cases
1. There are 10 conference rooms that all operate the same, but have hardware differences that are impossible to account for in SIMPL Windows. For example, each room might have a DM-MD8X8 chassis, but the input and output cards aren't all in the same order, or they might be different models but function the same. You can use Essentials with a unique configuration file for each hardware configuration.
2. You have a floor of conference rooms that all share some centralized hardware like DSP, AV Routing and a shared CEN-GWEXER gateway with multiple GLS-OIR-CSM-EX-BATT occupancy sensors. All the shared hardware can be defined in the Essentials configuration and bridged over an EISC to each program that needs access. The same device can even be exposed to multiple programs over different EISCs.
3. You have a SIMPL program that works for many room types, but because some rooms have different models of processors than others (CP3/CP3N/AV3/PRO3/DMPS3 variants), you have to maintain several versions of the program, compiled for each processor model to maintain access to features like the System Monitor slot. You can use Essentials running in a slot on a processor to expose the System Monitor and many other features of the processor, regardless of model. Now you only need to maintain a single SIMPL program defined for your most complex processor application (ex. PRO3)
## Join Map Documentation
[Join Map Documentation](JoinMaps)
## Device Type Join Maps
Please note that these joinmaps _may_ be using a deprecated implementation. The implementation is valid but nonetheless frowned upon for new features and plugins.
### AirMediaController
> supports: AM-200, AM-300
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/AirMediaControllerJoinMap.cs>
### AppleTvController
> supports: IR control of Apple TV
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/AppleTvJoinMap.cs>
### CameraControlBase
> supports: any camera that derives from CameraBase
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/CameraControllerJoinMap.cs>
### DisplayController
> supports: IR controlled displays, any two way display driver that derives from PepperDash.Essentials.Core.DisplayBase
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DisplayControllerJoinMap.cs>
### DmChasisController
> supports: All DM-MD-8x8/16x16/32x32 chassis, with or w/o DM-CPU3 Card
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmChassisControllerJoinMap.cs>
### DmRmcController
> supports: All DM-RMC devices
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmRmcControllerJoinMap.cs>
### DmTxController
> supports: All Dm-Tx devices
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmTxControllerJoinMap.cs>
### DmpsAudioOutputController
> supports: Program, Aux1, Aux2 outputs of all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmpsAudioOutputControllerJoinMap.cs>
### DmpsRoutingController
> supports: Av routing for all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmpsRoutingControllerJoinMap.cs>
### GenericRelayController
> supports: Any relay port on a Crestron Control System or Dm Endpoint
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/GenericRelayControllerJoinMap.cs>
### GenericLightingJoinMap
> supports: Devices derived from PepperDash.Essentials.Core.Lighting.LightingBase
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/GenericLightingJoinMap.cs>
### GlsOccupancySensorBase
> supports: Any Crestron GLS-Type Occupancy sensor - single/dual type
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/GlsOccupancySensorBaseJoinMap.cs>
### HdMdxxxCEController
> supports: HD-MD-400-C-E, HD-MD-300-C-E, HD-MD-200-C-E, HD-MD-200-C-1G-E-B/W
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/HdMdxxxCEControllerJoinMap.cs>
### IBasicCommunication
> supports: Any COM Port on a Control System or Dm Endpoint device, TCP Client, SSH Client, or UDP Server
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/IBasicCommunicationJoinMap.cs>
### IDigitalInput
> supports: Any Digital Input on a Control System, or DM Endpoint device
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/IDigitalInputJoinMap.cs>
### SystemMonitorController
> supports: Exposing the system monitor slot for any Control System
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/SystemMonitorJoinMap.cs>
## Example SIMPL Windows Program
We've provided an [example program](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for SIMPL Windows that works with the provided example Essentials configuration file [SIMPLBridgeExample_configurationFile.json](https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Example%20Configuration/SIMPLBridging/SIMPLBridgeExample_configurationFile.json). Load Essentials and the example SIMPL program to two slots on the same processor and you can get a better idea of how to take advantage of SIMPL Windows bridging.
Next: [Essentials architecture](Arch-summary)

338
SIMPL-Bridging.md

@@ -1,24 +1,24 @@
# SIMPL Windows Bridging
**Note : this entry is out of date - please see [SIMPL Windows Bridging - Updated](SIMPL-Bridging-Updated)**
**Note : this entry updates a deprecated method - for information related to that deprecated method, see [SIMPL Windows Bridging - Deprecated](SIMPL-Bridging-Deprecated)**
Essentials allows for devices defined within the SIMPL# Pro application to be bridged to a SIMPL Windows application over Ethernet Intersystem Communication (EISC). This allows a SIMPL Windows program to take advantage of some of the features of the SIMPL# Pro environment, without requiring the entire application to be written in C#.
Essentials allows for devices defined within the SIMPL# Pro application to be bridged to a SIMPL Windows application over Ethernet Intersystem Communication (EISC). This allows a SIMPL Windows program to take advantage of some of the features of the SIMPL# Pro environment, without requiring the entire application to be written in C#.
Some of the main advantages are:
1. The ability to instantiate devices from configuration.
1. The ability to leverage C# concepts to handle data intensive tasks (Serialization/Deserialization of JSON/XML, cyrptography, etc.).
1. The ability to reuse the same compiled SIMPL Windows program (regardless of target processor type) by offloading all the variables that may be room or hardware specific to Essentials.
1. The ability to handle multiple communciation types generically without changing the SIMPL Program (TCP/UDP/SSH/HTTP/HTTPS/CEC, etc.)
1. Much faster development cycle
1. Reduced processor overhead
1. Ability to easily share devices defined in Essentials between multiple other programs
2. The ability to leverage C# concepts to handle data intensive tasks (Serialization/Deserialization of JSON/XML, cyrptography, etc.).
3. The ability to reuse the same compiled SIMPL Windows program (regardless of target processor type) by offloading all the variables that may be room or hardware specific to Essentials.
4. The ability to handle multiple communciation types generically without changing the SIMPL Program (TCP/UDP/SSH/HTTP/HTTPS/CEC, etc.)
5. Much faster development cycle
6. Reduced processor overhead
7. Ability to easily share devices defined in Essentials between multiple other programs
## Implementation
Bridges are devices that are defined within the devices array in the config file. They are unique devices with a specialized purpose; to act as a bridge between Essentials Devices and applications programmed traditionally in Simpl Windows. This is accomplished by instantiating a Three Series Intersystem Communication symbol within the bridge device, and linking its Boolean/Ushort/String inputs and outputs to actions on one or multiple Essentials device(s). The definition for which joins map to which actions is defined within the device to be bridged to in a class that derives from JoinMapBase.
Bridges are devices that are defined within the devices array in the config file. They are unique devices with a specialized purpose: to act as a bridge between Essentials Devices and applications programmed traditionally in SIMPL Windows. This is accomplished by instantiating a Three Series Intersystem Communication symbol within the bridge device, and linking its Boolean/Ushort/String inputs and outputs to actions on one or multiple Essentials device(s). The definition for which joins map to which actions is defined within the device to be bridged to in a class that derives from JoinMapBase.
Let's consider the following Essentials Configuration:
Let's consider the following Essentials Configuration:
```JSON
{
@@ -104,7 +104,7 @@ Let's consider the following Essentials Configuration:
"uid": 4,
"name": "BridgeToDevices",
"group": "api",
"type": "eiscApi",
"type": "eiscapiadv",
"properties": {
"control": {
"tcpSshProperties": {
@@ -141,120 +141,80 @@ We have four Essentials Devices configured:
1. Bridge with a Key of "deviceBridge"
We want to have access to the com port for VTC Control from Simpl Windows and we want to control the display from Simpl Windows. To accomplish this, we have created a bridge device and added the devices to be bridged to the "devices" array on the bridge. As you can see we define the device key and the join start, which will determine which joins we will use on the resulting EISC to interact with the devices. In the Bridge control properties we defined ipid 03, and we will need a corresponding Ethernet System Intercommunication in the Simpl Windows program at ipid 03.
We want to have access to the com port for VTC Control from SIMPL Windows and we want to control the display from SIMPL Windows. To accomplish this, we have created a bridge device and added the devices to be bridged to the "devices" array on the bridge. As you can see we define the device key and the join start, which will determine which joins we will use on the resulting EISC to interact with the devices. In the Bridge control properties we defined ipid 03, and we will need a corresponding Ethernet System Intercommunication in the SIMPL Windows program at ipid 03.
Now that our devices have been built, we can refer to the device join maps to see which joins correspond to which actions.
Now that our devices have been built, we can refer to the device join maps to see which joins correspond to which actions.
See below:
```cs
namespace PepperDash.Essentials.Bridges
namespace PepperDash.Essentials.Core.Bridges
{
public class DisplayControllerJoinMap : JoinMapBase
public class DisplayControllerJoinMap : JoinMapBaseAdvanced
{
#region Digitals
/// <summary>
/// Turns the display off and reports power off feedback
/// </summary>
public uint PowerOff { get; set; }
/// <summary>
/// Turns the display on and repots power on feedback
/// </summary>
public uint PowerOn { get; set; }
/// <summary>
/// Indicates that the display device supports two way communication when high
/// </summary>
public uint IsTwoWayDisplay { get; set; }
/// <summary>
/// Increments the volume while high
/// </summary>
public uint VolumeUp { get; set; }
/// <summary>
/// Decrements teh volume while high
/// </summary>
public uint VolumeDown { get; set; }
/// <summary>
/// Toggles the mute state. Feedback is high when volume is muted
/// </summary>
public uint VolumeMute { get; set; }
/// <summary>
/// Range of digital joins to select inputs and report current input as feedback
/// </summary>
public uint InputSelectOffset { get; set; }
/// <summary>
/// Range of digital joins to report visibility for input buttons
/// </summary>
public uint ButtonVisibilityOffset { get; set; }
/// <summary>
/// High if the device is online
/// </summary>
public uint IsOnline { get; set; }
#endregion
[JoinName("Name")]
public JoinDataComplete Name = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Name", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Serial });
#region Analogs
/// <summary>
/// Analog join to set the input and report current input as feedback
/// </summary>
public uint InputSelect { get; set; }
/// <summary>
/// Sets the volume level and reports the current level as feedback
/// </summary>
public uint VolumeLevel { get; set; }
#endregion
[JoinName("PowerOff")]
public JoinDataComplete PowerOff = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Power Off", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital });
#region Serials
/// <summary>
/// Reports the name of the display as defined in config as feedback
/// </summary>
public uint Name { get; set; }
/// <summary>
/// Range of serial joins that reports the names of the inputs as feedback
/// </summary>
public uint InputNamesOffset { get; set; }
#endregion
[JoinName("PowerOn")]
public JoinDataComplete PowerOn = new JoinDataComplete(new JoinData() { JoinNumber = 2, JoinSpan = 1 },
new JoinMetadata() { Label = "Power On", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
public DisplayControllerJoinMap()
[JoinName("IsTwoWayDisplay")]
public JoinDataComplete IsTwoWayDisplay = new JoinDataComplete(new JoinData() { JoinNumber = 3, JoinSpan = 1 },
new JoinMetadata() { Label = "Is Two Way Display", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeUp")]
public JoinDataComplete VolumeUp = new JoinDataComplete(new JoinData() { JoinNumber = 5, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Up", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeLevel")]
public JoinDataComplete VolumeLevel = new JoinDataComplete(new JoinData() { JoinNumber = 5, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Level", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Analog });
[JoinName("VolumeDown")]
public JoinDataComplete VolumeDown = new JoinDataComplete(new JoinData() { JoinNumber = 6, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Down", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeMute")]
public JoinDataComplete VolumeMute = new JoinDataComplete(new JoinData() { JoinNumber = 7, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Mute", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeMuteOn")]
public JoinDataComplete VolumeMuteOn = new JoinDataComplete(new JoinData() { JoinNumber = 8, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Mute On", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("VolumeMuteOff")]
public JoinDataComplete VolumeMuteOff = new JoinDataComplete(new JoinData() { JoinNumber = 9, JoinSpan = 1 },
new JoinMetadata() { Label = "Volume Mute Off", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("InputSelectOffset")]
public JoinDataComplete InputSelectOffset = new JoinDataComplete(new JoinData() { JoinNumber = 11, JoinSpan = 10 },
new JoinMetadata() { Label = "Input Select", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
[JoinName("InputNamesOffset")]
public JoinDataComplete InputNamesOffset = new JoinDataComplete(new JoinData() { JoinNumber = 11, JoinSpan = 10 },
new JoinMetadata() { Label = "Input Names Offset", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Serial });
[JoinName("InputSelect")]
public JoinDataComplete InputSelect = new JoinDataComplete(new JoinData() { JoinNumber = 11, JoinSpan = 1 },
new JoinMetadata() { Label = "Input Select", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Analog });
[JoinName("ButtonVisibilityOffset")]
public JoinDataComplete ButtonVisibilityOffset = new JoinDataComplete(new JoinData() { JoinNumber = 41, JoinSpan = 10 },
new JoinMetadata() { Label = "Button Visibility Offset", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.DigitalSerial });
[JoinName("IsOnline")]
public JoinDataComplete IsOnline = new JoinDataComplete(new JoinData() { JoinNumber = 50, JoinSpan = 1 },
new JoinMetadata() { Label = "Is Online", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital });
public DisplayControllerJoinMap(uint joinStart)
: base(joinStart, typeof(CameraControllerJoinMap))
{
// Digital
IsOnline = 50;
PowerOff = 1;
PowerOn = 2;
IsTwoWayDisplay = 3;
VolumeUp = 5;
VolumeDown = 6;
VolumeMute = 7;
ButtonVisibilityOffset = 40;
InputSelectOffset = 10;
// Analog
InputSelect = 11;
VolumeLevel = 5;
// Serial
Name = 1;
InputNamesOffset = 10;
}
public override void OffsetJoinNumbers(uint joinStart)
{
var joinOffset = joinStart - 1;
IsOnline = IsOnline + joinOffset;
PowerOff = PowerOff + joinOffset;
PowerOn = PowerOn + joinOffset;
IsTwoWayDisplay = IsTwoWayDisplay + joinOffset;
ButtonVisibilityOffset = ButtonVisibilityOffset + joinOffset;
Name = Name + joinOffset;
InputNamesOffset = InputNamesOffset + joinOffset;
InputSelectOffset = InputSelectOffset + joinOffset;
InputSelect = InputSelect + joinOffset;
VolumeUp = VolumeUp + joinOffset;
VolumeDown = VolumeDown + joinOffset;
VolumeMute = VolumeMute + joinOffset;
VolumeLevel = VolumeLevel + joinOffset;
}
}
}
@@ -268,208 +228,182 @@ PowerOn = 2
IsTwoWayDisplay = 3
VolumeUp = 5
VolumeDown = 6
VolumeMute = 7
VolumeMute = 7
```cs
namespace PepperDash.Essentials.Bridges
namespace PepperDash.Essentials.Core.Bridges
{
public class IBasicCommunicationJoinMap : JoinMapBase
public class IBasicCommunicationJoinMap : JoinMapBaseAdvanced
{
#region Digitals
/// <summary>
/// Set High to connect, Low to disconnect
/// </summary>
public uint Connect { get; set; }
/// <summary>
/// Reports Connected State (High = Connected)
/// </summary>
public uint Connected { get; set; }
#endregion
[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 });
#region Analogs
/// <summary>
/// Reports the connections status value
/// </summary>
public uint Status { get; set; }
#endregion
[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 });
#region Serials
/// <summary>
/// Data back from port
/// </summary>
public uint TextReceived { get; set; }
/// <summary>
/// Sends data to the port
/// </summary>
public uint SendText { get; set; }
/// <summary>
/// Takes a JSON serialized string that sets a COM port's parameters
/// </summary>
public uint SetPortConfig { get; set; }
#endregion
[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 });
public IBasicCommunicationJoinMap()
[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 = 1;
SendText = 1;
SetPortConfig = 2;
Connect = 1;
Connected = 1;
Status = 1;
}
public override void OffsetJoinNumbers(uint joinStart)
{
var joinOffset = joinStart - 1;
TextReceived = TextReceived + joinOffset;
SendText = SendText + joinOffset;
SetPortConfig = SetPortConfig + joinOffset;
Connect = Connect + joinOffset;
Connected = Connected + joinOffset;
Status = Status + joinOffset;
}
}
}
```
TextReceived = 1
SendText = 1
SetPortConfig = 2
Connect = 1
Connected = 1
Status = 1
Considering our Bridge config, we can see that the display controls will start at join 1, and the VTC Com port will start at join 51. The result is a single EISC that allows us to interact with our Essentials devices.
Considering our Bridge config, we can see that the display controls will start at join 1, and the VTC Com port will start at join 51. The result is a single EISC that allows us to interact with our Essentials devices.
To control diplay power from Simpl Windows, we would connect Digital Signals to joins 1 & 2 on the EISC to control Display Power On & Off.
To control diplay power from SIMPL Windows, we would connect Digital Signals to joins 1 & 2 on the EISC to control Display Power On & Off.
To utilize the com port device, we would connect Serial Signals (VTC_TX$ and VTC_RX$) to join 51 on the EISC.
You can refer to our [Simpl Windows Bridging Example](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for a more complex example.
You can refer to our [SIMPL Windows Bridging Example](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for a more complex example.
Example device config: <https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Example%20Configuration/SIMPLBridging/SIMPLBridgeExample_configurationFile.json>
## Notes
1. It is important to realize that there are no safety checks (yet) when assigning joinStarts in bridge configurations. If you were to put two devices on a bridge with overlapping joins, the most recently bridged join would overwrite previously bridged joins. For now it is on the programmer to ensure there are no conflicting join maps.
1. It is important to realize that there are no safety checks (yet) when assigning joinStarts in bridge configurations. If you were to put two devices on a bridge with overlapping joins, the most recently bridged join would overwrite previously bridged joins. For now it is on the programmer to ensure there are no conflicting join maps.
1. There is _no_ limit to the amount of times a device may be bridged to. You may have the same device on multiple bridges across multiple applications without problem. That being said, we recommend using common sense. Accessing a single com port for VTC control via multiple bridges may not be wise...
2. There is _no_ limit to the amount of times a device may be bridged to. You may have the same device on multiple bridges across multiple applications without problem. That being said, we recommend using common sense. Accessing a single com port for VTC control via multiple bridges may not be wise...
1. A bridge need not only bridge between applications on the same processor. A bridge may bridge to an application on a completely separate processor; simply define the ip address in the Bridge control properties accordingly.
3. A bridge need not only bridge between applications on the same processor. A bridge may bridge to an application on a completely separate processor; simply define the ip address in the Bridge control properties accordingly.
1. For devices included in Essentials, you will be able to find defined join maps below. If you are building your own plugins, you will need to build the join map yourself. It would be beneficial to review the wiki entry on the [Feedback Class](https://github.com/PepperDash/Essentials/wiki/Feedback-Classes) for this.
4. For devices included in Essentials, you will be able to find defined join maps below. If you are building your own plugins, you will need to build the join map yourself. It would be beneficial to review the wiki entry on the [Feedback Class](https://github.com/PepperDash/Essentials/wiki/Feedback-Classes) for this.
1. When building plugins, we highly recommend reusing JoinMaps, as this will make code more easily interchangeable. For example; if you were to build a display plugin, we'd recommend you use/extend the existing DisplayControllerJoinMap. This way, you can swap plugins without needing any change on the Simpl Windows side. This is extremely powerful when maintaining Simpl Windows code bases for large deployments that may utilize differing equipment per room. If you can build a Simpl Windows program that interacts with established join maps, you can swap out the device via config without any change needed to Simpl Windows.
5. When building plugins, we highly recommend reusing JoinMaps, as this will make code more easily interchangeable. For example; if you were to build a display plugin, we'd recommend you use/extend the existing `DisplayControllerJoinMap`. This way, you can swap plugins without needing any change on the SIMPL Windows side. This is extremely powerful when maintaining SIMPL Windows code bases for large deployments that may utilize differing equipment per room. If you can build a SIMPL Windows program that interacts with established join maps, you can swap out the device via config without any change needed to SIMPL Windows.
1. Related to item 5, you can use the same paradigm with respect to physical device communication. If you were to have a DSP device in some rooms communicating over RS232 and some via SSH, it would be trival to swap the device from a Com port to an SSH client in the Essentials Devicee Config and update the Bridge Config to brigde to the desired communication method. Again this would require no change on the Simpl Windows side as long as you maintain the same join Start in the Bridge Device Configuration.
6. Related to item 5, you can use the same paradigm with respect to physical device communication. If you were to have a DSP device in some rooms communicating over RS232 and some via SSH, it would be trival to swap the device from a Com port to an SSH client in the Essentials Devicee Config and update the Bridge Config to brigde to the desired communication method. Again this would require no change on the SIMPL Windows side as long as you maintain the same join Start in the Bridge Device Configuration.
## Common Use Cases
1. There are 10 conference rooms that all operate the same, but have hardware differences that are impossible to account for in SIMPL Windows. For example, each room might have a DM-MD8X8 chassis, but the input and output cards aren't all in the same order, or they might be different models but function the same. You can use Essentials with a unique configuration file for each hardware configuration.
1. There are 10 conference rooms that all operate the same, but have hardware differences that are impossible to account for in SIMPL Windows. For example, each room might have a DM-MD8X8 chassis, but the input and output cards aren't all in the same order, or they might be different models but function the same. You can use Essentials with a unique configuration file for each hardware configuration.
1. You have a floor of conference rooms that all share some centralized hardware like DSP, AV Routing and a shared CEN-GWEXER gateway with multiple GLS-OIR-CSM-EX-BATT occupancy sensors. All the shared hardware can be defined in the Essentials configuration and bridged over an EISC to each program that needs access. The same device can even be exposed to multiple programs over different EISCs.
2. You have a floor of conference rooms that all share some centralized hardware like DSP, AV Routing and a shared CEN-GWEXER gateway with multiple GLS-OIR-CSM-EX-BATT occupancy sensors. All the shared hardware can be defined in the Essentials configuration and bridged over an EISC to each program that needs access. The same device can even be exposed to multiple programs over different EISCs.
1. You have a SIMPL program that works for many room types, but because some rooms have different models of processors than others (CP3/CP3N/AV3/PRO3/DMPS3 variants), you have to maintain several versions of the program, compiled for each processor model to maintain access to features like the System Monitor slot. You can use Essentials running in a slot on a processor to expose the System Monitor and many other features of the processor, regardless of model. Now you only need to maintain a single SIMPL program defined for your most complex processor application (ex. PRO3)
3. You have a SIMPL program that works for many room types, but because some rooms have different models of processors than others (CP3/CP3N/AV3/PRO3/DMPS3 variants), you have to maintain several versions of the program, compiled for each processor model to maintain access to features like the System Monitor slot. You can use Essentials running in a slot on a processor to expose the System Monitor and many other features of the processor, regardless of model. Now you only need to maintain a single SIMPL program defined for your most complex processor application (ex. PRO3)
## Join Map Documentation
[Join Map Documentation](JoinMaps)
## Device Type Join Maps
Please note that these joinmaps _may_ be using a deprecated implementation. The implementation is valid but nonetheless frowned upon for new features and plugins.
### AirMediaController
> supports: AM-200, AM-300
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/AirMediaControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/AirMediaControllerJoinMap.cs>
### AppleTvController
> supports: IR control of Apple TV
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/AppleTvJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/AppleTvJoinMap.cs>
### CameraControlBase
> supports: any camera that derives from CameraBase
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/CameraControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/CameraControllerJoinMap.cs>
### DisplayController
> supports: IR controlled displays, any two way display driver that derives from PepperDash.Essentials.Core.DisplayBase
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DisplayControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DisplayControllerJoinMap.cs>
### DmChasisController
> supports: All DM-MD-8x8/16x16/32x32 chassis, with or w/o DM-CPU3 Card
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmChassisControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmChassisControllerJoinMap.cs>
### DmRmcController
> supports: All DM-RMC devices
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmRmcControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmRmcControllerJoinMap.cs>
### DmTxController
> supports: All Dm-Tx devices
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmTxControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmTxControllerJoinMap.cs>
### DmpsAudioOutputController
> supports: Program, Aux1, Aux2 outputs of all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmpsAudioOutputControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmpsAudioOutputControllerJoinMap.cs>
### DmpsRoutingController
> supports: Av routing for all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/DmpsRoutingControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmpsRoutingControllerJoinMap.cs>
### GenericRelayController
> supports: Any relay port on a Crestron Control System or Dm Endpoint
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/GenericRelayControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/GenericRelayControllerJoinMap.cs>
### GenericLightingJoinMap
> supports: Devices derived from PepperDash.Essentials.Core.Lighting.LightingBase
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/GenericLightingJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/GenericLightingJoinMap.cs>
### GlsOccupancySensorBase
> supports: Any Crestron GLS-Type Occupancy sensor - single/dual type
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/GlsOccupancySensorBaseJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/GlsOccupancySensorBaseJoinMap.cs>
### HdMdxxxCEController
> supports: HD-MD-400-C-E, HD-MD-300-C-E, HD-MD-200-C-E, HD-MD-200-C-1G-E-B/W
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/HdMdxxxCEControllerJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/HdMdxxxCEControllerJoinMap.cs>
### IBasicCommunication
> supports: Any COM Port on a Control System or Dm Endpoint device, TCP Client, SSH Client, or UDP Server
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/IBasicCommunicationJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/IBasicCommunicationJoinMap.cs>
### IDigitalInput
> supports: Any Digital Input on a Control System, or DM Endpoint device
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/IDigitalInputJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/IDigitalInputJoinMap.cs>
### SystemMonitorController
> supports: Exposing the system monitor slot for any Control System
<https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Bridges/JoinMaps/SystemMonitorJoinMap.cs>
<https://github.com/PepperDash/Essentials/blob/master/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/SystemMonitorJoinMap.cs>
## Example SIMPL Windows Program
We've provided an [example program](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for SIMPL Windows that works with the provided example Essentials configuration file [SIMPLBridgeExample_configurationFile.json](https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Example%20Configuration/SIMPLBridging/SIMPLBridgeExample_configurationFile.json). Load Essentials and the example SIMPL program to two slots on the same processor and you can get a better idea of how to take advantage of SIMPL Windows bridging.
We've provided an [example program](https://github.com/PepperDash/EssentialsSIMPLWindowsBridgeExample) for SIMPL Windows that works with the provided example Essentials configuration file [SIMPLBridgeExample_configurationFile.json](https://github.com/PepperDash/Essentials/blob/master/PepperDashEssentials/Example%20Configuration/SIMPLBridging/SIMPLBridgeExample_configurationFile.json). Load Essentials and the example SIMPL program to two slots on the same processor and you can get a better idea of how to take advantage of SIMPL Windows bridging.
Next: [Essentials architecture](Arch-summary)

4
_Sidebar.md

@@ -7,7 +7,7 @@
**Usage**
* [Standalone Use](Standalone-Use)
* [SIMPL Windows Bridging](SIMPL-Bridging-Updated)
* [SIMPL Windows Bridging](SIMPL-Bridging)
* [Join Maps](JoinMaps)
**Technical documentation**
@@ -16,7 +16,7 @@
* [Configurable lifecycle](Arch-lifecycle)
* [Activation phases](Arch-activate)
* [More](Arch-topics)
* [Plugins](Plugins-Updated)
* [Plugins](Plugins)
* [Communication Basics](Communication-Basics)
* [Debugging](Debugging)
* [Feedback Classes](Feedback-Classes)