AUTOSAR NM CAN 3.3.0

Start Page

General

Specifications

With the specification CAN Network Management (version 3.3.0 of 2011-04-07), AUTOSAR (www.autosar.org) has defined a way to coordinate the transition between normal operation and bus-sleep mode of a CAN network.
  • AUTOSAR Specification of Generic Network Management Interface V1.2.0
  • AUTOSAR Specification of CAN Network Management V3.3.0

About this Document

Sample Configurations

This document describes the functions for AUTOSAR Network Management (NM) protocol, that are implemented via DLL file in Vector CANoe version starting with 7.5 SP4. These functions allow nodes simulated by CANoe to interact with hardware nodes attached to a CAN network.

In order to demonstrate the usage of the network management, a respective sample configuration with an current DLL (version 3.3.0) is installed along with CANoe:

  • Introduction
  • Overview of Sample Configurations

Name of the DLL

Distribution Restrictions

This DLL is delivered together with the CANoe installation:

  • AUTOSAR Network Management CAN 3.3.0 functions (ASRNM33.dll)

AUTOSAR standards may only be used by members of the AUTOSAR organization. Therefore this DLL may only be distributed to those eligible.

Basics

INI Files
  • Introduction for Add-ons
  • Assigning of DLL Files
  • CANdb Attributes
  • State Diagram
  • Introduction
  • Global Parameters
  • Node Specific Parameters
  • Usage of Partial Networking
  • Default INI Content

Function Availability

Function Overview
  • Supported Features
  • CAPL Functions
  • CAPL Callback Functions
FAQ

FAQ

Contact Vector Informatik GmbH if your concrete use case is not yet supported, and provide information on what you would like to do. You can also ask for newer versions of the DLL.

Disclaimer

  • The customer may only use the programs for Automotive Applications as defined in the AUTOSAR Premium Member Agreement („Automotive Applications means applications related to engine powered, land-based, non-railed vehicles for primary transportation purposes“).

AUTOSAR UDP NMAUTOSAR NM CAN 3.3.0
© Vector Informatik GmbH


Supported Features

AUTOSAR NM CAN 3.3.0 » Supported Features

Feature | Short Description
Configuration via database | The NM nodes are configured by assigning a CANdb database node to a simulation node in the CANoe Simulation Setup. The same attributes used for generating embedded ECU software are used.
Feature selection from INI file | Global settings for timeouts, counters, message format, and advanced features, additional node configuration can be specified in an INI file for every network. Additional INI files can be created for specific CANoe configurations.
Communication control | It is possible to enable and disable the sending of NM messages, as necessary for the ISO14229 Communication Control service.
Passive mode | A simulation node can be put into passive mode, i.e. though it will not send any NM messages, the NM state is still available.
Busload reduction | This optional feature can be activated in the INI file.
Immediate restart | If activated in the INI file, requesting the network during Prepare-Bus-Sleep will send a NM message immediately.
Active wake-up bit | A particular bit in the NM message is set to 1 for the node whose request leads to a network start.
Partial networking | Nodes can be configured to compose partial networks or interact with them, by receiving and sending partial network requests within the NM messages. These partial networks can be woken and shut down individually.
Car wake-up | It is possible to define a car wake-up bit which triggers a special indication.
Spontaneous transmissions | The sending of NM messages can be triggered spontaneously, e.g. to transmit user data without delay.
Immediate NM messages | If activated, nodes will send multiple NM messages in short intervals when in certain situations.
Message format | It is possible to configure the length of the CAN message and the positions of the NM node identifier and the control bit vector in the message. Also, the position of car wake-up and partial networking bits can be defined if these features are applied.
User data | The non-protocol bytes of the message can be used for the transfer of user data.


CANdb Attributes

AUTOSAR NM CAN 3.3.0 » Basics » CANdb Attributes

Introduction

The communication matrix of a CAN network is usually described by a CANdb database. It defines the nodes present on the network, and allows specification of their behavior by attributes.

Network attributes are assigned to the database as a whole, whereas node attributes define one particulate network node.

CANdb attributes are used to define NM parameters that are belonging to a certain CANoe configuration. Alternatively, a specific INI file may be used. Defining attributes in the database or in such a specific INI file allows multi-bus scenarios with different parameters.

Caution

Caution!

The mandatory (non-optional) attributes have to be defined and set correctly for the NM to work properly! The optional attributes may be absent, if the default values (from the INI file or computed by the DLL) should be used.
Caution

Caution!

If both a DBC database and a configuration specific INI file are used, parameters defined in the INI file override those defined in the database. Please mind the paragraph INI file Loading Sequence.

Cross Reference

For the usage of INI files and specific INI files in particular, see the corresponding pages.

Required Attributes

The following attributes are required by the node layer DLL and not included in the INI file by default. They must be defined either in the database or in of the INI files, or the measurement cannot be started!

For the meaning of the global parameters and node specific parameters , see the corresponding pages.

Attribute Name | Object | Type | Corresponding INI File Parameter | Description
NmAsrBaseAddress | Network | Hex | NM_BASE_ADDRESS | Possible CAN ID of first NM message
NmAsrMessageCount | Network | Integer | NM_MESSAGE_COUNT | Maximum number of NM nodes
NmAsrNodeIdentifier | Node | Hex | NM_NODE_IDENTIFIER | Node identifier
Note

Note

The CAN ID of the NM message a node sends is computed as
CAN ID := NmAsrBaseAddress + NmAsrNodeIdentifier

Only CAN messages with
NmAsrBaseAddress <= CAN ID < NmAsrBaseAddress + NmAsrMessageCount
are considered to be NM messages.

Optional Attributes

The following parameters are optional both in the database and in the INI files. Missing optional parameters will be initialized with computed default values. The INI file overwrites the values defined in the database.

Defining these attributes in the database allows multi-bus scenarios with different parameters.

For the meaning of the parameters, see the descriptions for INI file .

Attribute Name | Object | Type | Corresponding INI File Parameter
NmAsrCanMsgCycleTime | Network | Integer | CANNM_MSG_CYCLE_TIME
NmAsrTimeoutTime | Network | Integer | NM_TIMEOUT_TIME
NmAsrWaitBusSleepTime | Network | Integer | NM_WAIT_BUS_SLEEP_TIME
NmAsrRepeatMessageTime | Network | Integer | NM_REPEAT_MESSAGE_TIME
NmAsrCanMsgCycleOffset | Node | Integer | NM_CAN_MSG_CYCLE_ OFFSET Overwriting default value computed as NmAsrNodeIdentifier * NmAsrCanMsgCycleTime / NmAsrMessageCount
NmAsrCanMsgReducedTime | Node | Integer | NM_CAN_MSG_REDUCED_ TIME Overwriting default value computed as (128 + NmAsrNodeIdentifier) * NmAsrCanMsgCycleTime / 256
GenNWMSleepTime | Network | Integer | T_SLEEPTIME

Loading DLL via Database

Instead of assigning the DLL to a node in the Simulation Setup, it is possible to set the value of the string node attribute NodeLayerModules to ASRNM33.DLL. (See)


INI Files - Introduction

AUTOSAR NM CAN 3.3.0 » Basics » INI Files - Introduction

Main INI File

On measurement start, the DLL will read a number of parameters from the file AsrNM33.ini which is distributed along with this node layer DLL. Note that some values can be overwritten by CANdb attribute values. See

Note

Note

The file is searched at the path AsrNM33.dll is loaded from!

Specific INI Files

