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

Integration into applications

The SDK is shipped as a shared library. All declarations are available from a single header file:

# include "lucon_api.h"

Windows

Link your program against the lucon.dll. It contains statically linked dependencies as listed in dependencies.

Overview

The API consists of following main abstractions:

  • Connections encapsule 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
  • 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

The abstractions of the API are provided by means of handles which are returned by factory functions. After their last usage, all handles must be released with the function LUCON_FreeHandle

Warning
Users must release all acquired handles, otherwise their associated memory and resources are leaked.

Error Handling

The API design destinguishes two kinds of function signatures regarding the indication of success:

  1. Factory functions with return values of type LuconHandle. Successful calls return a handle value different from 0. In case of an error they return 0.
  2. Control functions returning values of type LuconResult. Successful calls are indicated by the return value LUCON_OK. Otherwise the call failed. The returned code gives an indication of what went wrong.

The result status of the most recent API call for each thread is internally saved in thread-local storage (except for calls to LUCON_GetLastApiResult).

After failed API calls a descriptive error message can be retreived by calling LUCON_GetLastApiResult

Functions which are copying output strings into user-provided buffers will return LUCON_ERR_BUFFER_TOO_SMALL if the value exceeds the provided buffersize. Users are encouraged to retry the call with a larger string buffer, e.g. doubling the size after each call.

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

Multi-Threading

For each phsyical 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 on different threads. For this reason concurrent access to one Lucon from multiple threads is allowed.

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 LUCON_DeviceSavePermanently and LUCON_ChannelSavePermanently.

Managing connectivity

The API provides two distinct interfaces to control connectivity:

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 LUCON_DeviceConnect involves a handshake with the hardware to check responsiveness, while LUCON_ConnectionClose only cares about initialization of the host resources.

In both cases users may check and monitor the responsivens of the device using the LUCON_DeviceSetConnectedChangedCallback, and LUCON_DeviceIsConnected. The event callback is internally uses a periodic beacon, if no traffic is generated by users. Its handshake will also be visible, if users monitor the communication with LUCON_ConnectionSetReadCallback and LUCON_ConnectionSetWriteCallback events.

Device hints

With LUCON_ConnectionSetHintCallback users can register to receive hint messages from the device: Lucon2 controllers will send such 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.