4 Communication and Commands

This chapter explains the LucidControl USB IO Module communication interface and the communication protocol.
While for most users it is not necessary to understand this in detail it is helpful for programmers implementing their own API (Application Programming Interface).
Since LucidControl USB IO Modules use the CDC (Comunication Device Class) profile of the USB standard it is possible to access LucidControl USB IO modules as common serial device which has several advantages:

  • Standardized device driver of the operating system can be used and a driver installation is not necessary
  • LucidControl can be controlled by using terminal programs
  • Portable equipment running under Microsoft Windows® as well as Linux
  • Newer releases of operating systems will support the device automatically and there is no reason to search for a new driver version

Based on the serial port the communication with LucidControl uses data frames which are described in the following.


4.1 Communication Frame

The data exchanged between the computer and LucidControl USB IO Modules are packed into communication frames.

Data sent to LucidControl are called Requests, data sent back from LucidControl are called Responses.

The communication follows a master-slave principle where LucidControl answers to Requests of the host only. LucidControl does not initiate a communication on its own.


4.1.1 Request Frame

A Request Frame is sent by a computer to LucidControl USB IO Module and starts the communication sequence.

The following tables shows the Request Frame on byte level.

All Header Fields are all mandantory, the Data Field is only present in the case that the LEN byte indicates this by a value different to 0.

Header Field Data Field
OPC P1 P2 LEN Data Field
1 Byte 1 Byte 1 Byte 1 Byte LEN Bytes
Field Description
OPC Opcode (Instruction) for command request
P1, P2 Command specific parameters
LEN Length; Number of bytes in Data Field
Data Field Optional Data Field containing LEN bytes sent to LucidControl.
Only available for LEN > 0

4.1.2 Response Frame

The Response Frame contains the answer of a LucidControl USB IO Module responding to a Request Frame.

The following tables shows the Response Frame on byte level.

All Header Fields are all mandantory, the Data Field is only present in the case that the LEN byte indicates this by a value different to 0.

Header Field Data Field
Status LEN Data Field
1 Byte 1 Byte LEN Bytes
Field Description
Status Status Code
LEN Length; Number of bytes in Data Field
Data Field Optional Data Field containing LEN bytes.
Only available for LEN > 0

Depending on the command and the execution state LucidControl may return more or less information.
In the case of success the Status Code has a value of 0x00 and LEN indicates how many bytes the Data Field contains.
In the case of error the Status Word is not equal to 0x00 and the Length indicates with a value of 0x00 that the Data Field is absent.
See section Error Status Codes and Messages for more detailes.


4.2 Value Types

LucidControl USB IO Modules handle various analog and digital signals. Commands accessing the inputs and outputs need specification of the Value Type in order to interpret the data correctly.
The following table describes the supported Value Types. The information if a LucidControl module supports a specific Value Type can be found in the modules user manual.

Value Type Description Size
0x00 Digital Logic Value
Value for digital inputs and outputs.
Supported values are either “00” and “01”.
1 Byte
0x0A Digital Counter Value
Input Counter for Digital Inputs.
Value Range: 0 ~ 65,535
2 Bytes
0x10 Analog Value
Value for analog inputs and outputs without unit or further specification.
Value Range: 0 ~ 65,535
2 Bytes
0x1C Voltage Value (signed)
Voltage of analog inputs and outputs
Resolution: 1 mV
Value Range: -30,000 mV ~ 30,000 mV
2 Bytes
0x1D Voltage Value (signed)
Voltage for analog inputs and outputs
Resolution: 1µV
Value Range: 100,000,000 µV ~ 100,000,000 µV
4 Bytes
0x40 Temperature Value (signed)
Temperature of RTD inputs
Resolution: 1/10 K
Value Range: -1,000.0 °C ~ 1,000.0 °C
Values: -10,000 ~ 10,000
2 Bytes
0x41 Temperature Value (signed)
Temperature for RTD inputs
Resolution: 1/100 K
Value Range: -1,000.00 °C ~ 1,000.00 °C
Values: -100,000 ~ 100,000
4 Bytes
0x50 Resistance Value
Resistance Value of RTD inputs
Resolution: 1/10 Ω
Value Range: 0 ~ 5,000 Ω
2 Bytes

Note
Values are represented in little-endial byte order.
A voltage of 5 V is represented by a value of 5,000,000 by using Value Type 0x1D. In the case the value is read from a module the Response Frame looks like this:

