API documentation¶

Here is a brief overview given for some of the most important functions, structs etc in the public API for the p-net Profinet stack.

For detailed documentation, read the include/pnet_api.h header file. It also contains error code definitions etc.

You can also build the Doxygen documentation for all functions by following the instructions given on the page “Additional Linux Details”.

Study the sample_app to get more information on how to use the API.

General¶

All functions return either 0 (zero) for a successful call or -1 for an unsuccessful call.

Initialization and handling¶

pnet_t *pnet_init(const pnet_cfg_t *p_cfg)¶

Initialize the Profinet stack.

This function must be called to initialize the Profinet stack.

Parameters: p_cfg – In: Profinet configuration. These values are used at first startup and at factory reset.
Returns: a handle to the stack instance, or NULL if an error occurred.

int pnet_application_ready(pnet_t *net, uint32_t arep)¶

Application signals ready to exchange data.

Sends a CControl request to the IO-controller.

This function must be called after the application has received the pnet_state_ind() user callback with PNET_EVENT_PRMEND, in order for a connection to be established.

If this CControl request (“Application ready”) is sent (to the PLC) before the DControl response (“Param end”) is sent (to the PLC) there will be problems at startup.

If this function does not see all PPM data and IOPS areas are set (by the app) then it returns error and the application must try again - otherwise the startup will hang.

Triggers the pnet_state_ind() user callback with PNET_EVENT_APPLRDY.

Parameters

net – InOut: The p-net stack instance
arep – In: The AREP

Returns

0 if the operation succeeded. -1 if an error occurred.

void pnet_handle_periodic(pnet_t *net)¶

Execute all periodic functions within the ProfiNet stack.

This function shall be called periodically by the application. The period is specified by the tick_us parameter, part of pnet_cfg_t configuration. The period should match the expected I/O data rate to and from the device.

Parameters: net – InOut: The p-net stack instance

int pnet_get_ar_error_codes(pnet_t *net, uint32_t arep, uint16_t *p_err_cls, uint16_t *p_err_code)¶

Fetch error information from the AREP.

Parameters

net – InOut: The p-net stack instance
arep – In: The AREP.
p_err_cls – Out: The error class. See PNET_ERROR_CODE_1_*
p_err_code – Out: The error code. See PNET_ERROR_CODE_2_*

Returns

0 If the AREP is valid. -1 if the AREP is not valid.

int pnet_ar_abort(pnet_t *net, uint32_t arep)¶

Application requests abortion of the connection.

Parameters

net – InOut: The p-net stack instance
arep – In: The AREP

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_factory_reset(pnet_t *net)¶

Application requests factory reset of the device.

Use this for example when a local hardware switch is used to do a factory reset.

Also closes any open connections.

Parameters: net – InOut: The p-net stack instance
Returns: 0 if the operation succeeded. -1 if an error occurred.

void pnet_show(pnet_t *net, unsigned level)¶

Show information from the Profinet stack.

Parameters

net – InOut: The p-net stack instance
level 0x0020 0x0400 0x0200 0x0800 0x1000 0x1001 0x1002 0x1003 0x2000 0x4000 0x8000 Bit 15 1 1 1 1 1 1

– In: The amount of detail to show.

0x0010              | Show compile time options | Show CMDEV | Show logbook | Show diagnosis | Show all sessions. | Show all ARs. |     include IOCR. |     include data_descriptors. |     include IOCR and data_descriptors. | Show CFG information. | Show scheduler information. | Show I&M data. in the level parameter: 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 I&M Scheduler CMINA AR Sessions Logbook class="mi">1                    Diagnosis 1            CMDEV 1          Options 1    More IOCR info on AR 1  More IOCR info on AR

Plug and pull modules/submodules¶

int pnet_plug_module(pnet_t *net, uint32_t api, uint16_t slot, uint32_t module_ident)¶

Plug a module into a slot.

This function is used to plug a specific module into a specific slot.

This function may be called from the pnet_exp_module_ind() call-back function of the application.

Parameters

net – InOut: The p-net stack instance
api – In: The API identifier.
slot – In: The slot number.
module_ident – In: The module ident number.

Returns

0 if a module could be plugged into the slot. -1 if an error occurred.

int pnet_plug_submodule(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint32_t module_ident, uint32_t submodule_ident, pnet_submodule_dir_t direction, uint16_t length_input, uint16_t length_output)¶

Plug a sub-module into a sub-slot.

This function is used to plug a specific sub-module into a specific sub-slot.

This function may be called from the pnet_exp_submodule_ind call-back function of the application.

If a module has not been plugged into the designated slot then it will be plugged automatically by this function.

Parameters