Besides the file AsrNM33.ini, a specific INI file may be created for each CAN network in a CANoe configuration, in order to override global settings, or to define node dependent parameters such as passive mode. Again, this allows multi-bus scenarios with different parameters.

Note

Note

The file is searched in the same directory as the CANoe configuration CFG file and must obey the naming rule:
[Network]_AsrNM33.INI, where [Network] denotes the name of the target CAN network in the configuration.

Important Note for CANoe RT Users

If you intend to use CANoe RT along with this node layer DLL, please mind that the possibility of transferring network specific INI files to the RT system is restricted by your CANoe version.

  • For CANoe 7.6 Service Pack 2 or higher, the transfer is done automatically.
  • For CANoe versions ranging from 7.5 to 7.6 (without Service Pack), the specific INI file must be added to the list of user files manually!
Note

Note

To add user files to your configuration, open the menu path Configuration|Options|Configuration Settings|User Files.

INI file Loading Sequence

Any of the two INI files is sufficient to run a configuration using AUTOSAR NM, as long as it holds all necessary parameters. However, if both are present for the loaded configuration, definitions in the specific INI file will take priority.

Note

Note

On measurement start, have a look at the Write Window to see which INI files were loaded for your configuration.

INI and DBC Files

Definitions in the specific INI file take precedence over definitions in the DBC database, leaving database usage optional. The lookup order for a parameter is as follows:

Procedure

Step by Step Procedure

  1. Specific INI file (if present)
  2. DBC database (if not found in the specific INI file)
  3. Main INI file (if not found in the database)

Concept Link Icon See Also


INI Files - Global Parameters

AUTOSAR NM CAN 3.3.0 » Basics » INI Files - Global Parameters

The following parameters are applied to the whole network. They can be defined in each of the possible INI files.

Note

Note

Parameters without a default value must be specified, unless they are defined in a DBC database.

Parameter

Section

Description

Default value

CANNM_MSG_CYCLE_TIME

[TIMER]

Period of the NM messages.

640 ms

NM_TIMEOUT_TIME

[TIMER]

In state Ready Sleep, the NM will wait this long before entering Prepare Bus-Sleep.

2000 ms

NM_WAIT_BUS_SLEEP_TIME

[TIMER]

In state Prepare Bus-Sleep, wait this long before entering Bus-Sleep.

1500 ms

NM_REMOTE_SLEEP_IND_TIME

[TIMER]

If a NM node has not received a NM message from another node for this long, it will signal Remote Sleep to the application.

1350 ms

NM_REPEAT_MESSAGE_TIME

[TIMER]

Defines how long the node stays in state Repeat Message.

3200 ms

T_SLEEPTIME

[TIMER]

Sleep timer for coupling between NM and interaction layer.

4000 ms

NM_IMMEDIATE_NM_CYCLE_TIME

[TIMER]

Reduced NM message period for the immediate transmissions feature.

100 ms

NM_PN_RESET_TIME

[TIMER]

Defines how long a PN is considered to be still requested after an NM message with bit set for the according PN (only relevant for indications and EIRA calculation).

2000 ms

NM_BASE_ADDRESS

[FEATURES]

CAN ID of first NM message.

—

NM_MESSAGE_COUNT

[FEATURES]

Maximum number of NM nodes.

—

NM_MESSAGE_FDF

[FEATURES]

If not 0, NM messages will be sent with FD Format indicator (FDF) equal to 1 (i.e. as CAN FD message).

0

NM_MESSAGE_BRS

[FEATURES]

If not 0, CAN FD NM message will be sent with Bit Rate Switch (BRS) equal to 1.

0

NM_TX_RX_MSG_ID_COMPUTATION_METHOD

[FEATURES]
  • 0: Tx NM message ID = NM base address + NM node identifier; Rx NM messages defined by range.
  • 1: Tx NM message and properties (FDF, BRS, DLC) derived from data base; Rx NM messages defined by range.
  • 2: Tx NM message ID = NM base address + NM node identifier; Rx NM messages derived from database.
  • 3: Tx NM message and properties (FDF, BRS, DLC) derived from data base; Rx NM messages derived from database.

0

NM_PN_EIRA_CALC_ENABLED

[FEATURES]

Defines if calculation of EIRA (External Internal Requests Aggregated) is enabled (1) or disabled (0). If enabled, there are also indications for request and release of PNs.

0

NM_PDU_LENGTH

[FEATURES]

Number of bytes of a NM message.

8

NM_PDU_NID_POSITION

[FEATURES]

Byte position of the node identifier in the NM message.

0

NM_PDU_CBV_POSITION

[FEATURES]

Byte position of the Control-Bit-Vector in the NM message.

1

NM_BUS_LOAD_REDUCTION_ENABLED

[FEATURES]

If not 0, the bus load reduction algorithm will be activated.

0

NM_IMMEDIATE_RESTART_ENABLED

[FEATURES]

If not 0, requesting the network during state Prepare-Bus-Sleep will send NM message immediately.

0

NM_IMMEDIATE_NM_TRANSMISSIONS

[FEATURES]

Defines the number of immediate NM PDUs which shall be transmitted (max. 255, 0 = deactivated).

0

NM_CAR_WAKEUP_RX_ENABLED

[FEATURES]

If not 0, the car wake-up indication is triggered when a car wake-up bit is received.

0

NM_CAR_WAKEUP_FILTER_ENABLED

[FEATURES]

If not 0, the car wake-up bit will be ignored unless received from a specified node ( node specific parameters ).

0

NM_CAR_WAKEUP_FILTER_NODE_ID

[FEATURES]

The node ID of the target node for the car wake-up filter (required for filtering).

—

NM_CAR_WAKEUP_BYTE_POSITION

[FEATURES]

Byte position of the car wake-up bit. Must point to user data.

(off)

NM_CAR_WAKEUP_BIT_POSITION

[FEATURES]

Bit position of the car wake-up bit.

(off)

NM_PN_ENABLED

[FEATURES]

If not 0, nodes will read and write the partial networking information and apply the PN filtering algorithm.

0

NM_PN_INFO_OFFSET

[FEATURES]

Start byte of the PN request bits. Must point to user data.

—

NM_PN_INFO_LENGTH

[FEATURES]

Length of the PN information in bytes (max. 8).

—

NM_PN_FILTER_MASK

[FEATURES]

Binary filter mask for NM messages, where 1 denotes the membership to a partial network.

—

NM_PN_REQUEST_MASK

[FEATURES]

Binary filter mask for NM messages, where 1 denotes that a PN is requested by the nodes.

—

NM_PN_HANDLE_MULTIPLE_NETWORK_REQUESTS

[FEATURES]

If not 0, additional calls to Nm_NetworkRequest will make a node switch to repeat message state.

0
Note

Note

The user data will start directly after the node identifier or the Control Bit Vector (whichever is last) in the message and run until its end!
Caution

Caution!

The node identifier and the control bit vector cannot occupy the same byte in the message! If their value is <0 or >= the message length, the respective parameter will NOT be sent!

The same applies to car wake-up bit and PN info range. Additionally, both of them must be located within the user data.

If no car wake-up bit position respectively PN info range is specific, the particular feature is completely deactivated!


INI Files - Node Specific Parameters

AUTOSAR NM CAN 3.3.0 » Basics » INI Files - Node Specific Parameters

For advanced NM configurations, some parameters can be assigned to a specific node only. To achieve this, a new section must be added to the INI file that is named exactly as the node is named in the CANdb database, or, in case no database node is assigned, as the node is titled in the Simulation Setup.

