Lucon SDK 1.0.7
Loading...
Searching...
No Matches
Functions related to a Lucon Device (Lucon communcation module).

Functions

LuconHandle LUCON_NewDevice (LuconHandle conn)
 creates a LuconHandle referring to a Lucon device
LuconResult LUCON_DeviceConnect (LuconHandle device)
 Start communicating with the device.
LuconResult LUCON_DeviceDisconnect (LuconHandle device)
 Stops communication and closes the connection to the device.
LuconResult LUCON_DeviceIsConnected (LuconHandle device, int32_t forceCheck, int32_t *const isConnected)
 Check connectivity of the device with the help of a handshake.
LuconResult LUCON_DeviceSetConnectedChangedCallback (LuconHandle device, LuconVoidCallback callback)
 Set a callback function to be called when the connection status of the device changes.
LuconResult LUCON_DeviceSetRestartedCallback (LuconHandle device, LuconVoidCallback callback)
 Set a callback function to be called when the host receives a restart hint from the device.
LuconResult LUCON_DeviceRestart (LuconHandle device, int32_t restartChannels)
 Triggers a restart of the Lucon. Either only the communication module can be restarted or all modules.
LuconResult LUCON_DeviceSavePermanently (LuconHandle device, int32_t restart)
 Persistently save the current parameters of the communication module in its EEPROM.
LuconResult LUCON_DeviceGetSerialNumber (LuconHandle device, char *const strbuf, const size_t buf_len)
 Read the serial number from the communication module as a string.
LuconResult LUCON_DeviceGetMacAddress (LuconHandle device, char *const strbuf, const size_t buf_len)
 Read the MAC address from the communication module as a string.
LuconResult LUCON_DeviceGetIpAddress (LuconHandle device, char *const strbuf, const size_t buf_len)
 Read the IP address setting from the communication module as a string.
LuconResult LUCON_DeviceSetIpAddress (LuconHandle device, const char *const address)
 Set the IPv4 address of the Lucon.
LuconResult LUCON_DeviceGetSubnetMask (LuconHandle device, char *const strbuf, const size_t buf_len)
 Read the IPv4 subnet mask from the device.
LuconResult LUCON_DeviceSetSubnetMask (LuconHandle device, const char *const subnet)
 Set the subnet mask of the device.
LuconResult LUCON_DeviceGetFirmwareVersion (LuconHandle device, char *const strbuf, const size_t buf_len)
 Read the current firmware version from the device.
LuconResult LUCON_DeviceGetChannelNumbers (LuconHandle device, uint8_t *const nbrs, const size_t buf_len, size_t *numChannels)
 Read the channel numbers of the available ("online") channels from the device.
LuconResult LUCON_DeviceGetChannel (LuconHandle device, const uint32_t channelNumber, LuconHandle *ptrChannelHandle)
 Create a handle to access the channel with the given channelNumber.
LuconResult LUCON_DeviceSetChannelsToContinuousMode (LuconHandle device, const uint8_t channelNumbers[], const struct LuconContinuousModeParameters params[], size_t numChannels)
 Set the desired continuous output currents of multiple channels in one command.
LuconResult LUCON_DeviceGetInfo (LuconHandle device, char *const result, const size_t buf_len)
 Compose a descriptive string by reading key parameters from the device.

Detailed Description

Function Documentation

◆ LUCON_DeviceConnect()

LuconResult LUCON_DeviceConnect ( LuconHandle device)
extern

Start communicating with the device.

If not yet done, the related connection will be opened. The connectivity to the device is checked with a handshake. Only if the expected answer is received, the call succeeds. Otherwise and error is returned. In this case the connection is closed again, if and only if it was opened during the call.

Parameters
deviceA handle to the device device to be connected.
Returns

◆ LUCON_DeviceDisconnect()

LuconResult LUCON_DeviceDisconnect ( LuconHandle device)
extern

Stops communication and closes the connection to the device.

See also
LUCON_DeviceConnect()
Parameters
deviceA handle to the device to be connected
Returns

◆ LUCON_DeviceGetChannel()

LuconResult LUCON_DeviceGetChannel ( LuconHandle device,
const uint32_t channelNumber,
LuconHandle * ptrChannelHandle )
extern

Create a handle to access the channel with the given channelNumber.

The user owns the handle which is returned on success. It must bee freed after use to avoid memory leaks! The operation will fail, if the channel with the given number is not available.

