Device mode

Owned by du
Apr 20, 2016

dev_Connect (connect to iqInterface over comport/USB in generic device mode)

Function:

int16 dev_Connect(uchar08 ucFromPortNo, uchar08 ucUntilPortNo, char08 *cpErrMsg);

Description:

To connect to iqInterface over comport or USB in the device mode call dev_Connect function with start and stop comport numbers (virtual in case of USB) which define a range where to look for iqInterface. Save the returned port number which will be a handle to perform all other operations.

Input Parameters:

  • uchar08 ucFromPortNo – (virtual) comport number to start looking for iqInterface with (inclusively)
  • uchar08 ucUntilPortNo – (virtual) comport number to stop looking for iqInterface (inclusively)

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

First successfully found (virtual) comport number to connect or negative error number. The comport number is an established connection handle for all other functions.

Example:

uchar08 ucPortNoStart = 0;
uchar08 ucPortNoFinish = 10;
int16 iPortNo = dev_Connect(ucPortNoStart, ucPortNoFinish, cpErrMsg);
 

dev_EthernetConnect (connect to iqInterface over Ethernet (tcp/ip) in generic device mode)

Function:

int16 dev_EthernetConnect(enet_ConnectionT * connection, uint16 uiSendRecvTimoutMs, char08 *cpErrMsg);

Description:

If you know the IP address of iqInterface in your network and port (10001 by default) you can use variable of type enet_ConnectionT to set the IP and port. To connect to iqInterface in generic device mode call dev_EthernetConnect with the IP/port variable and send/receive timeout in milliseconds as arguments instead of using dev_Connect. If you do not know the IP address you can try to search it using comm_EthernetSearch function before connecting. See also Ethernet connection.

Input Parameters:

  • enet_ConnectionT * connection – pointer to Ethernet connection variable
  • uint16 uiSendRecvTimoutMs – send/receive timeout in milliseconds used for underlying tcp/ip connection

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

Virtual handle number of successful Ethernet (tcp/ip) connection or negative error number. The virtual number is an established connection handle for all other functions the same as for comport/USB connection (see dev_Connect).

Example:

enet_ConnectionT connection;
uint16 uiSendRecvTimoutMs = 2000; // 2 sec
int16 iPortNo;
strcpy(connection. cpIqInterfaceIpAddr, “XXX.XXX.XXX.XXX”); // IPv4
connection.uiPort = 10001;
iPortNo  = dev_EthernetConnect(&connection, uiSendRecvTimoutMs, cpErrMsg);
dev_GetConfig(iPortNo, &config, cpErrMsg);
 

dev_Disconnect (disconnect iqInterface in generic device mode)

Function:

int16 dev_Disconnect(uint16 uiPortNo, char08 *cpErrMsg);

Description:

To disconnect iqInterface (free OS resources) call dev_Disconnect with a previously connected port number.

Input Parameters:

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

dev_Disconnect(iPortNo, cpErrMsg);
  

dev_GetConfig and dev_SetConfig (get/set generic device mode configuration)

Function:

int16 dev_GetConfig(uint16 uiPortNo, dev_ConfigT *pConfig, char08 *cpErrMsg);
int16 dev_SetConfig(uint16 uiPortNo, dev_ConfigT *pConfig, char08 *cpErrMsg);

Description:

You can load the generic device configuration in a variable of type dev_ConfigT, manipulate it and save it again to iqInterface before starting an IO-Link communication from master side.

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • dev_ConfigT *pConfig – pointer to variable of type dev_ConfigT to set configuration from or get to

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number (it is not allowed to configure generic device during active IO-Link communication from master side).

Example:

dev_ConfigT config;
dev_GetConfig(iPortNo, &config, cpErrMsg);
// manipulate config…
dev_SetConfig(iPortNo, &config, cpErrMsg);
 

dev_ConfigT (generic device mode configuration data type)

Description:

This structure holds the configuration parameters of iqInterface generic device mode. It is used to get or set them in dev_GetConfig and dev_SetConfig functions.

