SIMPL Communication Adapter
This library helps adapt a DGI Framework drivers that have a IDgiCommunication interface to a SIMPL+ module for interfacing with SIMPL communication symbols, like the TCP/IP Client, UDP/IP Communications or the a Serial Driver.
How to use
Refer to the DGI SIMPL Tascam BD-MP4K BluRay Module for an example:
A DGI SIMPL device driver, just like with the DGI Framework, should be unaware of the physical method of communication. In the DGI Framework that is easily accomplish by injecting a communication driver that implements the IDgiCommunications interface. However, this is not as easily achieved in SIMPL environment.
This adapter helps mediate communications between the device driver and the SIMPL+ module that will ultimately connect to one of the SIMPL communication symbols.
In order to do so a SIMPL# Device Driver should be created with a Crestron.SimplSharp.SDK.Library package. This Driver will use this SimplDgiCommunicationsAdapter that implements IDgiCommunications and will be injected into the device driver. SimplDgiCommunicationsAdapter will then expose some public members that will be used to interface with the SIMPL+ module.
_adapter = new SimplCommunicationsAdapter();
_tascamDriver = new TascamBdmp4KBluRayDriver(_adapter);
Now when the C# driver needs to send information to the SIMPL Communication Module to transmit to the device, it will be caught by the SimplDgiCommunicationsAdapter and will be passed to the SIMPL+ module through the ComDriverTransmitChanged event. All you need to do to implement this in your SIMPL# Library wrapper is the following:
_adapter.ComDriverTransmitChanged += (sender, message) =>
{
ComDriverTransmitChanged?.Invoke(this, new SimplStringEventArgs { Value = message });
};
On most circumstances where the RX strings are expected to be small all that is needed in the SIMPL+ side of things is to create an input join to receive the information from the Communication Module, and the pass it to the driver:
String_Input ComDriverReceived[65534];
Change ComDriverReceived {
BluRayDriver.ComDriverReceived(ComDriverReceived);
}
If data transmission and reception is expected to be in the hundreds of bytes it is recommended to implement the driver in the C# realm, since the switch between SIMPL and C# might not be ideal.
Class Diagram
A Class UML example of the implementation is shown below:
classDiagram
namespace SimplSharpLibraryDeviceDriver {
class DgiFrameworkDeviceDriver {
+DgiFrameworkDeviceDriver(IDgiCommunications)
}
class CommunicationDriver {
<<IDgiCommunications>>
+IsConnected bool
+ErrorMessage string
+Status StatusCodes
+Connect()
+ConnectAsync()
+Disconnect()
+DisconnectAsync()
+Send()
+SendAsync()
+ConnectionChanged(ConnectionChangedArgs) event
+StatusChanged(StatusChangedArgs) event
+DataReceived(DataReceivedArgs) event
}
class SimplDgiCommunicationAdapter {
+ushort ComDriverCommunicationType
+ComDriverConnectChanged(ushort) event
+ComDriverTransmitChanged(string) event
+DataReceived(DataReceivedArgs) event
+ComDriverConnectFeedback(ushort)
+ComDriverReceived(string)
+ComDriverStatus(ushort)
}
}
class SimpPlusCommunicationSymbol {
<<struct>>
+CommunicationType signal
+ConnectF signal
+Status signal
+RX signal
+Connect signal
+TX signal
}
DgiFrameworkDeviceDriver --> SimplDgiCommunicationAdapter : injects
CommunicationDriver <|-- SimplDgiCommunicationAdapter : implements
SimplDgiCommunicationAdapter --> SimpPlusCommunicationSymbol : adaptee
Sequence Diagram
A sequence diagram of the methods and events can be shown below:
sequenceDiagram
participant driver as DGI Framework Device Driver
participant adapter as DgiCommunicationsAdapter
participant SimplSharpDriver as Simpl Sharp Pro Device Driver Wrapper
participant SimplPlusModule as Simpl+ Module
participant SimplModule as Simpl Module
participant CommsModule as SIMPL Communication Module
Note over driver,CommsModule: Connect
driver->>+adapter: Hidden Connect()
adapter-->>-SimplSharpDriver: ComDriverConnectChanged(1)
activate SimplSharpDriver
SimplSharpDriver-->>SimplPlusModule: ComDriverTransmitChanged(1)
deactivate SimplSharpDriver
activate SimplPlusModule
SimplPlusModule->>SimplModule: ComDriver_Connect (Digital Join High)
deactivate SimplPlusModule
activate SimplModule
SimplModule->>CommsModule: Connect (Digital Join High)
deactivate SimplModule
Note over driver,CommsModule: Connect Async
driver->>+adapter: Hidden ConnectAsync()
adapter-->>SimplSharpDriver: ComDriverConnectChanged(1)
activate SimplSharpDriver
SimplSharpDriver-->>SimplPlusModule: ComDriverConnectChanged(1)
deactivate SimplSharpDriver
activate SimplPlusModule
SimplPlusModule-->>SimplModule: ComDriver_Connect (Digital Join High)
deactivate SimplPlusModule
activate SimplModule
SimplModule->>CommsModule: Connect (Digital Join High)
deactivate SimplModule
Note over adapter,CommsModule: time passes...
activate SimplModule
CommsModule->>SimplModule: Connect-F (Digital Join High)
SimplModule->>SimplPlusModule: ComDriver_Connect_Fb (Digital Join High)
deactivate SimplModule
activate SimplPlusModule
SimplPlusModule->>SimplSharpDriver: ComDriverConnectFeedback(1)
deactivate SimplPlusModule
activate SimplSharpDriver
SimplSharpDriver-->>adapter: Hidden ConnectionChanged(1)
deactivate SimplSharpDriver
adapter->>-driver: Task Completed
Note right of driver: Will immediately call ComDriverConnectChanged with true<br/>but will not report task completed until it receives<br/>a Connect-F High from the Comms Module
Note over driver,CommsModule: Connection Feedback
activate SimplModule
CommsModule->>SimplModule: Connect-F (Digital Join High)
SimplModule->>SimplPlusModule: ComDriver_Connect_Fb (Digital Join High)
deactivate SimplModule
activate SimplPlusModule
SimplPlusModule->>SimplSharpDriver: ComDriverConnectFeedback(1)
deactivate SimplPlusModule
activate SimplSharpDriver
SimplSharpDriver-->>+adapter: Hidden ConnectionChanged(1)
deactivate SimplSharpDriver
adapter-->>-driver: ConnectionChanged(args.IsConnected)
Note over driver,CommsModule: Status Feedback
CommsModule->>SimplModule: status (Analog Join State)
activate SimplModule
SimplModule->>SimplPlusModule: ComDriver_Status_Fb (Analog Join State)
deactivate SimplModule
activate SimplPlusModule
SimplPlusModule->>SimplSharpDriver: ComDriverStatus(status: ushort)
deactivate SimplPlusModule
activate SimplSharpDriver
SimplSharpDriver-->>+adapter: Hidden StatusChanged(enum StatusCodes)
deactivate SimplSharpDriver
adapter-->>-driver: StatusChanged(StatusCodes)
Note over driver,CommsModule: Send and Send Async
driver->>+adapter: Hidden Send(string or byte[]) or SendAsync(string or byte[])
loop for each 250 character chunk
adapter-->>SimplSharpDriver: ComDriverTransmitChanged(string)
activate SimplSharpDriver
SimplSharpDriver-->>SimplPlusModule: ComDriverTransmitChanged(SimplStringEventArgs)
activate SimplPlusModule
SimplPlusModule->>SimplModule: ComDriver_Transmit (String)
activate SimplModule
alt message bigger than 1000 characters
SimplModule->>SimplModule: Buffer the message
end
SimplModule->>CommsModule: TX$ (String)
deactivate SimplModule
deactivate SimplPlusModule
deactivate SimplSharpDriver
end
deactivate adapter
Note over driver,CommsModule: Receive
Note over driver,CommsModule: String communication between SIMPL and SIMPL+ can only happen in 250 character chunks (1200 character limit in series 4) It is best to implement applications with big data to send inside the C# driver instead of through an adapter.<br/>
CommsModule->>SimplModule: RX$ (String)
activate SimplModule
SimplModule->>SimplPlusModule: ComDriver_Received (String)
deactivate SimplModule
activate SimplPlusModule
SimplPlusModule->>SimplSharpDriver: ComDriverReceived(data: string)
deactivate SimplPlusModule
activate SimplSharpDriver
SimplSharpDriver-->>+adapter: Hidden DataReceived(data: string)
deactivate SimplSharpDriver
adapter-->>-driver: DataReceived(DataReceivedArgs)
Note over driver,CommsModule: Disconnect
driver->>+adapter: Hidden Disconnect()
adapter-->-SimplSharpDriver: ComDriverConnectChanged(0)
activate SimplSharpDriver
SimplSharpDriver->>SimplPlusModule: ComDriverConnectChanged(0)
deactivate SimplSharpDriver
activate SimplPlusModule
SimplPlusModule->>SimplModule: ComDriverConnect (Digital Join Low)
deactivate SimplPlusModule
activate SimplModule
SimplModule->>CommsModule: Connect (Digital Join Low)
deactivate SimplModule
Note over driver,CommsModule: Disconnect Async
driver->>+adapter: Hidden DisconnectAsync()
adapter-->>SimplSharpDriver: ComDriverConnectChanged(0) false
activate SimplSharpDriver
SimplSharpDriver->>SimplPlusModule: ComDriverConnectChanged(0)
deactivate SimplSharpDriver
activate SimplPlusModule
SimplPlusModule->>SimplModule: ComDriverConnect (Digital Join Low)
deactivate SimplPlusModule
activate SimplModule
SimplModule->>CommsModule: Connect (Digital Join Low)
deactivate SimplModule
Note over adapter,CommsModule: time passes...
CommsModule->>SimplModule: Connect-F (Digital Join Low)
activate SimplModule
SimplModule->>SimplPlusModule: ComDriverConnect-F (Digital Join Low)
deactivate SimplModule
activate SimplPlusModule
SimplPlusModule->>SimplSharpDriver: ComDriverConnectFeedback(0)
deactivate SimplPlusModule
activate SimplSharpDriver
SimplSharpDriver-->>adapter: ComDriverConnectChanged(0)
deactivate SimplSharpDriver
adapter->>-driver: Task Completed
Note right of driver: Will immediately call ComDriverConnectChanged with false<br/>but will not report task completed until it receives<br/>a Connect-F Low from the Comms Module