Application Callbacks

To use the full potential of PROFINET the stack allows you to interact at several stages of the protocol. For example you can withhold the sending of the application ready signal to the PLC or handle record data reads and writes to specific slots.

The first thing to use the callback system is to provide a callback function that the stack can call every time it wants to communicate with the application. The callback function must have the following prototype:

    GOAL_STATUS_T appl_pnioCb(
        GOAL_PNIO_T *pHdlPnio,          /**< PROFINET handle */
        GOAL_PNIO_CB_ID_T id,           /**< callback id */
        GOAL_PNIO_CB_DATA_T *pCb        /**< callback parameters */
    );

It is registered with the call to goal_pnioNew which takes the pointer to the callback function as second parameter.

res = goal_pnioNew(&pPnio, APPL_PNIO_ID, appl_pnioCb);

Now every time the appl_pnioCb is called, the GOAL_PNIO_CB_ID_T value contains the reason of the call. The GOAL_PNIO_CB_DATA_T structure contains an array of multiple unions were each array element has a special meaning depending on the GOAL_PNIO_CB_ID_T value.

The following subsections will provide you with the details on the available callback ids.

GOAL_PNIO_CB_ID_ALARM_ACK_TIMEOUT - Timeout waiting for Alarm ACK

Indicate that a timeout occurred in APMS while waiting for an alarm acknowledge.

Parameter	Description
pCb->data[0].idAr	application relation id
pCb->data[1].u16	timed out alarm sequence number

GOAL_PNIO_CB_ID_ALARM_NOTIFY_ACK - Alarm notification ACK received

Indicates that an alarm notification ACK was received.

Parameter	Description
pCb->data[0].idAr	application relation id
pCb->data[1].u16	alarm priority (low, high)
pCb->data[2].pAlarmNotifyAck	GOAL_PNIO_ALARM_NOTIFY_ACK_T structure pointer

GOAL_PNIO_CB_ID_ALARM_NOTIFY - Alarm notification received

Indicates that an alarm notification was received. If the callback isn't handled or GOAL_OK is returned the PROFINET stack will automatically acknowledge the received alarm notification.

Parameter	Description
pCb->data[0].idAr	application relation id
pCb->data[1].u16	alarm priority (low, high)
pCb->data[2].pAlarmNotify	GOAL_PNIO_ALARM_NOTIFY_T structure pointer
pCb->data[3].u32	user data length
pCb->data[4].pCu8	user data pointer

GOAL_PNIO_CB_ID_APPL_READY - Application Ready Response Received

Indicate that an application ready response was received. The return value has to be GOAL_OK.

Parameter	Description
pCb->data[0].idAr	application relation id

GOAL_PNIO_CB_ID_BLINK - Blink Request

Indicates that a DCP signal request was received and fills the callback data with the necessary information.

pCb->data[0].stateDcpBlink tells the application the initial signal request (START), the correct time to toggle the signal (TOGGLE) and when the signal phase is over (FINISH). This information can be used if the application wants to fully represent the signal by itself.

The second possibility is to use the cb->data[1].stateDcpLight data which contains either GOAL_PNIO_DCP_LIGHT_OFF or GOAL_PNIO_DCP_LIGHT_ON which can be used to handover the signal indicator directly to a LED or blink function.

If variant 1 or 2 is used than the callback has to return GOAL_OK_SUPPORTED otherwise the stack handles the blinking by itself by calling goal_targetSetLeds with the GOAL_PNIO_LED_SIGNAL define. For stack internal handling the implementation of goal_targetGetLeds and goal_targetSetLeds is mandatory.

Parameter	Description
pCb->data[0].stateDcpBlink	DCP blink state (start, toggle, finish)
pCb->data[1].stateDcpLight	DCP light state (on, off)

Return Values	Description
GOAL_OK	signal handled stack internal
GOAL_OK_SUPPORTED	application handles signal

    case GOAL_PNIO_CB_ID_BLINK:

#if FIRST_SCENARIO
        /**************************************/
        /* first scenario: act on blink state */
        /**************************************/
        switch (pCb->data[0].stateDcpBlink) {

            case GOAL_PNIO_DCP_BLINK_START:
                /* start blinking */
                break;

            case GOAL_PNIO_DCP_BLINK_TOGGLE:
                /* toggle signal */
                break;

            case GOAL_PNIO_DCP_BLINK_FINISH:
                /* switch signal off */
                break;
        }

        res = GOAL_OK_SUPPORTED;
        break;