net – InOut: The p-net stack instance
api – In: The API identifier.
slot – In: The slot number.
subslot – In: The sub-slot number.
module_ident – In: The module ident number.
submodule_ident – In: The sub-module ident number.
direction – In: The direction of data.
length_input – In: The size in bytes of the input data.
length_output – In: The size in bytes of the output data.

Returns

0 if the sub-module could be plugged into the sub-slot. -1 if an error occurred.

int pnet_pull_module(pnet_t *net, uint32_t api, uint16_t slot)¶

Pull a module from a slot.

This function may be used to unplug a module from a specific slot.

This function internally calls pnet_pull_submodule() on any plugged sub-modules before pulling the module itself.

Parameters

net – InOut: The p-net stack instance
api – In: The API identifier.
slot – In: The slot number.

Returns

0 if a module could be pulled from the slot. -1 if an error occurred.

int pnet_pull_submodule(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot)¶

Pull a sub-module from a sub-slot.

This function may be used to unplug a sub-module from a specific sub-slot.

Parameters

net – InOut: The p-net stack instance
api – In: The API identifier.
slot – In: The slot number.
subslot – In: The sub-slot number.

Returns

0 if the sub-module could be pulled from the sub-slot. -1 if an error occurred.

Periodic data¶

int pnet_input_set_data_and_iops(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, const uint8_t *p_data, uint16_t data_len, uint8_t iops)¶

Updates the IOPS and data of one sub-slot to send to the controller.

This function may be called to set new data and IOPS values of a sub-slot to send to the controller.

Parameters

net – InOut: The p-net stack instance
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
p_data – In: Data buffer.
data_len – In: Bytes in data buffer.
iops – In: The device provider status. See pnet_ioxs_values_t

Returns

0 if a sub-module data and IOPS was set. -1 if an error occurred.

int pnet_input_get_iocs(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint8_t *p_iocs)¶

Fetch the controller consumer status of one sub-slot.

This function may be called to retrieve the IOCS value of a sub-slot sent from the controller.

Parameters

net – InOut: The p-net stack instance
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
p_iocs – Out: The controller consumer status. See pnet_ioxs_values_t

Returns

0 if a sub-module IOCS was set. -1 if an error occurred.

int pnet_output_get_data_and_iops(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, bool *p_new_flag, uint8_t *p_data, uint16_t *p_data_len, uint8_t *p_iops)¶

Retrieve latest sub-slot data and IOPS received from the controller.

This function may be called to retrieve the latest data and IOPS values of a sub-slot sent from the controller.

If a valid new data (and IOPS) frame has arrived from the IO-controller since your last call to this function (regardless of the slot/subslot arguments) then the flag p_new_flag is set to true, else it is set to false. Note that this does not check whether the data content has changed from any previous frame.

Note that the latest data and IOPS values are copied to the application buffers regardless of the value of p_new_flag.

Parameters

net – InOut: The p-net stack instance
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
p_new_flag – Out: true if new data.
p_data – Out: The received data.
p_data_len – In: Size of receive buffer. Out: Received number of data bytes.
p_iops – Out: The controller provider status (IOPS). See pnet_ioxs_values_t

Returns

0 if a sub-module data and IOPS is retrieved. -1 if an error occurred.

int pnet_output_set_iocs(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint8_t iocs)¶

Set the device consumer status for one sub-slot.

This function is used to set the device consumer status (IOCS) of a specific sub-slot.

Parameters

net – InOut: The p-net stack instance
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
iocs – In: The device consumer status. See pnet_ioxs_values_t

Returns

0 if a sub-module IOCS was set. -1 if an error occurred.

int pnet_set_provider_state(pnet_t *net, bool run)¶

Implements the “Local set Provider State” primitive.

The application should call this function at least once during startup to set the provider status of frames sent to the controller.

The application may call this function at any time, e.g., to signal a temporary inability to produce new application data to the controller.

Its effect is similar to setting IOPS to PNET_IOXS_BAD for all sub-slots.

Parameters

net – InOut: The p-net stack instance
run – In: true to set state to “run”.

Returns

0 if the operation succeeded. -1 if an error occurred.

Redundant state etc¶

int pnet_set_primary_state(pnet_t *net, bool primary)¶

Set the state to “Primary” or “Backup” in the cyclic data sent to the IO-Controller.

Implements the “Local Set State” primitive.

By default the cyclic communication is “Primary”.

Parameters

net – InOut: The p-net stack instance
primary – In: true to set state to “Primary”.

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_set_redundancy_state(pnet_t *net, bool redundant)¶

Set the state to redundant in the cyclic data sent to the IO-Controller.

Implements the “Local Set Redundancy State” primitive.

By default the cyclic communication is not in redundant state.

Parameters

net – InOut: The p-net stack instance
redundant – In: true to set state to “redundant”.

Returns

0 if the operation succeeded. -1 if an error occurred.

