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

Table of Contents

SIMPL Communication Adapter

How to use

Class Diagram

Sequence Diagram