Lucon SDK 1.0.7
Loading...
Searching...
No Matches
Lucon SDK C# API

Integration into applications

We suggest to integrate the library using a nuget package reference. I contains transitive dependencies with their licenses listed in dependencies.

Overview

The API consists of following main abstractions:

  • Connection encapsules the communication to the device. These are used to listen for hint messages from the device, monitor the communication of the API or to send messages manually
  • A Device represents a Lucon communication module and provides functionality to parametrize and control it.
  • Channels represent the power modules connected to a Device and allow to control and parametrize their I/O behavior.

Resource Management

All classes which allocate unmanaged resources implement the IDisposable pattern with a finalizer.

Warning
Users are encouraged to manually dispose objects at the end of their lifetime to grant timely release of the related resources

Error Handling

Errors in the SDK are thrown as Exceptions of type LuconException.

Warning
Properties accessors referring to device parameters do not cache any device state but usually communicate to the device. For this reason property getters and setters may throw Exceptions.

In general there is no guarantee regarding the state of the LUCON device after an API call fails: For example the device might have updated the parameter to the new value after a delay, even if the setter failed with a timeout.

Multi-Threading

For each physical Lucon one single Connection shall be created, otherwise messages from the device to the controller may be lost.

The library internally serializes shared accesses to the connection, for example when using multiple Channels of one IDevice in different threads. For this reason concurrent access to one Lucon from multiple threads is allowed.

Care must be taken when event handlers for the DeviceConnection.DataSent and DeviceConnection.DataReceived are registered, as documented in the events.

Remarks

Transient parameters

The mutation of Lucon parameters is always transient, if not stated differently: The device holds the active parameters in volatile memory. At the restart of a device, its presisted settings are restored. To persist the current set of parameters, users must explicitly call the respective method. See IDevice.SavePermanently and IChannel.SavePermanently.

Managing connectivity

The API provides two distinct interfaces to control connectivity:

  • DeviceConnection.Open and DeviceConnection.Close
  • IDevice.Connect and IDevice.Disconnect

Users can choose either one of them according to their needs but should not mix their usage.

As noted in the respective documentation, the difference is that IDevice.Connect involves a handshake with the hardware to check responsiveness, while DeviceConnection.Close only cares about initialization of the host resources.

In both cases users may check and monitor the responsivens of the device using the IDevice.IsConnectedChanged event, IDevice.CheckIsConnected and IDevice.IsConnected. The monitoring event is implemented within the DeviceConnection to use a periodic beacon, if no traffic is generated by users. This handshake will also be visible, if users monitor the communication with DeviceConnection.DataSent or DeviceConnection.DataReceived events.

Device hints

Users may register an event handler for the DeviceConnection.HintReceived to receive hint messages from the device: Lucon2 controllers will send messages to the host to keep him informed for example about errors during operation. This includes errors during autonomous input-triggered operation of the controller. This feature might help you for example to keep track of hardware failures.