Like the global parameters, these can be defined in any of the two possible INI files.

Note

Note

Node specific parameters always depend on a CANoe configuration, respectively a CANdb database. It is highly recommended to store these in a network-specific INI file, and keep only the global configuration in the main INI file.
Note

Note

Most of the node specific parameters are global parameters as well. If any of them is defined both in global and local context, only the local value will be applied. It is therefore possible to configure defaults, which may be overridden by a node’s individual parameters.

Section [<Node Name>] | Description | Default value
NM_PASSIVE_MODE | If not 0, node will be in passive mode. | 0
NM_NODE_IDENTIFIER | Node identifier – must be specified, unless defined in a DBC database. | —
NM_CAN_MSG_CYCLE_OFFSET | Delay of the first NM message. Default computed as NmAsrNodeIdentifier * NmAsrCanMsgCycleTime / NmAsrMessageCount | see left
NM_CAN_MSG_REDUCED_TIME | Reduced cycle time when bus load reduction is active. Default computed as (128 + NmAsrNodeIdentifier) * NmAsrCanMsgCycleTime / 256 | see left
NM_ALL_NM_MESSAGES_KEEP_AWAKE | If not 0, this node will stay awake on any kind of NM message, disregarding the partial network information. | 0
NM_MESSAGE_FDF | If not 0, NM messages will be sent with FD Format indicator (FDF) equal to 1 (i.e. as CAN FD message). | n.a.
NM_MESSAGE_BRS | If not 0, CAN FD NM message will be sent with Bit Rate Switch (BRS) equal to 1. | n.a.
NM_MESSAGE_ID | If defined, the value will be taken as NM message ID for this node (use x at the end for an extended CAN ID). | n.a.
NM_CAR_WAKEUP_RX_ENABLED | global parameters | n.a.
NM_CAR_WAKEUP_FILTER_ENABLED | global parameters | n.a.
NM_CAR_WAKEUP_FILTER_NODE_ID | global parameters | n.a.
NM_PN_ENABLED | global parameters | n.a.
NM_PN_FILTER_MASK | global parameters | n.a.
NM_PN_REQUEST_MASK | global parameters | n.a.
NM_PN_HANDLE_MULTIPLE_NETWORK_REQUESTS | global parameters | n.a.


INI Files - Usage of Partial Networking

AUTOSAR NM CAN 3.3.0 » Basics » INI Files - Usage of Partial Networking

Introduction

This section provides more information about configuration and usage of the partial networking (PN) feature.

Configuration Rules

To use partial networking in your configuration, these rules must be followed, by editing the INI files accordingly:

  • A filter mask and a request mask must be available for every node that shall use PN (either through global default or in local scope). If one or both of them are missing, NM_PN_ENABLED will have no effect on this node.
  • The length of filter and request masks must always match NM_PN_INFO_LENGTH, i.e. (NM_PN_INFO_LENGTH * 8) bits must be supplied. Binary representation must be used, e.g.:
    NM_PN_FILTER_MASK=10001010
  • The position of the partial networking info range (denoted here as the request bits) must be correctly configured using the respective parameters.
Note

Note

A node may belong to multiple partial networks, and also request multiple partial networks. As for the latter, the parameter NM_PN_REQUEST_MASK only denotes the behaviour upon measurement start. The request bits may then be changed by CAPL code (Modification of User Data). PN membership, however, as defined by NM_PN_FILTER_MASK, is considered a constant.

Restrictions

The specification states the following dependencies between parameters:

  • NM_PN_HANDLE_MULTIPLE_NETWORK_REQUEST shall only be set when NM_PN_ENABLED is set. (This is not checked by the module.)
  • If NM_PN_HANDLE_MULTIPLE_NETWORK_REQUESTS is set, then NM_IMMEDIATE_NM_TRANSMISSIONS must be > 0.
  • If NM_PN_ENABLED is set, then usage of the CBV is mandatory, i.e. a valid value must be supplied for NM_PDU_CBV_POSITION.
Note

Note

Please make sure none of these restrictions are violated for the node layer DLL to function properly. A warning message in the Write Window will inform you in case of inconsistencies.

Notes for PN Usage

  • As the PN request bits reside in user data, the CAPL function Nm_SetUserData should be used with care as it can disturb the PN request bits.
  • If NM_PN_ENABLED is set, nodes will only process those messages with the partial network information bit set in the CBV. The combination of nodes which use PN and nodes which don’t may thus lead to unexpected behavior.
  • According to the specification, the software module is responsible to call Nm_NetworkRequest after any change to the request bits. This is not done by the node layer and must be handled by the node’s CAPL code.


INI Files - Default INI Content

AUTOSAR NM CAN 3.3.0 » Basics » INI Files - Default INI Content

Default AsrNM33.INI content

; AUTOSAR NM - CANoe node layer DLL configuration file
; V3.3.2

[FEATURES]
; Reduce NM message load in normal operation state
NM_BUS_LOAD_REDUCTION_ENABLED=0

; If 1, node will send NM message immediately when network is requested during prepare sleep [CNM035]
NM_IMMEDIATE_RESTART_ENABLED=0

; Number of bytes in the CAN message
NM_PDU_LENGTH=6

; Location of the NM id within the NM message
NM_PDU_NID_POSITION=0

; Location of the Control Bit Vector in the NM message
NM_PDU_CBV_POSITION=1

; Is car Wakeup enabled?
NM_CAR_WAKEUP_RX_ENABLED=0

; Position of car wake-up bit in user data
NM_CAR_WAKEUP_BYTE_POSITION=2
NM_CAR_WAKEUP_BIT_POSITION=0

; Partial networking configuration
NM_PN_ENABLED=0
NM_PN_INFO_OFFSET=3
NM_PN_INFO_LENGTH=2
NM_PN_HANDLE_MULTIPLE_NETWORK_REQUESTS=0

; Number of immediate NM transmissions
NM_IMMEDIATE_NM_TRANSMISSIONS=0

; All times are in milli seconds!

[TIMER]
; The NM frame should be sent with this period.
CANNM_MSG_CYCLE_TIME=640

; If Passive, wait this long before going to Prepare Sleep state.
NM_TIMEOUT_TIME=2000

; If Prepare Sleep, wait this long before going to Sleep state.
NM_WAIT_BUS_SLEEP_TIME=1500

; Use this interval when detecting remote sleep (0: off)
NM_REMOTE_SLEEP_IND_TIME=1350

; Stay in Repeat Message for this long
NM_REPEAT_MESSAGE_TIME=3200

; Cycle time for immediate transmissions
NM_IMMEDIATE_NM_CYCLE_TIME=100

Note

Note

For an example of an advanced parameter set using partial networks, please refer to the file CAN_AsrNM33.INI which is provided along with the AUTOSAR CAN NM sample configuration.


State Diagram

AUTOSAR NM CAN 3.3.0 » Basics » State Diagram

Introduction

This diagram is a simplified version of the state diagram shown in the specification. It denotes possible state transitions for NM nodes, triggers for such transitions as well as the corresponding callback functions. Transition triggers are denoted in green letters, and also in bold green letters if the trigger is a CAPL function.

State Diagram

Note

Note

The non-standard callbacks Nm_ControlBitVectorInd(), Nm_StateChangeNotification() and Nm_PreSendInd() are not shown in the diagram, as they are available independently of the node state.


Function Overview

AUTOSAR NM CAN 3.3.0 » Functions » Function Overview

