mcSetProperty

ECU Measurement and Calibration Toolkit Help

Edition Date: October 2018

Part Number: 371602T-01

»View Product Info
Download Help (Windows Only)

Purpose

Sets a property of the driver, the database, the ECU, a characteristic, a Measurement, or a Measurement task.

Format

mcTypeStatus mcSetProperty(
mcTypeTaskRef RefNum,
cstr Name,
u32 PropertyID,
u32 SizeOfValue,
void *Value);

Input

RefNum

RefNum is any ECU M&C task reference which consists of a valid link to the opened A2L database (DBRefNum), a selected ECU (ECURefNum) or a Measurement task (DAQRefNum). RefNum has to be valid for the related PropertyID type.

Name

Name is not used and can be set to NULL. This parameter may be used for further extensions.

PropertyID

Selects the property to set. For a description of each property, including its data type and PropertyId, refer to the Properties section.

SizeOfValue

Number of bytes allocated for the Value output. This size normally depends on the data type listed in the description of the property.

Value

Provides the property value. PropertyId determines the data type of the value.

Output

Return Value

The return value indicates the status of the function call as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.

Use the mcStatusToString function of the ECU M&C API to obtain a descriptive string for the return value.

Description

There are four types of properties which can be modified in the poly input value: ECU-specific properties, DAQ-specific properties, Characteristic-specific properties, and Measurement-specific properties.

ECU-Specific Properties

You cannot set an ECU property while the application is connected to the ECU. If you need to change a ECU property prior to connecting, call mcECUSelectEx, followed by mcSetProperty, and then mcECUConnect. After you connect to the ECU, you also can change a property by calling mcECUDisconnect, followed by mcSetProperty, and then mcECUConnect to restart the task. Refer to the ECU-Specific Properties table below for a list of ECU-specific values for PropertyID.

DAQ-Specific Properties

You cannot set a DAQ property while a Measurement task is running. If you need to change a property prior to starting a Measurement task call mcDAQInitialize, followed by mcSetProperty, and then mcDAQStartStop. After you start the Measurement task, you also can change a property by calling mcDAQStartStop, followed by mcSetProperty, and then mcDAQStartStop to restart the task. Refer to the DAQ-Specific Properties table below for a list of DAQ-specific values for PropertyID.

Properties

ECU-Specific Properties

Data TypeNameDescription
u32mcPropCANBaudrateSets the CAN Baud rate for XCP or CCP on CAN which is used to send commands and data from the host to the slave device.
u32mcPropCANTerminationFor all XNET devices, the termination is software selectable. XNET provides the option of 120 Ω between Bus Plus and Bus Minus or no termination. The Termination property configures the onboard termination of the NI-XNET interface CAN connector (port). The Boolean property supports two values: TRUE = Termination ON and FALSE = Termination Off. However, different CAN hardware has different termination requirements, and the termination values have different meanings. Refer to the Termination attribute in the XNET API for more details. (This property is supported for NI-XNET devices only.)

0 — FALSE (termination off)

1 — TRUE (termination on)

u64mcPropCANBaudrate64Set the Baud Rate in use by the CAN Interface with XCP protocol. Basic baud rates such as 125000 and 500000 are specified as numeric values. Advanced (or custom) baud rates are specific to the CAN interface in use and the description can be found in the NI-XNET documentation. The default value for the property is the baud rate set in the A2L database used for the application.

If NI-XNET is used and the A2L file specifies a sampling point for the baud rate which differs from the sampling point used internally in NI-XNET, ECUMC replaces the standard baud rate value by a custom 64-bit baud rate which uses the sampling point as close as possible to the sampling point in A2L database. You can find the documentation of the NI-XNET custom baud rate in NI-XNET Hardware and Software Help under Interface:64bit Baud Rate.

u64mcPropCANFDBaudrate64Set the CAN FD baud rate value (used for the data part of transmission).

If CAN FD is used, 64bit Baud Rate specifies the baud rate for the arbitration part of the CAN message, while this property specifies the baud rate for the data part of the CAN message. CAN FD is only supported by NI-XNET interfaces for XCP protocol.

Basic baud rates such as 500000 and 2000000 are specified as numeric values. Information about the advanced (or custom) baud rates can be found in the NI-XNET Hardware and Software Help under Interface:CAN:64bit FD Baud Rate. The default value for the property is the baud rate set in the CAN_FD section of the A2L database used for the application. You can set the property to use any other baud rate or custom baud rate according to NI-XNET specification.

