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

docs: first pass at using docfx

Browse Source
This commit is contained in:
Andrew Welker
2025-04-25 21:30:52 -05:00
parent e8276c4165
commit cc9492938b
48 changed files with 4244 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
.github/workflows/publish-docs.yml vendored Normal file
View File

@@ -0,0 +1,46 @@
name: Publish Docs
# Trigger the action on push to main
on:
push:
branches:
- add-docs-pages
- main
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
actions: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
publish-docs:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Dotnet Setup
uses: actions/setup-dotnet@v3
with:
dotnet-version: 8.x
- run: dotnet tool update -g docfx
- run: docfx ./docfx.json
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# Upload entire repository
path: './_site'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

2
.gitignore vendored
View File

@@ -392,3 +392,5 @@ essentials-framework/Essentials Interfaces/PepperDash_Essentials_Interfaces/Pepp
.DS_Store
/._PepperDash.Essentials.sln
.vscode/settings.json
_site/
api/

54
docfx.json Normal file
View File

@@ -0,0 +1,54 @@
{
"$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
"metadata": [
{
"src": [
{
"src": "src",
"files": [
"**/*.csproj"
]
}
],
"properties": {
"TargetFramework": "net472"
},
"dest": "api",
"namespaceLayout": "nested"
}
],
"build": {
"content": [
{
"files": [
"docs/**/*.{md,yml}",
"api/**/*.{md,yml}",
"index.md",
"toc.yml"
],
"exclude": [
"_site/**",
".github/**"
]
}
],
"resource": [
{
"files": [
"docs/images/**"
]
}
],
"output": "_site",
"template": [
"default",
"modern"
],
"globalMetadata": {
"_appName": "PepperDash Essentials",
"_appTitle": "PepperDash Essentials",
"_enableSearch": true,
"pdf": false
}
}
}

41
docs/Arch-1.md Normal file
View File