Shortcuts CAPL Functions | Shortcuts CAPL Callback Functions
NM Control | Network Mode Indications
NM Configuration | Notification of State Change
NM State | NM Event Indications
Node Information | NM Message Reception and Sending
Modification of User Data |
Communication Control |
Non-Standard Functionality |
DLL Configuration |
Coupling between NM and Interaction Layer |
Fault Injection |

CAPL Functions

Additional Functions

These functions are implemented in the DLL and can be called in CAPL programs.
Note that all functions start with the prefix Nm_.

Return Values

All functions returning long values indicate the success by returning
1 (OK), or a positive value indicating the requested information.
0 indicates that the action could not be executed; exceptions are described at the functions.

NM Control [▲ back]

Functions | Short Description
Nm_NetworkRequest | Indicate that the Nm node needs the network.
Nm_NetworkRelease | Indicate that the NM node doesn’t need the network.
Nm_PassiveStartUp | Make the NM leave the Bus-Sleep mode and enter the Repeat Message state.
Nm_RepeatMessageRequest | Make the NM leave Normal Operation or Ready Sleep state.
Nm_RequestBusSynch | Send a NM message immediately to resynchronize all NM timeouts in the nodes on the network.
Nm_Transmit | Send a NM message immediately and restart the NM cycle timer.

NM Configuration [▲ back]

Functions | Short Description
Nm_EnablePassiveMode | Start using the passive mode.
Nm_DisablePassiveMode | Stop using the passive mode.
Nm_EnablePartialNetworking | Start using partial networking for this node.
Nm_DisablePartialNetworking | Stop using partial networking for this node.
Nm_SetAutoStartParam | Define the behavior of NM at measurement start.
Nm_ActivateBusLoadReduction | Start using the bus load reduction algorithm.
Nm_DeactivateBusLoadReduction | Stop using the bus load reduction algorithm.

NM State [▲ back]

Functions | Short Description
Nm_GetState | The returned value indicates the NM state the node is currently in.
Nm_GetNodeIdentifier | Get the NM identifier of the node that sent the last received NM message.
Nm_GetUserData | Copy the user data of the last received NM message into the output buffer.
Nm_GetPduData | Copy the last received NM message completely into the buffer.
Nm_CheckRemoteSleepInd | Check if remote sleep has been detected.
Nm_GetNodeState | Check if the node with the given NM identifier has sent a NM message the last time the network was in Repeat Message state.
Nm_GetRequestState | The returned value indicates the NM request state the node is currently in.
Nm_IsPnCurrentlyRequested | This function allows to retrieve information about the status of a certain partial network.
Nm_GetPnCurrentInternalRequestBits | This function allows to retrieve information about the internal request status of all partial networks.
Nm_GetPnCurrentExternalRequestBits | This function allows to retrieve information about the external request status of all partial networks.

Node Information [▲ back]

Functions | Short Description
Nm_GetLocalNodeIdentifier | Return the NM identifier of this node.
Nm_GetNodeName | The CANdb name of this node is copied into the provided buffer.
Nm_GetPnRequestBitsDefault | The default partial network request bits (the PN info range) of this node are copied into the provided buffer.
Nm_GetPnAffilation | When using partial networking, a node filters NM messages according to the request mask of the message and its own filter mask.
Nm_IsPnEnabled | This function allows to retrieve information about whether partial networking is currently switched on or off for this node.

Modification of User Data [▲ back]

Functions | Short Description
Nm_SetUserData | Set the user data this node sends in its NM message to the byte sequence given.
Nm_SetCarWakeUpBit | Modify the car wake-up bit in the user data.
Nm_SetPnRequestBits | Set the partial network request bits (the PN info range) within the user data.

Communication Control [▲ back]

Functions | Short Description
Nm_DisableCommunication | Turn the sending of NM messages off.
Nm_EnableCommunication | Turn the sending of NM messages on.

Non-Standard Functionality [▲ back]

Functions | Short Description
Nm_SetControlBitVector | This function allows setting the Control Bit Vector byte sent by this node to any value.

DLL Configuration [▲ back]

Functions | Short Description
Nm_GetDLLInfo | Return additional information about the DLL.
Nm_SetVerbosity | Set the DLL’s verbosity.
Nm_CtrlSimulationOff | This function will turn off the complete NM simulation by the DLL.
Nm_CtrlSimulationOn | This function will turn on the complete NM simulation by the DLL.

Coupling between NM and Interaction Layer [▲ back]

Functions | Short Description
Nm_SetApplicationActivity | This function sets the NM’s application activity.
Nm_SetILSleepTime | This function changes the value for next reinitialization of the sleep timer.
Nm_ReinitSleepTimer | This function reinitializes the timer until NM releases the network.
Nm_ConfigureILNotifications | This function influences the coupling between NM and IL.

Fault Injection [▲ back]

Functions | Short Description
NmFI_IgnoreRepeatMessageBit | Defines the reaction upon received repeat message bit.

CAPL Callback Functions

Introduction

The CAPL program has to define these optional functions (marked with the postfix Ind or Notification) to receive indications about NM events like the reception of a PDU, or a state transition.

Network Mode Indications [▲ back]

Functions | Short Description
Nm_NetworkModeInd | This function indicate that the NM has entered the respective mode.
Nm_BusSleepModeInd | This function indicate that the NM has entered the respective mode.
Nm_PrepareBusSleepModeInd | This function indicate that the NM has entered the respective mode.

Notification of State Change [▲ back]

Functions | Short Description
Nm_StateChangeNotification | Every time the NM state machine changes from one state to another, this function will be called if it is defined.

NM Event Indications [▲ back]

Functions | Short Description
Nm_NetworkStartInd | A NM message has been received while the node is in Bus-Sleep mode.
Nm_RemoteSleepInd | Remote sleep indication.
Nm_PNRequestInd | Indication that a certain partial network is now requested.
Nm_PNReleaseInd | Indication that a certain partial network was released.

NM Message Reception and Sending [▲ back]

Functions | Short Description
Nm_PduRxInd | A call to this function indicates the reception of a NM message from another node.
Nm_PduRxInd2 | A call to this function indicates the reception of a NM message from another node.
Nm_ControlBitVectorInd | This function is called if a NM message with a non-zero Control-Bit-Vector is received.
Nm_PreSendInd | Directly before sending a NM message on the bus, this function is called to allow the CAPL program to change the actual message sent.
Nm_CarWakeUpInd | A call to this function indicates the reception of a NM message that has the car wake-up bit set.


Nm_NetworkRequest

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Control » Nm_NetworkRequest

Syntax

long Nm_NetworkRequest( )

Function

Indicate that the NM node needs the network.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup


Nm_NetworkRelease

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Control » Nm_NetworkRelease

Syntax

long Nm_NetworkRelease( )

Function

Indicate that the NM node doesn’t need the network, and allows it to enter Bus-Sleep mode.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_PassiveStartUp

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Control » Nm_PassiveStartUp

Syntax

long Nm_PassiveStartUp( )

Function

Make the NM leave the Bus-Sleep mode and enter the Repeat Message state, without actually requesting the bus.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_RepeatMessageRequest

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Control » Nm_RepeatMessageRequest

Syntax

long Nm_RepeatMessageRequest( )

Function

Make the NM leave Normal Operation or Ready Sleep state and enter Repeat Message state, and set the repeat message bit.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_RequestBusSynch

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Control » Nm_RequestBusSynch

Syntax

long Nm_RequestBusSynch( )

Function

Send a NM message immediately to resynchronize all NM timeouts in the nodes on the network. The NM cycle timer is not restarted, i.e. the message is sent independently of the NM message cycle.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_Transmit

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Control » Nm_Transmit

