mirror of
https://github.com/PepperDash/Essentials.git
synced 2026-01-11 19:44:52 +00:00
Lots of linking between docs; split up arch
hvolmer
37
Arch-1.md
Normal file
37
Arch-1.md
Normal file
@@ -0,0 +1,37 @@
|
||||
## Essentials 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, 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` 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](https://github.com/PepperDash/Essentials/wiki/Construction-and-Activation-phases-concepts#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
|
||||
|
||||
|
||||
|
||||
Next: [Configurable lifecycle](Arch-lifecycle.md)
|
||||
@@ -1,3 +1,5 @@
|
||||
## 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.
|
||||
@@ -101,4 +103,6 @@ As an example, [connecting-based routing](https://github.com/PepperDash/Essentia
|
||||
|
||||
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.
|
||||
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](Arch-topics.md)
|
||||
9
Arch-lifecycle.md
Normal file
9
Arch-lifecycle.md
Normal 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](Arch-activation))
|
||||
|
||||
|
||||
|
||||
Next: [Activation phases](Arch-activate)
|
||||
21
Arch-summary.md
Normal file
21
Arch-summary.md
Normal file
@@ -0,0 +1,21 @@
|
||||
## 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.
|
||||
|
||||
_Todo, try a text-based table:_
|
||||
|
||||
|
||||
|
||||
The diagram below shows the reference dependencies that exist between the different component libraries that make up the Essentials Framework.
|
||||
|
||||
|
||||
|
||||
Next: [Architecture](Arch-1)
|
||||
@@ -1,73 +1,14 @@
|
||||
### Summary
|
||||
PepperDash Essentials is an open source Crestron framework that can be configured as a standalone program capable of running a wide variety of system designs and can also be utilized as a plug-in architecture to augment other Simpl# Pro and Simpl Windows programs.
|
||||
## Configuration topics
|
||||
|
||||
Essentials Framework is a collection of C# / Simpl# Pro libraries that can be utilized in several different manners. It operates as a 100% configuration-driven system, and can be extended to add different workflows and behaviors, either through the addition of further device "types" or via the plug-in mechanism. The framework is a collection of "things" that are all related and interconnected, but in general do not have dependencies on each other.
|
||||
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.
|
||||
|
||||
### 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:_
|
||||
|
||||
|
||||
|
||||
The diagram below shows the reference dependencies that exist between the different component libraries that make up the Essentials Framework.
|
||||
|
||||
|
||||
|
||||
### 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 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` 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](https://github.com/PepperDash/Essentials/wiki/Construction-and-Activation-phases-concepts#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
|
||||
|
||||
|
||||
|
||||
#### Essentials Configurable System Lifecycle
|
||||
|
||||
|
||||
|
||||
### Activation phases additional topics and examples (OTHER DOCS)
|
||||
|
||||
Concepts (link)
|
||||
|
||||
Room and touchpanel activation (link)
|
||||
|
||||
#### Configure-first development
|
||||
### 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, and then handed to the developer of a configuration tool, only to discover that the object structure in the program is incompatible with the best ways to write the tool. This creates spaghetti code in config tools and tends to create tighter-coupling between objects than we desire to have. Later on a modified version of something is desired, and because the code was written in such a specific fashion, the code is hard to refactor into a new something, and the config tool becomes even more convoluted. The more-modern versions of configuration tools that are just starting to come out are very 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 similar things, and in our running systems, we want to ensure as much flexibility in design as possible, eliminating multiple classes and type with similar code.
|
||||
|
||||
#### Configuration reader process
|
||||
### 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:
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
### Essentials connection-based routing
|
||||
## Essentials connection-based routing
|
||||
|
||||
#### TL;DR
|
||||
### TL;DR
|
||||
|
||||
Routing is defined by a connection graph. A wiring diagram. Route-able 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
|
||||
### Summary
|
||||
|
||||
Essentials routing is described by defining a graph of connections between devices in a system, typically in configuration. Audio, video and combination connections, 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. Simply, 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 and the destination, executing switches 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.
|
||||
|
||||
#### Example system, a simple presentation system
|
||||
### 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.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
### Feedbacks
|
||||
## Feedback classes
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -22,3 +22,4 @@ To help understand Essentials Framework, we recommend starting with the current
|
||||
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".
|
||||
|
||||
Next: [Standalone use](Standalone-Use.md)
|
||||
|
||||
4
Home.md
4
Home.md
@@ -60,4 +60,6 @@ The `master` branch always contain the latest stable version. The `development`
|
||||
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.
|
||||
6. Your Pull Request will be reviewed by our team and evaluated for inclusion into the main repository.
|
||||
|
||||
Next: [Get started](Get-started.md)
|
||||
@@ -18,4 +18,4 @@ Some of the main advantages are:
|
||||
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)
|
||||
|
||||
|
||||
Next: [Essentials architecture](Arch-summary.md)
|
||||
@@ -19,4 +19,6 @@ By defining devices and a room in a JSON configuration file, Essentials can cont
|
||||
- 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)
|
||||
- One button meeting join for Video Calling (with supported Video Codec)
|
||||
|
||||
Next: [Simpl Windows bridging](SIMPL-Bridging.md)
|
||||
13
_Sidebar.md
13
_Sidebar.md
@@ -5,18 +5,17 @@
|
||||
* [Get Essentials](Get-started#download-or-clone)
|
||||
* [How to get started](Get-started#how-to)
|
||||
|
||||
**Technical documentation**
|
||||
|
||||
**Usage**
|
||||
* [Standalone Use](Standalone-Use)
|
||||
* [SIMPL Windows Bridging](SIMPL-Bridging)
|
||||
|
||||
**Technical Documentation**
|
||||
* [Essentials Architecture](Essentials-Architecture)
|
||||
* Subtopic
|
||||
* Another
|
||||
**Technical documentation**
|
||||
* [Essentials Architecture](Arch-summary)
|
||||
* [Devices and DeviceManager](Arch-1.md)
|
||||
* [Configurable lifecycle](Arch-lifecycle.md)
|
||||
* [Activation phases](Arch-activate.md)
|
||||
* [More](Arch-topics.md)
|
||||
* [Plugins](Plugins)
|
||||
* [Device Construction and Activation Phases](Device-Construction-and-Activation-Phases)
|
||||
* [Communication Basics](Communication-Basics)
|
||||
* [Debugging](Debugging)
|
||||
* [Feedback Classes](Feedback-Classes)
|
||||
|
||||
Reference in New Issue
Block a user