Header Field Data Field
Status LEN Value
0x00 0x04 0x40 0x4B 0x4C 0x00

4.3 Implemented Commands

This section explains all available commands supported by the LucidControl USB IO Modules.
Whether a module implements a specific command or not can be found in the module specific user manual.


4.3.1 GetIo

This command reads the value of a channel. For input and output channels the command returns the current state or value.
In the case that an output is read the command may return the state or value which was written to the output before.

Request Frame

OPC P1 P2 LEN
0x46 Channel Value Type 0
Value Description
Channel Number of input or output channel (Range: 0 ~ 3)
Value Type See LucidControl USB IO Module Value Types

Response Frame

Status LEN Data Field
Status Size Value

Size represents the length of the Value and must match with the Value Type.
In the case of an error the command returns Execution Status Code.

Example
Read the Input channel 3 of an analog voltage input. The input channel returns -5V.

Request Frame

OPC P1 P2 LEN
0x46 0x03 0x1D 0

Response Frame

Header Field Data Field
Status LEN Value
0x00 0x04 0xC0 0xB4 0xB3 0xFF

4.3.2 GetIoGroup

This command reads a group of channel values. For input and output channels the command returns the current states or values.
In the case that an output is read the command may return the states or values which were written to the output before.

Request Frame

OPC P1 P2 LEN
0x48 Channel Mask Value Type 0
Value Description
Channel Mask Channel Bit Mask specifying the channel number(s)

Channel Bit Position Value
0 0 0x01
1 1 0x02
2 2 0x04
3 3 0x08

Values can be bitwise combined
Examples
Accessing channel numbers 0 and 3 -> Value = 0x01 OR 0x08 = 0x09
Accessing channel numbers 1 and 2 -> Value = 0x02 OR 0x04 = 0x06

Value Type See LucidControl USB IO Module Value Types

Response Frame
In case of successful execution the command returns the value of the input channels specified in the Channel Mask.

Status LEN Data Field
Status Size Value(s)

Size represents the length of the Value and must be a multiple of Value Type size.

Example
Read the input channels 0 and 3 of an analog voltage input. The input channel 0 returns -5V input channel 3 returns 5V.

Request Frame

OPC P1 P2 LEN
0x48 0x09 0x1D 0

Response Frame

Header Field Data Field
Status LEN Value Channel 0 Value Channel 3
0x00 0x08 0xC0 0xB4 0xB3 0xFF 0x00 0x40 0x4B 0x4C

4.3.3 SetIo

This Command assigns a value to an output channel.

Request Frame

OPC P1 P2 LEN Data
0x40 Channel Value Type Length Value
Value Description
Channel Number of input or output channel (Range: 0 ~ 3)
Value Type See LucidControl USB IO Module Value Types
Length Size of the Value Type
Value Value to write

Response Frame

Status LEN
Status 0

The command does not return any data.

Example
This example sets the digital output channel 2 to logical “High” state

Request Frame
Example
Read the Input channel 3 of an analog voltage input. The input channel returns -5V.

Request Frame

OPC P1 P2 LEN Data
0x40 0x01 0x00 0x01 0x01

Response Frame

Status Length
0x00 0x00

4.3.4 SetIoGroup

This command writes values of the same value type to multiple output channels.

Request Frame

OPC P1 P2 LEN Data
0x42 Channel
Mask
Value Type Length Value(s)
Value Description
Channel Mask Channel Bit Mask specifying the channel number(s)

Channel Bit Position Value
0 0 0x01
1 1 0x02
2 2 0x04
3 3 0x08

Values can be bitwise combined
Examples
Accessing channel numbers 0 and 3 -> Value = 0x01 OR 0x08 = 0x09
Accessing channel numbers 1 and 2 -> Value = 0x02 OR 0x04 = 0x06

Value Type See LucidControl USB IO Module Value Types
Length Size of the Value Type
Value(s) One or more values to set in ascending order

Response Frame

Status Length
Status 0

The command does not return any data.

Example
Assuming a Analog Output Module is used, this example sets the output channels 0 and 3 of a voltage output to 2.5 V and 5.0 V.

Request Frame

OPC P1 P2 LEN Data Field
0x42 0x09 0x1D 0x08 Value Channel 0 Value Channel 1
0x00 0xA0 0x25 0x26 0x00 0x40 0x4B 0x4C

