Master mode

mst_Connect (connect to iqInterface over comport/USB in master mode)

Function

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

Description

To connect to iqInterface over comport or USB in the master mode call mst_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 ucFromPortNo – (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 = mst_Connect(ucPortNoStart, ucPortNoFinish, cpErrMsg);
 

mst_EthernetConnect (connect to iqInterface over Ethernet (tcp/ip) in master mode)

Function

int16 mst_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 master mode call mst_EthernetConnectwith the IP/port variable and send/receive timeout in milliseconds as arguments instead of using mst_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 mst_Connect).

Example

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

mst_Disconnect (disconnect iqInterface in master mode)

Function

int16 mst_Disconnect(uint16 uiPortNo, char08 *cpErrMsg);

Description

To disconnect iqInterface (free OS resources) call mst_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

mst_Disconnect(iPortNo, cpErrMsg); 

mst_GetGadgetID (get the master id)

Function

int16 mst_GetGadgetID(uint16 uiPortNo, uchar08 *ucpGadgetID, char08 *cpErrMsg);

Description

Function return Gadget ID for a connected device

Input Parameters

Output parameters

  • uchar08 *ucpGadgetID – pointer to one unsigned byte master id

Possible values: 0x01 - iqInterface, 0x02 - iqLink

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

Return value

ERR_NONE or negative error number.

Example

uchar08 id;
mst_GetGadgetID(iPortNo, &id, cpErrMsg);

mst_GetConfig and mst_SetConfig (get/set master mode configuration)

Function

int16 mst_GetConfig(uint16 uiPortNo, mst_ConfigT *pConfig, char08 *cpErrMsg);
int16 mst_SetConfig(uint16 uiPortNo, mst_ConfigT *pConfig, char08 *cpErrMsg);

Description

You can load the master configuration in a variable of type mst_ConfigT, manipulate it and save it again to iqInterface before starting an IO-Link communication using mst_GetConfig and mst_SetConfig functions.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • mst_ConfigT *pConfig – pointer to variable of type mst_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.

Example

mst_ConfigT config;
mst_GetConfig(iPortNo, &config, cpErrMsg);
// manipulate config …
mst_SetConfig(iPortNo, &config, cpErrMsg);
 

mst_ConfigT (master mode configuration data type)

Description

This structure holds the configuration parameters of iqInterface master mode. It is used to get or set them in mst_GetConfig and mst_SetConfig functions.

Fields

  • uint16 stackVersion (readonly) – 2 number version of iqStack master in connected iqInterface firmware (X.X: MSB – high number, LSB – low number)
  • IOLBaudrateT realBaudrate (readonly) – baudrate of current or last successful IO-Link communication, can be IOL_BAUDRATE_COM1 (4,8 kbit/s), IOL_BAUDRATE_COM2 (38,4 kbit/s) orIOL_BAUDRATE_COM3 (230,4 kbit/s)
  • uint16 cycleTimeOperate – IO-Link master cycle time in milliseconds in operate state (see Master cycle time)
  • uint16 restOfCycleTimeOperate – idle period of IO-Link master cycle time in milliseconds in operate state (see Master cycle time)

The following parameters manage device checking during the startup according to the state machine of Master System Manager in the IO-Link specification. The configured device IDvendor ID and serial number (index 0x0015, subindex 0x00) are compared with these parameters in connected IO-Link device. They are checked depending on the setting of theinspection level.

  • mst_InspectionLevelT inspectionLevel – inspection level, can beMST_IL_NO_CHECK (check only revision ID), MST_IL_TYPE_COMP(check also device and vendor ID) or MST_IL_IDENTICAL (check also serial number)
  • IOLRevisionIDT revisionID – configured IO-Link revision ID, can beIOL_REV_ID_V1_0 (v1.0) or IOL_REV_ID_V1_1 (v1.1)

Important