Alarms and diagnostics¶

void pnet_create_log_book_entry(pnet_t *net, uint32_t arep, const pnet_pnio_status_t *p_pnio_status, uint32_t entry_detail)¶

Application creates an entry in the log book.

This function is used to insert an entry into the Profinet log-book. Controllers may read the entire log-book using IODRead requests.

Parameters

net – InOut: The p-net stack instance
arep – In: The AREP.
p_pnio_status – In: The PNIO status.
entry_detail – In: Additional application information. Manufacturer specific.

int pnet_alarm_send_process_alarm(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t payload_usi, uint16_t payload_len, const uint8_t *p_payload)¶

Application issues a process alarm.

This function may be used by the application to issue a process alarm. Such alarms are sent to the controller using high-priority alarm messages.

Optional payload may be attached to the alarm. If payload_usi is != 0 and payload_len > 0 then the payload_usi and the payload at p_payload is attached to the alarm.

After calling this function the application must wait for the pnet_alarm_cnf() callback before sending another alarm. This function fails if the application does not wait for the pnet_alarm_cnf() between sending two alarms.

Note that the PLC can set the max alarm payload length at startup. This limit can be 200 to 1432 bytes.

This functionality is used for alarms triggered by the IO-device.

Parameters

net – InOut: The p-net stack instance
arep – In: The AREP.
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
payload_usi – In: The USI for the payload. Max 0x7fff
payload_len – In: Length in bytes of the payload. May be 0. Max PNET_MAX_ALARM_PAYLOAD_DATA_SIZE or value from PLC.
p_payload – In: The alarm payload (USI specific format).

Returns

0 if the operation succeeded. -1 if an error occurred (or waiting for ACK from controller: re-try later).

int pnet_alarm_send_ack(pnet_t *net, uint32_t arep, const pnet_alarm_argument_t *p_alarm_argument, const pnet_pnio_status_t *p_pnio_status)¶

Application acknowledges the reception of an alarm from the controller.

This function sends an ACK to the controller. This function must be called by the application after receiving an alarm in the pnet_alarm_ind() call-back. Failure to do so within the timeout specified in the connect of the controller will make the controller re-send the alarm.

This functionality is used for alarms triggered by the IO-controller.

Parameters

net – InOut: The p-net stack instance
arep – In: The AREP.
p_alarm_argument – In: The alarm argument (with slot, subslot, alarm_type etc)
p_pnio_status – In: Detailed ACK status.

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_std_add(pnet_t *net, const pnet_diag_source_t *p_diag_source, pnet_diag_ch_prop_type_values_t ch_bits, pnet_diag_ch_prop_maint_values_t severity, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint32_t ext_ch_add_value, uint32_t qual_ch_qualifier)¶

Add a diagnosis entry, in the standard format.

The channel error types and the extended channel error types are defined in Profinet 2.4 Services Annex F.

This sends a diagnosis alarm.

Uses the “Qualified channel diagnosis” format on the wire if the configuration parameter use_qualified_diagnosis is true, otherwise “Extended channel diagnosis”.

Parameters

net – InOut: The p-net stack instance.
p_diag_source – In: Slot, subslot, channel, direction etc.
ch_bits – In: Number of bits in the channel.
severity – In: Diagnosis severity.
ch_error_type – In: The channel error type.
ext_ch_error_type – In: The extended channel error type (more details on the channel error type). Use 0 if not given.
ext_ch_add_value – In: The extended channel error additional value. Typically a measurement value (for example number of dropped packets) related to the error.
qual_ch_qualifier – In: More detailed severity information. Used when severity = PNET_DIAG_CH_PROP_MAINT_QUALIFIED and the use_qualified_diagnosis is enabled. Max one bit should be set. Use 0 otherwise.

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_std_update(pnet_t *net, const pnet_diag_source_t *p_diag_source, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint32_t ext_ch_add_value)¶

Update the “extended channel error additional value”, for a diagnosis entry in the standard format.

The Profinet standard says that diagnosis updates should not be done at a higher frequency than 1 Hz.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
p_diag_source – In: Slot, subslot, channel, direction etc.
ch_error_type – In: The channel error type.
ext_ch_error_type – In: The extended channel error type (more details on the channel error type). Use 0 if not given.
ext_ch_add_value – In: New extended channel error additional value. Typically a measurement value (for example number of dropped packets) related to the error.

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_std_remove(pnet_t *net, const pnet_diag_source_t *p_diag_source, uint16_t ch_error_type, uint16_t ext_ch_error_type)¶

Remove a diagnosis entry in the standard format.

An error is returned if the diagnosis doesn’t exist.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
p_diag_source – In: Slot, subslot, channel, direction etc.
ch_error_type – In: The channel error type.
ext_ch_error_type – In: The extended channel error type (more details on the channel error type). Use 0 if not given.

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_usi_add(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t usi, uint16_t manuf_data_len, const uint8_t *p_manuf_data)¶

