- Created by Peter Schöne (Unlicensed), last modified by Christopher Telemann on Mar 25, 2021
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 6 Next »
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 ( |
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 ( |
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 ( |
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 | temporary flag (temporary = true) |
- No labels