Fields

  • uint16 stackVersion (readonly) – 2 number version of iqStack device in connected iqInterface firmware (X.X: MSB – high number, LSB – low number)
  • IOLBaudrateT supportedBaudrate – IO-Link communication baudrate, can be IOL_BAUDRATE_COM1 (4,8 kbit/s), IOL_BAUDRATE_COM2(38,4 kbit/s) or IOL_BAUDRATE_COM3 (230,4 kbit/s)
  • uint16 masterCycleTime (readonly) – IO-Link master cycle time in milliseconds used by master in current or last successful operate state
  • uint16 minCycleTime – device minimum cycle time in milliseconds in operate state
  • IOLRevisionIDT revisionID – IO-Link revision ID, can beIOL_REV_ID_V1_0 (v1.0) or IOL_REV_ID_V1_1 (v1.1), version of IO-Link communication to emulate
  • uchar08 ODSizePreoperate – On-request data bytes number in IO-Link communication message in preoperate state
  • uchar08 ODSizeOperate – On-request data bytes number in IO-Link communication message in operate state
  • boolean isPDInLengthBytes – TRUE: PDInLength in bytes, FALSE: in bits
  • uchar08 PDInLength – process data input byte number in IO-Link communication message in operate state
  • boolean isPDOutLengthBytes – TRUE: PDOutLength in bytes, FALSE: in bits
  • uchar08 PDOutLength – process data output byte number in IO-Link communication message in operate state
  • uint16 deviceVendorID – vendor ID
  • ulong32 deviceID – device ID
  • uchar08 deviceSerialNumber[MST_DEV_SER_NUM_MAX_LEN + 1] – configured device serial number
  • dev_ISDURspTypeT ISDURspType – see description of dev_GetODRequest
 

dev_GetODRequest (wait and read ISDU request from master)

Function:

int16 dev_GetODRequest(uint16  uiPortNo, uchar08 *ucType, uint16  *uiIndex, uchar08 *ucSubindex, uchar08 *ucpBuf, uint16 ucBufSize, uint16  *uiISDUErrCode, char08  *cpErrMsg);

Description:

In order that this function works the dev_ConfigT .ISDURspType should be set to OD_RSP_TYPE_AUTO or OD_RSP_TYPE_MANUAL by dev_SetConfig.

The default setting for ISDURspType is OD_RSP_TYPE_AT_ONCE after iqInterface reset. In this case iqInterface responds immediately to master according to configured (saved) ISDU parameters and this function is useless because it never gets a notification about ISDU request.

In case of OD_RSP_TYPE_AUTO this function makes iqInterface respond with configured (saved) ISDU parameters and confirm ISDU request to master which will not receive ISDU response without call of this function.

In case of OD_RSP_TYPE_MANUAL iqInterface does not response with configured ISDU parameters, the function just returns last received and pending ISDU request, reponse should be sent by dev_ODResponse.

ISDU requests to direct page 1 are not indicated by this function, because system manager of device stack is responsible for it.

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uint16 ucBufSize – max size of buffer ucpBuf

Output Parameters:

  • uint16 *ucType – type of ISDU request can beDEV_ODREQ_TYPE_WRITE, DEV_ODREQ_TYPE_WRITE_ERR,DEV_ODREQ_TYPE_READ, DEV_ODREQ_TYPE_READ_ERR
  • uint16 *uiIndex – index of ISDU request
  • uchar08 *ucSubindex – subindex of ISDU request
  • uchar08 *ucpBuf – data bytes of ISDU request
  • uchar08 *uiISDUErrCode – possible ISDU error code
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

Negative error number (ERR_PARAMETER - ucBufSize is too small for received ISDU request, ERR_INTERNAL - ISDU request waiting timeout) or size of ISDU data saved in ucpBuf.

Example:

uint16 uiIndex;
uchar08 ucSubindex;
uchar08 ucODType;
uchar08 ucpBuf[2], ucState;
uint16 uiISDUErr = 0;
int16 isduSize = dev_GetODRequest(iPortNo, &ucODType, &uiIndex, &ucSubindex, ucpBuf, 2, &uiISDUErr, cpErrMsg);
 

dev_ODResponse (send ISDU response to master)

Function:

int16 dev_ODResponse(uint16 uiPortNo, uchar08 ucType, uchar08 *ucpBuf, uint16 uiBytesCount, uint16 uiISDUErrCode, char08 *cpErrMsg);

Description:

This function sends ISDU response received by dev_GetODRequest in case of setting dev_ConfigT .ISDURspType to OD_RSP_TYPE_MANUAL. It also confirms the response to master which will not receive the response without this function call.

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uint16 *ucType – type of ISDU request can beDEV_ODREQ_TYPE_WRITE, DEV_ODREQ_TYPE_WRITE_ERR,DEV_ODREQ_TYPE_READ, DEV_ODREQ_TYPE_READ_ERR
  • uchar08 *ucpBuf – data bytes of ISDU read response if ucType isDEV_ODREQ_TYPE_READ
  • uint16 uiBytesCount – size of ISDU read response in buffer **ucpBuf ifucType is DEV_ODREQ_TYPE_READ
  • uchar08 *uiISDUErrCode – possible error code of ISDU response ifucType is DEV_ODREQ_TYPE_WRITE_ERR orDEV_ODREQ_TYPE_READ_ERR

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

