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 

/**< 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

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_

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 main_callback(
        GOAL_PNIO_T *pPnio,             /**< 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_pnioInit which takes the pointer to
the callback function as second parameter.

    res = goal\_pnioInit(&pPnio, main_callback);

Now every time the main_callback 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

cb->data[0].idAr

application relation id

cb->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

cb->data[0].idAr

application relation id

cb->data[1].u16

alarm priority (low, high)

cb->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

cb->data[0].idAr

application relation id

cb->data[1].u16

alarm priority (low, high)

cb->data[2].pAlarmNotify

GOAL_PNIO_ALARM_NOTIFY_T structure pointer

cb->data[3].u32

user data length

cb->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

cb->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.

cb->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

cb->data[0].stateDcpBlink

DCP blink state (start, toggle, finish)

cb->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 (cb->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(cb->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

cb->data[0].idAr

application relation id

cb->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

cb->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

cb->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

cb->data[0].idAr

application relation id

cb->data[1].u16

plug handle

GOAL_PNIO_CB_ID_EXP_SUBMOD - Expected Submodule

Indicates an expected submodule which can be plugged immediately.

Parameter

Description

cb->data[0].idAr

application relation id

cb->data[1].u32

API

cb->data[2].u16

slot number

cb->data[3].u16

subslot number

cb->data[4].u32

module ident number

cb->data[5].u32

submodule ident number

cb->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

cb->data[0].u32

ip address

cb->data[1].u32

netmask

cb->data[2].u32

gateway

cb->data[3].valBool

temporary setting flag

cb->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

cb->data[0].idAr

application relation id

GOAL_PNIO_CB_ID_NEW_IO_DATA - New IO Data

Indicates reception of new IO data.

Parameter

Description

cb->data[0].u16

cyclic frame id

cb->data[1].u16

data length

cb->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

cb->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

cb->data[0].pStatus

unused (pointer to PROFINET status)

cb->data[1].idAr

application relation id

cb->data[2].u32

API

cb->data[3].u16

slot

cb->data[4].u16

subslot

cb->data[5].u16

record index

cb->data[6].pU8

unused (pointer to store record data)

cb->data[7].u32

maximum record read data length

cb->data[8].i32

record busy index for delaying

cb->data[9].u32

sequence number

GOAL_PNIO_CB_ID_RELEASE_AR - Release Application Relation

Indicates that an application relation was released.

Parameter

Description

cb->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

cb->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

cb->data[0].pCu8

name of station

cb->data[1].u32

name of station length

cb->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

cb->data[0].pStatus

unused (pointer to PROFINET status)

cb->data[1].idAr

application relation id

cb->data[2].u32

API

cb->data[3].u16

slot

cb->data[4].u16

subslot

cb->data[5].u16

record index

cb->data[6].pCu8

pointer to read record data from

cb->data[7].u32

record data length

cb->data[8].i32

record busy index for delaying

cb->data[9].valBool

subslot locked status flag

cb->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

cb->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

cb->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

cb->data[0].pCu8

pointer to station name (unterminated)

cb->data[1].u32

length of station name

cb->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

cb->data[0].u32

IP address

cb->data[1].u32

netmask

cb->data[2].u32

gateway

cb->data[3].valBool

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.

GOAL_PNIO_CB_ID_ALARM_NOTIFY_ACK - Alarm notification ACK received

Indicates that an alarm notification ACK was received.

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.

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.

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.

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.

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.

GOAL_PNIO_CB_ID_END_OF_PARAM - Param End Received

Indicates that the parameter end information was received.

GOAL_PNIO_CB_ID_END_OF_PARAM_PLUG - Plug Param End Received

Indicates the the plug parameter end information was received.

GOAL_PNIO_CB_ID_EXP_SUBMOD - Expected Submodule

Indicates an expected submodule which can be plugged immediately.

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).

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.

GOAL_PNIO_CB_ID_NEW_IO_DATA - New IO Data

Indicates reception of new IO data.

GOAL_PNIO_CB_ID_PLUG_READY - Plug Ready Response Received

Indicates that a plug ready response was received.

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.

GOAL_PNIO_CB_ID_RELEASE_AR - Release Application Relation

Indicates that an application relation was released.

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.

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.

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.

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.

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.

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.

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.