If the A2L file specifies a sampling point for the CAN FD baud rate which differs from the sampling point used internally in NI-XNET, ECUMC replaces the standard baud rate value by a custom 64-bit baud rate which uses the sampling point as close as possible to the sampling point in A2L database. Refer to information about the custom baud rates in the NI-XNET Hardware and Software Help under Interface:64bit FD Baud Rate.

Transceiver Delay Compensation defined by the A2L database is not used while calculating the custom baud rate value, as the value is hardware implementation specific and the value found in the database may not match the NI-XNET specification. If you need very specific values for the CAN FD baud rate, you need to follow the NI-XNET documentation and set a custom baud

u32mcPropCANIOmodeSet the CAN I/O Mode of the specified interface.

The CAN I/O mode is only supported with XNET interfaces. It determines if the interface is running in CAN 2.0 mode (supports frames with payload up to 8 bytes), CAN FD mode (supports frames up to 64 bytes), or CAN FD+BRS mode (CAN FD with baud rate switching). The default value is determined by the A2L database used by the application.

In ECU Determined mode, the master can communicate with ECUs using either traditional CAN or CAN FD frames. The master starts the communication with a traditional CAN 2.0 frame; if the ECU responds in any mode, this mode is selected for further communication. If the ECU does not respond to the CAN 2.0 frame, the master repeats (after timeout) the first command using a CAN FD frame. In ECU Determined mode, the NI-XNET interface runs in CAN FD BRS mode, so the CAN FD baud rate must be set before using this mode. In CAN FD+BRS mode, the NI-XNET interface can receive and transmit CAN 2.0, CAN FD, and CAN FD+BRS frames.

0—mcCANioMode_CAN

1—mcCANioMode_CAN_FD

2—mcCANioMode_CAN_FD_BRS

3—mcCANioMode_ECU_Determined

Note Note  CAN FD is only supported with NI-XNET version 17.0.1 or later.
u32mcPropCANUseMaxDLCThis Boolean property determines if the master in CAN 2.0 mode transmits frames with the actual used payload length or always transmits the maximum number of bytes (8 bytes).

The default value of this property is being retrieved from the A2L database based on the MAX_DLC_REQUIRED keyword within the XCP_ON_CAN section.

0—FALSE

1—TRUE

u32mcPropCANFDMaxDLCThis property determines the payload length which should be used if the mcPropCANFDUseMaxDLC setting is TRUE.

The default value of this property is being retrieved from the A2L database based on the MAX_DLC keyword within the CAN_FD section.

The max value of this property is 64.

u32mcPropCANFDUseMaxDLCThis Boolean property determines if the master in CAN FD mode transmits frames with the actual used payload length or always transmits the maximum number of bytes, defined by the mcPropCANFDMaxDLC DLC setting (8…64 bytes).

The default value of this property is being retrieved from the A2L database based on the MAX_DLC_REQUIRED keyword within the CAN_FD section.

0—FALSE

1—TRUE

u32mcPropCmd_EXCHANGE_IDSets whether or not the EXCHANGE_ID command should be suppressed during connection to the ECU.
u32mcPropCROIDSets the CRO CAN Identifier (Command Receive Object) for XCP or CCP on CAN which is used to send commands and data from the host to the slave device.
u32mcPropDTOIDSets the DTO CAN Identifier (Data Transfer Object) for XCP or CCP on CAN which is used to send commands and data from the slave device to the host.
u32mcPropECU_BaudRateSets the Baud rate in use by the selected interface. This property applies to all tasks initialized with the NI-CAN interface. You can specify the following basic baud rates as the numeric rate: 33333, 83333, 100000, 125000, 200000, 250000, 400000, 500000, 800000, and 1000000. You can specify advanced baud rates as 8000XXYY hex, where YY is the value of Bit Timing Register 0 (BTR0), and XX is the value of Bit Timing Register 1 (BTR1).

For more information, refer to the Interface Properties dialog in MAX. The value of this property is originally set within MAX, but it can be changed using mcSetProperty.

u32mcPropECU_ByteOrderSets the byte order of the slave device.

0MSB_LAST

The Slave device uses the MSB_LAST (Intel) byte ordering.

1MSB_FIRST

The Slave device uses the MSB_FIRST (Motorola) byte ordering.

strmcPropECU_ChecksumSets the file name of the Checksum DLL used for verifying the checksum.
u32mcPropECU_CmdByteOrderSets the byte order for multi-byte command parameters.