Add a diagnosis entry in manufacturer-specified (“USI”) format.

If the diagnosis already exists, it is updated. Use pnet_diag_usi_update() instead if you would like to have an error if the diagnosis is missing when trying to update it.

A diagnosis in USI format is always assigned to the channel “whole submodule” (not individual channels). The severity is always “Fault”, the accumulative flag is false and the direction is “Manufacturer specific”.

It is recommended to use the standard diagnosis format in most cases. Use the manufacturer specific format (“USI format”) only if it’s not possible to use the standard format.

Note that the PLC can set the max alarm payload length at startup, and that affects how large diagnosis entries can be sent via alarms. This payload limit can be 200 to 1432 bytes.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
usi – In: The USI. Range 0..0x7fff
manuf_data_len – In: Length in bytes of the manufacturer specific diagnosis data. A value 0 is allowed. Max PNET_MAX_DIAG_MANUF_DATA_SIZE or value from PLC.
p_manuf_data – In: The manufacturer specific diagnosis data. Mandatory if manuf_data_len > 0, otherwise NULL.

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_usi_update(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t usi, uint16_t manuf_data_len, const uint8_t *p_manuf_data)¶

Update the manufacturer specific data, for a diagnosis entry in manufacturer-specified (“USI”) format.

An error is returned if the diagnosis doesn’t exist. Use pnet_diag_usi_add() instead if you would like to create the missing diagnosis when trying to update it.

Note that the PLC can set the max alarm payload length at startup, and that affects how large diagnosis entries can be sent via alarms. This payload limit can be 200 to 1432 bytes.

The Profinet standard says that diagnosis updates should not be done at a higher frequency than 1 Hz.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
usi – In: The USI. Range 0..0x7fff
manuf_data_len – In: Length in bytes of the manufacturer specific diagnosis data. A value 0 is allowed. Max PNET_MAX_DIAG_MANUF_DATA_SIZE or value from PLC.
p_manuf_data – In: New manufacturer specific diagnosis data. Mandatory if manuf_data_len > 0, otherwise NULL.

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_usi_remove(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t usi)¶

Remove a diagnosis entry in manufacturer-specified (“USI”) format.

An error is returned if the diagnosis doesn’t exist.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
api – In: The API.
slot – In: The slot.
subslot – In: The sub-slot.
usi – In: The USI. Range 0..0x7fff

Returns

0 if the operation succeeded. -1 if an error occurred.

Low-level diagnostic functions¶

These are used internally in the functions above for handling diagnosis in standard or in USI format. However they can be useful in situations where detailed control is required.

int pnet_diag_add(pnet_t *net, const pnet_diag_source_t *p_diag_source, pnet_diag_ch_prop_type_values_t ch_bits, pnet_diag_ch_prop_maint_values_t severity, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint32_t ext_ch_add_value, uint32_t qual_ch_qualifier, uint16_t usi, uint16_t manuf_data_len, const uint8_t *p_manuf_data)¶

Add a diagnosis entry, in standard or USI format.

This is a low-level function. Typically you should use one of these instead (which uses this function internally):

pnet_diag_std_add()
pnet_diag_usi_add()

Note that the PLC can set the max alarm payload length at startup, and that affects how large diagnosis entries can be sent via alarms. This payload limit can be 200 to 1432 bytes.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
p_diag_source – In: Slot, subslot, channel, direction etc.
ch_bits – In: Number of bits in the channel.
severity – In: Diagnosis severity.
ch_error_type – In: The channel error type.
ext_ch_error_type – In: The extended channel error type.
ext_ch_add_value – In: The extended channel error additional value.
qual_ch_qualifier – In: The qualified channel qualifier.
usi – In: The USI.
manuf_data_len – In: Length in bytes of the manufacturer specific diagnosis data. Max PNET_MAX_DIAG_MANUF_DATA_SIZE or value from PLC. (Only needed if USI <= 0x7fff, and may still be 0).
p_manuf_data – In: The manufacturer specific diagnosis data. (Only needed if USI <= 0x7fff).

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_update(pnet_t *net, const pnet_diag_source_t *p_diag_source, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint32_t ext_ch_add_value, uint16_t usi, uint16_t manuf_data_len, const uint8_t *p_manuf_data)¶

Update a diagnosis entry, in standard or USI format.

This is a low-level function. Typically you should use one of these instead (which uses this function internally):

pnet_diag_std_update()
pnet_diag_usi_update()

If the USI of the item is in the manufacturer-specified range then the USI is used to identify the item. Otherwise the other parameters are used (all must match):

