TWResearch.Communications 1.3.8

Introduction

TWResearch.Communication is a C# library that enables you to implement communication protocols using a fluent builder. The resulting ICommunication interface is device independent and can be used to control similar devices in the same way.

Communication

All communication protocols can be described in terms of commands and events. A command sends data to the device which can then possible reply with a response. An event is sent from the device without explicitely asking for it. The fluent builder allows you to specify these commands and replies. There a four builders for creating different types of communication:

1. Builder: this is used for basic communication protocols, usually when you have an SDK.
2. BuilderWithResponses: Use this if your communication protocol has reponses on the commands you are sending.
3. BuilderWithKey: Use this if the commands have an identifier which is created within the protocol.
4. BuilderWithKeyResponse: Use this if your communication protocol has reponses and identifiers.

Commands

Commands are classes that implement the ICommand or ICommand<TResult> interface. If you do not expect a answer use the ICommand interface, otherwise use the ICommand<TResult> interface where TResult is the type of the data that is returned by the command. Through the ICommunication.Commands interface you can send the command to the device.

Events

Events are classes that implement the IDeviceEvent interface. If the event is published in the builder you can subscribe to it using the ICommunication.Events interface.

Reponses

Responses are classes that implement the ICommandResponse or the ICommandResponse<TResult> interface. If the response is for a specific command you can use the CommandResponse<TCommand> and CommandResponse<TCommand, TResult> classes to send them. Responses are always intern and cannot be received through the ICommunication.Events interface.

Implementation guidelines

Command ready

Always determining when a command is ready. Reporting a command ready allows the system to start the next command, which should be as soon as possible. So, only if the device does not allow for concurrent (combinations of) commands, delay the ready reporting.

Blocking calls

If you are using an SDK that has blocking methods, wrap the method call(s) inside a Task and use Task variants of the command definitions.

Responses and events handling

If the SDK has a callback or event mechanism to report events/reponses, attach to the callback/event in the OnConnect. And remove them in the Disconnect. You can use the Environment to send the reponses to the commands and the events to the communication.

If you need to check if the device has sent a command or response, implement the code in an internal command which reads and parses the data from the device. It can then send the responses/events through the environment. This command should be set as Checkalive.

When creating a reponse, check if you have set the flags correctly.

• Clear the InSync flag if the responses can be returned out of order.
• Set the IsMultiple flag if it is possible that the current command has already handled this response and the next command is waiting for it. ACK is a good example of this; it can be replied to more than one command and it is possible that you receive an ACK on the next command before the first one has completed. The IsMultiple flag applies only to ready responses since a command is completed after any of the other responses.

Exception handling

All unhandled exceptions will cause the communication to disconnect. If an exception occurs within the system (which is a bug in the program), the communication will also shut down. If you expect a command to have exceptions but you do not want to disconnect, handle the exceptions within the command definition and return it within the result of the command.