0MSB_LAST

The CCP Slave device uses the MSB_LAST (Intel) byte ordering.

1MSB_FIRST

The CCP Slave device uses the MSB_FIRST (Motorola) byte ordering.

u32mcPropECU_CRO_IDSets the CAN identifier for the CRO ID (Command Receive Object), which is used to send commands and data from the host to the slave device.
u32mcPropECU_DTO_IDSets the DTO ID (Data Transmission Object) which is used by the ECU to respond to CCP commands and send data and status information to the CCP master.
u32mcPropECU_MasterIDSets CCP master ID information. This ID information is optional and specific to the ECU implementation. For more information about the CCP master ID information refer to the documentation for the ECU.
strmcPropECU_SeedChkDllPathDetermines the directory where the ECU M&C Toolkit expects to find the Seedkey or Checksum DLL. If the property is an empty string (default), the ECU M&C Toolkit expects the DLLs in the same directory as the A2L file. If your DLLs are in a different directory, set this property pointing to this directory.
strmcPropECU_SeedKey_CalSets the filename of the SeedKey DLL used for Calibration purposes. For Remote Seedkey access (refer to the LabVIEW examples), set the name to RSK:<server ip address>,<port>.
strmcPropECU_SeedKey_DAQSets the filename of the SeedKey DLL used for DAQ purposes. For Remote Seedkey access (refer to the LabVIEW examples), set the name to RSK:<server ip address>,<port>.
strmcPropECU_SeedKey_ProgSets the filename of the SeedKey DLL used for programming purposes. For Remote Seedkey access (refer to the LabVIEW examples), set the name to RSK:<server ip address>,<port>.
strmcPropECU_SeedKey_XCPSets the filename of the SeedKey DLL for XCP. For Remote Seedkey access (refer to the LabVIEW examples), set the name to RSK:<server ip address>,<port>.
strmcPropECU_LogFileNameSets a filename (full path) where the XCP or CCP protocol traffic is logged in ASCII format for debugging purposes. Setting this value to an empty path (NULL or empty string) disables logging (default). Note that on RT and cRIO systems, the logfile is created on the target system and must be transferred to the host after logging has been completed.

Note that no additional CAN port is used for the logging, which makes this method superior to any other method such as running a bus monitor parallel.
u8mcPropECU_Single_Byte_DAQ_ListsSets the ECU to support single-byte or multi-byte DAQ list entries.
u32mcPropECU_StationAddressSets the station address of the slave device. CCP is based on the idea that several ECUs can share the same CAN Arbitration IDs for CCP communication. To avoid communication conflicts, CCP defines a Station Address that has to be unique for all ECUs sharing the same CAN Arbitration IDs. Unless an ECU has been addressed by its Station Address, the ECU must not react to CCP commands sent by the CCP master.
u32mcPropECU_MeasSplitAllowedSets the Boolean property Meas Split Allowed.

For measurements in DAQ List mode, the master creates DAQ lists which determines frames with data transmitted by the ECU. The first byte in this frame (ODT) is a PID identifier, the remaining bytes in the frames are used for measurement data (e.g., with CAN 2.0, seven bytes can be used for data).

Depending on the measurements not all bytes in the frame can be used. For example, measuring seven 32-bit values in the ECU requires transmitting seven frames per sampling point, as only one 4-byte value can be placed in one frame. The other three bytes remain unused.

Setting this property to true (1) allows splitting the measurements across CAN frames, so the seven values can be packed into four frames only (4 frames * 7 bytes = 28 data bytes for DAQ data).

The default value is false (0).

u16mcPropECU_MappingModeAddress mapping mode to be used when accessing the ECU memory by addresses.
0No Mapping: Original addresses from the A2L database are used.
1Defined Pages: This mode requires setting the source and target pages. The memory pages are defined in the A2L database in the DEFINED_PAGES section. The source and target pages can be set either by the page name or by the logical page number (the last Set Property call defines the page).

If the original address takes place within the source page, it will be re-mapped to the target page with the same offset to the beginning of the page.