p_diag_source (all fields)
Channel error type.
Extended error type.

When the item is found either the manufacturer data is updated (for USI in manufacturer-specific range) or the extended channel additional value is updated.

Note that the PLC can set the max alarm payload length at startup, and that affects how large diagnosis entries can be sent via alarms. This payload limit can be 200 to 1432 bytes.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
p_diag_source – In: Slot, subslot, channel, direction etc.
ch_error_type – In: The channel error type.
ext_ch_error_type – In: The extended channel error type, or 0.
ext_ch_add_value – In: New extended channel error additional value.
usi – In: The USI.
manuf_data_len – In: Length in bytes of the manufacturer specific diagnosis data. Max PNET_MAX_DIAG_MANUF_DATA_SIZE or value from PLC. (Only needed if USI <= 0x7fff, and may still be 0).
p_manuf_data – In: New manufacturer specific diagnosis data. (Only needed if USI <= 0x7fff).

Returns

0 if the operation succeeded. -1 if an error occurred.

int pnet_diag_remove(pnet_t *net, const pnet_diag_source_t *p_diag_source, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint16_t usi)¶

Remove a diagnosis entry, in standard or USI format.

This is a low-level function. Typically you should use one of these instead (which uses this function internally):

pnet_diag_std_remove()
pnet_diag_usi_remove()

If the USI of the item is in the manufacturer-specified range then the USI is used to identify the item. Otherwise the other parameters are used (all must match):

p_diag_source (all fields)
Channel error type.
Extended error type.

This sends a diagnosis alarm.

Parameters

net – InOut: The p-net stack instance.
p_diag_source – In: Slot, subslot, channel, direction etc.
ch_error_type – In: The channel error type.
ext_ch_error_type – In: The extended channel error type, or 0.
usi – In: The USI.

Returns

0 if the operation succeeded. -1 if an error occurred.

Callbacks¶

The application should define call-back functions which are called by the stack when specific events occurs within the stack.

Note that most of these functions are mandatory in the sense that they must exist and return 0 for a functioning stack. Some functions are required to perform specific functionality.

typedef int (*pnet_connect_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_result_t *p_result)¶

Indication to the application that a Connect request was received from the controller.

This application call-back function is called by the Profinet stack on every Connect request from the Profinet controller.

The connection will be opened if this function returns 0 (zero) and the stack is otherwise able to establish a connection.

If this function returns something other than 0 (zero) then the Connect request is refused by the device. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success if not implemented).

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
p_result – Out: Detailed error information if return != 0.

Returns

0 on success. -1 if an error occurred.

typedef int (*pnet_release_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_result_t *p_result)¶

Indication to the application that a Release request was received from the controller.

This application call-back function is called by the Profinet stack on every Release request from the Profinet controller.

The connection will be closed regardless of the return value from this function. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success if not implemented).

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
p_result – Out: Detailed error information if return != 0.

Returns

0 on success. -1 if an error occurred.

typedef int (*pnet_dcontrol_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_control_command_t control_command, pnet_result_t *p_result)¶

Indication to the application that a DControl request was received from the controller.

This application call-back function is called by the Profinet stack on every DControl request from the Profinet controller.

The application is not required to take any action but the function must return 0 (zero) for proper function of the stack. If this function returns something other than 0 (zero) then the DControl request is refused by the device. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success if not implemented).

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
control_command – In: The DControl command code.
p_result – Out: Detailed error information if return != 0.

Returns

0 on success. -1 if an error occurred.

typedef int (*pnet_ccontrol_cnf)(pnet_t *net, void *arg, uint32_t arep, pnet_result_t *p_result)¶

Indication to the application that a CControl confirmation was received from the controller.

This application call-back function is called by the Profinet stack on every CControl confirmation from the Profinet controller.

The application is not required to take any action. The return value from this call-back function is ignored by the Profinet stack. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success?).

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
p_result – Out: Detailed error information.

Returns

0 on success. Other values are ignored.

typedef int (*pnet_state_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_event_values_t state)¶

Indication to the application that a state transition has occurred within the Profinet stack.

This application call-back function is called by the Profinet stack on specific state transitions within the Profinet stack.

At the very least the application must react to the PNET_EVENT_PRMEND state transition. After this event the application must call pnet_application_ready(), when it has finished its setup and it is ready to exchange data.

The return value from this call-back function is ignored by the Profinet stack.

It is optional to implement this callback (but then it would be difficult to know when to call the pnet_application_ready() function).

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
state – In: The state transition event. See pnet_event_values_t.

Returns

0 on success. Other values are ignored.

typedef int (*pnet_reset_ind)(pnet_t *net, void *arg, bool should_reset_application, uint16_t reset_mode)¶

Indication to the application that a reset request was received from the IO-controller.

