Application Programming Interface

This chapter lists the API functions that are provided by GOAL PROFINET.

goal_pnioInit - Register GOAL PROFINET in GOAL (appl_init)

This function registers GOAL PROFINET in GOAL and must be called in appl_init. Its main functionality is to register a set config manager variables before the NVS storage is initialized.

It returns a GOAL_STATUS_T status and has no parameters.

    GOAL_STATUS_T appl_init(
        void
    )
    {
        GOAL_STATUS_T res;                          /**< GOAL result */

        /* initialize GOAL PROFINET */
        res = goal_pnioInit();
        if (GOAL_RES_ERR(res)) {
            goal_logErr("failed to initialize GOAL PROFINET");
        }

        return res;
    }

goal_pnioNew - Create a GOAL PROFINET instance (appl_setup)

This function creates a new GOAL PROFINET instance by taking a snapshot of all pre-variables (goal_pnioCfg API) and allocating the necessary resources. The application has to provide a GOAL PROFINET instance id and a callback handler. The callback handler can also be NULL to only use GOAL PROFINET stack default behavior. It returns a GOAL_STATUS_T status and a GOAL PROFINET instance handle.

Parameter	Description

Parameter	Description
GOAL_PNIO_T **ppPnio	returned GOAL PROFINET instance handle
const uint32_t id	GOAL PROFINET instance id
GOAL_PNIO_FUNC_CB_T pFunc	GOAL PROFINET callback function

Table: goal_pnioNew parameters

See example 01_simple_io for a demonstration.

goal_pnioCfgDcpFactoryResetDisableSet - Configure DCP Factory Reset

Controls if DCP factory reset is available. If set to GOAL_TRUE DCP factory reset will be denied. Default: GOAL_FALSE.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
GOAL_BOOL_T flgDcpFactoryResetDisable	DCP Factory Reset Disable Flag

Table: goal_pnioCfgDcpFactoryResetDisableSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDcpAcceptMixcaseStationSet - Configure DCP Mixcase Stationname Acceptance

Controls if DCP accepts station names with mixed case spelling. If set to GOAL_TRUE DCP accepts mixed case station names. Default: GOAL_FALSE.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
GOAL_BOOL_T flgDcpAcceptMixcaseStation	DCP Mixcase Stationname Acceptance Flag

Table: goal_pnioCfgDcpAcceptMixcaseStationSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgVendorIdSet - Set Vendor Id

Configures the vendor id. Default: 0x028c (port GmbH)

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
uint16_t idVendor	Vendor ID

Table: goal_pnioCfgVendorIdSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDeviceIdSet - Set Device Id

Configures the device id. Default: 0x0001

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
uint16_t idDevice	Device ID

Table: goal_pnioCfgDeviceIdSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgVendorNameSet - Set Vendor Name

Configures the vendor name. Default: "port GmbH"

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strVendor	Vendor Name

Table: goal_pnioCfgVendorIdSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgPortDescSet - Set LLDP Port Description

Configures the LLDP port description. Default: "TestPort"

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strDescPort	Port Description

Table: goal_pnioCfgPortDescSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgSystemDescSet - Set LLDP System Description

Configures the LLDP system description. Default: "PROFINET System"

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strSystem	System Description

Table: goal_pnioCfgSystemDescSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgOrderIdSet - Set Order Id

Configures the order id. Default: "00210"

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strOrder	Order Id

Table: goal_pnioCfgOrderIdSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgSerialNumSet - Set Serial Number

Configures the serial number. Default: "20074"

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strNumSerial	Serial Number

Table: goal_pnioCfgSerialNumSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgHwRevSet - Set Hardware Revision

Configures the hardware revision. Default: 1

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
uint16_t idRevHw	Hardware Revision

Table: goal_pnioCfgHwRevSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgSwRevPrefixSet - Set Software Revision Prefix

Configures the software revision prefix. Default: "P"

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

Valid values are:

"V" - official
"R" - revision
"P" - prototype
"U" - under test
"T" - test device

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char chrRevSwPrefix	Software Revision Prefix

Table: goal_pnioCfgSwRevPrefixSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgSwRevFuncEnhSet - Set Software Revision Functional Enhancement