Response Frame

Status Length
0x00 0x00

4.3.5 SetParam

This command sets System Configuration Parameters of the module and IO Configuration Parameters of the inputs or outputs.

Request Frame

OPC P1 P2 LEN Data Field
0xA0 Channel
Mask
Option Length P-Address P-Value
Value Description
Channel Channel number for input or output channel configuration parameters
Option Parameter Set Options

Bit Position Value Description
0 0x01 Set Default
If bit is set the parameter value is set to its default value. Length must be set to 0 and Data Field must be omitted.
7 0x80 Persistent Parameter
Parameter is saved and restored on module startup.

Values can be bitwise combined

Length Length of the Data Field containing parameter address and parameter value. Must be at least 0x02 which is the length of the parameter address.
P-Address Parameter Address
This value specifies the 2 Byte address of the parameter. Adresses of IO configuration parameters can be found in the module specific documentation.
P-Value Parameter Value

Response Frame

Status Length
Status 0

The command does not return any data.

Example
Set the IO configuration parameter outDiCycleTime (Parameter Address = 0x1110) of output channel 0 to 750 ms and make it persistent. The parameter has a length of 4 Bytes.

OPC P1 P2 LEN Data Field
0xA0 0x00 0x80 0x06 P-Address P-Value
0x10 0x11 0xB0 0x71 0x0B 0x00

Response Frame

Status Length
0x00 0x00

[hr/]

4.3.6 GetParam

This command read System Configuration Parameters of the module and IO Configuration Parameters of the inputs or outputs.

Request Frame

OPC P1 P2 LEN Data
0xA2 Channel 0x00 0x02 P-Address
Value Description
Channel Number of input or output channel (Range: 0 ~ 3)
P-Address Parameter Address
This value specifies the 2 Byte parameter Addresses Adresses of IO configuration parameters can be found in the module specific documentation.

Response Frame
In case of successful execution the command returns the value of the specified parameter value. In case of an error no Data Field is returned.

Status LEN Data Field
Status Size P-Value

Example
Read the parameter outDiCycleTime (Parameter Address = 0x1110) of output channel 0. The command returns a value of 750 ms.

Request Frame

OPC P1 P2 LEN Data
0xA2 0x00 0x00 0x02 P-Address
0x10 0x11

Response Frame

Status LEN Data Field
0x00 0x04 0xB0 0x71 0x0B 0x00

[hr/]

4.3.7 CalibrateIo

This command performs LucidControl USB IO Module dependent calibration sequence.
More information can be found in the module specific documentation.

Request Frame

OPC P1 P2 LEN
0x52 Channel Option 0x00
Value Description
Channel Channel number for input or output calibration (Range: 0 ~ 3)
Option Calibration command specific option depending on the calibrated IO
LEN No Data Field present

Response Frame

Status LEN
Status 0

The command does not return any data.


4.3.8 GetId

This command returns the Identification Data Block of the LucidControl module.

Request Frame

OPC P1 P2 LEN
0xC0 0x00 Option 0x00
Value Description
Option Get Identification Option

Bit Position Value Description
0 0x01 Blink
If set the STATE Led of the module blinks once. This can help to find a specific module.

Response Frame
In case of successful execution the command returns the value of the identification data block.

docTable750″>

Status LEN Data Field
Status 0x10 Firmware
Revision
Hardware
Revision
Device
Class
Device
Type
Device
Serial No.
Reserved

4.4 Execution Status Codes and Messages

This table shows the Execution Status Codes which LucidControl USB IO Modules can return including their corresponding Execution Status Messages.

Status Code Status Execution Status Message
0x00 OK Success
0xA0 NO_SUPPORT Command not supported
0xB0 INV_LENGTH Invalid data length
0xB2 INV_P1 Invalid Parameter P1
0xB4 INV_P2 Invalid Parameter P2
0xB6 INV_VALUE Invalid Value or Value Type
0xB8 INV_CHANNEL Invalid IO Channel
0xBA INV_PARAM Invalid Parameter Address
0xC0 INV_DATA Invalid Data in Data Field
0xD0 ERR_EXECUTION Error during Command Execution

Previous Top Next
3 LucidIoCtrl Command Line Tool LucidControl USB IO Module Content