iqInterface cannot emulate legacy v1.0 master. The parameterrevisionID can be used as a configured revision ID. It is always compared with the revision ID of connected IO-Link device during the startup.

  • uint16 deviceVendorID – configured vendor ID
  • ulong32 deviceID – configured device ID
  • uchar08 deviceSerialNumber[MST_DEV_SER_NUM_MAX_LEN + 1] – configured device serial number
  • uchar08 deviceSerialNumberLen – length of deviceSerialNumber

The following parameters manage activation state of data storage and its upload/download during the next startup in master mode.

  • mst_DSActivStateT dsActivState – activation state of data storage, can be MST_DS_ACTIV_STATE_ENABLED,MST_DS_ACTIV_STATE_DISABLED orMST_DS_ACTIV_STATE_CLEARED (contains is cleared and data storage is enabled)
  • boolean dsUploadEnable – TRUE – upload is enabled, FALSE - upload is disabled
  • boolean dsDownloadEnable – TRUE – download is enabled, FALSE - download is disabled
 

mst_SetOperatingMode (change IO-Link operating mode)

Function

int16 mst_SetOperatingMode(uint16 uiPortNo, uchar08 ucOperMode, uchar08 ucStateToWait, uchar08 *ucpState, char08 *cpErrMsg);

Description

After configuring the master mode you can change IO-Link operation mode to preoperate, operate or auto (see also Change IO-Link operation mode) using mst_SetOperatingMode function. You should give it as arguments: an operation mode, communication state to wait for (normally corresponds to mode) and pointer to a variable where actually achieved state will be saved. In iqi_mst.h you can find all possible modes with prefixMST_OPERATING_MODE_ you can switch to and states modes with prefixMST_STATE_.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uchar08 ucOperMode – IO-Link operating mode, can beMST_OPERATING_MODE_INACTIVE,MST_OPERATING_MODE_AUTO,MST_OPERATING_MODE_PREOPERATE orMST_OPERATING_MODE_OPERATE
  • uchar08 ucStateToWait – state to wait, can be MST_STATE_INACTIVE,MST_STATE_CHK_FAULTMST_STATE_PREOPERATE orMST_STATE_OPERATE

Output Parameters

  • uchar08 *ucpState – pointer to variable where to return actually achieved state, which value can be MST_STATE_INACTIVE,MST_STATE_CHK_FAULTMST_STATE_PREOPERATE orMST_STATE_OPERATE
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value

ERR_NONE or negative error number.

Example

mst_StateT state;
uchar08 ucState;
mst_SetOperatingMode(iPortNo, MST_OPERATING_MODE_OPERATE, MST_STATE_OPERATE, &ucState, cpErrMsg);
state = (mst_StateT)ucState;

To deactivate the IO-Link communication switch to the inactive mode using mst_SetOperatingMode function (send a fallback command to IO-Link device)

mst_SetOperatingMode(iPortNo, MST_OPERATING_MODE_INACTIVE, MST_STATE_INACTIVE, &ucState, cpErrMsg);
 

mst_PowerControl (IO-Link device power supply control)

Function

int16 mst_PowerControl(uint16 uiPortNo, uchar08 ucSwitch, char08 *cpErrMsg);

Description

Connected IO-Link device power supply control.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uchar08 ucSwitch – on/off power supply switch flag (0 - off / disable, 1 - on / enable)

Output Parameters

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

Return value

ERR_NONE or negative error number.

Example

// switch off power supply
mst_PowerControl(iPortNo, 0 /* off */, cpErrMsg);
// switch on power supply
mst_PowerControl(iPortNo, 1 /* on */, cpErrMsg);

mst_GetStatus (get status of iqInterface and PD input in master mode)

Function

int16 mst_GetStatus(uint16 uiPortNo, uchar08 *pStatus, uchar08 *ucpPDInBuf, uint16 uiPDInBufSize, char08 *cpErrMsg);

Description

