mirror of
https://github.com/PepperDash/Essentials.git
synced 2026-01-11 19:44:52 +00:00
Adds Classes Referenced section to most pages
@@ -2,9 +2,9 @@
|
||||
|
||||
### 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.
|
||||
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` 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.
|
||||
`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
|
||||
|
||||
@@ -22,7 +22,7 @@ Types of things in `DeviceManager`:
|
||||
|
||||
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.
|
||||
> 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](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.
|
||||
|
||||
|
||||
@@ -6,8 +6,13 @@ The Essentials system architecture is a loose collection of "things" - generally
|
||||
|
||||
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:
|
||||
|
||||
### 1. Construction and addition to the DeviceManager (`PepperDash.Essentials.Core.DeviceManager`)
|
||||
#### Classes Referenced
|
||||
|
||||
* `PepperDash.Core.Device`
|
||||
* `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
|
||||
@@ -20,7 +25,7 @@ This stage is the main phase of startup, and where most devices will get up and
|
||||
|
||||
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.
|
||||
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!
|
||||
|
||||
|
||||
@@ -2,6 +2,10 @@
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
@@ -2,12 +2,15 @@
|
||||
|
||||
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 need to know the details of the method of communication 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 really need to know its communication method, we introduce the `IBasicCommunication` interface.
|
||||
|
||||
#### Classes covered
|
||||
#### 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
|
||||
|
||||
@@ -55,7 +58,7 @@ Essentials uses dependency injection concepts in its start up phase. Simply, mos
|
||||
|
||||

|
||||
|
||||
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 `CommunicationMonitor` device, for Fusion and other reporting.
|
||||
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.
|
||||
|
||||
|
||||
@@ -10,6 +10,16 @@ Essentials routing is described by defining a graph of connections between devic
|
||||
|
||||
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.
|
||||
|
||||
#### 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.
|
||||
|
||||
Reference in New Issue
Block a user