SAE J1939 Network Management (J1939Nm)

Provides the content of received Address Claimed (AC) PGs.

This function initializes the J1939 Network Management module.

This function resets the J1939 Network Management module to the uninitialized state.

Returns the version information of this module.

Indication of a received PDU from a lower layer communication interface module.

The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU.

Main function of the J1939 Network Management module. Used for scheduling purposes and timeout supervision.

Indicates reception of a Request or Request2 PG.

Request the network, since ECU needs to communicate on the bus.

Release the network, since ECU doesn't have to communicate on the bus.

Service Name J1939Nm_ Get State Syntax Std_ Return Type J1939Nm_ Get State ( Network Handle Type Network Handle, Nm_ State Type* nm State Ptr, Nm_ Mode Type* nm Mode Ptr ) Service ID [hex] 0x0d Sync/ Async Synchronous Reentrancy Reentrant Parameters (in) Network Handle Identification of the NM - channel Parameters (inout) None Parameters (out) nm State Ptr Pointer where state of the network management shall be copied to. nm Mode Ptr Pointer where the mode of the network management shall be copied to. Return value Std _ Return - Type E_ OK: No error E_ NOT_ OK: Getting of NM state has failed De scription Returns the state and the mode of the network management. Available via J1939Nm.h

Passive startup of the NM. It triggers the transition from Bus - Sleep Mode to the Network Mode without requesting the network.

This callout function returns the number of Can SM base cycles to wait additi onally to L1/ L2 after a Bus Off occurred.

This is the base type for the configuration of the J1939 Network Management module. A pointer to an instance of this structure will be used in the initialization of the J1939 Network Management module. The content of this structure is defined in chapter 10 Configuration specification.

A call to J1939 N m_Init initializes all internal variables and sets the J1939 Network Management module to the in itialized state.

A call to J1939 N m_DeInit sets the J1939 Network Management module back to the uninitialized state.

When J1939 N m_Init is called in initialized state, the J193 9 Network Management module shall not re - initialize its internal variables. It shall instead call Det_ReportError with the error code J1939 N M_E_REINIT if DET reporting is enabled via J1939NmDevErrorDetect .

The J1939 Network Management module shall use the J1939 N m_MainFunction for timing related purposes.

During initialization via J1939Nm_Init, the J1939 Networ k Management module shall silently assume the ‘S leep M ode ’ for all NodeChannels .

A call to J1939Nm_NetworkRequest shall set all NodeChannels of the reported channel to ‘NetworkMode’ . The J1939 Network Management module shall notif y this mode change to the NM Interface via Nm_NetworkMode, and shall trigger transmission of an AddressClaimed PG for each NodeChannel where J1939NmChannelUsesAddressArbitration is enabled .

If a node of the J1939 Network Management module is configured for deferred online state ( J1939NmNode StartUpDelay enabled) , it s NodeCh annels shall enter the sub state ‘Claiming’ of the state ‘Offline’ immediately after the switch from ‘SleepMode’ to ‘NetworkMode’ . The J1939 Network Management module shall report t h is state change to the Basic Software Mode Manager via BswM_J1939Nm_StateChangeNotification (NM_STATE_OFFLINE ) .

If a node of the J1939 Network Management module is configured for immediate online state ( J1939NmNode StartUpDelay disabled) , its NodeChannels shall enter the state ‘NormalOperation’ immediately after the switch from ‘SleepMode’ to ‘NetworkMode’ . The J1939 Network Management module shall report this state change to the Basic Software Mode Manager via BswM_J1939Nm_StateChangeNotification (NM_STATE_NORMAL_OPERATION ) .

Error Name: J1939NM_E_ADDRESS_LOST Short Description: The desired address could not be claimed. Long Description: During start - up of the ECU, all J1939Nm nodes need to send an address claim to the bus and wait for acceptance of the claimed address. If another ECU cl aims the same address and has a higher priority, the ECU loses its address and stops communication. This is a critical problem, because J1939Nm was not specified for networks where this can happen. Detection Criteria: Fail When address claiming failed, be cause an AddressClaimed message with higher priority was received (see [SWS_J1939Nm_00021]), the J1939 Network Management module shall report the extended production error J1939NM_E_ADDRESS_LOST with event status DEM_EVENT_STATUS_PREFAILED to DEM. Pass When address claiming succeeded, because the J1939 Network Management entered the state 'NormalOperation' (see [SWS_J1939Nm_00011] and [SWS_J1939Nm_00013]), the J1939 Network Management module shall report the extended production error J1939NM_E_ADDRESS_LO ST with event status DEM_EVENT_STATUS_PREPASSED to DEM. Secondary Parameters: Address claiming is started when a node enters NetworkMode for a channel. Time Required: Typically 250ms after changing to NetworkMode, but possible during entire run time when addresses can change at run time or ECUs are attached later (or wake up later). Monitor Frequency The bus is continuously monitored for AddressClaimed messages.

When the delay timer of a NodeChannel expires in sub state ‘ Claiming’, the J1939 Network Management module shall switch that NodeChannel to state ‘NormalOperation’ and shall report this state change to the Basic Software Mode Manager via BswM_J1939Nm_State ChangeNotification(NM_STATE_NORMAL_OPERATION) .

