PN_API_IM_addImCarrier()

uint32_t PN_API_IM_addImCarrier

(

PN_API_IM_SCarrier_t *

pImCarrier_p

)

Add an I&M carrier to stack.

Stack can handle I&M data independently. Priorly application shall provide all concerned I&M carriers, which are attached to the real submodules. I&M data will be stored on stack memory, enabling stack to process all external I&M data requests autonomously. External PROFINET participants can access I&M information over submodule address (api->slot->subslot). A number of I&M carriers, that can be stored on the stack is limited.

The content of the input parameter will be copied to stack. Application can safely modify or delete the instance after invoking the function.

Following rules will be observed in this function prior adding an I&M carrier.

• Basic parameters of the I&M carrier. It contains I&M0 data, which has valid values.
• Function will check, that no I&M carrier assigned to concerned submodule yet. Means, no other I&M carrier has specified address.
• If a device representative is being added: 1) function will check if no device representative is already assigned. 2) I&M device representative must support additionally I&M1, I&M2 and I&M3 data records. 3) I&M data records contain valid data (only visible characters).
• If a module representative is being added: 1) function will check if no module representative is already assigned to this module;

In case a submodule, module or device representative needed to be re-assigned, the old I&M carrier must be removed.

Remarks

Following general rules must be concerned, which are not in scope of this function

• I&M device representative is mandatory.
• I&M0 data of the device representative must be consistent with Chassis Id, RPC Annotation etc ...

Warning

• Corresponding real submodule must be plugged, using PN_API_DEV_APP_plugSubmodule().
• If a real submodule is being pulled with PN_API_DEV_APP_pullSubmodule(), attached I&M carrier (if available) will be removed as well.
• Application must register WriteRecordIndicatedCallback and take care of storing writable I&M data (I&M1, I&M2, I&M3, I&M3).

Parameters

[in]

pImCarrier_p

Pointer to I&M carrier, which is being added.

Returns

PN_API_IM_EError_t as uint32_t value.

Return values

PN_API_IM_eOK	Function successful.
PN_API_IM_eERR_ADD_INVALID_POINTER_PARAMETER	Invalid parameters (NULL pointers).
PN_API_IM_eERR_ADD_INVALID_ADDRESS	Invalid slot number (> 0x7FFF) or subslot number (> 0x9FFF).
PN_API_IM_eERR_ADD_NO_FREE_SPACE	No free space for a new I&M carrier.
PN_API_IM_eERR_ADD_INVALID_IM_VERSION	Invalid I&M version (major != 0x01 || minor != 0x01).
PN_API_IM_eERR_ADD_INVALID_SW_PREFIX	Invalid SW Revision prefix (for reference see PN_API_IM_EImSwRevPrefix_t).
PN_API_IM_eERR_ADD_INVALID_STRING	I&M1, I&M2 or I&M3 data contains a non-visible character.
PN_API_IM_eERR_ADD_SUBMODULE_ALREADY_ASSIGNED	An I&M carrier is already assigned to submodule with specified address.
PN_API_IM_eERR_ADD_MODULE_ALREADY_ASSIGNED	Specified module has already an I&M module representative.
PN_API_IM_eERR_ADD_DEVICE_ALREADY_ASSIGNED	I&M device representative is already assigned.
PN_API_IM_eERR_ADD_DEVICE_NO_IM123_SUPPORT	I&M device representative must support I&M1, I&M2 and I&M3 data.
PN_API_IM_eERR_ADD_SUBMODULE_NOT_PLUGGED	Corresponding real submodule isn't plugged.

Example

 #include <PN_API_IM.h>
 
//Concerned real submodule must be plugged
PN_API_DEV_APP_plugSubmodule();
 
...
 
//New instance of I&M Carrier.
PN_API_IM_SCarrier_t imCarrier;
 
//Fill I&M Carrier.
imCarrier.address.api = XXX;
...
imCarrier.im0.manufacturerId = XXX;
....
 
//Add I&M carrier to the stack and analyze result.
uint32_t result = PN_API_IM_addImCarrier(&imCarrier)
 
if (result == PN_API_IM_eOK) // success