Outdated Information
This online document might be outdated. Please see the LucidControl Product Series PDF documentation instead.
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)
Values can be bitwise combined |
|||||||||||||||
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)
Values can be bitwise combined |
|||||||||||||||
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
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
|
Response Frame
In case of successful execution the command returns the value of the identification data block.
Status | LEN | Data Field | |||||
---|---|---|---|---|---|---|---|
Status | 0x10 | Firmware Revision |
Hardware Revision |
Device Class |
Device Type |
Device Serial No. |
Reserved |
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 | – |
Leave a Reply
Want to join the discussion?Feel free to contribute!