The IO-controller can ask for communication parameters or application data to be reset, or to do a factory reset.

This application call-back function is called by the Profinet stack on every reset request (via the DCP “Set” command) from the Profinet controller.

The application should reset the application data if should_reset_application is true. For other cases this callback is triggered for diagnostic reasons.

The return value from this call-back function is ignored by the Profinet stack.

It is optional to implement this callback (if you do not have any application data that could be reset).

Reset modes:

0: (Power-on reset, not from IO-controller. Will not trigger this.)
1: Reset application data
2: Reset communication parameters (done by the stack)
99: Reset all (factory reset).

The reset modes 1-9 (out of which 1 and 2 are supported here) are defined by the Profinet standard. Value 99 is used here to indicate that the IO-controller has requested a factory reset via another mechanism.

In order to remain responsive to DCP communication and Ethernet switching, the device should not do a hard or soft reset for reset mode 1 or 2. It is allowed for the factory reset case (but not mandatory).

No arep information is available, as this callback typically is triggered when there is no active connection.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
should_reset_application – In: True if the user should reset the application data.
reset_mode – In: Detailed reset information.

Returns

0 on success. Other values are ignored.

typedef int (*pnet_signal_led_ind)(pnet_t *net, void *arg, bool led_state)¶

Indication to the application that the Profinet signal LED should change state.

Use this callback to implement control of the LED.

It is optional to implement this callback (but a compliant Profinet device must have a signal LED)

No arep information is available, as this callback typically is triggered when there is no active connection.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
led_state – In: True if the signal LED should be on.

Returns

0 on success. -1 if an error occurred. Will trigger a log message.

typedef int (*pnet_read_ind)(pnet_t *net, void *arg, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t idx, uint16_t sequence_number, uint8_t **pp_read_data, uint16_t *p_read_length, pnet_result_t *p_result)¶

Indication to the application that an IODRead request was received from the controller.

This application call-back function is called by the Profinet stack on every IODRead request from the Profinet controller which specify an application-specific value of idx (0x0000 - 0x7fff). All other values of idx are handled internally by the Profinet stack.

The application must verify the value of idx, and that p_read_length is large enough. Further, the application must provide a pointer to the binary value in pp_read_data and the size, in bytes, of the binary value in p_read_length.

The Profinet stack does not perform any endianness conversion on the binary value.

In case of error the application should provide error information in p_result.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
api – In: The AP identifier.
slot – In: The slot number.
subslot – In: The sub-slot number.
idx – In: The data record index.
sequence_number – In: The sequence number.
pp_read_data – Out: A pointer to the binary value.
p_read_length – InOut: The maximum (in) and actual (out) length in bytes of the binary value.
p_result – Out: Detailed error information if returning != 0

Returns

0 on success. -1 if an error occurred.

typedef int (*pnet_write_ind)(pnet_t *net, void *arg, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t idx, uint16_t sequence_number, uint16_t write_length, const uint8_t *p_write_data, pnet_result_t *p_result)¶

Indication to the application that an IODWrite request was received from the controller.

This application call-back function is called by the Profinet stack on every IODWrite request from the Profinet controller which specify an application-specific value of idx (0x0000 - 0x7fff). All other values of idx are handled internally by the Profinet stack.

The application must verify the values of idx and write_length and save (copy) the binary value in p_write_data. A future IODRead must return the latest written value.

The Profinet stack does not perform any endianness conversion on the binary value.

In case of error the application should provide error information in p_result.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
api – In: The API identifier.
slot – In: The slot number.
subslot – In: The sub-slot number.
idx – In: The data record index.
sequence_number – In: The sequence number.
write_length – In: The length in bytes of the binary value.
p_write_data – In: A pointer to the binary value.
p_result – Out: Detailed error information if returning != 0

Returns

0 on success. -1 if an error occurred.

typedef int (*pnet_exp_module_ind)(pnet_t *net, void *arg, uint32_t api, uint16_t slot, uint32_t module_ident)¶

Indication to the application that a module is requested by the controller in a specific slot.

This application call-back function is called by the Profinet stack to indicate that the controller has requested the presence of a specific module, ident number module_ident, in the slot number slot.

The application must react to this by configuring itself accordingly (if possible) and call function pnet_plug_module() to configure the stack for this module.

If the wrong module ident number is plugged then the stack will accept this, but signal to the controller that a substitute module is fitted.

This function should return 0 (zero) if a valid module was plugged. Or return -1 if the application cannot handle this request.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
api – In: The AP identifier.
slot – In: The slot number.
module_ident – In: The module ident number.

Returns

0 on success. -1 if an error occurred.

typedef int (*pnet_exp_submodule_ind)(pnet_t *net, void *arg, uint32_t api, uint16_t slot, uint16_t subslot, uint32_t module_ident, uint32_t submodule_ident, const pnet_data_cfg_t *p_exp_data)¶