See also
LUCON_FreeHandle
Parameters
deviceA handle to the device
channelNumberChannel number of the desired channel
ptrChannelHandleResult buffer recieving the new Functions related to a Lucon Channel (Lucon power module). handle
Returns

◆ LUCON_DeviceGetChannelNumbers()

LuconResult LUCON_DeviceGetChannelNumbers ( LuconHandle device,
uint8_t *const nbrs,
const size_t buf_len,
size_t * numChannels )
extern

Read the channel numbers of the available ("online") channels from the device.

The output buffer should have a capacity of at least 16 entries.

Parameters
deviceA handle to the device
nbrsThe output buffer receiving the channel numbers
buf_lenThe capcacity (maximum number of entries) of the nbrs output buffer
numChannelsA result buffer recieving the number of available channels. The first numChannels entries of nbrs are filled with valid data.
Returns

◆ LUCON_DeviceGetFirmwareVersion()

LuconResult LUCON_DeviceGetFirmwareVersion ( LuconHandle device,
char *const strbuf,
const size_t buf_len )
extern

Read the current firmware version from the device.

Output example: "1.0.1". The output buffer should have at least 10 bytes capacity.

Parameters
deviceA handle to the device
strbufThe output buffer receiving the firmware version as a zero-terminated ASCII string
buf_lenThe capacity of strbuf
Returns

◆ LUCON_DeviceGetInfo()

LuconResult LUCON_DeviceGetInfo ( LuconHandle device,
char *const result,
const size_t buf_len )
extern

Compose a descriptive string by reading key parameters from the device.

The result string is composed dynamically: The function attempts to read parameters from the device. An output buffer size of 1kB should be fully sufficient. If LUCON_ERR_BUFFER_TOO_SMALL is returned, we suggest to retry with twice the buffer size (multiple times if necessary).

Parameters
deviceA handle to the device
resultA string buffer receiving the description
buf_lenThe capcacity of the result buffer
Returns

◆ LUCON_DeviceGetIpAddress()

LuconResult LUCON_DeviceGetIpAddress ( LuconHandle device,
char *const strbuf,
const size_t buf_len )
extern

Read the IP address setting from the communication module as a string.

Output example: "10.0.30.2". The output buffer should have at least 16 bytes capacity. The returned IP address is the current transient setting. It may differ from the IP in use, if the setting was not saved yet or if the device was not yet restarted after a modification.

Parameters
deviceA handle to the device
strbufThe output buffer receiving the IP address as a zero-terminated ASCII string
buf_lenThe capacity of strbuf
Returns
a LuconResult indicating success or error of the operation

◆ LUCON_DeviceGetMacAddress()

LuconResult LUCON_DeviceGetMacAddress ( LuconHandle device,
char *const strbuf,
const size_t buf_len )
extern

Read the MAC address from the communication module as a string.

Output example: "68:27:19:95:1F:F5". At least 18 bytes of output buffer should be provided.

Parameters
deviceA handle to the device
strbufThe output buffer receiving the MAC address as a zero-terminated ASCII string
buf_lenThe capacity of strbuf
Returns

◆ LUCON_DeviceGetSerialNumber()

LuconResult LUCON_DeviceGetSerialNumber ( LuconHandle device,
char *const strbuf,
const size_t buf_len )
extern

Read the serial number from the communication module as a string.

Output example: "220000024". At least 16 bytes of output buffer should be provided.

Parameters
deviceA handle to the device
strbufThe output buffer receiving the serial number as a zero-terminated ASCII string.
buf_lenThe capacity of strbuf
Returns
a LuconResult indicating success or error of the operation

◆ LUCON_DeviceGetSubnetMask()

LuconResult LUCON_DeviceGetSubnetMask ( LuconHandle device,
char *const strbuf,
const size_t buf_len )
extern

Read the IPv4 subnet mask from the device.

Output example: "255.255.255.0". The output buffer should have at least 16 bytes capacity.

Parameters
deviceA handle to the device
strbufThe output buffer receiving the subnet mask as a zero-terminated ASCII string
buf_lenThe capacity of strbuf
Returns
a LuconResult indicating success or error of the operation

◆ LUCON_DeviceIsConnected()

LuconResult LUCON_DeviceIsConnected ( LuconHandle device,
int32_t forceCheck,
int32_t *const isConnected )
extern

Check connectivity of the device with the help of a handshake.

Parameters
deviceA handle to the device.
forceCheckif set to false==0, the function just returns the internal state. Otherwise, a request is sent to the device and responsiveness is checked.
isConnectedbuffer retrieving the boolean result of the connectivity check: 0==false.
Returns