When a NodeChannel loses its address in ‘NetworkMode’, it shall switch to the sub st ate ‘AcLost’ of state ‘Offline’ and , after a delay calculated according to [SWS_J1939Nm_00068] , trigger transmission of a Canno t ClaimAddress PG.

A call to J1939Nm_NetworkRelease shall set all NodeChannels of the reported channel to ‘ Sleep Mode’. The J1939 Network M anagement module shall notify this mode change to the NM Interface via Nm_BusSleepMode , and shall report a state change to ‘SleepMode’ to the NM Interface via Nm_StateChangeNotification(NM_STATE_BUS_SLEEP) and to BswM via BswM_J1939Nm_StateChangeNotificati on(NM_STATE_BUS_SLEEP) .

When the J1939 Network Management module needs to send an AddressClaimed ( or CannotClaimAddress ) PG, and no previous transmission is pending , it shall direc tly forward the corresponding PDU to the CAN Interface via CanIf_Transmit .

When the J1939 Network Management module needs to send an AddressClaimed ( or CannotClaimAddress ) PG, and the CAN Interface has not yet called J1939Nm_ TxConfirmation for the previous transmission, the J1939 Network Management module shall buffer this PG for later transmission.

Apart from the initial AddressClaimed PG, t he J1939 Network Management module shall buffer only the latest AddressClaimed or CannotClaimAddress PG.

A call to J1939Nm_TxConfirmation with result E_OK shall trigger transmission of a buffered AddressClaimed or CannotClaimAddress PG via CanIf_Transmit.

If J1939NmChannelUsesAddressArbitration is enabled, a call to J1939 N m_RxIndication indicating reception of an AddressClaimed PG with one of the source addresses configured via J1939NmNodePreferredAddress and a payload that has a higher numerical value than the NAME for this source address config ured via J1939NmNode NameXxx shall trigger transmission of an AddressClaimed PG for the according NodeChannel (see section 7.4 ) .

If J1939NmChannelUsesAddressArbitration is enabled, a call to J1939 N m_RxIndication indicating reception of an AddressClaimed PG with one of the sour ce addresses configured via J1939NmNodePreferredAddress and a payload that has a lower numerical value than the NAME for this source address configured via J1939NmNode NameXxx shall induce a state change of the according NodeChannel to the sub state ‘AcLost ’ of state ‘Offline’.

A call to J1939Nm_RequestIndication shall trigger transmission of an AddressClaimed PG when the addressed NodeChannel is in state ‘NormalOperation’ or sub state ‘Claiming’ of state ‘Offline’ .

A call to J1939Nm_Reque stIndication shall trigger transmission of a CannotClaimAddress PG after a delay calculated according to [SWS_J1939Nm_00068] when the addressed NodeChannel is in sub state ‘AcLost’ of state ‘Offline’.

Type of error Related error code Error value An API was called while the module was uninitialized J1939NM_ E_ UNINIT 0x01 The Init API was called twice J1939NM_ E_ REINIT 0x02 J1939Nm_ Init was called with an invalid configuration pointer J1939NM_ E_ INIT_ FAILED 0x03 An API service was called with a NULL pointer J1939NM_ E_ PARAM_ POINTER 0x10 An API service was called with a wrong ID J1939NM_ E_ INVALID_ PDU_ SDU_ ID 0x11 An API service was called with wrong network handle J1939NM_ E_ INVALID_ NETWORK_ ID 0x12 An API was called with an unsupported PGN J1939NM_ E_ INVALID_ PGN 0x13 An API was called with an illegal priority J1939NM_ E_ INVALID_ PRIO 0x14 An API was called with an illegal node address J1939NM_ E_ INVALID_ ADDRESS 0x15 An API was called with an illegal node ID J1939NM_ E_ INVALID_ NODE 0x16

If DET reporting is enabled via J1939NmDevErrorDetect, the J1939 Network Management module shall check PduIdType parameters (SDU/PDU IDs) of its API functions against the configured IDs, and shall report the development error J1939NM_E_INVALID_PDU_SDU_ID when an unknown ID is provided by the call.

If DET reporting is enabled via J1939NmDevErrorDetect, the J1939 Network Management module shall check NetworkHandleType parameters (ne twork handles) of its API functions against the referenced network handles of ComM, and shall report the development error J1939NM_E_INVALID_NETWORK_ID when an unknown handle is provided by the call.

Module Header File Imported Type Com Stack_ Types Com Stack_ Types.h Network Handle Type Com Stack_ Types.h Pdu Id Type Com Stack_ Types.h Pdu Info Type Com Stack_ Types.h Pdu Length Type Dem Rte_ Dem_ Type.h Dem _ Event Id Type Rte_ Dem_ Type.h Dem _ Event Status Type J1939Rm Rte_ J1939Rm_ Type.h J1939 Rm _ Ext Id Info Type Rte_ J1939Rm_ Type.h J1939 Rm _ Ext Id Type Nm Nm Stack_ types.h Nm _ Mode Type Nm Stack_ types.h Nm _ State Type Std Std_ Types.h Std _ Return Type Std_ Types.h Std _ Version Info Type