You can read master status with a current IO-Link state, process data input from IO-Link device and its validity using mst_GetStatus function with a pointer to master status variable and process data input buffer. You can use a bit field of type mst_StatusT (see example) to extract current IO-Link communication state, process data input validity (0 – valid, 1 - invalid) and whether a new event has come from device (0 – no events, 1 – new event). If a new event has come you can read it using mst_ReadEvent function.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uint16 uiPDInBufSize – size of process data input buffer ucpPDInBuf(32 bytes length is recommended)

Output Parameters

  • uchar08 *pStatus – pointer to variable where to return a status byte, it can be decoded using mst_StatusT data type (see example)
  • uchar08 *ucpPDInBuf – process data input sent by IO-Link device
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value

Actual size of process data input written to ucpPDInBuf or negative error number.

Example

uchar08 pdIn[32];
mst_StatusT status;
uchar08 pdInValidity;
uchar08 isNewEvent;
mst_GetStatus(iPortNo, (uchar08*)(&status), pdIn, 32, cpErrMsg);
state = (mst_StateT)(status.State);
pdInValidity = status.PDInInvalid; // 0 – valid, 1 – invalid
isNewEvent = status.Event; // 0 – no events, 1 – new event
 

mst_SetPDValue: (set process data output)

Function

int16 mst_SetPDValue(uint16 uiPortNo, uchar08 *ucpPDOutBuf, uint16 uiBytesCount, char08 *cpErrMsg);

Description

You can set process data output which will be transferred to IO-Link device using mst_SetPDValue function with a pointer to process data output buffer.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uchar08 *ucpPDOutBuf – process data output buffer to set
  • uint16 uiBytesCount – byte size of process data output buffer to setucpPDOutBuf

Output Parameters

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

Return value

ERR_NONE or negative error number.

Example

uchar08 pdOut[32];
// set pdOut …
mst_SetPDValue(iPortNo, pdOut, 2, cpErrMsg);
 

mst_SetPDValidity (set process data output validity)

Function

int16 mst_SetPDValidity(uint16 uiPortNo, boolean bValidity, char08 *cpErrMsg);

Description