◆ LUCON_DeviceRestart()

LuconResult LUCON_DeviceRestart ( LuconHandle device,
int32_t restartChannels )
extern

Triggers a restart of the Lucon. Either only the communication module can be restarted or all modules.

During a restart modules will reload their persisted settings. Transient changes will be lost! After the the function returns successfully, the connection will be lost! Only if the devices connection settings are unmodified, the devices connection settings are unmodified. Otherwise users must create a new connection.

Parameters
deviceA handle to the device
restartChannelsIf false (==0), only the communication module is restarted, otherwise additionally all channels are restarted.
Returns

◆ LUCON_DeviceSavePermanently()

LuconResult LUCON_DeviceSavePermanently ( LuconHandle device,
int32_t restart )
extern

Persistently save the current parameters of the communication module in its EEPROM.

Saves only(!) the communiction modules parameters. Note that some parameters (e.g. IP address) will only take effect after a restart of the module. During a device restart, the connection will be lost. The connection will be recovered after some time (typically < 5s) only if the devices connection settings are unomidifed. Otherwise users must create a new connection.

Parameters
deviceA handle to the device
restartIff !=0, the communication module will be restarted after saving.
Returns

◆ LUCON_DeviceSetChannelsToContinuousMode()

LuconResult LUCON_DeviceSetChannelsToContinuousMode ( LuconHandle device,
const uint8_t channelNumbers[],
const struct LuconContinuousModeParameters params[],
size_t numChannels )
extern

Set the desired continuous output currents of multiple channels in one command.

The continous mode parameters given by params are applied one-by-one in the given order to the channels with the given channelIds.

See also
LUCON_ChannelSetToContinuousMode
Parameters
deviceA handle to the device
channelNumbersan array with the numChannels numbers of channels to set
paramsan array with numChannels continuous mode parameters to be set
numChannelsthe lenght of the input parameter arrays
Returns

◆ LUCON_DeviceSetConnectedChangedCallback()

LuconResult LUCON_DeviceSetConnectedChangedCallback ( LuconHandle device,
LuconVoidCallback callback )
extern

Set a callback function to be called when the connection status of the device changes.

The device connection status indicates, whether the device is responsive. In the absence of other communication, the SDK sends beacon messages in regular intervals. Interruptions of the connection will be reported with some delay. The callback is invoked asynchronously after a status change. Users need to query the current connection status with LUCON_DeviceIsConnected

Parameters
deviceA handle to the device
callbackA pointer to the callback function. Pass NULL to reset a previously set callback.
Returns

◆ LUCON_DeviceSetIpAddress()

LuconResult LUCON_DeviceSetIpAddress ( LuconHandle device,
const char *const address )
extern

Set the IPv4 address of the Lucon.

The ip setting will take effect only after saving and restarting the device.

See also
LUCON_DeviceSavePermanently
LUCON_DeviceRestart
Parameters
deviceA handle to the device
addressA IPv4 address encoded as a ASCII string. Example: 10.30.0.2
Returns

◆ LUCON_DeviceSetRestartedCallback()

LuconResult LUCON_DeviceSetRestartedCallback ( LuconHandle device,
LuconVoidCallback callback )
extern

Set a callback function to be called when the host receives a restart hint from the device.

The callback function is invoked asynchronously whenever the host receives a message from the device which indicates a restart. This may happen e.g. after a supply-power interruption of the Lucon device or if a restart command was sent to the device. The device might already handle and answer commands before the event is raised! The does only incicate the restart of the communication module. A restart of individual channels can not be detected! It is not guaranteed, that all channels are available after a device restart.

Parameters
deviceA handle to the device
callbackA pointer to the callback function. Pass NULL to reset a previously set callback.
Returns

◆ LUCON_DeviceSetSubnetMask()

LuconResult LUCON_DeviceSetSubnetMask ( LuconHandle device,
const char *const subnet )
extern

Set the subnet mask of the device.

Parameters
deviceA handle to the device
subnetThe subnet mask to set as a zero-terminated ASCII string. Example: 255.255.255.0
Returns

◆ LUCON_NewDevice()

LuconHandle LUCON_NewDevice ( LuconHandle conn)
extern

creates a LuconHandle referring to a Lucon device

The user must provide a valid LuconHandle to a connection. The connection handle remains under ownership of the user. The user owns the returned device handle and must call LUCON_FreeHandle to release memory and resources related to the handle.

Parameters
connA LuconHandle to a connection
Returns
The new LuconHandle or NULL in case of an error