Configures the software revision functional enhancement. Default: 0x50

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
uint8_t idRevSwFuncEnh	Software Revision Functional Enhancement

Table: goal_pnioCfgSwRevFuncEnhSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgSwRevBugfixSet - Set Software Revision Bugfix

Configures the software revision bugfix. Default: 3

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
uint8_t idRevSwBugfix	Software Revision Bugfix

Table: goal_pnioCfgSwRevBugfixSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgSwRevIntChgSet - Set Software Revision Internal Change

Configures the software revision internal change. Default: 0x18

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
uint8_t idRevSwIntChg	Software Revision Internal Change

Table: goal_pnioCfgSwRevIntChgSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgSwRevCntSet - Set Software Revision Counter

Configures the software revision counter. Default: 0x0000

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
uint16_t idRevSwRevCnt	Software Revision Counter

Table: goal_pnioCfgSwRevCntSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgIm1TagFuncSet - Set I&M1 Tag Function

Configures the I&M1 tag function. Default: ""

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strIm1TagFunc	I&M1 Tag Function

Table: goal_pnioCfgIm1TagFuncSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgIm1TagLocSet - Set I&M1 Tag Location

Configures the I&M1 tag location. Default: ""

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strIm1TagLoc	I&M1 Tag Location

Table: goal_pnioCfgIm1TagLocSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgIm2DateSet - Set I&M2 Date

Configures the I&M2 date. Default: ""

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strIm2Date	I&M2 Date

Table: goal_pnioCfgIm2DateSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgIm3DescSet - Set I&M3 Description

Configures the I&M3 description. Default: ""

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strIm3Desc	I&M3 Description

Table: goal_pnioCfgIm3DescSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgIm4SigSet - Set I&M4 Signature (Functional Safety)

Configures the I&M4 signature. Default: ""

See document "Profile Guidelines Part 1: Identification & Maintenance Functions" for details.

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Parameter	Description

Parameter	Description
const char *strIm4Sig	I&M4 Signature

Table: goal_pnioCfgIm4SigSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDevDapSimpleSet - Configure Device DAP Simple Mode

Configures the device DAP simple mode. If flgDevDapSimple is GOAL_TRUE the GOAL PROFINET stack automatically creates the DAP and port slots and modules.

Default: GOAL_TRUE

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
GOAL_BOOL_T flgDevDapSimple	Device DAP Simple Mode Flag

Table: goal_pnioCfgDevDapSimpleSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDevDapApiSet - Set Device DAP API Number

Configures the device DAP API number. Default: 0

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
uint32_t idDevDapApi	Device DAP API Number

Table: goal_pnioCfgDevDapApiSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDevDapSlotSet - Set Device DAP Slot Number

Configures the device DAP slot number. Default: 0

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
uint16_t idDevDapSlot	Device DAP Slot Number

Table: goal_pnioCfgDevDapSlotSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDevDapSubslotSet - Set Device DAP Subslot Number

Configures the device DAP subslot number. Default: 1

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
uint16_t idDevDapSubslot	Device DAP Subslot Number

Table: goal_pnioCfgDevDapSubslotSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDevDapModuleSet - Set Device DAP Module Id

Configures the device DAP module id. Default: 1

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
uint32_t idDevDapMod	Device DAP Module Id

Table: goal_pnioCfgDevDapModuleSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgDevDapSubmoduleSet - Set Device DAP Submodule Id

Configures the device DAP submodule id. Default: 1

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
uint32_t idDevDapSubmod	Device DAP Submodule Id

Table: goal_pnioCfgDevDapSubmoduleSet parameters

See example 15_config_set for a demonstration.

goal_pnioCfgNetLinkSafetySet - Configure Device Port Disable Behavior

Configures the device port disable behavior. If flgNetLinkSafety is set to GOAL_TRUE the GOAL PROFINET stack doesn't allow the master to disable all Ethernet interfaces at the same time. Default: GOAL_TRUE

It returns a GOAL_STATUS_T status.

This function configures the GOAL PROFINET instance and must be called before goal_pnioNew to have an effect.

Warning: This function should not be used as the behavior can break conformity.

Parameter	Description

Parameter	Description
GOAL_BOOL_T flgNetLinkSafety	Device Port Disable Behavior