The frequency of invocations of J1939Nm_MainFunction is determined by the configuration parameter J1939NmMainFunctionPeriod .

Bsw M _ J1939 - Nm _ State - Change - Notification Bsw M_ J1939Nm.h Notification of current J1939Nm state after state changes. Can If _ Transmit Can If.h Requests transmission of a PDU. Dem _ Set Event - Status Dem.h Called by SW - Cs or BSW modules to report monitor status information to the Dem. BSW modules calling Dem_ Set Event Status can safely ignore the return value. This API will be available only if ( {Dem/ Dem Config Set/ Dem Event Parameter/ Dem Event Reporting Type} == STANDARD_ REPORTING) Nm _ Bus Sleep - Mode Nm.h Notification that the network management has entered Bus - Sleep Mode. Nm _ Network - Mode Nm.h Notification that the network management has entered Network Mode. Nm _ State - Change - Notification Nm.h Notification that the state of the lower layer <Bus Nm> has changed.

Det _ Report Error Det.h Service to report development errors.

The < User_AddressClaimedIndication > function shall only be available if J1939NmUserCallout is configured .

If enabled via J1939NmUserCallout , the J1939Nm shall forward the source address and the content of each AddressClaimed PG to the call - out function <User_AddressClaimed Indication> (see SWS_J1939Nm_00028 ) .

When J1939Nm_TxConfirmation is called with result E_OK for the initial AddressClaimed PG of a NodeChannel ( transmitted during the transition to the ‘Claiming’ sub state ) , the J1939 Network Management module shall start the delay timer for this NodeChannel .

When CanIf_Transmit returns with E_NOT_OK or when J1939Nm_TxConfirmation is cal led with result E_NOT_OK, the transmission of that PG shall be triggered again .

When all NodeChannels of a channel are configured for deferred online state ( J1939NmNode StartUpDelay enabled), the J1939 Network Management module shall report the state change of these NodeChannels to the ‘Offline’ state immediately to the NM Interface via Nm_StateChangeNotification(NM_STATE_OFFLINE).

When the first NodeChannel of a channel changes its state to ‘NormalOperation’, the J1939 Network Management module shall report this state change imm ediately to the NM Interface via Nm_StateChangeNotification(NM_STATE_NORMAL_OPERATION).

When a NodeChannel switches from state ‘NormalOperation’ to the sub state ‘AcLost’ of state ‘Offline’, the J1939 Network Management module shall notify the Basic Software Mode Manager via BswM_J1939Nm_StateChangeNotification(NM_STATE_OFFLINE).

When the last NodeChannel of a channel changes its state to ‘Offline’, the J1939 Network Management module shall report this state change immediately to the NM Interface via Nm_StateChangeNotification(NM_STATE_OFFLINE).

The J1939 Network Management module shall ignore the request indication when the 'sourceAddress' or the 'priority' are not in the valid range, or when 'node' is not one of the configured node IDs (see J1939NmNodeId), or when 'requestedPgn' is not the PGN o f AC, or when 'destAddress' is not 0xFF or the address of the reported node. If DET reporting is enabled via J1939NmDevErrorDetect, the J1939 Network Management module shall report the corresponding development error: J1939NM_E_INVALID_NODE for 'node', J19 39NM_E_INVALID_PGN for 'requestedPgn', J1939NM_E_INVALID_ADDRESS for 'sourceAddress' or 'destAddress', and J1939NM_E_INVALID_PRIO for 'priority'.

The J1939Nm shall calculate a random number for delaying bus off recovery and transmission of a CannotClaimAddress PG. The calculation shall use the NAME of a node as seed.

When J1939Nm_GetBusOffDelay is called, J1939Nm shall return a random number based on the NAMEs of all nodes attached to the reported channel. This random number gives the delay time, based on the ticktime configured via J1939NmBusOffDelayTickPeriod.

If gateway support is enabled via J1939NmGatewaySupport, and the configuration contains a J1939NmSharedAddressSpace, the J1939Nm shall transmit all AddressClaimed messages received on one of the channels referenced by J1939NmSharedAddressSpace on all other channels referenced by the same J1939NmSharedAddressSpace.

If gateway support is enabled via J1939NmGatewaySupport, and the configuration contains a J1939NmExternalNode, the channels referenced by J1939NmExternalNodeGatewayedChannelRef shall be treated like internal node channels, with the difference that the state transition from SleepMode to NetworkMode is triggered by the reception of an AddressClaimed message from the external node and enters NormalOperation immediately, and the transition to SleepMode is triggered by the reception of a CannotClaimAddress message from the same node.

The J1939 Network Management module shall use a meta data item of type CAN_ID_32 to provide the source address of transmitted AddressClaimed and CannotClaimAddress PGs. The source address resides in the last (least significant) byte of the meta data item.

The J1939 Network Management module shall use a meta data item of type CAN_ID_32 to determine the source address of received AddressClaimed and CannotClaimAddress PGs. The source address resides in the last (least significant) byte of the meta data item.