2ADDR_MAPPING: Use address mapping defined in the A2L database in the ADDR_MAPPING section.
strmcPropECU_MappingSourceNameName of the source page to be used for the address mapping in Defined Pages mode.
u16mcPropECU_MappingSourceLogical page number of the source page to be used for the address mapping in Defined Pages mode.
strmcPropECU_MappingTargetNameName of the target page to be used for the address mapping in Defined Pages mode.
u16mcPropECU_MappingTargetLogical page number of the source page to be used for the address mapping in Defined Pages mode.
u32 mcPropECU_TimingFactor Sets the timing factor, which you can use to increase XCP or CCP command timeout values. For details on the default Command Timeout values, refer to the XCP or CCP Protocol Specification.
u32 mcPropECU_XCP_Timeout_T1
mcPropECU_XCP_Timeout_T2
mcPropECU_XCP_Timeout_T3
mcPropECU_XCP_Timeout_T4
mcPropECU_XCP_Timeout_T5
mcPropECU_XCP_Timeout_T6
mcPropECU_XCP_Timeout_T7
Sets one of the seven timeout values (in milliseconds) defined in the XCP standard for the various XCP commands. For details of which timeout applies to a specific command, refer to the XCP standard. The values are typically read from an A2L file, but may be overridden manually.

Note that the mcPropECU_TimingFactor property might modify this value.
u32 mcPropECU_CCP_Timeout_T_std Sets the timeout value (in milliseconds) for most of the CCP commands. For details of which timeout applies to a specific command, refer to the CCP standard. Default: 40. Standard: 25. The default is chosen slightly higher to allow for slower ECUs.

Note that the mcPropECU_TimingFactor property might modify this value.
u32 mcPropECU_CCP_Timeout_T_pgm Sets the timeout value (in milliseconds) for the CCP programming commands. For details of which timeout applies to a specific command, refer to the CCP standard. Default: 120. Standard: 100. The default is chosen slightly higher to allow for slower ECUs.

Note that the mcPropECU_TimingFactor property might modify this value.
u32 mcPropECU_CCP_Timeout_T_mem Sets the timeout value (in milliseconds) for the CCP memory commands. For details of which timeout applies to a specific command, refer to the CCP standard. Default and Standard: 30000.

Note that the mcPropECU_TimingFactor property might modify this value.
u32 mcPropECU_CCP_Timeout_T_diag Sets the timeout value (in milliseconds) for the CCP DIAG_SERVICE command. Default and Standard: 500.

Note that the mcPropECU_TimingFactor property might modify this value.
u32 mcPropECU_CCP_Timeout_T_act Sets the timeout value (in milliseconds) for the CCP ACTION_SERVICE command. Default: 500. Standard: 5000.

Note that the mcPropECU_TimingFactor property might modify this value.
strmcPropIPAddressSets the IP address for XCP on Ethernet (TCP or UDP) as a string.
u16mcPropIPPortSets the IP port for XCP on Ethernet (TCP or UDP).
i32mcPropIPSourcePortSets the source port (XCP master port) used for Ethernet communication. The default value is -1, which indicates that the source port will be chosen by the operating system. Valid port values are 0 to 65535. Note that port 0 is reserved and typically should not be used.
u32mcPropOptCmd_ACTION_SERVICESets whether the ECU supports the optional CCP Command ACTION_SERVICE.
u32mcPropOptCmd_BUILD_CHKSUMSets whether the ECU supports the optional CCP Command BUILD_CHKSUM.
u32mcPropOptCmd_CLEAR_MEMORYSets whether the ECU supports the optional CCP Command CLEAR_MEMORY.
u32mcPropOptCmd_DIAG_SERVICESets whether the ECU supports the optional CCP Command DIAG_SERVICE.
u32mcPropOptCmd_DNLOAD_6Sets whether the ECU supports the optional CCP Command DNLOAD_6.
u32mcPropOptCmd_GET_ACTIVE_CAL_PAGESets whether the ECU supports the optional CCP Command GET_ACTIVE_CAL_PAGE.
u32mcPropOptCmd_GET_S_STATUSSets whether the ECU supports the optional CCP Command GET_S_STATUS.
u32mcPropOptCmd_GET_SEEDSets whether the ECU supports the optional CCP Command GET_SEED.
u32mcPropOptCmd_MOVESets whether the ECU supports the optional CCP Command MOVE.
u32mcPropOptCmd_PROGRAMSets whether the ECU supports the optional CCP Command PROGRAM.
u32mcPropOptCmd_PROGRAM_6Sets whether the ECU supports the optional CCP Command PROGRAM_6.
u32mcPropOptCmd_SELECT_CAL_PAGESets whether the ECU supports the optional CCP Command SELECT_CAL_PAGE.
u32mcPropOptCmd_SET_S_STATUSSets whether the ECU supports the optional CCP Command SET_S_STATUS.
u32mcPropOptCmd_SHORT_UPSets whether the ECU supports the optional CCP Command SHORT_UP.
u32mcPropOptCmd_START_STOP_ALLSets whether the ECU supports the optional CCP Command START_STOP_ALL.
u32mcPropOptCmd_TESTSets whether the ECU supports the optional CCP Command TEST.
u32mcPropOptCmd_UNLOCKSets whether the ECU supports the optional CCP Command UNLOCK.
u8mcPropPGM_AccessMethod Selects the selected access mode for mcProgram and mcClearMemory.