Note

Note

The original purpose of Nm_Transmit( ) is to rapidly transmit user data on change. To emulate this behavior, always call Nm_Transmit( ) after a call to Nm_SetUserData( ), Nm_SetPnRequestBits( ) or Nm_SetCarWakeUpBit( ).

Syntax

long Nm_Transmit( )

Function

Send a NM message immediately and restart the NM cycle timer.

Parameters

—

Return Values

The specification defines that Nm_Transmit shall only be available under certain conditions. This is indicated by the return value:

  • 0: not executed (sending not possible because of the node state)
  • 1: OK
  • 2: feature is not activated (non-standard behaviour)
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_EnablePassiveMode

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Configuration » Nm_EnablePassiveMode

Note

Note

These function is only available during Bus-Sleep!

Syntax

long Nm_EnablePassiveMode( )

Function

Start using the passive mode: During Bus-Sleep, a node may be put into passive mode, or back to active mode. In passive mode, the node will then never send NM messages, but receive the NM messages from other nodes and compute the network’s state accordingly.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_DisablePassiveMode

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Configuration » Nm_DisablePassiveMode

Note

Note

These function is only available during Bus-Sleep!

Syntax

long Nm_DisablePassiveMode( )

Function

Stop using the passive mode: During Bus-Sleep, a node may be put into passive mode, or back to active mode. In passive mode, the node will then never send NM messages, but receive the NM messages from other nodes and compute the network’s state accordingly.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_EnablePartialNetworking

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Configuration » Nm_EnablePartialNetworking

Syntax

long Nm_EnablePartialNetworking( )

Function

Start using partial networking for this node. All relevant parameters must be available (INI Files Partial Network) or the function call will fail. Please also consider the restrictions stated in that section when activating the PN feature from CAPL.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_DisablePartialNetworking

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Configuration » Nm_DisablePartialNetworking

Note

Note

Nm_DisablePartialNetworking( ) will not reset the PN request bits. They will, however, no longer be interpreted by other nodes.

Syntax

long Nm_DisablePartialNetworking( )

Function

Stop using partial networking for this node. All relevant parameters must be available (INI Files Partial Network) or the function call will fail. Please also consider the restrictions stated in that section when activating the PN feature from CAPL.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_SetAutoStartParam

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Configuration » Nm_SetAutoStartParam

Note

Note

The default behavior (i.e. when Nm_SetAutoStartParam is omitted) is analogous to Nm_SetAutoStartParam(2).

Syntax

void Nm_SetAutoStartParam(dword autoStartParam)

Function

Define the behavior of NM at measurement start. If used at all, the function must be called within the on preStart event handler of a CAPL Program.

Parameters

autoStartParam: determines the start up behavior

  • 0: No automatic network request at measurement start by NM (network requests via CAPL or from the interaction layer might still lead to a transition into repeat message at measurement start)
  • 1: Automatic network request at measurement start
  • 2: Automatic network request if interaction layer is present, no automatic network request in case interaction layer is absent

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.10

CANoe

—

Node Context in the


Nm_ActivateBusLoadReduction

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Configuration » Nm_ActivateBusLoadReduction

Note

Note

It is possible to define the initial behavior in the INI files, but the function calls will take precedence.

Syntax

long Nm_ActivateBusLoadReduction( )

Function

Start using the bus load reduction algorithm.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_DeactivateBusLoadReduction

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Configuration » Nm_DeactivateBusLoadReduction

Note

Note

It is possible to define the initial behavior in the INI files, but the function calls will take precedence.

Syntax

long Nm_DeactivateBusLoadReduction( )

Function

Stop using the bus load reduction algorithm.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetState

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetState

Syntax

long Nm_GetState( )

Function

The returned value indicates the NM state the node is currently in.

Parameters

—

Return Values
  • 0: NM_STATE_UNINIT
  • 1: NM_STATE_BUS_SLEEP
  • 2: NM_STATE_PREPARE_BUS_SLEEP
  • 3: NM_STATE_READY_SLEEP
  • 4: NM_STATE_NORMAL_OPERATION
  • 5: NM_STATE_REPEAT_MESSAGE
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetNodeIdentifier

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetNodeIdentifier

Syntax

long Nm_GetNodeIdentifier( )

Function

Get the NM identifier of the node that sent the last received NM message.

Parameters

—