// config generic device before starting IO-Link communication
dev_ConfigT config;
config.ISDURspType = OD_RSP_TYPE_MANUAL;
dev_SetConfig(iPortNo, &config, cpErrMsg);
// ... IO-Link communication is being started
uint16 uiIndex;
uchar08 ucSubindex;
uchar08 ucODType;
uchar08 ucpBuf[2], ucState;
uint16 uiISDUErr = 0;
int16 isduSize = dev_GetODRequest(iPortNo, &ucODType, &uiIndex, &ucSubindex, ucpBuf, 2, &uiISDUErr, cpErrMsg);
// ... process received ISDU request
// ISDU read ok response
uchar08 ucpBuf[2]; // ... fill ucpBuf with response data
dev_ODResponse(iPortNo, DEV_ODREQ_TYPE_READ, ucpBuf, 2, 0, cpErrMsg);
// ISDU read error response
dev_ODResponse(iPortNo, DEV_ODREQ_TYPE_READ_ERR, 0, 0, 0x8011, cpErrMsg);
// ISDU write ok response
dev_ODResponse(iPortNo, DEV_ODREQ_TYPE_WRITE, 0, 0, 0, cpErrMsg);
// ISDU write error response
dev_ODResponse(iPortNo, DEV_ODREQ_TYPE_WRITE_ERR, 0, 0, 0x8011, cpErrMsg);
 

dev_AddISDU (add new ISDU parameter to generic device)

Function:

int16 dev_AddISDU(uint16 uiPortNo, uint16 uiFlag, uint16 uiIndex, uchar08 ucSubindex, uchar08 *ucpBuf, uint16 uiBytesCount, char08  *cpErrMsg);

Description:

You can add new ISDU parameters using dev_AddISDU function with an ISDU index, subindex, data, data length and a read/write flag as arguments. Master can read and write the ISDU parameter value depending on its access level. The data length of added ISDU will be fixed and checked for exact equality in case of write operation from master. You cannot delete one previously added ISDU parameter but you can delete all of them using dev_RemoveAllISDU function (clear ISDU structure) and add all remained ISDU parameters again. The ISDU structure (subindexes within one index) must always stay consistent, see ISDU Parameters.

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uint16 uiFlag – flag where ISDU read/write access is decoded, variable of type dev_ISDU_FlagT to encode access (see example)
  • uint16 uiIndex – index of ISDU parameter to add
  • uchar08 ucSubindex – subindex of ISDU parameter to add
  • uchar08 *ucpBuf – data bytes of ISDU parameter value to add
  • uint16 uiBytesCount – size of ISDU parameter value “ucpBuf” to add

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

dev_ISDU_FlagT ISDUFlag;
uchar08 od[256];
uchar08 ISDULength = 2; // ISDU length is 2 bytes
uint16 index = 0x0015;
uchar08 subindex = 0
dev_RemoveAllISDU(iPortNo, cpErrMsg);
ISDUFlag.Data = 0;
ISDUFlag.Bits.IsRead = TRUE;
ISDUFlag.Bits.IsWrite = TRUE;
// fill “od” buffer with ISDU data …
dev_AddISDU(iPortNo, ISDUFlag.Data, index, subindex, od, ISDULength, cpErrMsg);
 

dev_RemoveAllISDU (remove all ISDU parameters from generic device)

Function:

int16 dev_RemoveAllISDU (uint16 uiPortNo, char08  *cpErrMsg);

Description:

Remove all ISDU parameters previously added by dev_AddISDU.

Input Parameters:

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

dev_RemoveAllISDU(iPortNo, cpErrMsg);
 

dev_GetISDUValue (get ISDU parameter value)

Function:

int16 dev_GetISDUValue(uint16 uiPortNo, uint16 uiIndex, uchar08 ucSubindex, uchar08 *ucpBuf, uint16 uiBufSize, char08  *cpErrMsg);

Description:

Every time (also during active IO-Link communication) you can get ISDU parameter current value which could be changed by master. To get it use dev_GetISDUValue function with ISDU index, subindex, buffer and its size to return value as arguments. The function returns an actual size of ISDU parameter value returned to the buffer.

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uint16 uiIndex – index of ISDU parameter to get value
  • uchar08 ucSubindex – subindex of ISDU parameter to get value
  • uint16 uiBufSize – size of buffer ucpBuf for ISDU parameter value to get

Output Parameters:

  • uchar08 *ucpBuf – pointer to buffer to return ISDU parameter value to get
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

uchar08 odBufferSize = 256;
uchar08 odActualSize = dev_GetISDUValue(iPortNo, index, subindex, od, odBufferSize, cpErrMsg);
 

dev_SetISDUValue (set ISDU parameter value)

Function:

int16 dev_SetISDUValue(uint16 uiPortNo, uint16 uiIndex, uchar08 ucSubindex, uchar08 *ucpBuf, uint16 uiBytesCount, char08  *cpErrMsg);