@@ -0,0 +1,41 @@
# Essentials architecture
## Device and DeviceManager
---
[YouTube Video - The Device Model in PepperDash Essentials](https://youtu.be/QF4vCQfOYGw)
***
A `Device` (`PepperDash.Core.Device`) is a logical construct. It may represent a piece of hardware, a port, a socket, a collection of other devices/ports/constructs that define an operation, or any unit of logic that should be created at startup and exist independent of other devices.
`DeviceManager` (`PepperDash.Essentials.Core.DeviceManager`) is the collection of all Devices. The collection of everything we control, and other business logic in a system. See the list below for what is typical in the device manager.
## Flat system design
In Essentials, most everything we do is focused in one layer: The Devices layer. This layer interacts with the physical Crestron and other hardware and logical constructs underneath, and is designed so that we rarely act directly on the often-inconsistent hardware layer. The `DeviceManager` is responsible for containing all of the devices in this layer.
Types of things in `DeviceManager`:
* Rooms
* Sources
* Codecs, DSPs, displays, routing hardware
* IR Ports, Com ports, SSh Clients, ...
* Occupancy sensors and relay-driven devices
* Logical devices that manage multiple devices and other business, like shade or lighting scene controllers
* Fusion connectors to rooms
A Device doesn't always represent a physical piece of hardware, but rather a logical construct that "does something" and is used by one or more other devices in the running program. For example, we create a room device, and its corresponding Fusion device, and that room has a Cisco codec device, with an attached SSh client device. All of these lie in a flat collection in the `DeviceManager`.
> The `DeviceManager` is nothing more than a modified collection of things, and technically those things don't have to be Devices, but must at least implement the `IKeyed` (`PepperDash.Core.IKeyed`) interface (simply so items can be looked up by their key.) Items in the `DeviceManager` that are Devices are run through additional steps of [activation](~/docs/Arch-activate.md#2-pre-activation) at startup. This collection of devices is all interrelated by their string keys.
In this flat design, we spin up devices, and then introduce them to their "coworkers and bosses" - the other devices and logical units that they will interact with - and get them all operating together to form a running unit. For example: A room configuration will contain a "VideoCodecKey" property and a "DefaultDisplayKey" property. The `DeviceManager` provides the room with the codec or displays having the appropriate keys. What the room does with those is dependent on its coding.
> In the default Essentials routing scheme, the routing system gets the various devices involved in given route from `DeviceManager`, as they are discovered along the defined tie-lines. This is all done at route-time, on the fly, using only device and port keys. As soon as the routing operation is done, the whole process is released from memory. This is extremely-loose coupling between objects.
This flat structure ensures that every device in a system exists in one place and may be shared and reused with relative ease. There is no hierarchy.
## Architecture drawing
![Architecture overview](~/docs/images/arch-overview.png)
Next: [Configurable lifecycle](~/docs/Arch-lifecycle.md)

158
docs/Arch-activate.md Normal file
View File

@@ -0,0 +1,158 @@
# Essentials architecture: DeviceManager activation
## What is all this?
The Essentials system architecture is a loose collection of "things" - generally real or logical Devices - that all need to relate to each other. In the interest of keeping Essentials extensible and flexible, we use an non-ordered collection of objects that should only have references to each other in the least-binding way possible. Meaning: Devices should be designed to be able to function without related objects present, and when they are present they should only retain loose reference to those other objects for memory management and later deconstruction as Essentials grows into a real-time configurable environment.
In order to facilitate this loose coupling, Essentials devices go through five phases during the startup process: Construction; addition to `DeviceManager`; pre-activation; activation; post-activation. We will describe what is optimal behavior for each of the steps below:
### Classes Referenced
* `PepperDash.Core.Device`
* `PepperDash.Essentials.Core.EssentialsDevice`
* `PepperDash.Essentials.Core.DeviceManager`
* `PepperDash.Essentials.Core.Privacy.MicrophonePrivacyController`
## 1. Construction and addition to the DeviceManager
In general, a device's constructor should only be used to get the "framework" of the device in place. All devices are constructed in this stage. Rooms and fusion bridges included. Simple devices like IR driver devices, and devices with no controls can be completely spun up in this phase. All devices are added to the `DeviceManager` after they are constructed, but may not be fully functional.
## 2. Pre-activation
This stage is rarely used. It exists to allow an opportunity for any necessary logic to take place before the main activation phase.
## 3. Activation
This stage is the main phase of startup, and where most devices will get up and running, if they need additional startup behavior defined. The developer will code an optional overridden `CustomActivate()` method on the device class. This is where hardware ports may be set up; signals and feedbacks linked; UI drivers fired up; rooms linked to their displays and codec... With the exception of early-designed devices, most new Essentials classes do all of their startup here, rather than in their constructors.
Remember that in your `CustomActivate()` method, you cannot assume that a device you depend on is alive and running yet. It may be activating later. You _can_ depend on that device's existence, and link yourself to it, but it may not be functional yet. In general, there should be no conditions in any Essentials code that depend on device startup sequence and ordering. All rooms, devices, classes should be able to function without linked devices being alive, and respond appropriately when they do come to life. Any post-activation steps can be done in step four below - and should be avoided in general.
If the `CustomActivate()` method is long, consider breaking it up into many smaller methods. This will enhance exception handling and debugging when things go wrong, with more-detailed stack traces, and makes for easier-to-read code.
Note: It is best-practice in Essentials to not write arbitrarily-timed startup sequences to ensure that a "system" or room is functional. Rather, we encourage the developer to use various properties and conditions on devices to aggregate together "room is ready" statuses that can trigger further action. This ensures that all devices can be up and alive, allowing them to be debugged within a program that may otherwise be misbehaving - as well as not making users and expensive developers wait for code to start up!
```cs
public override bool CustomActivate()
{
Debug.Console(0, this, "Final activation. Setting up actions and feedbacks");
SetupFunctions();
SetupFeedbacks();
EISC.SigChange += EISC_SigChange;
...
}
```
## 4. Post-activation
This phase is used primarily to handle any logic in a device that might be dependent on another device, and we need to ensure that we have waited for the dependent device to be activated first. For example, if we look at the `MicrophonePrivacyController` class, this is a "virtual" device whose purpose is to control the mute state of microphones from one or more contact closure inputs as well as provide feedback via different colored LEDs as to the current mute state. This virtual-device doesn't actually represent any sort of physical hardware device, but rather relies on associating itself with other devices that represent digital inputs and relays as well as whatever device is responsible for preforming the actual muting of the microphones.
We can see in the example below that during the `CustomActivate()` phase, we define a post-activation action via a lambda in `AddPostActivationAction()` that will execute during the post-activation phase. The purpose here is to check the state of the microphone mute and set the state of the relays that control the LEDs accordingly. We need to do this as a post-activation action because we need to make sure that the devices PrivacyDevice, RedLedRelay and GreenLedRelay are fully activated before we can attempt to interact with them.
### **Example**
```cs
public override bool CustomActivate()
{
foreach (var i in Config.Inputs)
{
var input = DeviceManager.GetDeviceForKey(i.DeviceKey) as IDigitalInput;
if(input != null)
AddInput(input);
}
var greenLed = DeviceManager.GetDeviceForKey(Config.GreenLedRelay.DeviceKey) as GenericRelayDevice;
if (greenLed != null)
GreenLedRelay = greenLed;
else
Debug.Console(0, this, "Unable to add Green LED device");
var redLed = DeviceManager.GetDeviceForKey(Config.RedLedRelay.DeviceKey) as GenericRelayDevice;
if (redLed != null)
RedLedRelay = redLed;
else
Debug.Console(0, this, "Unable to add Red LED device");
AddPostActivationAction(() => {
CheckPrivacyMode();
PrivacyDevice.PrivacyModeIsOnFeedback.OutputChange -= PrivacyModeIsOnFeedback_OutputChange;
PrivacyDevice.PrivacyModeIsOnFeedback.OutputChange += PrivacyModeIsOnFeedback_OutputChange;
});
initialized = true;
return base.CustomActivate();
}
void CheckPrivacyMode()
{
if (PrivacyDevice != null)
{
var privacyState = PrivacyDevice.PrivacyModeIsOnFeedback.BoolValue;
if (privacyState)
TurnOnRedLeds();
else
TurnOnGreenLeds();
}
}
```
## Activation exceptions
Each of the three activation phases operates in a try/catch block for each device. This way if one device has a fatal failure during activation, the failure will be logged and the system can continue to activate. This allows the developer to chase down multiple issues per load while testing, or to fix configuration omissions/errors as a group rather than one-at-a-time. A program can theoretically be fully-initialized and have many or all devices fail. We generally do not want to depend on exception handling to log device failures. Construction and activation code should have plenty of null checks, parameter validity checks, and debugging output to prevent exceptions from occurring. `String.IsEmptyOrNull(myString)` and `if(myObject == null)` are your friends. Invite them often.
## Interdependence
In any real-world system, devices and business logic need to talk to each other, otherwise, what's the point of all this coding? When creating your classes and configuration, it is best practice to _try_ not to "plug" one device into another during construction or activation. For example your touchpanel controller class has a `Display1` property that holds the display-1 object. Rather, it may be better to refer to the device as it is stored in the `DeviceManager` when it's needed using the static `DeviceManager.GetDeviceForKey(key)` method to get a reference to the device, which can be cast using various interfaces/class types, and then interacted with. This prevents objects from being referenced in places where the developer may later forget to dereference them, causing memory leak. This will become more important as Essentials becomes more able to be reconfigured at runtime.
As an example, [connection-based routing](~/docs/Connection-based-routing.md#essentials-connection-based-routing) uses these methods. When a route is requested, the collection of tielines and devices is searched for the devices and paths necessary to complete a route, but there are no devices or tie lines that are object-referenced in running code. It can all be torn down and reconfigured without any memory-management dereferencing, setting things to null.
## Device Initialization
Once the `DeviceManager` has completed the activation phase cycle for all devices, the devices themselves can be initialized. The `EssentialsDevice` class subscribes to the `DeviceManager.AllDevicesActivated` event and invokes the virtual `Initialize()` method on `Device` in a separate thread. This allows all devices to concurrently initialize in parallel threads.
The main task that should be undertaken in the `Initialize()` method for any 3rd party device class, it to begin communication with the device via its API. Ideally, no class that communicates with a 3rd party device outside the program should attempt to start communicating before this point.
### Example (from `PepperDash.Essentials.Devices.Common.VideoCodec.Cisco.CiscoSparkCodec`)
```cs
public override void Initialize()
{
var socket = Communication as ISocketStatus;
if (socket != null)
{
socket.ConnectionChange += new EventHandler<GenericSocketStatusChageEventArgs>(socket_ConnectionChange);
}
Communication.Connect();
CommunicationMonitor.Start();
const string prefix = "xFeedback register ";
CliFeedbackRegistrationExpression =
prefix + "/Configuration" + Delimiter +
prefix + "/Status/Audio" + Delimiter +
prefix + "/Status/Call" + Delimiter +
prefix + "/Status/Conference/Presentation" + Delimiter +
prefix + "/Status/Cameras/SpeakerTrack" + Delimiter +
prefix + "/Status/RoomAnalytics" + Delimiter +
prefix + "/Status/RoomPreset" + Delimiter +
prefix + "/Status/Standby" + Delimiter +
prefix + "/Status/Video/Selfview" + Delimiter +
prefix + "/Status/Video/Layout" + Delimiter +
prefix + "/Status/Video/Input/MainVideoMute" + Delimiter +
prefix + "/Bookings" + Delimiter +
prefix + "/Event/CallDisconnect" + Delimiter +
prefix + "/Event/Bookings" + Delimiter +
prefix + "/Event/CameraPresetListUpdated" + Delimiter +
prefix + "/Event/UserInterface/Presentation/ExternalSource/Selected/SourceIdentifier" + Delimiter;
}
```
## The goal
Robust C#-based system code should not depend on "order" or "time" to get running. We do not need to manage the order of our startup in this environment. Our Room class may come alive before our DSP and or Codec, and the Room is responsible for handling things when those devices become available. The UI layer is responsible for blocking the UI or providing status when the Room's requirements are coming alive, or if something has gone away. We use events or `Feedbacks` to notify dependents that other devices/classes are ready or not, but we do not prevent continued construction/activation of the system when many of these events don't happen, or don't happen in a timely fashion. This removes the need for startup management, which is often prolonged and consumes _tons_ of developer/installer time. A fully-loaded Essentials system may go through activation in several seconds, with all devices concurrently getting themselves going, where legacy code may take 10 minutes.
When designing new Device-based classes, be it rooms, devices, port controllers, bridges, make them as independent as possible. They could exist alone in a program with no required partner objects, and just quietly exist without failing. We want the system to be fast and flexible, and keeping the interdependence between objects at a minimum improves this flexibility into the future.
Next: [More architecture](~/docs/Arch-topics.md)

9
docs/Arch-lifecycle.md Normal file
View File

@@ -0,0 +1,9 @@
# Essentials Configurable System Lifecycle
The diagram below describes how Essentials gets a program up and running.
(The various activation phases are covered in more detail on the [next page](~/docs/Arch-activate.md))
![Lifecycle](~/docs/images/lifecycle.png)
Next: [Activation phases](~/docs/Arch-activate.md)

19
docs/Arch-summary.md Normal file
View File

@@ -0,0 +1,19 @@
# Essentials architecture
## Summary
PepperDash Essentials is an open-source framework for control systems, built on Crestron's Simpl# Pro framework. It can be configured as a standalone program capable of running a wide variety of system designs and can also be used to augment other Crestron programs.
Essentials is a collection of C# libraries that can be used in many ways. It is a 100% configuration-driven framework that can be extended to add different workflows and behaviors, either through the addition of new device-types and classes, or via a plug-in mechanism. The framework is a collection of things that are all related and interconnected, but in general do not have strong dependencies on each other.
## Framework Libraries
The table below is a guide to understand the basic organization of code concepts within the various libraries that make up the architecture.
![Table](~/docs/images/arch-table.PNG)
The diagram below shows the reference dependencies that exist between the different component libraries that make up the Essentials Framework.
![Architecture drawing](~/docs/images/arch-high-level.png)
Next: [Architecture](~/docs/Arch-1.md)

156
docs/Arch-topics.md Normal file
View File

@@ -0,0 +1,156 @@
# Configuration topics
Configuration is central to Essentials. On this page we will cover configuration-related topics, including the important concept of configure-first and some details about the config file process.
## Classes Referenced
- `PepperDash.Essentials.Core.Config.DeviceConfig`
## Configure-first development
## Framework Libraries
The table below is meant to serve as a guide to understand the basic organization of code concepts within the various libraries that make up the architecture.
_Todo, try a text-based table:_
![Table](~/docs/images/arch-table.PNG)
The diagram below shows the reference dependencies that exist between the different component libraries that make up the Essentials Framework.
![Architecture drawing](~/docs/images/arch-high-level.png)
### Architecture
#### Device and DeviceManager
A `Device` is a logical construct. It may represent a piece of hardware, a port, a socket, a collection of other devices/ports/constructs that define an operation, or any unit of logic that should be created at startup and exist independent of other devices.
`DeviceManager` is the collection of all Devices. The collection of everything we control on a system. **ADD SOME MORE HERE**
#### Flat system design
In Essentials, most everything we do is focused in one layer: The Devices layer. This layer interacts with the physical Crestron and other hardware and logical constructs underneath, and is designed so that we rarely act directly on the often-inconsistent hardware layer. The `DeviceManager` is responsible for containing all of the devices in this layer.
Types of devices:
- Rooms
- Sources
- Codecs, DSPs, displays, routing hardware
- IR Ports, Com ports, SSh Clients, ...
- Occupancy sensors and relay-driven devices
- Logical devices that manage multiple devices and other business, like shade or lighting scene controllers
- Fusion connectors to rooms
A Device doesn't always represent a physical piece of hardware, but rather a logical construct that "does something" and is used by one or more other devices in the running program. For example, we create a room device, and its corresponding Fusion device, and that room has a Cisco codec device, with an attached SSh client device. All of these lie in a flat collection in the `DeviceManager`.
> The `DeviceManager` is a modified collection of objects, and those objects don't have to inherit from Devices or EssentialsDevices, but must at least implement the `IKeyed` interface (so items can be looked up by their key.) Items in the `DeviceManager` that are Devices are run through additional steps of activation at startup. This collection of devices is all interrelated by their string keys.
In this flat design, we spin up devices, and then introduce them to their "coworkers and bosses" - the other devices and logical units that they will interact with - and get them all operating together to form a running unit. For example: A room configuration will contain a "VideoCodecKey" property and a "DefaultDisplayKey" property. The `DeviceManager` provides the room with the codec or displays having the appropriate keys. What the room does with those is dependent on its coding.
> In the default Essentials routing scheme, the routing system gets the various devices involved in given route from `DeviceManager`, as they are discovered along the defined tie-lines. This is all done at route-time, on the fly, using only device and port keys. As soon as the routing operation is done, the whole process is released from memory. This is extremely-loose coupling between objects.
This flat structure ensures that every device in a system exists in one place and may be shared and reused with relative ease. There is no hierarchy.
#### Architecture drawing
![Architecture overview](~/docs/images/arch-overview.png)
#### Essentials Configurable System Lifecycle
![Lifecycle](~/docs/images/lifecycle.png)
### Activation phases additional topics and examples (OTHER DOCS)
Concepts (link)
Room and touchpanel activation (link)
#### Configure first development
One of the primary concepts that has been adopted and must be adhered to when writing for Essentials framework is the concept of "configure first." The simple version is: Write what you need to do in the related configuration file (and configuration tool) first, then write the code that runs from that configuration. This ensures that the running code can actually be configured in the "flat" structure of devices and rooms that Essentials uses.
Often, code is written and tested first without consideration for configurability. Then, when a developer tries to make it configurable, they discover that the code as written doesn’t support it without complicated configuration files. This creates spaghetti code in tools that are written to generate configurations and tends to create tighter coupling between objects than we desire. Later, a modified version of the original program is desired, but because the code was written in such a specific fashion, the code is hard to refactor and extend. This causes the configuration tool and configuration files to become even more convoluted. The modern versions of configuration tools that are starting to come out are modular and componentized. We want to ensure as much re-use of these modules as possible, with extensions and added features added on, rather than complete rewrites of existing code. In our running systems, we want to ensure as much flexibility in design as possible, eliminating multiple classes with similar code.
### Configuration reader process
At the heart of the Essentials framework is the configuration system. While not technically necessary for a system written with the Essentials framework, it is the preferred and, currently, the only way to build an Essentials system. The configuration file is JSON, and well-defined (but not well documented, yet). It is comprised of blocks:
- info (object) Contains metadata about the config file
- devices (array) Contains, well, the devices we intend to build and load
- rooms (array, typically only one) Contains the rooms we need
- sourceLists (object) Used by one or more rooms to represent list(s) of sources for those rooms
- tieLines (array) Used by the routing system to discover routing between sources and displays
In addition, a downloaded Portal config file will most likely be in a template/system form, meaning that the file contains two main objects, representing the template configuration and its system-level overrides. Other metadata, such as Portal UUIDs or URLs may be present.
At startup, the configuration file is read, and a ReadyEvent is fired. Upon being ready, that configuration is loaded by the ConfigReader.LoadConfig() method. The template and system are merged into a single configuration object, and that object is then deserialized into configuration wrapper classes that define most of the structure of the program to be built. (Custom configuration objects were built to allow for better type handling rather than using JToken methods to parse out error-prone property names.)
For example, a `DeviceConfig` object:
```cs
namespace PepperDash.Essentials.Core.Config
{
public class DeviceConfig
{
[JsonProperty("key")]
public string Key { get; set; }
[JsonProperty("uid")]
public int Uid { get; set; }
[JsonProperty("name")]
public string Name { get; set; }
[JsonProperty("group")]
public string Group { get; set; }
[JsonProperty("type")]
public string Type { get; set; }
[JsonProperty("properties")]
[JsonConverter(typeof(DevicePropertiesConverter))]
public JToken Properties { get; set; }
}
}
```
_Every_ `Device` present must adhere to those five properties plus a properties object. The properties object will have its own deserialization helpers, depending on what its structure is.
Once the ConfigReader has successfully read and deserialized the config file, then `ControlSystem.Load()` is called. This does the following in order:
1. Loads Devices
2. Loads TieLines
3. Loads Rooms
4. Loads LogoServer
5. Activation sequence
This ordering ensures that all devices are at least present before building tie lines and rooms. Rooms can be built without their required devices being present. In principle, this could break from the loosely-coupled goal we have described, but it is the clearest way to build the system in code. The goal is still to build a room class that doesn't have functional dependencies on devices that may not be ready for use.
In each device/room step, a device factory process is called. We call subsequent device factory methods in the various libraries that make up Essentials until one of them returns a functional device. This allows us to break up the factory process into individual libraries, and not have a huge list of types and build procedures. Here's part of the code:
```cs
// Try local factories first
var newDev = DeviceFactory.GetDevice(devConf);
if (newDev == null)
newDev = BridgeFactory.GetDevice(devConf);
// Then associated library factories
if (newDev == null)
newDev = PepperDash.Essentials.Core.DeviceFactory.GetDevice(devConf);
if (newDev == null)
newDev = PepperDash.Essentials.Devices.Common.DeviceFactory.GetDevice(devConf);
if (newDev == null)
newDev = PepperDash.Essentials.DM.DeviceFactory.GetDevice(devConf);
if (newDev == null)
newDev = PepperDash.Essentials.Devices.Displays.DisplayDeviceFactory.GetDevice(devConf);
```
In each respective factory, or device constructor, the configuration's properties object is either converted to a config object or read from using `JToken` methods. This builds the device which may be ready to go, or may require activation as described above.
A similar process is carried out for rooms, but as of now, the room types are so few that they are all handled in the `ControlSystem.LoadRooms()` method.
_This process will soon be enhanced by a plug-in mechanism that will drill into dynamically-loaded DLLs and load types from factories in those libraries. This is where custom essentials systems will grow from._
After those five steps, the system will be running and ready to use.

15
docs/Bridging-To-Hardware-Resources.md Normal file
View File

@@ -0,0 +1,15 @@
# Bridging to Hardware and Network Resources
One of the most powerful features of Essentials is the ability to bridge SIMPL to and hardware resource to any piece of equipment instantiated inside of essentials. You can bridge directly to a comport on the processor just as easily as you can to the comport of an instantiated DM device. A simple change in the connection location of a display can be made with just a few keystrokes. This isn't restricted to comports either. Devices and direct connections can be linked to Digital Inputs, IR Ports, Relays, Comports, SSH, TCP/IP, UDP, and Cresnet resources.
## Examples
Follow the links below for examples of bridging to hardware and network resources.
**[GenericComm Bridging](~/docs/GenericComm.md)**
**[RelayOutput Bridging](~/docs/RelayOutput.md)**
**[Digital Input Bridging](~/docs/DigitalInput.md)**
**[Card Frame Bridging](~/docs/CardFrame.md)**

14
docs/CardFrame.md Normal file
View File

@@ -0,0 +1,14 @@
{
"key": "cardCage1",
"uid": 1,
"name": "Internal Card Cage",
"type": "internalcardcage",
"group": "cardCage",
"properties": {
"cards": {
"1": "c3com3",
"2": "c3com3",
"3": ""
}
}
},

77
docs/Communication-Basics.md Normal file
View File

@@ -0,0 +1,77 @@
# Unifying communication methods
In networked A/V systems, devices can use many different methods of communication: COM ports, TCP/IP sockets, Telnet, SSh. Generally, the data protocol and commands that are sent and received using any of these methods are the same, and it is not necessary for a device to know the details of the communication method it is using. A Samsung MDC protocol display in room 1 using RS232 speaks the same language as another Samsung MDC does in the next room using TCP/IP. For these, and most cases where the device doesn't need to know its communication method, we introduce the `IBasicCommunication` interface.
## Classes Referenced
* `PepperDash.Core.IBasicCommunication`
* `PepperDash.Core.ISocketStatus`
* `PepperDash.Core.GenericTcpIpClient`
* `PepperDash.Core.GenericSshClient`
* `PepperDash.Core.GenericSecureTcpIpClient`
* `PepperDash.Essentials.Core.ComPortController`
* `PepperDash.Essentilas.Core.StatusMonitorBase`
## IBasicCommunication and ISocketStatus
All common communication controllers will implement the `IBasicCommunication` interface, which is an extension of `ICommunicationReceiver`. This defines receive events, connection state properties, and send methods. Devices that need to use COM port, TCP, SSh or other similar communication will require an `IBasicCommunication` type object to be injected at construction time.
```cs
/// <summary>
/// An incoming communication stream
/// </summary>
public interface ICommunicationReceiver : IKeyed
{
event EventHandler<GenericCommMethodReceiveBytesArgs> BytesReceived;
event EventHandler<GenericCommMethodReceiveTextArgs> TextReceived;
bool IsConnected { get; }
void Connect();
void Disconnect();
}
/// <summary>
/// Represents a device that uses basic connection
/// </summary>
public interface IBasicCommunication : ICommunicationReceiver
{
void SendText(string text);
void SendBytes(byte[] bytes);
}
/// <summary>
/// For IBasicCommunication classes that have SocketStatus. GenericSshClient,
/// GenericTcpIpClient
/// </summary>
public interface ISocketStatus : IBasicCommunication
{
event EventHandler<GenericSocketStatusChageEventArgs> ConnectionChange;
SocketStatus ClientStatus { get; }
}
```
### Developing devices with communication
Essentials uses dependency injection concepts in its start up phase. Simply, most devices use the same methods of communication, and are often communication-agnostic. During the build-from-configuration phase, the communication method device is instantiated, and then injected into the device that will use it. Since the communication device is of `IBasicCommunication`, the device controller receiving it knows that it can do things like listen for events, send text, or be notified when sockets change.
### Device Factory, Codec example
![Communication Device factory](~/docs/images/comm-device-factory.png)
The DeviceManager will contain two new devices after this: The Cisco codec, and the codec's `GenericSshClient`. This enables easier debugging of the client using console methods. Some devices like this codec will also have a `StatusMonitorBase` device, for Fusion and other reporting.
> `ComPortController` is `IBasicCommunication` as well, but methods like `Connect()` and `Disconnect()` do nothing on these types.
#### ISocketStatus
`PepperDash.Core.GenericTcpIpClient`, `GenericSshClient` and some other socket controllers implement `ISocketStatus`, which is an extension of `IBasicCommunication`. This interface reveals connection status properties and events.
```cs
public interface ISocketStatus : IBasicCommunication
{
event EventHandler<GenericSocketStatusChageEventArgs> ConnectionChange;
SocketStatus ClientStatus { get; }
}
```
Classes that are using socket-based comms will need to check if the communication is `ISocketStatus` and link up to the `ConnectionChange` event for connection handling.

291
docs/ConfigurationStructure.md Normal file
View File

@@ -0,0 +1,291 @@
# Configuration Structure
---
[YouTube Video - Configuring PepperDash Essentials](https://youtu.be/EK8Ti9a1o7s)
***
The Essentials configuration structure is designed to allow minimum duplication of data across systems that share many similarities, which makes it ideally suited for applications where large numbers of duplicate room types must be deployed.
At a high level, the idea is to define a template of all of the common configuration shared by a group of systems of the same type. Then individual differences per system instance can be defined in a system block that either add data missing in the template, or override the default values set in the template.
## Top Level Object Structure (Double Config)
```cs
{
// This object is deserialized to type PepperDash.Essentials.Core.Config.EssentialsConfig
"system_url":"", // For Portal use only
"template_url":"", // For Portal use only
"template":{
// This object is deserialized to type PepperDash.Essentials.Core.EssentialsConfig
// For most manually generated configuration, only define data here. Leave system empty
},
"system":{
// This object is deserialized to type PepperDash.Essentials.Core.EssentialsConfig
// Any data here will be overlayed on top of the data in template. In the case of duplicate values
// the value in system will be overwrite any value in template
}
}
```
## Object Structure for `template` and `system` (`PepperDash.Essentials.Core.EssentialsConfig`)
``` js
{
"info": {
// This object is deserialized to type PepperDash.Essentials.Core.Config.InfoConfig
// Contains information about the system/configuration
},
"devices": [
// This object is deserialized to type List<PepperDash.Essentials.Core.Config.DeviceConfig>
// An array of devices
],
"rooms": [
// This object is deserialized to type List<PepperDash.Essentials.Core.Config.DeviceConfig>
// An array of rooms. These are not automatically deserialized
],
"tielines":[
// An array of tie lines that describe the connections between routing ports on devices
],
"sourceLists":{
// This object is deserialized to type Dictionary<string, Dictionary<string, PepperDash.Essentials.Core.SourceListItem>>
// An object that contains a collection
},
"joinMaps":{
// This object is deserialized to type Dictionary<string, string> where the value is a serialized class that inherits from JoinMapBase to be deserialized later
// Used to define custom join maps for bridging devices to SIMPL
}
}
```
## The Template and System Concept (Merging Configurations)
In order to understand how and why we use a double configuration concept, it's important to understand the relationship between a Template and a System in Portal.  A System represents a physical installed group of hardware(either currently or in the future), acting together usually as part of a single control system program.  A system MUST inherit from a Template.  A Template represents the common elements of one or more systems.
The idea being that configuration values that are common to all systems can be stored in the configuration for the template.  Then, any configuration values that are unique to a particular system cane be stored in the configuration of the System.  By "merging" the System configuration values over top of the Template configuration values, the resulting data contains all of the values that should be shared by each system that inherits from a common template, as well as the unique values for each individual system.
Below is an example of a double configuration containing both template and system properties.
```JSON
{
"template": {
"info": {
"name": "Template Name",
"description": "A 12 person conference room"
},
"devices": [
],
"rooms": [
]
},
"system": {
"info": {
"name": "System Name",
"myNewSystemProperty": "Some Value"
},
"devices": [
],
"rooms": [
]
}
}
```
Below is an example of the result of merging the above double configuration example into a single configuration.
```JSON
{
"info": {
"name": "System Name", // Since this property existed in both the template and system, the system value replaces the template value after the merge
"description": "A 12 person conference room", // This property existed only in the template and is unchanged after the merge
"myNewSystemProperty": "Some Value" // This property existed only in the system and is unchanged after the merge
},
"devices": [
],
"rooms": [
]
}
```
---
## Device Object Structure
The devices array is meant to hold a series of device objects.  The basic device object structure is defined below.
```JSON
{
"key": "someUniqueString", // *required* a unique string
"name": "A friendly Name", // *required* a friendly name meant for display to users
"type": "exampleType", // *required* the type identifier for this object.
"group": "exampleGroup", // *required* the group identifier for this object. This really equates to a category for the device,
// such as "lighting" or "displays" and may be deprecated in future in favor of "category"
"uid":0, // *required* a unique numeric identifier for each device
"properties": { // *required* an object where the configurable properties of the device are contained
"control": { // an object to contain all of the properties to connect to and control the device
"method": "ssh", // the control method used by this device
"tcpSshProperties": { // contains the necessary properties for the specified method
"address": "1.2.3.4",
"port": 22,
"username": "admin",
"password": "uncrackablepassword"
}
},
"someCustomProperty": "I Love Tacos!"
}
// Do NOT add any custom data at the top level of the device object. All custom data must be in the properties object.
}
```
Some additional details about specific properties that are important to note:
* "key": This value needs to be unique in the array of devices objects
* "uid": This value also needs to be unique for reasons related to configuration tools and template/system merging
* "type": Think of this as a way to identify what specific module you might associate with this device.  In Essentials, this value is used to determine what class will be instantiated for the device (ex. "necmpsx" or "samsungMdc" for two types of displays)
* "properties":  This object is used to store both specific and miscellaneous data about the device.
* Specific data, like that shown above in the "control" object has a pre-defined structure.
* Other data must be stored as objects or new properties inside the "properties" object such as "someCustomProperty" in the example above.
* Do NOT add any additional properties at the top level of the device object.  All custom data must be in the "properties" object.
## The Device Properties.Control Object
The control object inside properties has some reserved properties that are used by configuration tools and Essentials that require some caution.
```JSON
{
"properties": { // *required* an object where the configurable properties of the device are contained
"control": { // an object to contain all of the properties to connect to and control the device
// Example of the reserved properties for a socket based port (ssh, tcpIp, udp)
"method": "ssh", // the control method used by this device
"tcpSshProperties": { // contains the necessary properties for the specified method
"address": "1.2.3.4", // IP Address or hostname
"port": 22,
"username": "admin",
"password": "uncrackablepassword",
"autoReconnect": true, // If true, the client will attempt to re-connect if the connection is broken externally
"AutoReconnectIntervalMs": 2000 // The time between re-connection attempts
},
// Example of the reserved properties for a Com port
"method": "com",
"controlPortNumber": 1, // The number of the com port on the device specified by controlPortDevKey
"controlPortDevKey": "processor", // The key of the device where the com port is located
"comParams": { // This object contains all of the com spec properties for the com port
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 9600,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
}
}
}
}
```
---
## Device Merging
The following examples illustrate how the device key and uid properties affect how devices are merged together in a double configuration scenario.  In order for a template device and a system device to merge, they must have the same key and uid values
```JSON
{
"template": {
"info": {
"name": "Template Name",
"description": "A 12 person conference room"
},
"devices": [
{ // This is the template device
"key": "display-1",
"name": "Display",
"type": "samsungMdc",
"group": "displays",
"uid":0,
"properties": {
"control": {
"method": "ssh",
"tcpSshProperties": {
"address": "", // Note that at the template level we won't know the actual IP address so this value is left empty
"port": 22,
"username": "admin",
"password": "uncrackablepassword"
}
}
}
}
],
"rooms": [
]
},
"system": {
"info": {
"name": "System Name",
"myNewSystemProperty": "Some Value"
},
"devices": [
{ // This is the system device
"key": "display-1",
"uid":0,
"properties": {
"control": {
"tcpSshProperties": {
"address": "10.10.10.10" // Note that the actual IP address is specified at the system level
}
}
}
}
],
"rooms": [
]
}
}
```
Below is an example of the result of merging the above double configuration example into a single configuration.  
```JSON
{
"info": {
"name": "System Name",
"description": "A 12 person conference room",
"myNewSystemProperty": "Some Value"
},
"devices": [
{
"key": "display-1",
"name": "Display",
"type": "samsungMdc",
"group": "displays",
"uid":0,
"properties": {
"control": {
"method": "ssh",
"tcpSshProperties": {
"address": "10.10.10.10", // Note that the merged device object inherits all of the template
// properties and overwrites the template address property with the system value
"port": 22,
"username": "admin",
"password": "uncrackablepassword"
}
}
}
}
],
"rooms": [
]
}
```

81
docs/Connection-Based-Routing.md Normal file
View File

@@ -0,0 +1,81 @@
# Essentials connection-based routing
## TL;DR
Routing is defined by a connection graph or a wiring diagram. Routeable devices are sources, midpoints, or destinations. Devices are connected by tie lines. Tie lines represent the cables connecting devices, and are of type audio, video or both. Routes are made by telling a destination to get an audio/video/combined route from a source.
## Summary
Essentials routing is described by defining a graph of connections between devices in a system, typically in configuration. The audio, video and combination connections are like a wiring diagram. This graph is a collection of devices and tie lines, each tie line connecting a source device, source output port, destination device and destination input port. Tie lines are logically represented as a collection.
When routes are to be executed, Essentials will use this connection graph to decide on routes from source to destination. A method call is made on a destination, which says “destination, find a way for source xyz to get to you.” An algorithm analyzes the tie lines, instantly walking backwards from the destination, down every connection until it finds a complete path from the source. If a connected path is found, the algorithm then walks forward through all midpoints to the destination, executing switches as required until the full route is complete. The developer or configurer only needs to say “destination, get source xyz” and Essentials figures out how, regardless of what devices lie in between.
### Classes Referenced
* `PepperDash.Essentials.Core.Routing.IRoutingSource`
* `PepperDash.Essentials.Core.Routing.IRoutingOutputs`
* `PepperDash.Essentials.Core.Routing.IRoutingInputs`
* `PepperDash.Essentials.Core.Routing.IRoutingInputsOutputs`
* `PepperDash.Essentials.Core.Routing.IRoutingSinkNoSwitching`
* `PepperDash.Essentials.Core.Routing.IRoutingSinkWithSwitching`
## Example system, a simple presentation system
The diagram below shows the connections in a simple presentation system, with a few variations in connection paths. Example routes will be described following the diagram.
Each visible line between ports on devices represents a tie line. A tie line connects an output port on one device to an input port on another device, for example: an HDMI port on a document camera to an HDMI input on a matrix switcher. A tie line may be audio, video or both. It is essentially a logical representation of a physical cable in a system. This diagram has 12 tie lines, and those tie lines are defined in the tieLines array in configuration.
![Routing system diagram](~/docs/images/routing-system-diagram.png)
Let’s go through some examples of routing, using pseudo-code:
1. Method call: “Projector 1, show Doc cam.” Routing will walk backwards through DM-RMC-3 and DM-8x8 iterating through all “wired up” ports until it finds a path back to the Doc cam. Routing will then step back through all devices in the discovered chain, switching routes on those that are switchable: Doc cam: no switching; DM 8x8: route input 3 to output 3; DM-RMC-3: no switching; Projector 1: Select input HDMI In. Route is complete.
2. Method call: “Projector 2, show Laptop, video-only.” Routing will walk backwards through DM-RMC-4, DM 8x8, DM-TX-1, iterating through all connected ports until it finds a connection to the laptop. Routing then steps back through all devices, switching video where it can: Laptop: No switching; DM-TX-1: Select HDMI in; DM 8x8: Route input 5 to output 4; DM-RMC-4: No switching; Projector 2: Select HDMI input. Route is complete.
3. Method call: “Amplifier, connect Laptop audio.” Again walking backwards to Laptop, as in #2 above. Switching will take place on DM-TX-1, DM 8x8, audio-only.
4. Very simple call: “Lobby display, show signage controller.” Routing will walk back on HDMI input 1 and immediately find the signage controller. It then does a switch to HDMI 1 on the display.
All four of the above could be logically combined in a series of calls to define a possible “scene” in a room: Put Document camera on Projector 1, put Laptop on Projector 2 and the audio, put Signage on the Lobby display. They key takeaway is that the developer doesn’t need to define what is involved in making a certain route. The person configuring the system defines how it’s wired up, and the code only needs to tell a given destination to get a source, likely through configuration as well.
All of the above routes can be defined in source list routing tables, covered elsewhere (**make link)**.
---
### Definitions
#### Ports
Ports are logical representations of the input and output ports on a device.
#### Source
A source is a device at the beginning of a signal chain. For example, a set-top box, or a camera. Source devices typically have only output ports.
Source devices in Essentials must implement `IRoutingOutputs` or `IRoutingSource`
#### Midpoint
A midpoint is a device in the middle of the signal chain. Typically a switcher, matrix or otherwise. Examples: DM chassis; DM-TX; DM-RMC; A video codec. These devices will have input and output ports.
Midpoint devices must implement `IRoutingInputsOutputs`. Midpoints with switching must implement `IRouting`.
#### Sink
A sink is a device at the end of a full signal path. For example, a display, amplifier, encoder, etc. Sinks typically contain only input ports. They may or may not have switching, like a display with several inputs. Classes defining sink devices must implement `IRoutingSinkNoSwitching` or `IRoutingSinkWithSwitching`.
#### Tie-line
A tie-line is a logical representation of a physical cable connection between two devices. It has five properties that define how the tie-line connects two devices. A configuration snippet for a single tie line connecting HDMI output 1 on a Cisco RoomKit to HDMI input 1 on a display, carrying both audio and video, is shown below.
```json
{
"sourceKey": "ciscoSparkPlusCodec-1",
"sourcePort": "HdmiOut1",
"destinationKey": "display-1",
"destinationPort": "HdmiIn1",
"type": "audioVideo"
}
```
### Interfaces
Todo: Define Interfaces IRouting, IRoutingOutputs, IRoutingInputs

274
docs/Debugging.md Normal file
View File

@@ -0,0 +1,274 @@
# Methods of Debugging
1. You can use Visual Studio step debugging
- Pros:
- Detailed real time debugging into with breakpoints and object inspection
- Cons:
- Doesn't really work remotely
- On processors with Control Subnet, you must be connected to the CS interface to use step debugging. Often not practical or possible.
- No logging
- Using breakpoints stops the program and can interrupt system usage
- Requires the running application to be built in debug mode, not release mode
2. You can use the Debug class features build into the PepperDash.Core library.
- Pros:
- Can be easily enabled from console
- Allows for setting the level of verbosity
- Works when troubleshooting remotely and doesn't require a connection to the CS interface of the processor.
- Allows for logging to the Crestron error log or a custom log stored on removable media
- Works regardless of build type setting (debug/release)
- Can easily identify which class instance is generating console messages
- Can use console commands to view the state of public properties on devices
- Can use console commands to call methods on devices
- Doesn't stop the program
- Cons:
- No detailed object inspection in real time
- Only prints console statements already in code
- When enabled at the highest level of verbosity, it can produce a significant amount of data in console. Can be hard to find messages easily.
- No current mechanism to filter messages by device. (can be filtered by 3rd party tools easily, though)
- Not very effective in debugging applications running on the VC-4 platform as only log messages get printed to the Syslog
## How to use the PepperDash.Core Debug Class
The majority of interaction is done via console, preferably via an SSH session through Crestron Toolbox, PuTTy or any other suitable application.
In code, the most useful method is `Debug.Console()` which has several overloads. All variations take an integer value for the level (0-2) as the first argument. Level 0 will ALWAYS print. Level 1 is for typical debug messages and level 2 is for verbose debugging. In cases where the overloads that accept a `Debug.ErrorLogLevel` parameter are used, the message will ALWAYS be logged, but will only print to console if the current debug level is the same or higher than the level set in the `Debug.Console()` statement.
All statements printed to console are prefixed by a timestamp which can be greatly helpful in debugging order of operations.
```cs
// The most basic use, sets the level (0) and the message to print.
Debug.Console(0, "Hello World");
// prints: [timestamp]App 1:Hello World
// The string parameter has a built in string.Format() that takes params object[] items
string world = "World";
Debug.Console(0, "Hello {0}", world);
// prints: [timestamp]App 1:Hello World
// This overload takes an IKeyed as the second parameter and the resulting statement will
// print the Key of the device in console to help identify the class instance the message
// originated from
Debug.Console(0, this, "Hello World");
// prints: [timestamp]App 1:[deviceKey]Hello World
// Each of the above overloads has a corresponding variant that takes an argument to indicate
// the level of error to log the message at as well as printing to console
Debug.Console(0, Debug.ErrorLogLevel.Notice, "Hello World");
// prints: [timestamp]App 1:Hello World
```
## Console Commands
### General Console Commands
Below are is a non-exhaustive list of some of the Essentials specific console commands that allow interaction with the application at runtime.
### `help user`
Will print the available console commands for each program slot. Console commands can be added and removed dynamically by Essentials and may vary by the version of Essentials that is running. This is the best place to start to determine the available commands registered for each instance of Essentials running on a processor.
### `reportversions:[slot]`
Will print the running versions of all .dll libraries. Useful for determining the exact build version of the Essentials application and all plugins
### `gettypes:[slot] [searchString(optional)]`
The `searchString` value is an optional parameter to filter the results.
Will print all of the valid `type` values registered in the `DeviceFactory` for the running Essentials application. This helps when generating config structure and defining devices. Device types added by plugins will also be shown.
### `showconfig:[slot]`
Will print out the merged config object
### `donotloadonnextboot:[slot] [true/false]`
When the value is set to true, Essentials will pause when starting up, to allow for a developer to attach to the running process from an IDE for purposes of step debugging. Once attached, issuing the command `go:[slot]` will cause the configuration file to be read and the program to initialize. This value gets set to false when the `go` command is issues.
### DeviceManager Console Commands
The following console commands all perform actions on devices that have been registered with the `PepperDash.Essentials.Core.DeviceManager` static class
### `Appdebug:[slot][0-2]`
Gets or sets the current debug level where 0 is the lowest setting and 2 is the most verbose
### `getjoinmap:[slot] [bridgeKey][deviceKey (optional)]
For use with SIMPL Bridging. Prints the join map for the specified bridge. If a device key is specified, only the joins for that device will be printed.
Example:
```sh
RMC3>appdebug:1 // Gets current level
RMC3>AppDebug level = 0
RMC3>appdebug:1 1 // Sets level to 1 (all messages level 1 or lower will print)
RMC3>[Application 1], Debug level set to 1
```
### `Devlist:[slot]`
Gets the current list of devices from `DeviceManager`
Prints in the form [deviceKey] deviceName
Example:
```sh
// Get the list of devices for program 1
RMC3>devlist:1
RMC3>[16:34:05.819]App 1:28 Devices registered with Device Mangager:
[16:34:05.834]App 1: [cec-1] Tx 5 cec 1
[16:34:05.835]App 1: [cec-1-cec]
[16:34:05.835]App 1: [cec-5] Rmc 1 cec 1
[16:34:05.836]App 1: [cec-5-cec]
[16:34:05.836]App 1: [cec-6] Dm Chassis In 1 cec 1
[16:34:05.837]App 1: [cec-6-cec]
[16:34:05.837]App 1: [cec-7] Dm Chassis Out 1 cec 1
[16:34:05.838]App 1: [cec-7-cec]
[16:34:05.838]App 1: [comm-1] Generic comm 1
[16:34:05.838]App 1: [comm-1-com]
[16:34:05.839]App 1: [comm-2] Rmc comm 1
[16:34:05.839]App 1: [comm-2-com]
[16:34:05.840]App 1: [comm-3] Rmc comm 2
[16:34:05.840]App 1: [comm-3-com]
[16:34:05.841]App 1: [dmMd8x8-1] DM-MD8x8 Chassis 1
[16:34:05.842]App 1: [dmRmc100C-1] DM-RMC-100-C Out 3
[16:34:05.843]App 1: [dmRmc200C-1] DM-RMC-200-C Out 2
[16:34:05.843]App 1: [dmRmc4kScalerC-1] DM-RMC-4K-SCALER-C Out 1
[16:34:05.844]App 1: [dmTx201C-1] DM-TX-201C 1
[16:34:05.845]App 1: [eisc-1A]
[16:34:05.845]App 1: [gls-odt-1] GLS-ODT-CN 1
[16:34:05.846]App 1: [gls-oir-1] GLS-OIR-CN 1
[16:34:05.846]App 1: [processor]
[16:34:05.847]App 1: [ssh-1] Generic SSH 1
[16:34:05.847]App 1: [ssh-1-ssh]
[16:34:05.848]App 1: [systemMonitor]
[16:34:05.848]App 1: [tcp-1] Generic TCP 1
[16:34:05.849]App 1: [tcp-1-tcp]
```
### `Setdevicestreamdebug:[slot][devicekey][both/rx/tx/off]`
Enables debug for communication on a single device
Example:
```sh
PRO3>setdevicestreamdebug:1 lights-1-com both
[13:13:57.000]App 1:[lights-1-com] Sending 4 characters of text: 'test'
PRO3>setdevicestreamdebug:1 lights-1-com off
```
### `Devprops:[slot][devicekey]`
Gets the list of public properties on the device with the corresponding `deviceKey`
Example:
```sh
// Get the properties on the device with Key 'cec-1-cec'
// This device happens to be a CEC port on a DM-TX-201-C's HDMI input
RMC3>devprops:1 cec-1-cec
[
{
"Name": "IsConnected",
"Type": "Boolean",
"Value": "True",
"CanRead": true,
"CanWrite": false
},
{
"Name": "Key",
"Type": "String",
"Value": "cec-1-cec",
"CanRead": true,
"CanWrite": true
},
{
"Name": "Name",
"Type": "String",
"Value": "",
"CanRead": true,
"CanWrite": true
},
{
"Name": "Enabled",
"Type": "Boolean",
"Value": "False",
"CanRead": true,
"CanWrite": true
}
]
RMC3>
```
### `Devmethods:[slot][devicekey]`
Gets the list of public methods available on the device
Example:
```sh
// Get the methods on the device with Key 'cec-1-cec'
RMC3>devmethods:1 cec-1-cec
[
{
"Name": "SendText",
"Params": [
{
"Name": "text",
"Type": "String"
}
]
},
{
"Name": "SendBytes",
"Params": [
{
"Name": "bytes",
"Type": "Byte[]"
}
]
},
{
"Name": "SimulateReceive",
"Params": [
{
"Name": "s",
"Type": "String"
}
]
},
//... Response abbreviated for clarity ...
]
RMC3>
```
### `Devjson:[slot][json formatted object {"devicekey", "methodname", "params"}]`
Used in conjunction with devmethods, this command allows any of the public methods to be called from console and the appropriate arguments can be passed in to the method via a JSON object.
This command is most useful for testing without access to hardware as it allows both simulated input and output for a device.
Example:
```sh
// This command will call the SendText(string text) method on the
// device with the Key 'cec-1-cec' and pass in "hello world" as the
// argument parameter. On this particular device, it would cause
// the string to be sent via the CEC Transmit
RMC3>devjson:1 {"deviceKey":"cec-1-cec", "methodName":"SendText", "params": ["hello world\r"]}
// This command will call SimulateReceive(string text) on the device with Key 'cec-1-cec'
// This would simulate receiving data on the CEC port of the DM-TX-201-C's HDMI input
RMC3>devjson:1 {"deviceKey":"cec-1-cec", "methodName":"SimulateReceive", "params": ["hello citizen of Earth\r"]}
```
For additional examples, see this [file](https://github.com/PepperDash/Essentials/blob/main/devjson%20commands.json).

171
docs/DigitalInput.md Normal file
View File

@@ -0,0 +1,171 @@
# DigitalInput
Digital Inputs can be bridged directly to SIMPL from any device that is both inlcuded within essentials and has a relay.
Consider the following example.
```JSON
{
"template": {
"roomInfo": [
{}
],
"devices": [
{
"key": "processor",
"uid": 0,
"type": "pro3",
"name": "pro3",
"group": "processor",
"supportedConfigModes": [
"compliance",
"essentials"
],
"supportedSystemTypes": [
"hudType",
"presType",
"vtcType",
"custom"
],
"supportsCompliance": true,
"properties": {}
},
{
"key": "DigitalInput-1",
"uid": 3,
"name": "Digital Input 1",
"group": "api",
"type": "digitalInput",
"properties": {
"portDeviceKey" : "processor",
"portNumber" : 1,
"disablePullUpResistor" : true
}
},
{
"key": "DigitalInput-2",
"uid": 3,
"name": "Digital Inptut 2",
"group": "api",
"type": "digitalInput",
"properties": {
"portDeviceKey" : "processor",
"portNumber" : 2,
"disablePullUpResistor" : true
}
},
{
"key": "deviceBridge",
"uid": 4,
"name": "BridgeToDevices",
"group": "api",
"type": "eiscapiadv",
"properties": {
"control": {
"tcpSshProperties": {
"address": "127.0.0.2",
"port": 0
},
"ipid": "03",
"method": "ipidTcp"
},
"devices": [
{
"deviceKey": "DigitalInput-1",
"joinStart": 1
},
{
"deviceKey": "DigitalInput-2",
"joinStart": 2
}
]
}
}
]
}
}
```
## RelayOutput Configuration Explanation
This configuration is meant for a Pro3 device, and instantiates two relay ports and links them to an eisc bridge to another processor slot on ipid 3. Let's break down the ```DigitalInput-1``` device.
```JSON
{
"key": "DigitalInput-1",
"uid": 3,
"name": "Digital Input 1",
"group": "api",
"type": "digitalInput",
"properties": {
"portDeviceKey" : "processor",
"portNumber" : 1,
"disablePullUpResistor" : true
}
}
```
**```Key```**
The Key is a unique identifier for essentials. The key allows the device to be linked to other devices also defined by key. All Keys MUST be unique, as every device is added to a globally-accessible dictionary. If you have accidentally utilized the same key twice, Essentials will notify you during startup that there is an issue with the device.
**```Uid```**
The Uid is reserved for use with an PepperDash internal config generation tool, and is not useful to Essentials in any way.
**```Name```**
The Name a friendly name assigned to the device. Many devices pass this data to the bridge for utilization in SIMPL.
**```Group```**
Utilized in certain Essentials devices. In this case, the value is unimportant.
**```Type```**
The Type is the identifier for a specific type of device in Essentials. A list of all valid types can be reported by using the consolecommand ```gettypes``` in Essentials. In this case, the type is ```digitalInput```. This type is valid for any instance of a Relay Output.
**```Properties```**
These are the properties essential to the instantiation of the identified type.
### Properties
There are two properties relevant to the instantiation of a relay device.
**```portDeviceKey```**
This property maps to the ```key``` of the device upon which the relay resides.
**```portNumber```**
This property maps to the number of the relay on the device you have mapped the relay device to. Even if the device has only a single relay, ```portNumber``` must be defined.
**```disablePullUpResistor```**
This is a boolean value, therefore it is a case-sensitive ```true``` or ```false``` utilized to determine if the pullup resistor on the digital input will be disabled or not.
### The JoinMap
The joinmap for a ```digitalInput``` device is comprised of a single digital join.
```cs
namespace PepperDash.Essentials.Core.Bridges
{
public class IDigitalInputJoinMap : JoinMapBaseAdvanced
{
[JoinName("InputState")]
public JoinDataComplete InputState = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Room Email Url", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital });
public IDigitalInputJoinMap(uint joinStart)
: base(joinStart, typeof(IDigitalInputJoinMap))
{
}
}
}
```
```InputState``` is a digital join that represents the feedback for the associated Digital Input Device. Its join is set to 1.

128
docs/Feedback-Classes.md Normal file
View File

@@ -0,0 +1,128 @@
# Feedback classes
***
* [YouTube Video - Using Feedbacks in PepperDash Essentials](https://youtu.be/5GQVRKbD9Rk)
***
The various Feedback classes are like "signals". They can enable various events, and are designed to be used where we need small data events to be sent without requiring custom handlers.
## Why Feedbacks?
We have been writing "code" in an environment, Simpl, for years and have taken for granted the power that signals in that environment give us. With the release of the ability to develop in C#, we have been handed a massive set of tools to potentially make our lives better, but because of the age and limited scope of the .NET 3.5 Compact Framework, many of the things that have been very easy to do in the past have become challenging or bulky to write. Crestron classes have things called "Sigs", which are a less-functional version of the signal that we used in Simpl, but we have no ability to use our own Sigs around our own classes. This forces us to break out of the constraints and mindset of Simpl programming, but simultaneously keeps us partially bound to the "old way" of doing things.
Signals as we have known them since Simpl came around are great. They allow a certain type of functional programming to be built, where things operate in solutions, and we are given a whole set of behaviors that we don't really have to think about: Something goes high, the next thing responds, something else happens, etc. With our older C# framework, it is most straightforward (and least-flexible) to take Sig transitions and handle them using very-flat and bulky coding techniques: Switch/case blocks, if/else blocks, slow dictionaries... In the Essentials environment (and in many other frameworks) these methods quickly reveal their flaws.
Enter the Feedback. We want to define simple events that can be attached to various things - TP Sigs, EISC, event handlers - and maintain their own state. This simplifies the interface to various device classes, and allows us to define functional, simple classes with well-defined means of connecting them together.
### Feedbacks are similar to signals
Feedbacks can:
- Fire an event (OutputChange)
- Be linked to one or more matching Crestron Sigs and update those Sigs
- May contain complex computations to define the output value
- Be put into test mode and have their value function overridden
A Feedback is defined on a class using a C# construct called a `Func`. A `Func` is a small operation that returns a single value and is typically written in a lambda. The operation/expression in the `Func` is calculated when FireUpdate() is called on the Feedback. The result is then available for all objects listening to this Feedback.
[Func documentation (MSDN)](<https://msdn.microsoft.com/en-us/library/bb534960(v=vs.110).aspx>)
#### Creating Feedbacks
The following `IntFeedback` returns the value of the `_VolumeLevel` field in this display class:
```cs
public class MyDisplay
{
public IntFeedback VolumeLevelFeedback { get; private set; }
...
public MyDisplay(...)
{
VolumeLevelFeedback = new IntFeedback(() => { return _VolumeLevel; });
...
```
This BoolFeedback, adapted from the DmTx201Controller class, defines the `Func` first, and then creates the BoolFeedback using that `Func`. The value returned is true if the input is the digital-HDMI connection, and the TX hardware's VideoAttributes.HdcpActiveFeedback is true as well.
```cs
public class MyTx
{
public BoolFeedback HdcpActiveFeedback { get; private set; }
Func HdcpActiveFeedbackFunc = () =>
ActualVideoInput == DmTx200Base.eSourceSelection.Digital
&& tx.HdmiInput.VideoAttributes.HdcpActiveFeedback.BoolValue,
...
public MyTx(...)
{
HdcpActiveFeedback = new BoolFeedback(HdcpActiveFeedbackFunc);
...
```
#### Triggering Feedback
In your classes, when you need to update the objects listening to a Feedback, you will call MyFeedback.FireUpdate() inside your class. This will trigger the evaluation of the Func value, update any linked Sigs, and fire the OutputChange event.
```cs
int _VolumeLevel;
void ComDataChanged(string data) // volume=77
{
if(data.StartsWith("volume="))
{
_VolumeLevel = MyParseVolumeMethod(data); // get the level, 77
VolumeLevelFeedback.FireUpdate(); // all listeners updated
```
#### Using Feedbacks
Feedbacks of the various types have BoolValue, IntValue, UShortValue, and StringValue properties that return the current value of the Feedback.
```cs
if (MyTxDevice.HdcpActiveFeedback.BoolValue)
{
... do something that needs to happen when HDCP is active ...
```
Feedbacks all share an OutputChange event, that fires an event with an empty EventArgs object. The event handler can go get the appropriate \*Value property when the event fires. The example below is a bit contrived, but explains the idea.
```cs
...
MyDisplayDevice.VolumeLevelFeedback.OutputChange += MyDisplayVolumeHandler;
...
}
void MyDisplayVolumeHandler(object o, EventArgs a)
{
MobileControlServer.VolumeLevel = MyDisplayDevice.VolumeLevelFeedback.IntValue;
```
Feedbacks also have a LinkInputSig(\*InputSig sig) method that can directly trigger one or more Sigs on a Crestron device, without requiring an event handler. This is very useful for attaching states of our devices to Crestron touchpanels or EISCs, for example. The BoolFeedback class also has a LinkComplementInputSig(BoolInputSig sig) method that will invert the BoolFeedback's value to one or more attached Sigs.
As well as updating upon change, the Feedback will set the Sig's value to the Feedback value upon calling the LinkInputSig method. This eliminates the need to walk through an object, property-by-property, and update several Sig values - as well as setting up to watch those values for changes. It is all handled in one step.
```cs
public class MyClass
{
Tsw760 MyTp;
MyDisplay Display;
HookUpSigsMethod()
{
...
// changes to VolumeLevelFeedback will automatically propagate to UShortInputSig 123
// changes to HdcpActiveFeedback will propogate to BoolInputSig 456
// and these two panel Sigs are updated immediately as well.
Display.VolumeLevelFeedback.LinkInputSig(MyTp.UshortInput[123]);
MyHdcpDevice.HdcpActiveFeedback.LinkInputSig(MyTp.BoolInput[456]);
```

381
docs/GenericComm.md Normal file
View File

@@ -0,0 +1,381 @@
# GenericComm
One of the most common scenarios in control system development is utilizing RS232 to connect to a device. Essentials doesn't restrict you to connecting a native essentials device or plugin to the comport. You can directly access the comport, and even set baudrates on the fly if you so desire.
Similarly you can instantiate one of several socket types in this manner and bridge them directly to SIMPL.
Consider the following example.
```JSON
{
"template": {
"roomInfo": [
{}
],
"devices": [
{
"key": "processor",
"uid": 0,
"type": "pro3",
"name": "pro3",
"group": "processor",
"supportedConfigModes": [
"compliance",
"essentials"
],
"supportedSystemTypes": [
"hudType",
"presType",
"vtcType",
"custom"
],
"supportsCompliance": true,
"properties": {}
},
{
"key": "Comport-1",
"uid": 3,
"name": "Comport 1",
"group": "api",
"type": "genericComm",
"properties": {
"control": {
"method": "com",
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 115200,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
},
"controlPortNumber": 1,
"controlPortDevKey": "processor",
}
}
},
{
"key": "Comport-2",
"uid": 3,
"name": "Comport 2",
"group": "api",
"type": "genericComm",
"properties": {
"control": {
"method": "ssh",
"tcpSshProperties": {
"address": "192.168.1.57",
"port": 22,
"username": "",
"password": "",
"autoReconnect": true,
"autoReconnectIntervalMs": 10000
}
}
}
},
{
"key": "deviceBridge",
"uid": 4,
"name": "BridgeToDevices",
"group": "api",
"type": "eiscapiadv",
"properties": {
"control": {
"tcpSshProperties": {
"address": "127.0.0.2",
"port": 0
},
"ipid": "03",
"method": "ipidTcp"
},
"devices": [
{
"deviceKey": "Comport-1",
"joinStart": 1
},
{
"deviceKey": "Comport-2",
"joinStart": 3
}
]
}
}
]
}
}
```
## GenericComm Configuration Explanation
This configuration is meant for a Pro3 device, and instantiates one comport and one SSH session and links them to an eisc bridge to another processor slot on ipid 3. Let's break down the ```Comport-1``` device.
```JSON
{
"key": "Comport-1",
"uid": 3,
"name": "Comport 1",
"group": "comm",
"type": "genericComm",
"properties": {
"control": {
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 115200,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
},
"controlPortNumber": 1,
"controlPortDevKey": "processor",
"method": "com"
}
}
}
```
**```Key```**
The Key is a unique identifier for essentials. The key allows the device to be linked to other devices also defined by key. All Keys MUST be unique, as every device is added to a globally-accessible dictionary. If you have accidentally utilized the same key twice, Essentials will notify you during startup that there is an issue with the device.
**```Uid```**
The Uid is reserved for use with an PepperDash internal config generation tool, and is not useful to Essentials in any way.
**```Name```**
The Name a friendly name assigned to the device. Many devices pass this data to the bridge for utilization in SIMPL.
**```Group```**
Utilized in certain Essentials devices. In this case, the value is unimportant.
**```Type```**
The Type is the identifier for a specific type of device in Essentials. A list of all valid types can be reported by using the consolecommand ```gettypes``` in Essentials. In this case, the type is ```genericComm```. This type is valid for any instance of a serial-based communications channel such as a Serial Port, SSH, UDP, or standard TCP/IP Socket.
**```Properties```**
These are the properties essential to the instantiation of the identified type.
#### Control
The properties within this property are dependant on the type of genericComm you wish to instantiate. There is one common property for control of any type, and that is ```method```. The ```method``` property requires a string that maps to the following enumerations in Essentials :
```cs
namespace PepperDash.Core
{
// Summary:
// Crestron Control Methods for a comm object
public enum eControlMethod
{
None = 0,
Com = 1,
IpId = 2,
IpidTcp = 3,
IR = 4,
Ssh = 5,
Tcpip = 6,
Telnet = 7,
Cresnet = 8,
Cec = 9,
Udp = 10,
}
}
```
These enumerations are not case sensitive. Not all methods are valid for a ```genericComm``` device. For a comport, the only valid type would be ```Com```. For a direct network socket, valid options are ```Ssh```, ```Tcpip```, ```Telnet```, and ```Udp```.
##### ComParams
A ```Com``` device requires a ```comParams``` object to set the propeties of the comport. The values of all proeprties are case-insensitive.
```JSON
{
"comParams": {
"hardwareHandshake": "None",
"parity": "None",
"protocol": "RS232",
"baudRate": 115200,
"dataBits": 8,
"softwareHandshake": "None",
"stopBits": 1
}
```
**Valid ```hardwareHandshake``` values are as follows**
```sh
"None"
"Rts"
"Cts"
"RtsCts"
```
**Valid ```parity``` values are as follows**
```sh
"None"
"Even"
"Odd"
"Mark"
```
**Valid ```protocol``` values are as follows**
```sh
"RS232"
"RS422"
"RS485"
```
**Valid ```baudRate``` values are as follows**
```sh
300
600
1200
1800
2400
3600
4800
7200
9600
14400
19200
28800
38400
57600
115200
```
**Valid ```dataBits``` values are as follows**
```sh
7
8
```
**Valid ```softwareHandshake``` values are as follows**
```sh
"None"
"XON"
"XONT"
"XONR"
```
**Valid ```stopBits``` values are as follows**
```sh
1
2
```
Additionally, a ```control``` object for a physical hardware port needs to map to that physical port. This is accomplished by utilizing the ```controlPortDevKey``` and ```port``` properties.
**```controlPortDevKey```**
This property maps to the ```key``` of the device upon which the port resides.
**```port```**
This property maps to the number of the port on the device you have mapped the relay device to. Even if the device has only a single port, ```port``` must be defined.
##### TcpSshParams
A ```Ssh```, ```TcpIp```, or ```Udp``` device requires a ```tcpSshProperties``` object to set the propeties of the socket.
```Json
{
"tcpSshProperties": {
"address": "192.168.1.57",
"port": 22,
"username": "",
"password": "",
"autoReconnect": true,
"autoReconnectIntervalMs": 10000
}
}
```
**```address```**
This is the IP address, hostname, or FQDN of the resource you wish to open a socket to. In the case of a UDP device, you can set either a single whitelist address with this data, or an appropriate broadcast address.
**```port```**
This is the port you wish to utilize for the socket connection. Certain protocols require certain ports - ```Ssh``` being ```22``` and ```Telnet``` being ```23```.
**```username```**
This is the username (if required) for authentication to the device you are connecting to. Typcally only required for ```Ssh``` connections.
**```password```**
This is the password (if required) for authentication to the device you are connecting to. Typcally only required for ```Ssh``` connections.
**```autoreconnect```**
This is a boolean value, therefore it is a case-sensitive ```true``` or ```false``` utilized to determine if the socket will attempt to reconnect upon loss of connection.
**```autoReconnectIntervalMs```**
This is the duration of time, in Miliseconds, that the socket will wait before discrete connection attempts if ```autoreconnect``` is set to true.
##### The JoinMap
The join map for a generic comms device is fairly simple.
```cs
namespace PepperDash.Essentials.Core.Bridges
{
public class IBasicCommunicationJoinMap : JoinMapBaseAdvanced
{
[JoinName("TextReceived")]
public JoinDataComplete TextReceived = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Text Received From Remote Device", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Serial });
[JoinName("SendText")]
public JoinDataComplete SendText = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Text Sent To Remote Device", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Serial });
[JoinName("SetPortConfig")]
public JoinDataComplete SetPortConfig = new JoinDataComplete(new JoinData() { JoinNumber = 2, JoinSpan = 1 },
new JoinMetadata() { Label = "Set Port Config", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Serial });
[JoinName("Connect")]
public JoinDataComplete Connect = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Connect", JoinCapabilities = eJoinCapabilities.FromSIMPL, JoinType = eJoinType.Digital });
[JoinName("Connected")]
public JoinDataComplete Connected = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Connected", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital });
[JoinName("Status")]
public JoinDataComplete Status = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Status", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Analog });
public IBasicCommunicationJoinMap(uint joinStart)
: base(joinStart, typeof(IBasicCommunicationJoinMap))
{
}
}
}
```
```TextReceived``` is a stream of strings received **FROM** the connected device.
```SendText``` is for any strings you wish to send **TO** the connected device.
```Connect``` connects to a remote socket device on the rising edge of the signal.
```Connected``` represents the current connection state. High for Connected, low for Disconnected.
```Status``` is an analog value that is representative of the connection states as reported by the SIMPL TCP/IP socket symbol.
All of the preceeding joins are set to join ```1```. The second serial input join is reserved for ```2```. It allows you to send a ```comparams``` json object as a string, utilizing the same format mentioned previously in this document. Doing so will override the configured comport specifications.

26
docs/Get-started.md Normal file
View File

@@ -0,0 +1,26 @@
# Get started
---
[YouTube Video - Getting Started with PepperDash Essentials](https://youtu.be/FxEZtbpCwiQ)
***
## Download or clone
You may clone Essentials at <https://github.com/PepperDash/Essentials.git>
## How to Get Started
This section assumes knowledge of loading programs to and working with the file system on a Crestron processor.
1. Using an SFTP client, load `PepperDashEssentials1.4.32.cpz` to the processor in program slot 1 and start the program by sending console command `progload -p:1`
1. On first boot, the Essentials Application will build the necessary configuration folder structure in the User/Program1/ path.
1. The application has some example configuration files included. Copy `/Program01/Example Configuration/EssentialsSpaceHuddleRoom/configurationFile-HuddleSpace-2-Source.json` to the `/User/Program1/` folder.
1. Copy the SGD files from `/Program01/SGD` to `/User/Program1/sgd`
1. Reset the program via console `progreset -p:1`. The program will load the example configuration file.
1. Via console, you can run the `devlist:1` command to get some insight into what has been loaded from the configuration file into the system . This will print the basic device information in the form of ["key"] "Name". The "key" value is what we can use to interact with each device uniquely.
1. Run the command `devprops:1 display-1`. This will print the real-time property values of the device with key "display-1".
1. Run the command `devmethods:1 display-1`. This will print the public methods available for the device with key "display-1".
1. Run the command `devjson:1 {"deviceKey":"display-1","methodName":"PowerOn", "params": []}`. This will call the method PowerOn() on the device with key "display-1".
1. Run the provided example XPanel SmartGraphics project and connect to your processor at the appropriate IPID.
Next: [Standalone use](~/docs/Standalone-Use.md)

25
docs/Glossary-of-Terms.md Normal file
View File

@@ -0,0 +1,25 @@
# Glossary of Terms
**Assembly**
An assembly is a file that is automatically generated by the compiler upon successful compilation of every . NET application. It can be either a Dynamic Link Library or an executable file. It is generated only once for an application and upon each subsequent compilation the assembly gets updated.
**Device**
A base class, defined in the PepperDash.Core library (`PepperDash.Core.Device`). It can represent a physical device, or a virtual device or behaviour. Generally, most new classes defined in the Essentials ecosystem should derive from Device.
**DeviceManager**
A static class (`PepperDash.Core.Essentials.DeviceManager`) that contains an unordered collection of Devices. Devices are added/registered to the DeviceManager and later can be retrieved as references by Key.
**Essentials Application**
A Crestron SIMPL# Pro application that is made up of the Essentials Framework and any optionally any number of Essentials Plugins
**Essentials Framework**
The collection of core libraries that make up the framework
**Essentials Plugins**
SIMPL# Pro libraries that reference the Essentials Framework and are loaded at runtime to add or extend functionality
**IKeyed**
An important interface defined in PepperDash.Core that requires a string property named Key, whose value must be unique.
**PepperDash.Core**
A SIMPL# utility library referenced by Essentials Framework.

59
docs/Home.md Normal file
View File

@@ -0,0 +1,59 @@
# Welcome to PepperDash Essentials!
PepperDash Essentials is an open-source framework for control systems, built on Crestron's Simpl# Pro framework. It can be configured as a standalone program capable of running a wide variety of system designs and can also be used to augment other Crestron programs.
Essentials is a collection of C# libraries that can be used in many ways. It is a 100% configuration-driven framework that can be extended to add different workflows and behaviors, either through the addition of new device-types and classes, or via a plug-in mechanism. The framework is a collection of things that are all related and interconnected, but in general do not have strong dependencies on each other.
---
## Get started
- [Download essentials build or clone repo](~/docs/Get-started.md)
- [How to get started](~/docs/Get-started.md)
- [YouTube Video Series Playlist](https://youtube.com/playlist?list=PLKOoNNwgPFZdV5wDEBDZxTHu1KROspaBu)
- [Discord Server](https://discord.gg/6Vh3ssDdPs)
Or use the links to the right to navigate our documentation.
---
## Benefits
- Runs on Crestron 3-Series, **4-Series** and VC-4 Control System platforms
- Reduced hardware overhead compared to S+ and Simpl solutions
- Quick development cycle
- Shared resources made easily available
- More flexibility with less code
- Configurable using simple JSON files
- Is awesome
---
## Comment
The Essentials wiki is clearly in-progress right now. Take a look at the links to the right. We are actively working on this documentation, so please be patient with us. If you have any comments on or suggestions for the documentation, please file an issue here, with as much detail as you can provide: <https://github.com/PepperDash/Essentials/issues>
Thanks!
---
## Collaboration
Essentials is an open-source project and we encourage collaboration on this community project. For features that may not be useful to the greater community, or for just-plain learning, we want to remind developers to try writing plugins for Essentials. More information can be found here: [Plugins](~/docs/Plugins.md)
### Open-source-collaborative workflow
The `main` branch always contain the latest stable version. The `development` branch is used for most development efforts.
[GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) will be used as the workflow for this collaborative project. To contribute, follow this process:
1. Fork this repository ([More Info](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks))
2. Create a branch using standard GitFlow branch prefixes (feature/hotfix) followed by a descriptive name.
- Example: `feature/add-awesomeness` or `hotfix/really-big-oops`
- When working on a new feature or bugfix, branch from the `development` branch. When working on a hotfix, branch from `main`.
3. Make commits as necessary (often is better). And use concise, descriptive language, leveraging issue notation and/or [Closing Keywords](https://help.github.com/articles/closing-issues-using-keywords) to ensure any issues addressed by your work are referenced accordingly.
4. When the scope of the work for your branch is complete, make sure to rebase your branch in case further progress has been made since the repo was forked
5. Create a Pull Request to pull your branch into the appropriate branch in the main repository.
6. Your Pull Request will be reviewed by our team and evaluated for inclusion into the main repository.
Next: [Get started](~/docs/Get-started.md)

103
docs/IR-Driver-Bridging.md Normal file
View File

@@ -0,0 +1,103 @@
## Legacy IR Driver Bridging
```json
{
"id": "1",
"name": "Apple TV",
"key": "appleTv-1",
"type": "genericIrController",
"uid": 3,
"group": "devices",
"properties": {
"control": {
"method": "ir",
"irFile": "Apple_AppleTV_4th_Gen_Essentials.ir",
"controlPortDevKey": "processor",
"controlPortNumber": "1"
}
}
}
```
## Bridge Join Map IR Driver Bridging
```json
{
"id": "1",
"name": "Apple TV",
"key": "appleTv-1",
"type": "genericIrController",
"uid": 3,
"group": "devices",
"properties": {
"control": {
"method": "ir",
"irFile": "Apple_AppleTV_4th_Gen_Essentials.ir",
"controlPortDevKey": "processor",
"controlPortNumber": "1",
"useBridgeJoinMap": true
}
}
}
```
Both methods will bridge the IR signals with `Standard Command` defined in the IR file.
The `useBridgeJoinMap` property implements `GenericIrControllerJoinMap.cs` to standardized IR driver `Standard Command` signal joins. This allows users to swap IR drivers that implement `Standard Command` while bridging IR signals consistently between drivers. For example, when `useBridgeJoinMap` is present, channel up will be mapped to join-22 + device `joinstart` for any IR driver that has the signal marked as `Standard Command`.
## GenericIrControllerJoinMap (Example)
### Digitals
| Join Number | Join Span | Description | Type | Capabilities |
| ----------- | --------- | ----------- | ------------------- | ------------ |
| 1 | 1 | PLAY | Digital | FromSIMPL |
| 2 | 1 | STOP | Digital | FromSIMPL |
| 3 | 1 | PAUSE | Digital | FromSIMPL |
| 4 | 1 | FSCAN | Digital | FromSIMPL |
| 5 | 1 | RSCAN | Digital | FromSIMPL |
| 9 | 1 | POWER | Digital | FromSIMPL |
| 10 | 1 | 0 | Digital | FromSIMPL |
| 11 | 1 | 1 | Digital | FromSIMPL |
| 12 | 1 | 2 | Digital | FromSIMPL |
| 13 | 1 | 3 | Digital | FromSIMPL |
| 14 | 1 | 4 | Digital | FromSIMPL |
| 15 | 1 | 5 | Digital | FromSIMPL |
| 16 | 1 | 6 | Digital | FromSIMPL |
| 17 | 1 | 7 | Digital | FromSIMPL |
| 18 | 1 | 8 | Digital | FromSIMPL |
| 19 | 1 | 9 | Digital | FromSIMPL |
| 21 | 1 | ENTER | Digital | FromSIMPL |
| 22 | 1 | CH+ | Digital | FromSIMPL |
| 23 | 1 | CH- | Digital | FromSIMPL |
| 27 | 1 | POWER_ON | Digital | FromSIMPL |
| 28 | 1 | POWER_OFF | Digital | FromSIMPL |
| 30 | 1 | LAST | Digital | FromSIMPL |
| 41 | 1 | BACK | Digital | FromSIMPL |
| 42 | 1 | GUIDE | Digital | FromSIMPL |
| 43 | 1 | INFO | Digital | FromSIMPL |
| 44 | 1 | MENU | Digital | FromSIMPL |
| 45 | 1 | UP_ARROW | Digital | FromSIMPL |
| 46 | 1 | DN_ARROW | Digital | FromSIMPL |
| 47 | 1 | LEFT_ARROW | Digital | FromSIMPL |
| 48 | 1 | RIGHT_ARROW | Digital | FromSIMPL |
| 49 | 1 | SELECT | Digital | FromSIMPL |
| 54 | 1 | PAGE_UP | Digital | FromSIMPL |
| 55 | 1 | PAGE_DOWN | Digital | FromSIMPL |
| 61 | 1 | A | Digital | FromSIMPL |
| 62 | 1 | B | Digital | FromSIMPL |
| 63 | 1 | C | Digital | FromSIMPL |
| 64 | 1 | D | Digital | FromSIMPL |
### Analogs
| Join Number | Join Span | Description | Type | Capabilities |
| ----------- | --------- | ----------- | ------------------- | ------------ |
### Serials
| Join Number | Join Span | Description | Type | Capabilities |
| ----------- | --------- | ----------- | ------------------- | ------------ |

155
docs/JoinMaps.md Normal file
View File

@@ -0,0 +1,155 @@
# What is a Join Map?
A join map is a class that defines the list of joins accessible to an `EssentialsBridgeableDevice` across an EISC Bridge.
## Why use a Join Map?
A join map is necessary to bridge joins across an EISC bridge from Essentials to a SIMPL program. Join maps can be overriden in a configuration as necessary, but by default each device has a standard join map that publishes joins as a function of the joinOffset property of the device within a given Essentials Bridge. Join maps are reusable and extensible. Several join maps for standard device types already exist within Essentials, and those can be utilized for plugin creation without creation of a new join map. Utilizing standard join maps allows you to create a consistent API between device types that allows switching of devices via config without any new SIMPL or SIMPL#Pro code being written.
## How Join maps Work
Whenever you instantiate a device and link that device to an EISC bridge utilizing your configuration in Essentials, the method `LinkToApi()` is called. This method matches various methods, feedbacks, and properties to joins on the EISC bridge in order to create a consistent API for communication to SIMPL.
Whenever `LinkToApi()` is called, it creates a new instance of the device's joinMap class on demand. The constructor of that joinMap creates an object containing the join metadata, adds any configured join offsets to the standard join map, and adds all associated joins to a global join list that can be easily referenced from the command line.
There are several components for each join within a join map.
```cs
[JoinName("Online")]
public JoinDataComplete Online = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Reports Online Status", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital });
```
### Attribute
```cs
[JoinName("Online")]
```
If the attribute is present, the join data is added to the publically available list `Joins`. This can be used to "prebuild" functionality within a join map that you may not yet need. If you do not add this attribute (or simply comment it out), the join data will not be displayed whenever join data is printed using the `getjoinmap` command.
### JoinData
```cs
JoinData() { JoinNumber = 1, JoinSpan = 1 };
```
`JoinData` contains the pertinent information for the bridge. JoinData contains the information that the bridge utilizes to create each associated connection from the EISC to the methods, properties, and feedbacks associated with a device.
`JoinNumber` is the 1-based index of the join you wish to tie to a given method, property, or feedback. This join, combined with the offset defined in the brdige's configuration for a device, will give you the SIMPL EISC join linked to the given data.
`JoinSpan` determines a number of associated joins. Perhaps you have a list of Camera Presets, or a list of inputs. You can create one single join map entry and define the span of all associated join types.
A `JoinData` object with a `JoinNumber` of 11 and a `JoinSpan` of 10 and a `joinOffset` of 0 is associated with joins 11-20 on the EISC.
### JoinMetadata
```cs
JoinMetadata() { Label = "Reports Online Status", JoinCapabilities = eJoinCapabilities.ToSIMPL, JoinType = eJoinType.Digital }
```
`JoinMetadata` provides the data reported when the `getjoinmap` command is used.
`Label` is the description of the what this join does.
`JoinCapabilities` is represented by an enum defining the direction that the data is flowing for this join. Appropriate values are:
```cs
public enum eJoinCapabilities
{
None = 0,
ToSIMPL = 1,
FromSIMPL = 2,
ToFromSIMPL = ToSIMPL | FromSIMPL
}
```
`JoinType` is represented by an enum defining the data type in SIMPL. Appropriate values are:
```cs
public enum eJoinType
{
None = 0,
Digital = 1,
Analog = 2,
Serial = 4,
DigitalAnalog = Digital | Analog,
DigitalSerial = Digital | Serial,
AnalogSerial = Analog | Serial,
DigitalAnalogSerial = Digital | Analog | Serial
}
```
### JoinDataComplete
```chsarp
JoinDataComplete(JoinData data, JoinMetadata metadata);
```
`JoinDataComplete` represents the `JoinData` and the `JoinMetadata` in a single object. You can call an instance of `JoinDataComplete` to report any information about a specific join. In a device bridge, you would utilize the `JoinNumber` property to link a feature from the plugin to the EISC API.
### Example Join Map
This is the join map for `IBasicCommunication` Devices
```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))
{
}
}
}
```
### Returning Data on Join Maps
A mechanism for printing join maps to console from a running Essentials program is built in to Essentials.
Given a single Generic Communication device with a `joinStart` of 11 and a key of "Com-1", defined on a bridge with a key of "Bridge-1" and IPID of A0, the command `getjoinmap Bridge-1 Com-1` would return:
```sh
Join Map for device 'Com-1' on EISC 'Bridge-1':
GenericComm:
Digitals:
Found 2 Digital Joins
Join Number: '11' | JoinSpan: '1' | Label : 'Connect' | Type: 'Digital' | Capabilities : 'FromSimpl'
Join Number: '11' | JoinSpan: '1' | Label : 'Connected' | Type: 'Digital' | Capabilities : 'ToSimpl'
Analogs:
Found 1 Analog Joins
Join Number: '11' | JoinSpan: '1' | Label : 'Status' | Type: 'Analog' | Capabilities : 'ToSimpl'
Serials:
Found 3 Serial Joins
Join Number: '11' | JoinSpan: '1' | Label : 'Text Received From Remote Device' | Type: 'Serial' | Capabilities : 'FromSimpl'
Join Number: '11' | JoinSpan: '1' | Label : 'Text Sent To Remote Device' | Type: 'Serial' | Capabilities : 'ToSimpl'
Join Number: '12' | JoinSpan: '1' | Label : 'Set Port Config' | Type: 'Serial' | Capabilities : 'FromSimpl'
```

74
docs/Plugins-Deprecated.md Normal file
View File

@@ -0,0 +1,74 @@
# Deprecated
**Note : this entry is out of date - please see [Plugins](~/docs/Plugins.md)**
## 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](~/docs/images/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](~/docs/SIMPL-Bridging.md).
## 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)

131
docs/Plugins.md Normal file
View File

@@ -0,0 +1,131 @@
# What are Essentials Plugins?
**Note : this entry updates a deprecated method - for information related to that deprecated method, see [Plugins - Deprecated](~/docs/Plugins-Deprecated.md)**
***
* [YouTube Video - Loading Plugins in PepperDash Essentials](https://youtu.be/NA64iyNNAgE)
* [YouTube Video - Build Your Own Plugin, Part 1](https://youtu.be/m2phC8g3Kfk)
* [YouTube Video - Build Your Own Plugin, Part 2](https://youtu.be/2_PrWRk6Gy0)
***
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](~/docs/images/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](~/docs/SIMPL-Bridging.md).
## 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)

164
docs/RelayOutput.md Normal file
View File

@@ -0,0 +1,164 @@
# RelayOutput
Relays can be bridged directly to SIMPL from any device that is both inlcuded within essentials and has a relay.
Consider the following example.
```JSON
{
"template": {
"roomInfo": [
{}
],
"devices": [
{
"key": "processor",
"uid": 0,
"type": "pro3",
"name": "pro3",
"group": "processor",
"supportedConfigModes": [
"compliance",
"essentials"
],
"supportedSystemTypes": [
"hudType",
"presType",
"vtcType",
"custom"
],
"supportsCompliance": true,
"properties": {}
},
{
"key": "Relay-1",
"uid": 3,
"name": "Relay 1",
"group": "api",
"type": "relayOutput",
"properties": {
"portDeviceKey" : "processor",
"portNumber" : 1
}
},
{
"key": "Relay-2",
"uid": 3,
"name": "Relay 2",
"group": "api",
"type": "relayOutput",
"properties": {
"portDeviceKey" : "processor",
"portNumber" : 2
}
},
{
"key": "deviceBridge",
"uid": 4,
"name": "BridgeToDevices",
"group": "api",
"type": "eiscapiadv",
"properties": {
"control": {
"tcpSshProperties": {
"address": "127.0.0.2",
"port": 0
},
"ipid": "03",
"method": "ipidTcp"
},
"devices": [
{
"deviceKey": "Relay-1",
"joinStart": 1
},
{
"deviceKey": "Relay-2",
"joinStart": 2
}
]
}
}
]
}
}
```
## RelayOutput Configuration Explanation
This configuration is meant for a Pro3 device, and instantiates two relay ports and links them to an eisc bridge to another processor slot on ipid 3. Let's break down the ```Relay-1``` device.
```JSON
{
"key": "Relay-1",
"uid": 3,
"name": "Relay 1",
"group": "api",
"type": "relayOutput",
"properties": {
"portDeviceKey" : "processor",
"portNumber" : 1
}
}
```
**```Key```**
The Key is a unique identifier for essentials. The key allows the device to be linked to other devices also defined by key. All Keys MUST be unique, as every device is added to a globally-accessible dictionary. If you have accidentally utilized the same key twice, Essentials will notify you during startup that there is an issue with the device.
**```Uid```**
The Uid is reserved for use with an PepperDash internal config generation tool, and is not useful to Essentials in any way.
**```Name```**
The Name a friendly name assigned to the device. Many devices pass this data to the bridge for utilization in SIMPL.
**```Group```**
Utilized in certain Essentials devices. In this case, the value is unimportant.
**```Type```**
The Type is the identifier for a specific type of device in Essentials. A list of all valid types can be reported by using the consolecommand ```gettypes``` in Essentials. In this case, the type is ```relayOutput```. This type is valid for any instance of a Relay Output.
**```Properties```**
These are the properties essential to the instantiation of the identified type.
### Properties
There are two properties relevant to the instantiation of a relay device.
**```portDeviceKey```**
This property maps to the ```key``` of the device upon which the relay resides.
**```portNumber```**
This property maps to the number of the relay on the device you have mapped the relay device to. Even if the device has only a single relay, ```portNumber``` must be defined.
### The JoinMap
The joinmap for a ```relayOutput``` device is comprised of a single digital join.
```cs
namespace PepperDash.Essentials.Core.Bridges
{
public class GenericRelayControllerJoinMap : JoinMapBaseAdvanced
{
[JoinName("Relay")]
public JoinDataComplete Relay = new JoinDataComplete(new JoinData() { JoinNumber = 1, JoinSpan = 1 },
new JoinMetadata() { Label = "Device Relay State Set / Get", JoinCapabilities = eJoinCapabilities.ToFromSIMPL, JoinType = eJoinType.Digital });
public GenericRelayControllerJoinMap(uint joinStart)
: base(joinStart, typeof(GenericRelayControllerJoinMap))
{
}
}
}
```
```Relay``` is a digital join that represents both the trigger and the feedback for the associated relay device. Its join is set to 1.

477
docs/SIMPL-Bridging-Deprecated.md Normal file
View File

@@ -0,0 +1,477 @@
# Deprecated
**Note : this entry is out of date - please see [SIMPL Windows Bridging](~/docs/SIMPL-Bridging.md)**
## 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/main/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](~/docs/Feedback-Classes.md) 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/main/PepperDashEssentials/Bridges/JoinMaps/AirMediaControllerJoinMap.cs>
### AppleTvController
> supports: IR control of Apple TV
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/AppleTvJoinMap.cs>
### CameraControlBase
> supports: any camera that derives from CameraBase
<https://github.com/PepperDash/Essentials/blob/main/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/main/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/main/PepperDashEssentials/Bridges/JoinMaps/DmChassisControllerJoinMap.cs>
### DmRmcController
> supports: All DM-RMC devices
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmRmcControllerJoinMap.cs>
### DmTxController
> supports: All Dm-Tx devices
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmTxControllerJoinMap.cs>
### DmpsAudioOutputController
> supports: Program, Aux1, Aux2 outputs of all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmpsAudioOutputControllerJoinMap.cs>
### DmpsRoutingController
> supports: Av routing for all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmpsRoutingControllerJoinMap.cs>
### GenericRelayController
> supports: Any relay port on a Crestron Control System or Dm Endpoint
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/GenericRelayControllerJoinMap.cs>
### GenericLightingJoinMap
> supports: Devices derived from PepperDash.Essentials.Core.Lighting.LightingBase
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/GenericLightingJoinMap.cs>
### GlsOccupancySensorBase
> supports: Any Crestron GLS-Type Occupancy sensor - single/dual type
<https://github.com/PepperDash/Essentials/blob/main/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/main/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/main/PepperDashEssentials/Bridges/JoinMaps/IBasicCommunicationJoinMap.cs>
### IDigitalInput
> supports: Any Digital Input on a Control System, or DM Endpoint device
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/IDigitalInputJoinMap.cs>
### SystemMonitorController
> supports: Exposing the system monitor slot for any Control System
<https://github.com/PepperDash/Essentials/blob/main/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/main/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](~/docs/Arch-summary.md)

411
docs/SIMPL-Bridging-Updated.md Normal file
View File

@@ -0,0 +1,411 @@
# SIMPL Windows Bridging
***
* [YouTube Video - SIMPL Windows in PepperDash Essentials](https://youtu.be/P2jNzsfpgJE)
***
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": "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.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/main/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](~/docs/Feedback-Classes.md) 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](~/docs/JoinMaps.md)
## 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/main/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/AirMediaControllerJoinMap.cs>
### AppleTvController
> supports: IR control of Apple TV
<https://github.com/PepperDash/Essentials/blob/main/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/AppleTvJoinMap.cs>
### CameraControlBase
> supports: any camera that derives from CameraBase
<https://github.com/PepperDash/Essentials/blob/main/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/main/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/main/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmChassisControllerJoinMap.cs>
### DmRmcController
> supports: All DM-RMC devices
<https://github.com/PepperDash/Essentials/blob/main/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmRmcControllerJoinMap.cs>
### DmTxController
> supports: All Dm-Tx devices
<https://github.com/PepperDash/Essentials/blob/main/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/main/essentials-framework/Essentials%20Core/PepperDashEssentialsBase/Bridges/JoinMaps/DmpsAudioOutputControllerJoinMap.cs>
### DmpsRoutingController
> supports: Av routing for all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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](~/docs/Arch-summary.md)

475
docs/SIMPL-Bridging.md Normal file
View File

@@ -0,0 +1,475 @@
# SIMPL Windows Bridging
**Note : this entry is out of date - please see [SIMPL Windows Bridging - Updated](~/docs/SIMPL-Bridging-Updated.md)**
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/main/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](~/docs/Feedback-Classes.md) 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/main/PepperDashEssentials/Bridges/JoinMaps/AirMediaControllerJoinMap.cs>
### AppleTvController
> supports: IR control of Apple TV
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/AppleTvJoinMap.cs>
### CameraControlBase
> supports: any camera that derives from CameraBase
<https://github.com/PepperDash/Essentials/blob/main/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/main/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/main/PepperDashEssentials/Bridges/JoinMaps/DmChassisControllerJoinMap.cs>
### DmRmcController
> supports: All DM-RMC devices
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmRmcControllerJoinMap.cs>
### DmTxController
> supports: All Dm-Tx devices
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmTxControllerJoinMap.cs>
### DmpsAudioOutputController
> supports: Program, Aux1, Aux2 outputs of all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmpsAudioOutputControllerJoinMap.cs>
### DmpsRoutingController
> supports: Av routing for all DMPS3 Control Systems
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/DmpsRoutingControllerJoinMap.cs>
### GenericRelayController
> supports: Any relay port on a Crestron Control System or Dm Endpoint
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/GenericRelayControllerJoinMap.cs>
### GenericLightingJoinMap
> supports: Devices derived from PepperDash.Essentials.Core.Lighting.LightingBase
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/GenericLightingJoinMap.cs>
### GlsOccupancySensorBase
> supports: Any Crestron GLS-Type Occupancy sensor - single/dual type
<https://github.com/PepperDash/Essentials/blob/main/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/main/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/main/PepperDashEssentials/Bridges/JoinMaps/IBasicCommunicationJoinMap.cs>
### IDigitalInput
> supports: Any Digital Input on a Control System, or DM Endpoint device
<https://github.com/PepperDash/Essentials/blob/main/PepperDashEssentials/Bridges/JoinMaps/IDigitalInputJoinMap.cs>
### SystemMonitorController
> supports: Exposing the system monitor slot for any Control System
<https://github.com/PepperDash/Essentials/blob/main/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/main/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](~/docs/Arch-summary.md)

27
docs/Standalone-Use.md Normal file
View File

@@ -0,0 +1,27 @@
# Standalone application
Essentials was originally designed as a standalone SIMPL# Pro control system application and has developed into a versatile, pluggable application. This page describes how to use our built-in room types for a completely self-contained "one-slot" control program.
By defining devices and a room in a JSON configuration file, Essentials can control an entire AV control system for a room. A file can be manually created in an IDE such as Visual Studio Code, or it can be generated by a friendly web-based configuration tool on [PepperDash Portal](http://pepperdash.com/products/), or some other configuration tool application, both requiring no knowledge of JSON. These tools step a user through building the necessary devices and setting to achieve a full working room.
## Included standalone room types
* `EssentialsHuddleSpaceRoom` - Presentation-only Huddle Room
* Single display device (multiples supported if all displaying mirrored content)
* Use the display's speakers or another device for audio
* Any number of presentation sources
* Fusion Room and Static Asset integration with device usage tracking and schedule awareness
* Occupancy Sensor integration with vacancy shutdown
* Audio/video routing via Crestron DM hardware
* `EssentialsHuddleVtc1Room` - Single-display ATC/VTC capable Huddle Room
* All of the above, plus:
* Audio calling via a DSP/Audio Codec or Video Codec
* Video calling via a Video Codec
* Microphone Mute button and LED color control
* Schedule awareness via Video Codec
* One button meeting join for Video Calling (with supported Video Codec)
See Also: [[Supported Devices|Supported-Devices]]
Next: [Simpl Windows bridging](~/docs/SIMPL-Bridging-Updated.md)

68
docs/Supported-Devices.md Normal file
View File

@@ -0,0 +1,68 @@
# Essentials Framework Devices by Type
## Cameras
* VISCA protocol
* Cisco (via codec)
* Zoom (via Zoom Room)
## Disc Player
* Any IR disc player that implements standard RAD commands
## Displays
* Any IR display that implements standard RAD commands
* Samsung MDC protocol (commercial)
* NEC Professional series flat panel
* Avocor VTF
* Panasonic TH series flat panels
* Panasonic Projectors [(via plugin)](https://github.com/PepperDash/epi-display-panasonic-projectors)
* LG Commercial series [(via plugin)](https://github.com/PepperDash/epi-display-lg)
* Generic CEC control via HDMI [(via plugin)](https://github.com/PepperDash/epi-generic-cec-display)
* Crestron Certified Driver Display [(via plugin)](https://github.com/batourin/epi-display-ccd)
## Lighting/Shading
* Lutron Quantum
* Somfy Shades (relay control)
## Power Controllers
* Digital Logger
## Set Top Boxes
* Any IR set top box that implements standard RAD commands
## Streaming Players
* AppleTV (IR)
* Roku (IR)
## Video Codecs
* Cisco CE series (C/SX/RoomKit)
* Zoom Room
## DSPs / Audio Codecs
* BiAmp Tesira [(via plugin](https://github.com/PepperDash/epi-dsp-tesira)
## Crestron Devices
* AM-200/300 Airmedia
* All DM Chassis (8x8 * 128x128)
* All DM input/output cards
* All DMPS Processors
* All DM Transmitter models (with COM/IR/Relay/CEC port access)
* All DM Receiver models (with COM/IR/Relay/CEC port access)
* DGE-100
* DM-DGE-200-C
* DIN-8SW8
* CEN-IO-DIGIN-104
* CEN-RFGWEX/GWEXER
* GLS-ODT/OIR-C-CN Occupancy Sensors
* TSW-XXX series touchpanels
* XPanel for SmartGraphics
* Fusion Room and Assets

1
docs/getting-started.md Normal file
View File

@@ -0,0 +1 @@
# Getting Started

BIN
docs/images/Plugin Load Sequence.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 398 KiB

BIN
docs/images/arch-high-level.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 228 KiB

BIN
docs/images/arch-overview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 337 KiB

BIN
docs/images/arch-table.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 100 KiB

BIN
docs/images/comm-device-factory.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 104 KiB

BIN
docs/images/lifecycle.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 648 KiB

BIN
docs/images/routing-system-diagram.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 230 KiB

51
docs/toc.yml Normal file
View File

@@ -0,0 +1,51 @@
items:
- name: Home
href: Home.md
- name: Get started
href: Get-started.md
- name: Usage
href: Standalone-Use.md
items:
- name: SIMPL Windows Bridging
href: SIMPL-Bridging.md
items:
- name: Join Maps
href: JoinMaps.md
- name: Bridging to Hardware Resources
href: Bridging-To-Hardware-Resources.md
items:
- name: GenericComm Bridging
href: GenericComm.md
- name: RelayOutput Bridging
href: RelayOutput.md
- name: Digital Input Bridging
href: DigitalInput.md
- name: IR Driver Bridging
href: IR-Driver-Bridging.md
- name: Technical documentation
href: Arch-summary.md
items:
- name: Devices and DeviceManager
href: Arch-1.md
- name: Configurable lifecycle
href: Arch-lifecycle.md
- name: Activation phases
href: Arch-activate.md
- name: More
href: Arch-topics.md
- name: Plugins
href: Plugins.md
- name: Communication Basics
href: Communication-Basics.md
- name: Debugging
href: Debugging.md
- name: Feedback Classes
href: Feedback-Classes.md
- name: Connection Based Routing
href: Connection-Based-Routing.md
- name: Configuration Structure
href: ConfigurationStructure.md
- name: Supported Devices
href: Supported-Devices.md
- name: Glossary of Terms
href: Glossary-of-Terms.md

63
index.md Normal file
View File

@@ -0,0 +1,63 @@
---
_layout: landing
---
# Welcome to PepperDash Essentials!
PepperDash Essentials is an open-source framework for control systems, built on Crestron's Simpl# Pro framework. It can be configured as a standalone program capable of running a wide variety of system designs and can also be used to augment other Crestron programs.
Essentials is a collection of C# libraries that can be used in many ways. It is a 100% configuration-driven framework that can be extended to add different workflows and behaviors, either through the addition of new device-types and classes, or via a plug-in mechanism. The framework is a collection of things that are all related and interconnected, but in general do not have strong dependencies on each other.
---
## Get started
- [Download essentials build or clone repo](~/docs/Get-started.md)
- [How to get started](~/docs/Get-started.md)
- [YouTube Video Series Playlist](https://youtube.com/playlist?list=PLKOoNNwgPFZdV5wDEBDZxTHu1KROspaBu)
- [Discord Server](https://discord.gg/6Vh3ssDdPs)
Or use the links to the right to navigate our documentation.
---
## Benefits
- Runs on Crestron 3-Series, **4-Series** and VC-4 Control System platforms
- Reduced hardware overhead compared to S+ and Simpl solutions
- Quick development cycle
- Shared resources made easily available
- More flexibility with less code
- Configurable using simple JSON files
- Is awesome
---
## Comment
The Essentials wiki is clearly in-progress right now. Take a look at the links to the right. We are actively working on this documentation, so please be patient with us. If you have any comments on or suggestions for the documentation, please file an issue here, with as much detail as you can provide: <https://github.com/PepperDash/Essentials/issues>
Thanks!
---
## Collaboration
Essentials is an open-source project and we encourage collaboration on this community project. For features that may not be useful to the greater community, or for just-plain learning, we want to remind developers to try writing plugins for Essentials. More information can be found here: [Plugins](~/docs/Plugins.md)
### Open-source-collaborative workflow
The `main` branch always contain the latest stable version. The `development` branch is used for most development efforts.
[GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) will be used as the workflow for this collaborative project. To contribute, follow this process:
1. Fork this repository ([More Info](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks))
2. Create a branch using standard GitFlow branch prefixes (feature/hotfix) followed by a descriptive name.
- Example: `feature/add-awesomeness` or `hotfix/really-big-oops`
- When working on a new feature or bugfix, branch from the `development` branch. When working on a hotfix, branch from `main`.
3. Make commits as necessary (often is better). And use concise, descriptive language, leveraging issue notation and/or [Closing Keywords](https://help.github.com/articles/closing-issues-using-keywords) to ensure any issues addressed by your work are referenced accordingly.
4. When the scope of the work for your branch is complete, make sure to rebase your branch in case further progress has been made since the repo was forked
5. Create a Pull Request to pull your branch into the appropriate branch in the main repository.
6. Your Pull Request will be reviewed by our team and evaluated for inclusion into the main repository.
Next: [Get started](~/docs/Get-started.md)

2
src/Directory.Build.props
View File

@@ -13,6 +13,8 @@
<GeneratePackageOnBuild>True</GeneratePackageOnBuild>
<PackageLicenseFile>LICENSE.md</PackageLicenseFile>
<PackageReadmeFile>README.md</PackageReadmeFile>
<GenerateDocumentationFile>True</GenerateDocumentationFile>
<ProduceReferenceAssembly>true</ProduceReferenceAssembly>
</PropertyGroup>
<ItemGroup>
<None Include="..\..\LICENSE.md" Pack="true" PackagePath=""/>

43
src/PepperDash.Core/Directory.build.targets
View File

@@ -1,43 +0,0 @@
<Project>
<ItemGroup>
<None Include="$(TargetDir)\$(TargetName).$(Version).cpz" Condition="$(ProjectType) == 'Program'">
<Pack>true</Pack>
<PackagePath>content;</PackagePath>
</None>
<None Include="$(PackageOutputPath)\$(TargetName).$(Version).cplz" Condition="$(ProjectType) == 'ProgramLibrary'">
<Pack>true</Pack>
<PackagePath>content;</PackagePath>
</None>
</ItemGroup>
<Target Name="Create CPLZ" AfterTargets="Build; Rebuild" Condition="$(ProjectType) == 'ProgramLibrary'">
<Message Text="Creating CPLZ"></Message>
<MakeDir Directories="$(PackageOutputPath)" Condition="!Exists($(PackageOutputPath))"></MakeDir>
<ZipDirectory SourceDirectory="$(TargetDir)" DestinationFile="$(PackageOutputPath)\$(TargetName).$(Version).cplz" Overwrite="true"/>
</Target>
<Target Name="Clean CPLZ" AfterTargets="AfterClean" Condition="$(ProjectType) == 'ProgramLibrary'">
<Delete Files="$(PackageOutputPath)\$(TargetName).$(Version).cplz"/>
</Target>
<Target Name="Copy CPZ" AfterTargets="SimplSharpPostProcess" Condition="$(ProjectType) == 'Program'">
<Message Text="Copying CPZ"></Message>
<Move SourceFiles="$(TargetDir)\$(TargetName).cpz" DestinationFiles="$(TargetDir)\$(TargetName).$(Version).cpz"/>
<Copy SourceFiles="$(TargetDir)\$(TargetName).$(Version).cpz" DestinationFiles="$(PackageOutputPath)\$(TargetName).$(Version).cpz"/>
</Target>
<Target Name="Clean CPZ" AfterTargets="AfterClean" Condition="$(ProjectType) == 'Program'">
<Delete Files="$(PackageOutputPath)\$(TargetName).$(Version).cpz"/>
</Target>
<Target Name="Copy CLZ" AfterTargets="SimplSharpPostProcess">
<Message Text="Copying CLZ"></Message>
<Move SourceFiles="$(TargetDir)\$(TargetName).clz" DestinationFiles="$(TargetDir)\$(TargetName).$(Version).clz"/>
<Copy SourceFiles="$(TargetDir)\$(TargetName).$(Version).clz" DestinationFiles="$(PackageOutputPath)\$(TargetName).$(Version).clz"/>
</Target>
<Target Name="Clean CLZ" AfterTargets="AfterClean">
<Delete Files="$(PackageOutputPath)\$(TargetName).$(Version).clz"/>
</Target>
<Target Name="SimplSharpNewtonsoft" BeforeTargets="FindReferenceAssembliesForReferences;ResolveReferences">
<ItemGroup>
<ReferencePath Condition="'%(FileName)' == 'Newtonsoft.Json.Compact'">
<Aliases>doNotUse</Aliases>
</ReferencePath>
</ItemGroup>
</Target>
</Project>

21
src/PepperDash.Core/EssentialsPlugins-builds-4-series-caller.yml
View File

@@ -1,21 +0,0 @@
name: Build Essentials Plugin
on:
push:
branches:
- '**'
jobs:
getVersion:
uses: PepperDash/workflow-templates/.github/workflows/essentialsplugins-getversion.yml@main
secrets: inherit
build-4Series:
uses: PepperDash/workflow-templates/.github/workflows/essentialsplugins-4Series-builds.yml@main
secrets: inherit
needs: getVersion
if: needs.getVersion.outputs.newVersion == 'true'
with:
newVersion: ${{ needs.getVersion.outputs.newVersion }}
version: ${{ needs.getVersion.outputs.version }}
tag: ${{ needs.getVersion.outputs.tag }}
channel: ${{ needs.getVersion.outputs.channel }}

7
src/PepperDash.Essentials.Core/File/FileIO.cs
View File

@@ -76,7 +76,7 @@ namespace PepperDash.Essentials.Core
/// <summary>
/// Get the data with fileInfo object
/// </summary>
/// <param name="fileName"></param>
/// <param name="file"></param>
/// <returns></returns>
public static string ReadDataFromFile(FileInfo file)
{
@@ -192,11 +192,6 @@ namespace PepperDash.Essentials.Core
}
/// <summary>
///
/// </summary>
/// <param name="data"></param>
/// <param name="filePath"></param>
/// <summary>
///
/// </summary>

2
src/PepperDash.Essentials.Core/Room/Interfaces.cs
View File

@@ -81,7 +81,7 @@ namespace PepperDash.Essentials.Core
void StartShutdown(eShutdownType type);
}
/// <summary""'""">
/// <summary>
/// Describes a room with a tech password
/// </summary>
public interface ITechPassword

3
src/PepperDash.Essentials.Devices.Common/Codec/iHasCallHistory.cs
View File

@@ -9,6 +9,7 @@ using Newtonsoft.Json.Converters;
namespace PepperDash.Essentials.Devices.Common.Codec
{
public interface IHasCallHistory
{
CodecCallHistory CallHistory { get; }
@@ -110,7 +111,7 @@ namespace PepperDash.Essentials.Devices.Common.Codec
/// <summary>
/// Takes the Cisco occurence type and converts it to the matching enum
/// </summary>
/// <param name="s"></para
/// <param name="s"></param>
public eCodecOccurrenceType ConvertToOccurenceTypeEnum(string s)
{
switch (s)

4
toc.yml Normal file
View File

@@ -0,0 +1,4 @@
- name: Docs
href: docs/
- name: API
href: api/