Return Values
  • 0x00 .. 0xFF: node identifier
  • -1: error (e.g. no message has been received so far, function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetUserData

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetUserData

Syntax

long Nm_GetUserData(BYTE dataOut[], dword bufferLen)

Function

Copy the user data of the last received NM message into the output buffer.

Parameters
  • dataOut
    Output buffer for the user data.
  • bufferLen
    Size of the output buffer.

Return Values
  • >=0: number of bytes copied
  • -1: error (e.g. no message has been received so far, function is called in 'on preStart' or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetPduData

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetPduData

Syntax

long Nm_GetPduData(BYTE pduOut[], dword bufferLen)

Function

Copy the last received NM message completely into the buffer.

Parameters
  • dataOut
    Output buffer for the user data.
  • bufferLen
    Size of the output buffer.

Return Values
  • >=0: number of bytes copied
  • -1: error (e.g. no message has been received so far, function is called in 'on preStart' or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_CheckRemoteSleepInd

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_CheckRemoteSleepInd

Syntax

long Nm_CheckRemoteSleepInd( )

Function

Check if remote sleep (all nodes except this one allow transition to Bus-Sleep) has been detected, i.e. this node is the last one keeping the bus awake.

Parameters

—

Return Values
  • 1: remote sleep is indicated
  • 0: remote sleep is not indicated

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetNodeState

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetNodeState

Note

Note

The usage of partial networking influences the capability to detect nodes. In consequence nodes may remain undetected.

Syntax

long Nm_GetNodeState(dword nodeId)

Function

Check if the node with the given NM identifier has sent a NM message the last time the network was in Repeat Message state. Precondition for retrieval of meaningful information in a node is a preceding call of the function Nm_RepeatMessageRequest and the completion of the subsequent repeat message phase.

Parameters
  • nodeId
    Target node ID, range 0x00 – 0xFF

Return Values
  • 2: information is not (yet) available (e.g. node detection not started or ongoing)
  • 1: target node has been detected
  • 0: target node has not been detected
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetRequestState

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetRequestState

Syntax

long Nm_GetRequestState( )

Function

The returned value indicates the NM request state the node is currently in.

Parameters

—

Return Values
  • 0: NM_REQUEST_STATE_RELEASED
  • 1: NM_REQUEST_STATE_REQUESTED
  • 2: NM_REQUEST_STATE_PASSIVE
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.9

CANoe

—

Node Context in the


Nm_IsPnCurrentlyRequested

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_IsPnCurrentlyRequested

Note

Note

This function works only if parameter NM_PN_EIRA_CALC_ENABLED is set to 1.

Syntax

long Nm_IsPnCurrentlyRequested(long partialNetworkId, long flags)

Function

This function allows to retrieve information about the status of a certain partial network. Thereby it is possible to differentiate between the scope of the node and the network scope.

Parameters
  • partialNetworkId
    Specifies for which partial network the status information should be retrieved.
  • flags
    0: local scope, i.e. consider only partial networks relevant for the node (result depends on filter mask)
    1: network wide scope

Return Values
  • -1: error (e.g. illegal partial network, function is called in on preStart or protocol engine is inactive)

In all other cases the return value has to be interpreted bitwise.

Bit 0

  • 0: current node does not request partial network itself
  • 1: current node requests partial network itself

Bit 1

  • 0: other nodes do not request partial network
  • 1: at least one other node requests partial network

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.21

CANoe

—

Node Context in the


Nm_GetPnCurrentInternalRequestBits

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetPnCurrentInternalRequestBits

Note

Note

This function works only if parameter NM_PN_EIRA_CALC_ENABLED is set to 1.

Syntax

long Nm_GetPnCurrentInternalRequestBits(BYTE bufferOut[], dword bufferSize, dword numberOfBitsOut []))

Function

This function allows to retrieve information about the internal request status of all partial networks. Information about a single partial network can be retrieved via function Nm_IsPnCurrentlyRequested.

Parameters
  • bufferOut
    Byte array in which the request status of the partial networks will be written.
  • bufferSize
    Size of the byte array in number of bytes.
  • numberOfBitsOut
    Number of bits needed and/or written to the byte array.

Return Values
  • 1: OK
  • 0: not executed (e.g. partial networking not available)
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.21

CANoe

—

Node Context in the


Nm_GetPnCurrentExternalRequestBits

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM State » Nm_GetPnCurrentExternalRequestBits

Note

Note

This function works only if parameter NM_PN_EIRA_CALC_ENABLED is set to 1.

Syntax

long Nm_GetPnCurrentExternalRequestBits(long flags, byte bufferOut[], dword bufferSize, dword numberOfBitsOut []))

Function

This function allows to retrieve information about the external request status of all partial networks. Information about a single partial network can be retrieved via function Nm_IsPnCurrentlyRequested.

Parameters
  • flags
    0: local scope, i.e. consider only partial networks relevant for the node (result depends on filter mask)
    1: network wide scope
  • bufferOut
    Byte array in which the request status of the partial networks will be written.
  • bufferSize
    Size of the byte array in number of bytes.
  • numberOfBitsOut
    Number of bits needed and/or written to the byte array.

Return Values
  • 1: OK
  • 0: not executed (e.g. partial networking not available)
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.21

CANoe

—

Node Context in the


Nm_GetLocalNodeIdentifier

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Node Information » Nm_GetLocalNodeIdentifier

Syntax | dword Nm_GetLocalNodeIdentifier( )
Function | Return the NM identifier of this node.
Parameters | —
Return Values | Node identifier, range 0x00 – 0xFF
Availability | Since Version | Restricted To | Measurement Setup | Simulation / Test Setup
 | CANoe 7.5 SP4 + DLL 3.3.0 | CANoe | — | Node Context in the Simulation Setup


Nm_GetNodeName

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Node Information » Nm_GetNodeName

Syntax

void Nm_GetNodeName(char bufferOut[], dword bufferSize)

Function

The CANdb database name of this node is copied into the provided buffer.

Parameters
  • bufferOut
    Output buffer for the node name.
  • bufferSize
    Size of the output buffer.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetPnRequestBitsDefault

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Node Information » Nm_GetPnRequestBitsDefault

Note

Note

Nm_GetPnRequestBitsDefault( ) returns the request bits which would be used in case of a network request. These may deviate from the currently sent partial network request bits.

Syntax

long Nm_GetPnRequestBitsDefault( BYTE bufferOut[], dword bufferSize, dword pnRequestBitsLengthOut[])

Function

The default partial network request bits (the PN info range) of this node are copied into the provided buffer.

Parameters
  • bufferOut
    Output buffer for the PN request bits.
  • bufferSize
    Size of the output buffer.
  • pnRequestBitsLengthOut
    Number of bits in PN request mask.

Return Values
  • 1: OK
  • 0: not executed (partial networking is either not available (i.e. some relevant parameters have not been configured) or the buffer has an insufficient size)
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetPnAffiliation

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Node Information » Nm_GetPnAffiliation

Syntax

long Nm_GetPnAffiliation(long partialNetworkId)

Function

When using partial networking, a node filters NM messages according to the request mask of the message and its own filter mask. Via this function it is possible to retrieve information about the partial networks contained in the filter mask.

Parameters
  • partialNetworkId
    Specifies for which partial network the affiliation should be retrieved.

Return Values
  • 0: partial network not relevant for node
  • 1: partial network relevant for node
  • -1: error (e.g. illegal partial network, function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.21

CANoe

—

Node Context in the


Nm_IsPnEnabled

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Node Information » Nm_IsPnEnabled

Syntax

long NM_IsPnEnabled( )

Function

This function allows to retrieve information about whether partial networking is currently switched on or off for this node.

Parameters
    —

Return Values
  • 1: partial networking is switched on for this node
  • 0: partial networking is switched off for this node
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.23

CANoe

—

Node Context in the


Nm_SetUserData

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Modification of User Data » Nm_SetUserData

Note

Note

If the CAN message length or the protocol bytes’ positions are changed in the INI file, it is possible that no user data can be configured with this function! It may be possible to use the PreSend-callback to access the data sent, though.

If partial networking is used, this function will most likely disturb the partial network request bits within the user data.

Syntax

void Nm_SetUserData(BYTE userData[], dword count)

Function

Set the user data this node sends in its NM message to the byte sequence given, where only the bytes after node identifier or Control Bit Vector are changed.

Parameters
  • userData
    User data to be set.
  • bufferSize
    Length of the user data buffer (cannot exceed the configured user data length).

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_SetCarWakeUpBit

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Modification of User Data » Nm_SetCarWakeUpBit

Syntax

long Nm_SetCarWakeUpBit(long value)

Function

Modify the car wake-up bit in the user data. Is only available when the car wake-up bit is configured (else, 0 will be returned).

Parameters
  • value
    The desired boolean value (0 = false, >0 = true).

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_SetPnRequestBits

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Modification of User Data » Nm_SetPnRequestBits

Note

Note

According to the specification, the software module is responsible to call Nm_NetworkRequest() after any change to the request bits. This is not done by the node layer module and must be handled by the node’s CAPL code.

Syntax

long Nm_SetPnRequestBits(BYTE requestVector[])

Function

Set the partial network request bits (the PN info range) within the user data. All relevant parameters must be available (INI Files Partial Network) or the function call will fail.

Parameters
  • requestVector
    The desired PN request bits, which are interpreted bit-wise. Must have the same length as the configured PN info range.

Return Values
  • 1: OK
  • 0: not executed
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_DisableCommunication

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Communication Control » Nm_DisableCommunication

Note

Note

These functions are only available during Normal Operation state!

Syntax

long Nm_DisableCommunication( )

Function

Turn the sending of NM messages off. The node will proceed as if the sending of the messages succeeded, though. This is needed for the ISO14229 Communication Control service.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed (wrong NM state)
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_EnableCommunication

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Communication Control » Nm_EnableCommunication

Note

Note

These functions are only available during Normal Operation state!

Syntax

long Nm_EnableCommunication( )

Function

Turn the sending of NM messages on. The node will proceed as if the sending of the messages succeeded, though. This is needed for the ISO14229 Communication Control service.

Parameters

—

Return Values
  • 1: OK
  • 0: not executed (wrong NM state)
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_SetControlBitVector

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Non Standard Functionality » Nm_SetControlBitVector

Note

Note

The specification only defines the use of the Repeat Message bit, Partial Network Information bit and Active Wakeup bit. Setting other bits in the Control Bit Vector may lead to unexpected behavior of ECUs.

Syntax

void Nm_SetControlBitVector(dword controlBits)

Function

This function allows setting the Control Bit Vector byte sent by this node to any value.

Parameters
  • controlBits
    The desired CBV, which is interpreted bit-wise.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_GetDLLInfo

AUTOSAR NM CAN 3.3.0 » CAPL Functions » DLL Configuration » Nm_GetDLLInfo

Syntax

dword Nm_GetDLLInfo(dword selector)

Function

Return additional information about the DLL.

Parameters
  • selector
    Selects different return values (see below).

Return Values
  • selector = 0: The DLL’s file version as BCD, e.g. 0x010203 for V1.2.3
  • selector = 1: The DLL’s major version
  • selector = 2: The DLL’s minor version
  • selector = 3: The DLL’s build number

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_SetVerbosity

AUTOSAR NM CAN 3.3.0 » CAPL Functions » DLL Configuration » Nm_SetVerbosity

Syntax

dword Nm_SetVerbosity(dword selector)

Function

Set the DLL’s verbosity. The higher the value, the more information is printed in the Write Window.

Parameters

level: The desired verbosity level.

  • 0: Report only critical errors
  • 1: Report errors resulting from misconfiguration etc.
  • 2: Warn if an unexpected protocol state is reached and report missing mandatory callbacks
  • 3: Inform of missing optional callbacks and minor issues
  • >3: Report low-level events like timer setup and expiration

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_CtrlSimulationOff

AUTOSAR NM CAN 3.3.0 » CAPL Functions » DLL Configuration » Nm_CtrlSimulationOff

Note

Note

If you turn on the simulation again, the bus state Network Released is assumed. If you desire the bus to be requested, then you have to call Nm_NetworkRequest( ) explicitly.

Syntax

long Nm_CtrlSimulationOff( )

Function

This function will turn off the complete NM simulation by the DLL. While the NM simulation is off, any API call (except Nm_CtrlSimulationOn()) will not have any effect and the DLL will not sent any NM messages!

Parameters

—

Return Values
  • 1: OK
  • 0: not executed

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.0.5

CANoe

—

Node Context in the


Nm_CtrlSimulationOn

AUTOSAR NM CAN 3.3.0 » CAPL Functions » DLL Configuration » Nm_CtrlSimulationOn

Note

Note

If you turn on the simulation again, the bus state Network Released is assumed. If you desire the bus to be requested, then you have to call Nm_NetworkRequest( ) explicitly.

Syntax

long Nm_CtrlSimulationOn( )

Function

This function will turn on the complete NM simulation by the DLL. While the NM simulation is off, any API call (except Nm_CtrlSimulationOn()) will not have any effect and the DLL will not sent any NM messages!

Parameters

—

Return Values
  • 1: OK
  • 0: not executed

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.0.5

CANoe

—

Node Context in the


Nm_SetApplicationActivity

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Coupling between NM and Interaction Layer » Nm_SetApplicationActivity

Syntax

long Nm_SetApplicationActivity(long isActive)

Function

This function sets the NM’s application activity. If the flag is set (isActive = 1) and the network is sleeping, nothing will happen. But if the network wakes up later, it will stay active until the flag is reset again. If the flag is set and the network is active, it will stay active until the flag is reset again.

Parameters

isActive

  • 0: no activity
  • 1: activity

Return Values
  • 1: OK
  • 0: not executed (no change of isActive)
  • -1: error (e.g. function is called in on preStart or protocol engine is inactive)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_SetILSleepTime

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Coupling between NM and Interaction Layer » Nm_SetILSleepTime

Syntax

long Nm_SetILSleepTime(dword timeMS)

Function

This function changes the value for next reinitialization of the sleep timer. An on-going timer is not influenced.

Parameters

timeMS: new value of the timer in milliseconds

Return Values
  • 1: OK
  • 0: not executed (no IL)
  • -1: error

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the


Nm_ReinitSleepTimer

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Coupling between NM and Interaction Layer » Nm_ReinitSleepTimer

Syntax | long Nm_ReinitSleepTimer(long isActive)
Function | This function reinitializes the timer until NM releases the network. Calling has no effect if there is no interaction layer.
Parameters | —
Return Values | —
Availability | Since Version | Restricted To | Measurement Setup | Simulation / Test Setup
 | CANoe 7.5 SP4 + DLL 3.3.0 | CANoe | — | Node Context in the Simulation Setup


Nm_ConfigureILNotifications

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Coupling between NM and Interaction Layer » Nm_ConfigureILNotifications

Note

Note

The usage of this function affects the behaviour of NM and IL heavily.

Syntax

long Nm_ConfigureILNotifications(dword direction, dword mode)

Function

This function influences the coupling between NM and IL. The coupling normally takes care of forwarding certain events automatically. Implementing CAPL callback functions of the IL and NM may break open this coupling.

Parameters

direction: specifies which events are affected

  • 0: Events from NM to IL (e.g. network mode indication)
  • 1: Events from IL to NM (e.g. network request due to clamp 15)

mode: specifies the according effect, the value is interpreted bitwise

Bit 0

  • 0: Open – events are not propagated automatically
  • 1: Fixed – events are propagated automatically even in case of according CAPL callback functions (does not work for direction = 1)

Bit 1

  • 0: —
  • 1: Default behavior – events are propagated if there is no according CAPL callback function (overwrites settings from Bit 0)

Bit 2

  • 0: NM is aware of an existing IL
  • 1: NM is unaware of an existing IL (independent of direction)

Return Values
  • 1: OK
  • 0: not executed (wrong parameter values or illegal combination)

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.15

CANoe

—

Node Context in the


NmFI_IgnoreRepeatMessageBit

AUTOSAR NM CAN 3.3.0 » CAPL Functions » Fault Injection » NmFI_IgnoreRepeatMessageBit

Syntax

void NmFI_IgnoreRepeatMessageBit(long value)

Function

Defines the reaction upon received repeat message bit.

Parameters
  • 0: normal behavior
  • 1: repeat message bit will be ignored

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.19

CANoe

—

Node Context in the


Nm_NetworkModeInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » Network Mode Indications » Nm_NetworkModeInd

Syntax

void Nm_NetworkModeInd( )

Function

This function indicate that the NM has entered the respective mode.

Parameters

—

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

The new mode is indicated in the Write Window.

void Nm_NetworkModeInd()
{
Write( "Nm_NetworkModeInd: Network Mode");
}


Nm_BusSleepModeInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » Network Mode Indications » Nm_BusSleepModeInd

Syntax

void Nm_BusSleepModeInd( )

Function

This function indicate that the NM has entered the respective mode.

Parameters

—

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

The new mode is indicated in the Write Window.

void Nm_BusSleepModeInd()
{
Write( "Nm_BusSleepModeInd: Sleep Mode");
}


Nm_PrepareBusSleepModeInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » Network Mode Indications » Nm_PrepareBusSleepModeInd

Syntax

void Nm_PrepareBusSleepModeInd( )

Function

These function indicate that the NM has entered the respective mode.

Parameters

—

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

The new mode is indicated in the Write Window.

void Nm_PrepareBusSleepModeInd()
{
Write( "Nm_PrepareBusSleepModeInd: Prepare Sleep Mode");
}


Nm_StateChangeNotification

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » Notification of State Change » Nm_StateChangeNotification

Syntax

void Nm_StateChangeNotification(long previousState, long currentState)

Function

Every time the NM state machine changes from one state to another, this function will be called if it is defined.

Parameters
  • previousState
    The NM state which is left.
  • currentState
    The NM state which is entered. (Please refer to the NM State functions for the table of values.)

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

Indicate the old and new state in the Write Window.

void Nm_StateChangeNotification( long previousState,
long currentState)
{
Write( "Nm_StateChangeNotification: From %d to %d"
, previousState, currentState);
}


Nm_NetworkStartInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » NM Event Indications » Nm_NetworkStartInd

Syntax

void Nm_NetworkStartInd( )

Function

A NM message has been received while the node is in Bus-Sleep mode. Typically Nm_PassiveStartUp( ) will be called to let the node enter Repeat-Message state.

Parameters

—

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

Call start-up function to change to Repeat Message state.

void Nm_NetworkStartInd()
{
Write( "Nm_NetworkStartInd: Network started");
Nm_PassiveStartUp();
}


Nm_RemoteSleepInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » NM Event Indications » Nm_RemoteSleepInd

Syntax

void Nm_RemoteSleepInd(long flag)

Function

If no other node on the network has sent a NM message for a configurable amount of time, this function is called with flag==1. If later another node’s NM message is seen on the network, this function is called again with flag==0.

Parameters

flag: The indication type:

  • 0: Indicates that Remote sleep state is left
  • 1: Indicates that Remote sleep state is entered

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.0.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

Indicate whether other nodes allow the network to go to sleep.

void Nm_RemoteSleepInd( long flag)
{
if( flag)
Write( "Nm_RemoteSleepInd: Other nodes ready to sleep");
else
Write( "Nm_RemoteSleepInd: Another node requests network");
}


Nm_PNRequestInd

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Event Indications » Nm_PNRequestInd

Note

Note

This indication will be only called if parameter NM_PN_EIRA_CALC_ENABLED is set to 1.

Syntax

void Nm_PNRequestInd(long partialNetworkId)

Function

Indication that a certain partial network is now requested. The indication will be only called if the partial network is included in the filter mask of the node.

Parameters
  • networkId
    Specifies which partial network was requested.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.21

CANoe

—

Node Context in the


Nm_PNReleaseInd

AUTOSAR NM CAN 3.3.0 » CAPL Functions » NM Event Indications » Nm_PNReleaseInd

Note

Note

This indication will be only called if parameter NM_PN_EIRA_CALC_ENABLED is set to 1.

Syntax

void Nm_PNReleaseInd(long partialNetworkId)

Function

Indication that a certain partial network was released. The indication is called as soon as a certain time elapsed without any NM message requesting the partial network. This time is specified with the parameter NM_PN_RESET_TIME.

Parameters
  • networkId
    Specifies which partial network was released.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.21

CANoe

—

Node Context in the


Nm_PduRxInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » NM Message Reception and Sending » Nm_PduRxInd

Note

Note

This callback will not work in case that the database has AUTOSAR 4.2 format or newer. Please use the callback Nm_PduRxInd2 for these database formats.

Syntax

void Nm_PduRxInd(dword canId, dword identifier, long bRepeatMessageBit, BYTE data[])

Function

A call to this function indicates the reception of a NM message from another node. The arguments are taken from the NM message directly.

Parameters
  • canId
    The CAN ID of the message.
  • identifier
    The NM source identifier in the NM message or 0, if the source identifier is not transferred.
  • bRepeatMessageBit
    1 if the Repeat-Message bit is set,
    0 otherwise.
  • data
    The message’s data bytes including the protocol bytes.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

Report the NM message received in the Write Window.

void Nm_PduRxInd( dword canId, dword identifier,
long bRepeatMessageBit, BYTE data[])
{
Write( "Nm_PduRxInd: CAN ID=0x%x, NM id=%d, RM=%d, %d byte"
, canId, identifier, bRepeatMessageBit, elcount(data) );
}


Nm_PduRxInd2

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » NM Message Reception and Sending » Nm_PduRxInd2

Note

Note

This callback will only work in case that the database has AUTOSAR 4.2 format or newer. Please use the callback Nm_PduRxInd for other database formats.

Syntax

void Nm_PduRxInd2(dword busContext, dword shortId, dword longId, char name[], dword sourceNodeIdentifier, long repeatMessageBit, BYTE data[])

Function

A call to this function indicates the reception of a NM message from another node. The arguments are taken from the NM message directly.

Parameters
  • busContext
    Bus context of the node layer calling this function.
  • shortId
    Short header ID of the AUTOSAR PDU.
  • longId
    Long header ID of the AUTOSAR PDU.
  • name
    Name of the AUTOSAR PDU.
  • sourceNodeIdentifier
    The NM source identifier in the NM message or 0, if the source identifier is not transferred.
  • bRepeatMessageBit
    1: f the Repeat-Message bit is set
    0: otherwise
  • data
    The message’s data bytes including the protocol bytes.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 9.0 SP2
+ DLL 3.3.0

CANoe

—

Node Context in the Simulation Setup


Nm_ControlBitVectorInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » NM Message Reception and Sending » Nm_ControlBitVectorInd

Syntax

void Nm_ControlBitVectorInd(dword sourceId, dword controlBits)

Function

This function is called if a NM message with a non-zero Control-Bit-Vector is received. In addition to the vector itself, the identifier of the sender node is given.

Parameters
  • sourceId
    The NM source identifier in the NM message or 0, if the source identifier is not transferred.
  • controlBits
    The Control Bit Vector received.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

Print the identifier of the sending node in the Write Window.

void Nm_ControlBitVectorInd( dword sourceId, dword controlBits)
{
Write( "Nm_ControlBitVectorInd: from node %d, bits %02x"
, sourceId, controlBits);
}


Nm_PreSendInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » NM Message Reception and Sending » Nm_PreSendInd

Note

Note

Changing the NM message may disturb the protocol and result in undesired effects!

Syntax

void Nm_PreSendInd(WORD dlcInOut[], BYTE data[])

Function

Directly before sending a NM message on the bus, this function is called to allow the CAPL program to change the actual message sent. Any message byte can be altered by the function.

Parameters
  • dlcInOut
    The DLC of the message to be sent (alterable).
  • data
    The message data to be sent (alterable).

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

Every NM message sent by this node is patched to be 7 bytes long, and byte 6 is set to 0xFF.

void Nm_PreSendInd( WORD dlcInOut[], BYTE data[])
{
dlcInOut[0] = 7; // change the DLC of the message sent
data[6] = 0xFF; // patch a value
}


Nm_CarWakeUpInd

AUTOSAR NM CAN 3.3.0 » CAPL Callback Functions » NM Message Reception and Sending » Nm_CarWakeUpInd

Syntax

void Nm_CarWakeUpInd(dword canId, dword identifier, long bRepeatMessageBit, BYTE data[])

Function

A call to this function indicates the reception of a NM message that has the car wake-up bit set. Is only called if NM_CAR_WAKEUP_RX_ENABLED=1.

Parameters
  • canId
    The CAN ID of the message.
  • identifier
    The NM source identifier in the NM message or 0, if the source identifier is not transferred.
  • bRepeatMessageBit
    1 if the Repeat-Message bit is set,
    0 otherwise.
  • data
    The message’s data bytes including the protocol bytes.

Return Values

—

Availability

Since Version

Restricted To

Measurement Setup

Simulation / Test Setup

CANoe 7.5 SP4
+ DLL 3.3.0

CANoe

—

Node Context in the
Simulation Setup

Example

Example

Start up the node when the car wake-up bit is received

void Nm_CarWakeUpInd( dword canId, dword identifier,
long bRepeatMessageBit, BYTE data[])
{
Write( "Nm_CarWakeUpInd: from node %d", canId);
Nm_NetworkRequest();
}