#endif /* FIRST_SCENARIO */

#if SECOND_SCENARIO
        /***************************************/
        /* second scenario: act on light state */
        /***************************************/
        vendorBlinkFunction(pCb->data[1].stateDcpLight);
        res = GOAL_OK_SUPPORTED;
        break;
#endif /* SECOND_SCENARIO */

#if THIRD_SCENARIO
        /**************************************************************/
        /* third scenario: do nothing / PROFINET stack handles signal */
        /**************************************************************/
#endif /* THIRD_SCENARIO */

GOAL_PNIO_CB_ID_CONNECT_FINISH - Connect Request Done

Indicates that a connect request was fully processed and allows the application to cancel it by setting the error status and return a value that is not GOAL_OK.

Parameter	Description
pCb->data[0].idAr	application relation id
pCb->data[1].pStatus	pointer to PROFINET status

GOAL_PNIO_CB_ID_CONNECT_REQUEST - Connect Request

Indicates that the processing of a connect request has been started. The parameter pointer is set to NULL.

GOAL_PNIO_CB_ID_CONNECT_REQUEST_EXP_START - Expected Submodule Block Start

Indicates that an expected submodule block starts. This can be used to unplug all modules before the request callback for each module comes in.

Parameter	Description
pCb->data[0].idAr	application relation id

GOAL_PNIO_CB_ID_END_OF_PARAM - Param End Received

Indicates that the parameter end information was received.

Parameter	Description
pCb->data[0].idAr	application relation id

GOAL_PNIO_CB_ID_END_OF_PARAM_PLUG - Plug Param End Received

Indicates the the plug parameter end information was received.

Parameter	Description
pCb->data[0].idAr	application relation id
pCb->data[1].u16	plug handle

GOAL_PNIO_CB_ID_EXP_SUBMOD - Expected Submodule

Indicates an expected submodule which can be plugged immediately.

Parameter	Description
pCb->data[0].idAr	application relation id
pCb->data[1].u32	API
pCb->data[2].u16	slot number
pCb->data[3].u16	subslot number
pCb->data[4].u32	module ident number
pCb->data[5].u32	submodule ident number
pCb->data[6].valBool	module flag (true = module, false = submodule)

GOAL_PNIO_CB_ID_FACTORY_RESET - Factory Reset

Indicates a factory reset.

The parameter pointer is set to NULL.

GOAL_PNIO_CB_ID_IO_DATA_TIMEOUT - Cyclic Timeout

Indicates that an output endpoint timed out.

GOAL_PNIO_CB_ID_NET_IP_SET - IP Configuration Update

Indicate that the IP configuration was updated. The internal change flag indicates if the change was triggered by PROFINET DCP (PN_TRUE) or by an external caller like DHCP (PN_FALSE).

Parameter	Description
pCb->data[0].u32	ip address
pCb->data[1].u32	netmask
pCb->data[2].u32	gateway
pCb->data[3].valBool	temporary setting flag
pCb->data[4].valBool	internal update flag

GOAL_PNIO_CB_ID_NEW_AR - New Application Relation

Indicates a new application relation. A return value different from GOAL_OK drops the AR and replies with an error.

Parameter	Description
pCb->data[0].idAr	application relation id

GOAL_PNIO_CB_ID_NEW_IO_DATA - New IO Data

Indicates reception of new IO data.

Parameter	Description
pCb->data[0].u16	cyclic frame id
pCb->data[1].u16	data length
pCb->data[2].pCu8	data pointer

GOAL_PNIO_CB_ID_PLUG_READY - Plug Ready Response Received

Indicates that a plug ready response was received.

Parameter	Description
pCb->data[0].idAr	application relation id

GOAL_PNIO_CB_ID_READ_RECORD - Read Record Data

Indicates that record data that couldn't be handled by the stack itself should be read. Before this callback is called, the stack checks if the API, slot and subslot combination is valid. If the function returns GOAL_OK the request will be denied with "invalid index". To handle the request the callback needs to return GOAL_OK_SUPPORTED. It can either respond directly or later by calling goal_pnioRecReadFinish. Also the now PROFINET status can be set through goal_pnioRecReadFinish. If the response isn't GOAL_OK or GOAL_OK_SUPPORTED the stack will automatically respond with application read error. The parameter "sequence number" is used later when the response is send to detect if the request has expired.