Indication to the application that a sub-module is requested by the controller in a specific sub-slot.

This application call-back function is called by the Profinet stack to indicate that the controller has requested the presence of a specific sub-module, ident number submodule_ident, in the sub-slot number subslot, with module ident number module_ident in slot slot.

If a module has not been plugged in the slot slot then an automatic plug request is issued internally by the stack.

The application must react to this by configuring itself accordingly (if possible) and call function pnet_plug_submodule() to configure the stack with the correct input/output data sizes.

If the wrong sub-module ident number is plugged then the stack will accept this, but signal to the controller that a substitute sub-module is fitted.

This function should return 0 (zero) if a valid sub-module was plugged. Or return -1 if the application cannot handle this request.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
api – In: The AP identifier.
slot – In: The slot number.
subslot – In: The sub-slot number.
module_ident – In: The module ident number.
submodule_ident – In: The sub-module ident number.
p_exp_data – In: The expected data configuration

Returns

0 on success. -1 if an error occurred.

typedef int (*pnet_new_data_status_ind)(pnet_t *net, void *arg, uint32_t arep, uint32_t crep, uint8_t changes, uint8_t data_status)¶

Indication to the application that the data status received from the controller has changed.

This application call-back function is called by the Profinet stack to indicate that the received data status has changed.

The application is not required by the Profinet stack to take any action. It may use this information as it wishes. The return value from this call-back function is ignored by the Profinet stack.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
crep – In: The CREP.
changes – In: The changed bits in the received data status. See pnet_data_status_bits_t
data_status – In: Current received data status (after changes). See pnet_data_status_bits_t

Returns

0 on success. Other values are ignored.

typedef int (*pnet_alarm_ind)(pnet_t *net, void *arg, uint32_t arep, const pnet_alarm_argument_t *p_alarm_argument, uint16_t data_len, uint16_t data_usi, const uint8_t *p_data)¶

The IO-controller has sent an alarm to the device.

This functionality is used for alarms triggered by the IO-controller.

When receiving this indication, the application shall respond with pnet_alarm_send_ack(), which may be called in the context of this callback.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
p_alarm_argument – In: The alarm argument (with slot, subslot, alarm_type etc)
data_len – In: Data length
data_usi – In: Alarm USI
p_data – In: Alarm data

Returns

0 on success. Other values are ignored.

typedef int (*pnet_alarm_cnf)(pnet_t *net, void *arg, uint32_t arep, const pnet_pnio_status_t *p_pnio_status)¶

The controller acknowledges the alarm sent previously. It is now possible to send another alarm.

This functionality is used for alarms triggered by the IO-device.

It is optional to implement this callback. The return value from this call-back function is ignored by the Profinet stack.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
p_pnio_status – In: Detailed ACK information.

Returns

0 on success. Other values are ignored.

typedef int (*pnet_alarm_ack_cnf)(pnet_t *net, void *arg, uint32_t arep, int res)¶

The controller acknowledges the alarm ACK sent previously.

This functionality is used for alarms triggered by the IO-controller.

It is optional to implement this callback. The return value from this call-back function is ignored by the Profinet stack.

Parameters

net – InOut: The p-net stack instance
arg – InOut: User-defined data (not used by p-net)
arep – In: The AREP.
res – In: 0 if ACK was received by the remote side. This is cnf(+). -1 if ACK was not received by the remote side. This is cnf(-).

Returns

0 on success. Other values are ignored.

Selected enums¶

enum pnet_event_values_t¶

The events are sent from CMDEV to the application using the pnet_state_ind() call-back function.

Values:

enumerator PNET_EVENT_ABORT¶: The AR has been closed.

enumerator PNET_EVENT_STARTUP¶: A connection has been initiated.

enumerator PNET_EVENT_PRMEND¶: Controller has sent all write records.

enumerator PNET_EVENT_APPLRDY¶: Controller has acknowledged the APPL_RDY message

enumerator PNET_EVENT_DATA¶

enum pnet_ioxs_values_t¶

Values used for IOCS and IOPS.

Values:

enumerator PNET_IOXS_BAD¶

enumerator PNET_IOXS_GOOD¶

enum pnet_submodule_dir_t¶

Values used when plugging a sub-module using pnet_plug_submodule().

Values:

enumerator PNET_DIR_NO_IO¶

enumerator PNET_DIR_INPUT¶

enumerator PNET_DIR_OUTPUT¶

enumerator PNET_DIR_IO¶

enum pnet_control_command_t¶

CControl command codes used in the pnet_dcontrol_ind() call-back function.

Values:

enumerator PNET_CONTROL_COMMAND_PRM_BEGIN¶

enumerator PNET_CONTROL_COMMAND_PRM_END¶