0x00—Absolute Access Mode (default). The MTA uses physical addresses.

0x00—Functional Access Mode. The MTA functions as a block sequence number of the new flash content file.

0x80...0xFF—User defined. It is possible to use different access modes for clearing and programming.

u8mcPropPGM_CompressionMethod Selects the selected compression method used for mcProgram.

0—Data is uncompressed (default).

0x80...0xFF—User defined.

u8mcPropPGM_EncryptionMethod Selects the selected encryption method used for mcProgram.

0—Data is not encrypted (default).

0x80...0xFF—User defined.

u8mcPropPGM_ProgrammingMethod Selects the selected programming method used for mcProgram.

0—Sequential programming (default).

0x80...0xFF—User defined.

DAQ-Specific Properties

Data TypeNameDescription
u32mcPropDAQ_DTO_IDSets the DTO ID (Data Transmission Object) which is used by the ECU to respond to send data from the DAQ lists to the CCP master.
strmcPropDAQ_EventChannelNameSets the event channel name to which the Measurement task is assigned. If there is no event channel name defined in the A2L file, you can set the Event Channel Number manually by passing a decimal number as a string.
i32mcPropDAQ_ModeSets the mode of an M&C Measurement task.

0DAQ List

The data is transmitted from the ECU in equidistant time intervals as defined in the A2L database. The data can be read back with mcDAQRead as Single point data using sample rate = 0, or as waveform using a sample rate > 0. Input channel data is received from the DAQ messages. Use mcDAQRead to obtain input samples as single-point, array, or waveform.

1Polling

In this mode the data from the Measurement task is uploaded from the ECU whenever mcDAQRead is called.

u16mcPropDAQ_PrescalerSets the Prescaler, which reduces the desired transmission frequency of the associated DAQ list.
f64mcPropDAQ_SampleRateDefines the sample rate in Hz for the M&C Measurement task. The sample rate is defined in mcDAQInitialize, mcDAQInitializeEx, mcDAQListInitialize, and mcDAQListInitializeEx functions or by mcSetProperty.
u32mcPropDAQ_TimingSourceSets the timing source used for DAQ measurements. The default is Automatic. Values are:
0Automatic

The default method (1, 2, or 3, below) is selected.

1Host Timing

Timestamps are generated from the host system time whenever a frame arrives.

This mode is always available.

This is the default for XCP on TCP/UDP if the ECU does not support timestamps.

2CAN Timing

Timestamps are generated from the network interface hardware (e.g. NI-XNET hardware).

This mode is available only if the network hardware generates timestamps.

This is the default for XCP on CAN if the ECU does not support timestamps.

3ECU Timing

Timestamps are taken from the ECU data. The Start Time is taken from the host, and increments are taken from the ECU.

This mode is only available if the ECU generates timestamps; in this case, it is default.

Characteristic-Specific Properties

Data TypeNameDescription
double[]mcPropChar_X_AxisSets the X-axis values on which the Characteristic is defined. The Characteristic dimension must be at least 1.
double[]mcPropChar_Y_AxisSets the Y-axis values on which the Characteristic is defined. The Characteristic dimension must be 2.
u32mcPropChar_ByteOrderSets the specified byte order of the selected Characteristic:

0—Intel format

Bytes are in little-endian order, with least-significant bit first.

1—Motorola format

Bytes are in big-endian order, with most-significant bit first.

Measurement-Specific Properties

Data TypeNameDescription
u32mcPropMeas_ByteOrderSets the specified byte order of the selected Measurement:

0—Intel format

Bytes are in little-endian order, with least-significant bit first.

1—Motorola format

Bytes are in big-endian order, with most-significant bit first.

WAS THIS ARTICLE HELPFUL?

Not Helpful