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

Output parameters

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

Output parameters

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

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

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

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

Output parameters

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

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 ID, vendor 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.

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.

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

 

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

Output Parameters

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

Output Parameters

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

Output Parameters

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

Output Parameters

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

Output Parameters

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

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

Output Parameters

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

Output Parameters

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

Output Parameters

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

Output Parameters

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

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

Output Parameters

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

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