enumerator PNET_CONTROL_COMMAND_APP_RDY¶

enumerator PNET_CONTROL_COMMAND_RELEASE¶

enumerator PNET_CONTROL_COMMAND_RDY_FOR_COMPANION¶

enumerator PNET_CONTROL_COMMAND_RDY_FOR_RTC3¶

enum pnet_data_status_bits_t¶

Data status bits used in the pnet_new_data_status_ind() call-back function.

Values:

enumerator PNET_DATA_STATUS_BIT_STATE¶

enumerator PNET_DATA_STATUS_BIT_REDUNDANCY¶: 0 => BACKUP, 1 => PRIMARY

enumerator PNET_DATA_STATUS_BIT_DATA_VALID¶: Meaning depends on STATE bit

enumerator PNET_DATA_STATUS_BIT_RESERVED_1¶: 0 => INVALID, 1 => VALID

enumerator PNET_DATA_STATUS_BIT_PROVIDER_STATE¶

enumerator PNET_DATA_STATUS_BIT_STATION_PROBLEM_INDICATOR¶: 0 => STOP, 1 => RUN

enumerator PNET_DATA_STATUS_BIT_RESERVED_2¶: 0 => Problem detected, 1 => Normal operation

enumerator PNET_DATA_STATUS_BIT_IGNORE¶: 0 => Evaluate data status, 1 => Ignore the data status (typically used on a frame with subframes)

enum pnet_diag_ch_prop_type_values_t¶

Channel size in bits.

Values:

enumerator PNET_DIAG_CH_PROP_TYPE_UNSPECIFIED¶

enumerator PNET_DIAG_CH_PROP_TYPE_1_BIT¶

enumerator PNET_DIAG_CH_PROP_TYPE_2_BIT¶

enumerator PNET_DIAG_CH_PROP_TYPE_4_BIT¶

enumerator PNET_DIAG_CH_PROP_TYPE_8_BIT¶

enumerator PNET_DIAG_CH_PROP_TYPE_16_BIT¶

enumerator PNET_DIAG_CH_PROP_TYPE_32_BIT¶

enumerator PNET_DIAG_CH_PROP_TYPE_64_BIT¶

enum pnet_diag_ch_prop_dir_values_t¶

Channel direction.

Values:

enumerator PNET_DIAG_CH_PROP_DIR_MANUF_SPEC¶

enumerator PNET_DIAG_CH_PROP_DIR_INPUT¶

enumerator PNET_DIAG_CH_PROP_DIR_OUTPUT¶

enumerator PNET_DIAG_CH_PROP_DIR_INOUT¶

enum pnet_diag_ch_prop_maint_values_t¶

Diagnosis severity.

Values:

enumerator PNET_DIAG_CH_PROP_MAINT_FAULT¶

enumerator PNET_DIAG_CH_PROP_MAINT_REQUIRED¶

enumerator PNET_DIAG_CH_PROP_MAINT_DEMANDED¶

enumerator PNET_DIAG_CH_PROP_MAINT_QUALIFIED¶

Selected typedefs¶

Network and device configuration.

Configuration of the stack is performed by transferring a structure in the call to pnet_init().

Along with the configuration the initial (default) values of the I&M data records are conveyed as well as the values used for sending LLDP frames.

struct pnet_im_0_t¶

The I&M0 data record is read-only by the controller.

This data record is mandatory.

struct pnet_im_1_t¶

The I&M1 data record is read-write by the controller.

This data record is optional. If this data record is supported by the application then bit 1 in the im_supported member of I&M0 shall be set.

struct pnet_im_2_t¶

The I&M2 data record is read-write by the controller.

This data record is optional. If this data record is supported by the application then bit 2 in the im_supported member of I&M0 shall be set.

struct pnet_im_3_t¶

The I&M3 data record is read-write by the controller.

This data record is optional. If this data record is supported by the application then bit 3 in the im_supported member of I&M0 shall be set.

struct pnet_im_4_t¶

The I&M4 data record is read-write by the controller.

Used for functional safety.

This data record is optional. If this data record is supported by the application then bit 4 in the im_supported member of I&M0 shall be set.

struct pnet_cfg_device_id_t¶

The device-specific vendor and device identities.

The vendor id is obtained from Profibus International.

The device id is assigned by the vendor.

struct pnet_cfg_t¶

This is all the configuration needed to use the Profinet stack.

The application must supply the values in the call to function pnet_init().

struct pnet_alarm_spec_t¶: Summary of all diagnosis items, sent in an alarm. Only valid for alarms attached to the Diagnosis ASE See Profinet 2.4 Services, section 7.3.1.6.5.1 Alarm Notification

struct pnet_alarm_argument_t¶

struct pnet_diag_source_t¶