To set validity of current process data output use “mst_SetPDValidity” function.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • boolean bValidity – process data output validity (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

mst_SetPDValidity(iPortNo, TRUE, cpErrMsg);
 

mst_WaitODRsp (Wait for ISDU response)

Function

int16 mst_WaitODRsp(uint16 uiPortNo, char08 *cpErrMsg);

Description

This function waits ISDU response from device with timeoutMST_OD_TIMEOUT after sending ISDU request with mst_StartReadOD or mst_StartWriteOD. The function is used to make asynchronous ISDU read/write requests (see example). The response can be read by mst_GetReadODRsp and mst_GetWriteODRsp.

Input Parameters

Output Parameters

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

Return value

ERR_NONE or negative error number (ERR_INTERNAL – wait timeoutMST_WRITE_OD_TIMEOUT, see code in uipISDUErr)

Example

int16 error_or_size;
// asynchronous ISDU read request example
uchar08 ucpBuf[255]; // buffer with request result
uint16 index = 0x0015;
uchar08 subindex = 0x00;
uint16 uiISDUErr = 0; // possible ISDU error
mst_StartReadOD(iPortNo, index, subindex, cpErrMsg);
if (mst_WaitODRsp(uiPortNo, cpErrMsg) == ERR_NONE)
{
    error_or_size = mst_GetReadODRsp(iPortNo, ucpBuf, 255, &uiISDUErr, cpErrMsg)
    if (error_or_size >= ERR_NONE)
    {
        // reponse ok, process 'error_or_size' number of data bytes in ucpBuf
    }
    else
    {
        // ISDU error in uiISDUErr
    }
}
else
{
    // ISDU response waiting timeout
}
// asynchronous ISDU write request example
uchar08 ucpBuf[255]; // buffer to write
uchar08 lengthToWrite = 5; // write 5 first bytes of *ucpBuf* buffer
uint16 index = 0x0015;
uchar08 subindex = 0x00;
uint16 uiISDUErr = 0; // possible ISDU error
// fill *ucpBuf* buffer with data bytes to write …
mst_StartWriteOD(iPortNo, index, subindex, ucpBuf, lengthToWrite, cpErrMsg);
if (mst_WaitODRsp(uiPortNo, cpErrMsg) == ERR_NONE)
{
    error_or_size = mst_GetWriteODRsp(iPortNo, &uiISDUErr, cpErrMsg)
    if (error_or_size >= ERR_NONE)
    {
        // reponse ok
    }
    else
    {
        // ISDU error in uiISDUErr
    }
}
else
{
    // ISDU response waiting timeout
}
 

mst_StartReadOD (Start asynchronous ISDU read request)

Function

int16 mst_StartReadOD(uint16 uiPortNo, uint16 uiIndex, uchar08 ucSubindex, char08 *cpErrMsg);

Description

Starts asynchronous ISDU read request. Device response can be waited for by mst_WaitODRsp and read by mst_GetReadODRsp.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uint16 uiIndex – ISDU index to read
  • uchar08 ucSubindex – ISDU subindex to read

Output Parameters

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

Return value

ERR_NONE or negative error number

Example

See example of mst_WaitODRsp.

 

mst_GetReadODRsp (Get ISDU read response)

Function

int16 mst_GetReadODRsp(uint16 uiPortNo, uchar08 *ucpBuf, uint16 uiBufSize, uint16* uipISDUErr, char08 *cpErrMsg);

Description

Reads ISDU read response from device started by mst_StartReadOD and waited by mst_WaitODRsp.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uint16 uiBufSize – size of On-request data buffer ucpBuf

Output Parameters

  • char08 *ucpBuf – pointer to On-request data buffer to return read ISDU data
  • uint16 *uipISDUErr – pointer to variable to return possible ISDU error code
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value

Negative error number (ERR_OPERATION – ISDU error, see code inuipISDUErr) or size of response data in buffer ucpBuf

Example

See example of mst_WaitODRsp.

 

mst_ReadOD (ISDU read request)

Function

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

Description

To make ISDU read request use “mst_ReadOD” function with an ISDU index, subindex, response data buffer and a pointer to possible ISDU error. The function is a short hand for call sequence of ISDU read described in example of mst_WaitODRsp.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uint16 uiIndex – ISDU index to read
  • uchar08 ucSubindex – ISDU subindex to read
  • uint16 uiBufSize – size of On-request data buffer ucpBuf

Output Parameters

  • char08 *ucpBuf – pointer to On-request data buffer to return read ISDU data
  • uint16 *uipISDUErr – pointer to variable to return possible ISDU error code
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value

Negative error number (ERR_OPERATION – ISDU error, see code inuipISDUErr) or size of response data in buffer ucpBuf

Example

uchar08 ucpBuf[255]; // buffer with request result
uint16 index = 0x0015;
uchar08 subindex = 0x00;
uint16 uiISDUErr = 0; // possible ISDU error
mst_ReadOD(iPortNo, index, subindex, ucpBuf, 255, &uiISDUErr, cpErrMsg);
 

mst_StartWriteOD (Start asynchronous ISDU Write request)

Function

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

Description

Starts asynchronous ISDU Write request. Device response can be waited for by mst_WaitODRsp and read by mst_GetWriteODRsp.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uint16 uiIndex – ISDU index to Write
  • uchar08 ucSubindex – ISDU subindex to Write
  • char08 *ucpBuf – pointer to On-request data buffer to write
  • uint16 uiBytesCount – bytes number in On-request data buffer ucpBufto write

Output Parameters

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

Return value

ERR_NONE or negative error number

Example

See example of mst_WaitODRsp.

 

mst_GetWriteODRsp (Get ISDU Write response)

Function

int16 mst_GetWriteODRsp(uint16 uiPortNo, uint16* uipISDUErr, char08 *cpErrMsg);

Description

Reads ISDU Write response from device started by mst_StartWriteOD and waited by mst_WaitODRsp.

Input Parameters

Output Parameters

  • uint16 *uipISDUErr – pointer to variable to return possible ISDU error code
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value

ERR_NONE or negative error number (ERR_OPERATION – ISDU error, see code in uipISDUErr)

Example

See example of mst_WaitODRsp.

 

mst_WriteOD (ISDU write request)

Function

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

Description

To make ISDU write request use mst_WriteOD function with an ISDU index, subindex, data buffer to write, its length and a pointer to possible ISDU error. The function is a short hand for call sequence of ISDU write described in example of mst_WaitODRsp.

Input Parameters

  • uchar08 uiPortNo – (virtual) comport number to disconnect obtained previously from mst_Connect or mst_EthernetConnect functions
  • uint16 uiIndex – ISDU index to write
  • uchar08 ucSubindex – ISDU subindex to write
  • char08 *ucpBuf – pointer to On-request data buffer to write
  • uint16 uiBytesCount – bytes number in On-request data buffer ucpBufto write

Output Parameters

  • uint16 *uipISDUErr – pointer to variable to return possible ISDU error code
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value

ERR_NONE or negative error number (ERR_OPERATION – ISDU error, see code in uipISDUErr)

Example

uchar08 ucpBuf[255]; // buffer to write
uchar08 lengthToWrite = 5; // write 5 first bytes of *ucpBuf* buffer
uint16 index = 0x0015;
uchar08 subindex = 0x00;
uint16 uiISDUErr = 0; // possible ISDU error
// fill *ucpBuf* buffer with data bytes to write …
mst_WriteOD(iPortNo, index, subindex, ucpBuf, lengthToWrite, &uiISDUErr, cpErrMsg);
 

mst_ReadEvent (receive an IO-Link event from device)

Function

int16 mst_ReadEvent(uint16 uiPortNo, uchar08 *ucpQualifier, uint16 *uipCode, char08 *cpErrMsg);

Description

If you await an event from IO-Link device you can receive it using mst_ReadEvent function with a pointer to a qualifier and a code of received event. A Fields attribute of variable of type EventQualifierT contains event instance, source, type and mode (see example and IO-Link event qualifier). You can also receive IO-Link communication lost event (code 0xFF22) this way in case of IO-Link communication interruption. To monitor whether a new event has come from device use mst_GetStatus function.

Input Parameters

Output Parameters

  • uchar08 *ucpQualifier – pointer to byte with received event qualifier where event instance, source, type and mode are encoded according to IO-Link specification, variable of type EventQualifierT can be used to decode these event attributes (see example)
  • uchar08 * uipCode – pointer to received event code
  • char08 *cpErrMsg – pointer to buffer to return error message (minimum 256 bytes)

Return value

ERR_NONE or negative error number (ERR_INTERNAL is returned if timeout occurred and no event was received)

Example

EventQualifierT eventQualifier;
uchar08 ucEventQualifier;
uint16 uiEventCode;
mst_ReadEvent(iPortNo, &ucEventQualifier, &uiEventCode, cpErrMsg));
eventQualifier.Byte = ucEventQualifier;

// eventQualifier.Instance: received event instance, can be
// EVENT_INSTANCE_PL – from device physical layer
// EVENT_INSTANCE_DL – from device data link layer
// EVENT_INSTANCE_AL – from device application layer
// EVENT_INSTANCE_APPL – from device application

// eventQualifier.Source: received event source, can be
// EVENT_SOURCE_REMOTE – from device
// EVENT_SOURCE_LOCAL – from master

// eventQualifier.Type: received event type, can be
// EVENT_TYPE_NOTIFICATION
// EVENT_TYPE_WARNING
// EVENT_TYPE_ERROR

// eventQualifier.Mode: received event mode, can be
// EVENT_MODE_SINGLE_SHOT – appears only once
// EVENT_MODE_APPEARS – event appears to disappear later
// EVENT_MODE_DISAPPEARS - event disappears