Description:

You can also set ISDU parameter current value using dev_SetISDUValue function with ISDU index, subindex, buffer with value to set and its size as arguments. The value length must equal its length at the moment of adding the ISDU parameter.

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uint16 uiIndex – index of ISDU parameter to set value
  • uchar08 ucSubindex – subindex of ISDU parameter to set value
  • uchar08 *ucpBuf – data bytes of ISDU parameter value to set
  • uint16 uiBytesCount – size of ISDU parameter value ucpBuf to set

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

uchar08 odSizeToSet = 5;
// fill “od” buffer with value to set
dev_SetISDUValue(iPortNo, index, subindex, od, odSizeToSet, cpErrMsg));
 

dev_GetStatus (get generic device status)

Function:

int16 dev_GetStatus(uint16 uiPortNo, uchar08 *pStatus, uchar08 *ucpPDOutBuf, uint16 uiPDOutBufSize, char08 *cpErrMsg);

Description:

You can get current state of IO-Link communication, process data output which master sends and its validity using dev_GetStatus function with a pointer to status byte and process data output buffer to return it. Then you can use a dev_StatusT structure to extract current IO-Link state of typedev_StateT and process data output validity (0 – valid, 1 - invalid). Possible IO-Link states are enumerated in the iqi_dev.h header file with a prefixDEV_STATE_ (see also example).

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uchar08 *pStatus – pointer to byte where generic device status is encoded
  • uint16 uiPDOutBufSize – size of process data output bufferucpPDOutBuf

Output Parameters:

  • uchar08 *ucpPDOutBuf – pointer to buffer to return process data output
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

Actual data bytes number (process data output size) written toucpPDOutBuf or negative error number.

Example:

dev_StatusT status;
dev_StateT state;
uchar08 validity;
uchar08 pdOut[32];
dev_GetStatus(iPortNo, (uchar08*)&status, pdOut, 32, cpErrMsg));
state = (dev_StateT)(status.State); // DEV_STATE_INACTIVE, DEV_STATE_SIO, DEV_STATE_STARTUP, DEV_STATE_PREOPERATE, DEV_STATE_OPERATE
validity = status.PDInInvalid; // 0 – valid, 1 - invalid
 

dev_SetPDIn (set process data input and its validity)

Function:

int16 dev_SetPDIn(uint16 uiPortNo, uchar08 *ucpPDInBuf, uint16 uiBytesCount, boolean bValidity, char08 *cpErrMsg);

Description:

You can set current process data input to send to master in IO-Link operate state using dev_SetPDIn function with process data input buffer to set, its size and validity flag as arguments.

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uchar08 *ucpPDInBuf – pointer to buffer with process data input to set
  • uint16 uiBytesCount – data bytes number in process data input buffer “ucpPDInBuf” to set
  • boolean bValidity – process data input validity to set (TRUE – valid,FALSE - invalid)

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

uchar08 pdIn[32];
uchar08 pdInSize = 2;
boolean validity = TRUE; // (TRUE – valid, FALSE - invalid)
// fill “pdIn” buffer with data to set …
dev_SetPDIn(iPortNo, pdIn, pdInSize, validity, cpErrMsg);
 

dev_SendEvent (send IO-Link event to master)

Function:

int16 dev_SendEvent(uint16  uiPortNo, uchar08 ucQualifier, uint16  uiCode, char08  *cpErrMsg);

Description:

To send an IO-Link event to master in preoperate or operate state use dev_SendEvent function with the event qualifier byte and code as arguments. The event qualifier byte must be encoded according to IO-link specification with the event instance, source, type and mode. It can be constructed using a variable of type EventQualifierT and corresponding enumerations from iqi_dev.h with prefixes EVENT_INSTANCE_,EVENT_SOURCE_, EVENT_TYPE_ and EVENT_MODE_ (see example andIO-Link event qualifier).

Input Parameters:

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from dev_Connect or dev_EthernetConnect functions
  • uchar08 ucQualifier – qualifier byte of event to send with encoded event attributes according to IO-Link specification
  • uint16 uiCode – code of event to send

Output Parameters:

  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value:

ERR_NONE or negative error number.

Example:

EventQualifierT eventQualifier;
eventQualifier.Byte = 0;
eventQualifier.Fields.Instance = EVENT_INSTANCE_APPL;
eventQualifier.Fields.Source = EVENT_SOURCE_REMOTE;
eventQualifier.Fields.Type = EVENT_TYPE_NOTIFICATION;
eventQualifier.Fields.Mode = EVENT_MODE_SINGLE_SHOT;
uiEventCode = 0x1234;
dev_SendEvent(iPortNo, eventQualifier.Byte, uiEventCode, cpErrMsg);