Parameter	Description
pCb->data[0].pStatus	unused (pointer to PROFINET status)
pCb->data[1].idAr	application relation id
pCb->data[2].u32	API
pCb->data[3].u16	slot
pCb->data[4].u16	subslot
pCb->data[5].u16	record index
pCb->data[6].pU8	unused (pointer to store record data)
pCb->data[7].u32	maximum record read data length
pCb->data[8].i32	record busy index for delaying
pCb->data[9].u32	sequence number

GOAL_PNIO_CB_ID_RELEASE_AR - Release Application Relation

Indicates that an application relation was released.

Parameter	Description
pCb->data[0].idAr	application relation id

GOAL_PNIO_CB_ID_RESET_TO_FACTORY - Reset To Factory

Indicates a reset to factory request. If there is a separate request handling outside of the stack the application must return GOAL_OK_SUPPORTED. If the application doesn't return from the callback with GOAL_OK or GOAL_OK_SUPPORTED the DCP error "0x04 suboption not set" is sent back to the DCP set request sender.

Parameter	Description
pCb->data[0].u16	reset to factory action

GOAL_PNIO_CB_ID_STATION_NAME - Station Name Changed

Indicates a station name change. If the permanent flag is set to GOAL_TRUE, the station name is stored in NVS, otherwise the station name is only stored temporary and the NVS value is cleared.

Parameter	Description
pCb->data[0].pCu8	name of station
pCb->data[1].u32	name of station length
pCb->data[2].valBool	permanent flag

GOAL_PNIO_CB_ID_WRITE_RECORD - Write Record Data

Indicates that record data that couldn't be handled by the stack itself should be written. Before this callback is called, the stack checks if the API, slot and subslot combination is valid.

If the function returns GOAL_OK the request will be denied with "invalid index".

To handle the request the callback needs to return GOAL_OK_SUPPORTED. It can either respond directly or later by calling goal_pnioRecWriteFinish. Also the now PROFINET status can be set through goal_pnioRecWriteFinish.

If the response isn't GOAL_OK or GOAL_OK_SUPPORTED the stack will automatically respond with application read error.

The parameter "sequence number" is used later when the response is send to detect if the request has expired.

Parameter	Description
pCb->data[0].pStatus	unused (pointer to PROFINET status)
pCb->data[1].idAr	application relation id
pCb->data[2].u32	API
pCb->data[3].u16	slot
pCb->data[4].u16	subslot
pCb->data[5].u16	record index
pCb->data[6].pCu8	pointer to read record data from
pCb->data[7].u32	record data length
pCb->data[8].i32	record busy index for delaying
pCb->data[9].valBool	subslot locked status flag
pCb->data[10].u32	sequence numbers

GOAL_PNIO_CB_ID_INIT - Stack initialized

Indicates that the PROFINET stack is fully initialized. The parameter pointer is set to NULL. At this point it is safe to create the device configuration.

GOAL_PNIO_CB_ID_LLDP_UPDATE - LLDP Update

Signalizes that the device on the partner port changed.

Parameter	Description
pCb->data[0].u32	GOAL Ethernet Port Id

GOAL_PNIO_CB_ID_CONN_REQ_EXP_FINISH - Connect Request Expected Submodule Block Finish

This callback is called after the Expected Submodule Block in the Connect Request has been parsed.

Parameter	Description
pCb->data[0].idAr	application relation id

GOAL_PNIO_CB_ID_STATION_NAME_VERIFY - DCP Station Name Verification

Let the application verify a DCP Station Name Set Request.

If the function returns a GOAL error status the set request will be denied.

Parameter	Description
pCb->data[0].pCu8	pointer to station name (unterminated)
pCb->data[1].u32	length of station name
pCb->data[2].valBool	permanent flag (permanent = true)

GOAL_PNIO_CB_ID_NET_IP_SET_VERIFY - DCP IP Configuration Verification

Let the application verify a DCP IP Configuration Set Request.

If the function returns a GOAL error status the set request will be denied.

Parameter	Description
pCb->data[0].u32	IP address
pCb->data[1].u32	netmask
pCb->data[2].u32	gateway
pCb->data[3].valBool	temporary flag (temporary = true)

1 Application Callbacks