PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -1- 1 CONTENTS .............................................................................................................................................................. 2 2 INTRODUCTION .................................................................................................................................................... 4 3 SOFTWARE STRUCTURE .................................................................................................................................... 4 3.1 3.2 3.3 4 PSFPTCLINAAMLXMANAGER OBJECT ......................................................................................................... 6 4.1 5 Background......................................................................................................................................................... 7 Logging Property ................................................................................................................................................ 8 PTC04 Property .................................................................................................................................................. 9 Exchange Method ............................................................................................................................................... 9 _Exchange Method ........................................................................................................................................... 11 GetLinBusState Method.................................................................................................................................... 12 GetSetting Method ............................................................................................................................................ 12 OpenProfile Method ......................................................................................................................................... 13 SaveProfile Method .......................................................................................................................................... 13 SaveProfileAs Method ...................................................................................................................................... 14 SendWakeUpPulse Method .............................................................................................................................. 14 SetSetting Method............................................................................................................................................. 15 ValidateId Method ............................................................................................................................................ 16 SetVbatConnected Method ............................................................................................................................... 16 SetVbatLevel Method ....................................................................................................................................... 17 MELEXCM LOADER METHODS OF PSFPTCLINAAMLXDEVICE.......................................................... 17 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 6.10 6.11 6.12 6.13 6.14 6.15 6.16 6.17 6.18 6.19 7 Background......................................................................................................................................................... 6 PSFPTCLINAAMLXDEVICE OBJECT............................................................................................................... 7 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10 5.11 5.12 5.13 5.14 5.15 6 Object Model ...................................................................................................................................................... 4 Object Structure and Hierarchy .......................................................................................................................... 4 Objects with Interfaces ....................................................................................................................................... 5 How to upload a HEX file ................................................................................................................................ 18 How to download a HEX file............................................................................................................................ 18 MlxcmUploadHexFile Method ......................................................................................................................... 18 MlxcmVerifyHexFile Method .......................................................................................................................... 19 MlxcmDownloadHexFile Method .................................................................................................................... 20 MlxcmUpload Method...................................................................................................................................... 21 MlxcmDownload Method................................................................................................................................. 21 ConfigureMlxcmLoader Method ...................................................................................................................... 22 ConfigureLinLoader Method ............................................................................................................................ 23 ConfigureFastLoader Method ........................................................................................................................... 24 MlxcmAbortLoader Method ............................................................................................................................. 24 MlxcmSaveHexFileInXram Method................................................................................................................. 25 MlxcmUploadFromXram Method .................................................................................................................... 26 MlxcmVerifyWithXram Method ...................................................................................................................... 27 LoaderLog Property.......................................................................................................................................... 27 MlxcmNvramUploadHexFile Method .............................................................................................................. 28 MlxcmNvramDownloadHexFile Method ......................................................................................................... 28 MlxcmNvramUpload Method........................................................................................................................... 29 MlxcmNvramDownload Method...................................................................................................................... 30 ENUMERATION CONSTANTS .......................................................................................................................... 31 7.1 7.2 SettingCodes enumeration ................................................................................................................................ 31 LoaderProtocolCodes enumeration................................................................................................................... 32 PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -2- 7.3 8 NvramOptionCodes enumeration ..................................................................................................................... 32 DISCLAIMER ........................................................................................................................................................ 33 PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -3- MLXPTCLIN PSF is MS Windows software library, which meets the requirements for a Product Specific Functions (PSF) module, defined in Melexis Programmable Toolbox (MPT) object model. The library implements in-process COM objects for interaction with MLXPTCLIN firmware. It is designed primarily to be used by MPT Framework application, but also can be loaded as a standalone in-process COM server by other applications that need to communicate with the above-mentioned Melexis hardware. ! " MPT object model specifies that a PSF module must expose two COM objects which implement certain COM interfaces. MLXPTCLIN PSF implements these two objects and two additional objects for advanced operations. • PSFPTCLINAAMLXManager object – implements IPSFManager standard MPT interface. This is a standard PSFManager object. MPT Framework and other client applications create a temporary instance of that object, just for device scanning procedure. After that this instance is released. This is the first required object. Refer to MPT Developer Reference document for more information about PSFManager object and IPSFManager interface. • PSFPTCLINAAMLXDevice object – implements IPSFPTCLINAAMLXDevice specific interface. However, this interface derives from IMPTDevice standard MPT interface and therefore PSFPTCLINAAMLXDevice also implements the functionality of MPTDevice standard MPT object. In addition to standard IMPTDevice methods, IPSFPTCLINAAMLXDevice interface exposes methods, which are specific to this library. They are described in this document. This is the second required COM object. Refer to MPT Developer Reference document for more information about MPTDevice object and IMPTDevice interface. # $% PSFPTCLINAAMLXManager PSFPTCLINAAMLXDevice PTC04 PTC04-LIN PSF Library Object Model Ver.1.10 PTC04PSFDevice 2009-02-19 -4- $ IPSFPTCLINAAMLXDevice IPSFManager IMPTDevice IDispatch PSFPTCLINAAMLX Manager IDispatch PSFPTCLINAAMLX Device ISupportErrorInfo IPTC04PSFDevice ISupportErrorInfo ISpecifyPropertyPages IPersist IMPTDevice IDispatch PTC04PSF Device ISupportErrorInfo ISpecifyPropertyPages IPersist PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -5- & & ! '! '! ) ( *( This object is created only once and is destroyed when the library is unmapped from process address space. Each subsequent request for this object returns the same instance. PSFPTCLINAAMLXManager object implements standard MPT category CATID_MLXMPTPSFSerialModule, which is required for automatic device scanning. C++ standalone client applications can create an instance of this object by using the standard COM API CoCreateInstance with class ID CLSID_PSFPTCLINAAMLXManager, or ProgID “MPT. PSFPTCLINAAMLXManager”: hRes = ::CoCreateInstance(CLSID_PSFPTCLINAAMLXManager, NULL, CLSCTX_INPROC, IID_IPSFManager, (void**) &pPSFMan); Visual Basic applications should call CreateObject function to instantiate PSFPTCLINAAMLXManager: Set PSFMan = CreateObject(“MPT. PSFPTCLINAAMLXManager”) The primary objective of this instantiation is to call ScanStandalone method. C++: hRes = pPSFMan->ScanStandalone(dtSerial, varDevices, &pDevArray); Or in Visual Basic: Set DevArray = PSFMan.ScanStandalone(dtSerial) ScanStandalone function returns collection of PSFPTCLINAAMLXDevice objects, one for each connected PTC04. The collection is empty if there are no connected devices. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -6- + + ! ', ', ) *( This object implements standard MPT category CATID_MLXMPTPSFSerialDevice as well as library specific CATID_MLXMPTLINPTC04Device category. It also declares required specific category CATID_MLXMPTLINPTC04UIModule for identification of required user interface modules. This object can be created directly with CoCreateInstance/CreateObject or by calling the device scanning procedure ScanStandalone of PSFPTCLINAAMLXManager object. The following Visual Basic subroutine shows how to instantiate PSFPTCLINAAMLXDevice object by performing device scan on the system: Sub CreateDevice() Dim PSFMan As PSFPTCLINAAMLXManager, DevicesCol As ObjectCollection, I As Long On Error GoTo lError Set PSFMan = CreateObject("MPT.PSFPTCLINAAMLXManager") Set DevicesCol = PSFMan.ScanStandalone(dtSerial) If DevicesCol.Count <= 0 Then MsgBox ("No PTC-04 programmers found!") Exit Sub End If ' Dev is a global variable of type PSFPTCLINAAMLXDevice ‘ Select first device from the collection Set Dev = DevicesCol(0) MsgBox (Dev.Name & " device found on " & Dev.Channel.Name) If DevicesCol.Count > 1 Then For I = 1 To DevicesCol.Count - 1 ' We are responsible to call Destroy(True) on the device objects we do not need Call DevicesCol(I).Destroy(True) Next I End If Exit Sub lError: MsgBox Err.Description Err.Clear End Sub Developers can also manually connect the device object to a serial channel object thus bypassing standard device scanning procedure. The following Visual Basic subroutine allows manual connection along with standard device scanning depending on input parameter bAutomatic: Sub CreateDevice(bAutomatic As Boolean) Dim PSFMan As PSFPTCLINAAMLXManager, DevicesCol As ObjectCollection, I As Long Dim CommMan As CommManager, Chan As MPTChannel On Error GoTo lError If bAutomatic Then ' Automatic device scanning begins here Set PSFMan = CreateObject("MPT.PSFPTCLINAAMLXManager") Set DevicesCol = PSFMan.ScanStandalone(dtSerial) If DevicesCol.Count <= 0 Then MsgBox ("No PTC-04 programmers found!") Exit Sub End If If DevicesCol.Count > 1 Then For I = 1 To DevicesCol.Count - 1 'We are responsible to call Destroy(True) on device objects we do not need Call DevicesCol(I).Destroy(True) Next I End If Set MyDev = DevicesCol(0) Else PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -7- ' Manual connection begins here Set CommMan = CreateObject("MPT.CommManager") Set MyDev = CreateObject("MPT.PSFPTCLINAAMLXDevice") I = ActiveWorkbook.Names("SerialPort").RefersToRange.Value2 Set Chan = CommMan.Channels.CreateChannel(CVar(I), ctSerial) MyDev.Channel = Chan ' Check if a PTC04 programmer is connected to this channel Call MyDev.CheckSetup(False) End If MsgBox (MyDev.Name & " programmer found on " & MyDev.Channel.Name) Exit Sub lError: MsgBox Err.Description Err.Clear End Sub PSFPTCLINAAMLXDevice object implements IMPTDevice standard MPT interface. Please refer to MPT Developer reference document for description of the properties and methods of this interface. In addition PSFPTCLINAAMLXDevice object implements IPSFPTCLINAAMLXDevice library specific interface, which derives from IMPTDevice. The following is a description of its properties and methods. + (( ( % Specifies whether logging information is generated while working with the library. Syntax Visual Basic: Property Logging as Boolean C++: HRESULT get_Logging([out,retval] VARIANT_BOOL* pValue); HRESULT set_Logging([in] VARIANT_BOOL Value); Parameters pValue An address of VARIANT_BOOL variable that receives current value of the property. VARIANT_TRUE means that logging is active, VARIANT_FALSE means inactive. Value A VARIANT_BOOL specifying new value for the property. VARIANT_TRUE activates the logging, VARIANT_FALSE deactivates it. Return value Visual Basic: True if logging is active, False otherwise. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. *pValue contains valid value. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -8- + .& % This property holds a reference to PTC04PSFDevice co-object. Syntax Visual Basic: Property PTC04 as Object C++: HRESULT get_PTC04([out][retval] LPDISPATCH* pVal); HRESULT set_PTC04([in] LPDISPATCH Value); Parameters Value An IDispatch* specifying new PTC04 device object. Nothing happens if the object is the same instance as the existing one. Otherwise PSFPTCLINAAMLXDevice object releases its current PTC04 device object and connects to the new one. This also includes replacing of the communication Channel object with the one from the new PTC04PSFDevice object. pVal Address of IDispatch* pointer variable that receives the interface pointer to the PTC04 device object. If the invocation succeeds, the caller is responsible for calling IUnknown::Release() on the pointer when it is no longer needed. Return value Visual Basic: A reference to the PTC04PSFDevice co-object. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. *pVal contains valid pointer. Any other error code The operation failed. *pVal contains NULL. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. +& /0 $ ( ! $ Sends a frame to and receives a response from the LIN bus. Syntax Visual Basic: Function Exchange(Buffer, bParameter As Byte, isCRC2 As Boolean, pbtDiag As Byte, ResponseTimeout As Long) C++: HRESULT Exchange([in] VARIANT Buffer, [in] unsigned char bParameter, [in] VARIANT_BOOL isCRC2, [out] unsigned char* pbtDiag, [in, defaultvalue(0)] long ResponseTimeout, [out, retval] VARIANT * pvResult ); Parameters PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 -9- Buffer A Variant value containing an array of bytes to be send. bParameter A Byte providing several parameters, defining the frame to be sent: Parameter byte D7 D6 D5 D4 D3 D2 D1 D0 Breaklength Reserved M2S Number of bytes in S2M message 1 = send break 1 = M2S message M2S = 0: Number of bytes that a slave of 18 bittimes 0 = S2M message will send 0 = send break M2S = 1: Data is ignored of 36 bittimes isCRC2 A flag showing the type of the checksum: TRUE – the frame_id will be included in the checksum. FALSE – the frame_id won’t be included in the checksum. This parameter also affects the kind of the checksum over the received frame. pbtDiag An address of Byte variable, which will receive the diagnostic byte returned from PTC04. This byte indicates if an error has occurred: D7 D6 D5 D4 D3 D2 D1 D0 Vmaster Error message 0 = master supply OK 0x00: no error 1 = no master supply 0x01: no slave answer on an S2M message 0x02: busy, a message is travelling over the bus ResponseTimeout A long specifying the time (in ms) to wait the PTC04 to answer a single command. In case this value is 0 (default), this parameter will be set to the value of PTC04.ResponseTimeout property. pvResult An address of Variant variable that gets received frame as array of bytes. Return value Visual Basic: A Variant containing an array of bytes representing received frame. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. *pvResult contains a valid value. Any other error code The operation failed. * pvResult is empty. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 10 - ++ 1/0 $ ( ! $ Sends a frame to and receives a response from the LIN bus. This method couldn’t be called from Visual Basic. Syntax C++: HRESULT _Exchange((/*[in]*/ unsigned char * pSend, /*[in,out]*/ unsigned char * pbLength, /*[in]*/ unsigned char bParameter, /*[in]*/ unsigned char isCRC2, /*[out]*/ unsigned char* pbDiag, /*[in, defaultvalue(0)]*/ long lResponseTimeout, /*[out, retval]*/ unsigned char ** ppRecv); Parameters pSend An array of bytes to be send. pbLength An address of Byte variable containing the length of the pSend array. After the method execution the variable will be set to the length of *ppRecv array. bParameter A Byte providing several parameters, defining the frame to be sent. See Exchange method description for details. isCRC2 A flag showing the type of the checksum: non zero – the frame_id will be included in the checksum. 0 – the frame_id won’t be included in the checksum. This parameter also affects the kind of the checksum over the received frame. pbDiag An address of Byte variable, which will receive the diagnostic byte returned from the PTC04. This byte indicates if an error has occurred. See Exchange method description for details. ResponseTimeout A long specifying the time (in ms) to wait the PTC04 to answer a single command. In case this value is 0 (default), this parameter will be set to the value of PTC04.ResponseTimeout property. ppRecv An address of array of bytes that gets received frame. Before calling this method, the address must contain NULL. After successful execution, the address will contain a valid address of the returned array. The caller is responsible to free the used memory by calling LocalFree API function. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. *ppRecv and *pbLength contain a valid value. Any other error code The operation failed. *ppRecv and *pbLength contain zero. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 11 - +2 3 ) ! $ Returns a byte representing current state of the LIN bus. This state can be one of the following: State value 1 2 3 4 5 Explanation Normal state: the LIN bus is in normal operation, the bus is recessive and ready to transport messages Wake up: At least one wake up pulse is seen since the previous state request Dominant: The bus is stuck at the dominant level for more that the maximal wake up period Transceiving: LIN messages are travelling on the bus Sending wake up: the master is sending a wake up pulse to the slaves Syntax Visual Basic: Function GetLinBusState() As Byte C++: HRESULT GetLinBusState([out, retval] unsigned char * pVal ); Parameters pVal An address of a Byte which will get the status information. Return value Visual Basic: A Byte containing status information received from PTC04. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. *pVal contains a valid value. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. +4 3 (! $ Returns the value of a particular setting. Syntax Visual Basic: Function GetSetting(settingID as SettingCodes) C++: HRESULT GetSetting([in] SettingCodes settingID, [out,retval] TVariant* pVal); Parameters PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 12 - settingID A SettingCodes constant specifying the ID of the setting. pVal An address of VARIANT variable that will receive the return value of the method. The caller is responsible to call VariantClear on that variable when it is no longer needed. Return value Visual Basic: A Variant containing the value of a setting. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. *pVal contains valid value. Any other error code The operation failed. *pVal is Empty. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. +5 " ! $ Opens the specified file and updates the settings. Syntax Visual Basic: Sub OpenProfile(FileName as String) C++: HRESULT OpenProfile([in] BSTR FileName); Parameters FileName A String specifying the path of the file to open. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. +6 - " ! $ Saves the settings into a previously opened profile. This function fails if there is not a profile in use. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 13 - Syntax Visual Basic: Sub SaveProfile() C++: HRESULT SaveProfile(); Parameters none Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. + . - " ! $ Saves the settings into the specified file. Syntax Visual Basic: Sub SaveProfileAs(FileName as String) C++: HRESULT SaveProfileAs([in] BSTR FileName); Parameters FileName A String specifying the path of the file. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. + 7 * 8 " ! $ This method sends a wake-up pulse to the slaves. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 14 - Syntax Visual Basic: Sub SendWakeUpPulse() C++: HRESULT SendWakeUpPulse (); Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. + (! $ Changes the value of a particular setting. Sets an associated internal variable. The setting is also sent immediately to the firmware. NOTE: If necessary, the changes can be saved in the profile with a subsequent call to SaveProfile or SaveProfileAs methods. Syntax Visual Basic: Sub SetSetting(settingID as SettingCodes, Value) C++: HRESULT SetSetting([in] SettingCodes settingID, [in] TVariantInParam Value); Parameters settingID A SettingCodes constant specifying the ID of the setting to modify. Value A VARIANT containing new value for the setting. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 15 - + 9 " ! $ Validates an identifier byte according to the LIN specification. Input byte must be in the range from 0 to 63. Syntax Visual Basic: Function ValidateId(bId As Byte) As Byte C++: HRESULT ValidateId ([in] unsigned char bId, [out, retval] unsigned char * pbNewId); Parameters bId A Byte containing an identifier to be validated. pbNewId An address of the result byte. Return value Visual Basic: A Byte containing validated identifier. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. *pbNewId contains a valid value. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. + & 9 ! $ This method connects or disconnects a programmable power supply to Vbat line. The level of the PPS can be set by SetVbatLevel method. The order of calling both methods is not important. Syntax Visual Basic: Sub SetVbatConnected(Status As Boolean) C++: HRESULT SetVbatConnected([in] VARIANT_BOOL Status); Parameters Status A Boolean specifying what to be done – True to connect or False to disconnect PPS and Vbat. Return value PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 16 - C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. + + 9 - "! $ This method sets the level of the PPS, which can be connected to Vbat line. The doesn’t always set directly the Vbat line. Connection or disconnection to Vbat is controlled by SetVbatConnected method. The order of calling both methods is not important. Syntax Visual Basic: Sub SetVbatLevel(Voltage As Single) C++: HRESULT SetVbatLevel([in] float Voltage); Parameters Voltage A Single voltage level to set on the PPS for Vbat line. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 ! "0 ! " : $ ! ', - These methods are members of PSFPTCLINAAMLXDevice object and are separated only for clarity. Their aim is to upload and download memory of MelexCM slave device, connected to LIN bus. Prior to calling any Download, Update or Verify method it' s necessary to have configured the corresponding protocol(s) and the loader. The methods for that are: ConfigureLinLoader - must be called when LIN or Fast protocol is used ConfigureFastLoader - must be called when Fast, FastStandalone or SlowStandalone protocol is used ConfigureMlxcmLoader – always Also for the LIN or Fast protocols it' s necessary to set setting of the MLXLINPSFDevice object to the required baudrate in LIN mode. These configurations have to be done once and can be used for many subsequent loader method calls. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 17 - Another possibility is to use several settings instead of ConfigureXXX method calls. Related setting enumeration constants are 2 # " #/' " The following Visual Basic code marks the necessary steps to pass in order to upload a file. ‘ MyDev is an object of PSFPTCLINAAMLXDevice ‘ Prior to running this procedure MyDev must be created and connected to PTC04 (see p.5.1) ‘ Configure LIN network address MyDev.ConfigureLinLoader Parameter:=0, NAD:=127 ‘ Configure LIN baudrate MyDev.SetSetting settingId:=SettingLinSpeed, Value:=9600 ‘ Configure Fast protocol baudrate MyDev.ConfigureFastLoader Parameter:=0, BaudRate:=100000 ‘ Configure the protocol and specify the path to Melexis loader code HEX file MyDev.ConfigureMlxcmLoader Protocol:=LoaderProtocolFast, LoaderFilename:="loader.hex" ‘ Upload the file firmware.hex (full path must be specified); do not sink progress events MyDev.MlxcmUploadHexFile Filename:="firmware.hex", Progress:=Nothing, Hint:=Empty ‘ Compare the file firmware.hex(full path must be specified) with the device’s memory ‘ do not sink progress events MyDev.MlxcmVerifyHexFile Filename:="firmware.hex", Progress:=Nothing, Hint:=Empty 2 # " #/' " The following Visual Basic code marks the necessary steps to pass in order to download full Flash contents to a HEX file. ‘ MyDev is an object of PSFPTCLINAAMLXDevice ‘ Prior to running this procedure MyDev must be created and connected to PTC04 (see p.5.1) ‘ Configure LIN node address (NAD); Parameter is reserved (not used) MyDev.ConfigureLinLoader Parameter:=0, NAD:=127 ‘ Configure LIN baudrate MyDev.SetSetting settingId:=SettingLinSpeed, Value:=9600 ‘ Configure Fast protocol baudrate; Parameter is reserved (not used) MyDev.ConfigureFastLoader Parameter:=0, BaudRate:=100000 ‘ Configure the protocol and specify the path to Melexis loader code HEX file MyDev.ConfigureMlxcmLoader Protocol:=LoaderProtocolFast, LoaderFilename:="loader.hex" ‘ Download area [0; 0x8000) to file downloaded.hex (full path must be specified); do not sink progress events MyDev.MlxcmDownloadHexFile Filename:="downloaded.hex", StartAddr:=0, Len:=32768, Progress:=Nothing, Hint:=Empty 2 ! "0 : 8 " # 0 " ! $ This method uploads data from a .HEX file into a MelexCM device. Syntax PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 18 - Visual Basic: Sub MlxcmUploadHexFile(Filename as String, Progress as Object, Hint as Variant) C++: HRESULT MlxcmUploadHexFile([in] BSTR Filename, [in] LPDISPATCH Progress, [in] TVariantInParam Hint); Parameters Filename A String specifying the full path to .HEX file. Progress Object that implements IMPTProgressCallback interface. It should have implementation of methods OnStart, OnProgress and OnEnd. Nothing (NULL) can be passed if the callback is not needed. Hint A Variant that is sent back to callback object as parameter in Onxxx methods. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2& ! "0 : 9 %# 0 " ! $ This method compares data from a .HEX file with that into a MelexCM device. Note that the range [0x2000; 0x2400) is not verified. Syntax Visual Basic: Sub MlxcmVerifyHexFile (Filename as String, Progress as Object, Hint as Variant, [StartAddr As Long], [EndAddr As Long = &H7FFFFFFF&]) C++: HRESULT MlxcmVerifyHexFile ([in] BSTR Filename, [in] LPDISPATCH Progress, [in] TVariantInParam Hint, [in,defaultvalue(0)] long StartAddr, [in,defaultvalue(0x7FFFFFFF)] long EndAddr); Parameters Filename A String specifying the full path to .HEX file. Progress Object that implements IMPTProgressCallback interface. It should have implementation of methods OnStart, OnProgress and OnEnd. Nothing (NULL) can be passed if the callback is not needed. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 19 - Hint A Variant that is sent back to callback object as parameter in Onxxx methods. StartAddr A Long value, specifying the start address (inclusive) of the region to be uploaded. The data from the HEX file, which is outside the region, will be ignored. EndAddr A Long value, specifying the end address (exclusive) of the region to be uploaded. The data from the HEX file, which is outside the region, will be ignored. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2+ ! "0 : , " # 0 " ! $ This method reads data from certain area of a MelexCM device and saves it into a .HEX file. Syntax Visual Basic: Sub MlxcmDownloadHexFile (Filename as String, StartAddr as Long, EndAddr as Long, Progress as Object, Hint as Variant) C++: HRESULT MlxcmDownloadHexFile ([in] BSTR Filename, [in] long StartAddr, [in] long EndAddr, [in] LPDISPATCH Progress, [in] TVariantInParam Hint); Parameters Filename A String specifying the full path to .HEX file. StartAddr A Long specifying the start address (inclusive) of memory area to be read. EndAddr A Long specifying the end address (exclusive) of the area to be read. Progress Object that implements IMPTProgressCallback interface. It should have implementation of methods OnStart, OnProgress and OnEnd. Nothing (NULL) can be passed if the callback is not needed. Hint A Variant that is sent back to callback object as parameter in Onxxx methods. Return value PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 20 - C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 22 ! "0 : 8 " ! $ This method uploads data into a MelexCM device. Syntax Visual Basic: Sub MlxcmUpload (StartAddr as Long, Format as Long, Data as Variant) C++: HRESULT MlxcmUpload([in] long StartAddr, [in] long Format, [in] TVariantInParam Data); Parameters StartAddr A Long specifying the start address of memory area to be uploaded. Format A Long specifying the format of the data in Data. Possible values are: Value Format 1 Data is an array of bytes. This is the preferred format for Visual Basic applications. 2 Data is an ANSI string packed in bstrVal member of *pvarID. This is the preferred format for C++ applications because of the best performance. It is a binary data so the string can contain zeroes and may not be zero terminated. Callers can get its real length by calling SysStringByteLen API on bstrVal member. Data A Variant containing the data to be uploaded. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 24 ! "0 : , " ! $ This method reads data from a MelexCM device. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 21 - Syntax Visual Basic: Function MlxcmDownload (StartAddr as Long, EndAddr as Long, Format as Long) as Variant C++: HRESULT MlxcmDownload ([in] long StartAddr, [in] long EndAddr, [in] long Format, [out,retval] TVariant* pData); Parameters StartAddr A Long specifying the start address (inclusive) of the memory area to be read. EndAddr A Long specifying the end address (exclusive) of the memory area to be read. Format A Long specifying the format of the returned data in pData. Possible values are: Value 1 Format Return value is an array of bytes. This is the preferred format for Visual Basic applications. Return value is an ANSI string packed in bstrVal member of *pvarID. This is the preferred format for C++ applications because of the best performance. It is a binary data so the string can contain zeroes and may not be zero terminated. Callers can get its real length by calling SysStringByteLen API on bstrVal member. 2 pData An address of VARIANT variable that will receive the data read from the device. The caller is responsible to call VariantClear on that variable when it is no longer needed. Return value Visual Basic: A Variant containing the data read from the device. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 25 ( ! "0 : ! $ This method configures parameters used in uploading and downloading functions. Note: These configuration parameters can be get/set via GetSetting and SetSetting methods, and specifying . This allows them to be loaded from and stored to a file profile using the corresponding methods. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 22 - Syntax Visual Basic: Sub ConfigureMlxcmLoader (Protocol as LoaderProtocolCodes, LoaderFilename as String) C++: HRESULT ConfigureMlxcmLoader ([in] LoaderProtocolCodes Protocol, [in] BSTR LoaderFilename); Parameters Protocol A LoaderProtocolCodes constant specifying the protocol to be used while uploading and downloading. By default library uses Fast protocol. LoaderFilename A String specifying the full path to .HEX file, containing the code of the loader program. This parameter must be set once before uploading. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 26 ( ! $ This method configures parameters relevant to LIN protocol used for uploading and downloading. Note: NAD parameter can be the corresponding methods. get/set via GetSetting and SetSetting methods . This allows it to be loaded from and stored to a file profile using Syntax Visual Basic: Sub ConfigureLinLoader (Parameter as Long, NAD as Byte) C++: HRESULT ConfigureLinLoader ([in] long Parameter, [in] unsigned char NAD); Parameters Parameter Reserved. NAD A Byte specifying NAD of the LIN node which will be used for uploading or downloading memory. Return value PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 23 - C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 . ( ! $ This method configures parameters relevant to fast protocol used for uploading and downloading. Note: Fast loader baudrate can be get/set via GetSetting and SetSetting methods and specifying . This allows it to be loaded from and stored to a file profile using the corresponding methods. Syntax Visual Basic: Sub ConfigureFastLoader (Parameter as Long, Baudrate as Long) C++: HRESULT ConfigureFastLoader ([in] long Parameter, [in] long Baudrate); Parameters Parameter Reserved. Baudrate A Long specifying the required baudrate for fast protocol. Possible values are between 5000 and 200000 [bps]. The default value is 125000 [bps]. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 ! "0 : ! $ This method stops uploading or downloading process. Syntax Visual Basic: PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 24 - Sub MlxcmAbortLoader() C++: HRESULT MlxcmAbortLoader (); Parameters none Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 ! "0 : - # 0 " ' : ! $ This method uploads data from a .HEX file into the PTC04’s XRAM. Then the methods MlxcmUploadFromXram and MlxcmVerifyWithXram can be used to perform operations with a MelexCM device. Syntax Visual Basic: Sub MlxcmSaveHexFileInXram(Filename As String, Progress As Object, Hint as Variant, ByRef LoaderPtr As Long, ByRef MlxPtr As Long, ByRef UserPtr As Long, [StartAddr As Long = 0], [EndAddr As Long = &H7FFFFFFF]) C++: HRESULT MlxcmSaveHexFileInXram ([in] BSTR Filename, [in] LPDISPATCH Progress, [in] TVariantInParam Hint, [out] long* LoaderPtr, [out] long* MlxPtr, [out] long* UserPtr, [in,defaultvalue(0)] long StartAddr, [in,defaultvalue(0x7FFFFFFF)] long EndAddr); Parameters Filename A String specifying the full path to .HEX file. Progress Object that implements IMPTProgressCallback interface. It should have implementation of methods OnStart, OnProgress and OnEnd. Nothing (NULL) can be passed if the callback is not needed. Hint A Variant that is sent back to callback object as parameter in Onxxx methods. LoaderPtr MlxPtr UserPtr PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 25 - An address of a Long variable that will receive the XRAM starting address of the corresponding code part. These variables are required later in MlxcmUploadFromXram and MlxcmVerifyWithXram methods. StartAddr A Long value, specifying the start address (inclusive) of the region to be uploaded. The data from the HEX file, which is outside the region, will be ignored. EndAddr A Long value, specifying the end address (exclusive) of the region to be uploaded. The data from the HEX file, which is outside the region, will be ignored. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 ! "0 : 8 " :' : ! $ This method uploads the data stored in PTC04’s XRAM into a MelexCM device. Syntax Visual Basic: Sub MlxcmUploadFromXram(LoaderPtr As Long, MlxPtr As Long, UserPtr As Long) C++: HRESULT MlxcmUploadFromXram ([in] long LoaderPtr, [in] long MlxPtr, [in] long UserPtr); Parameters LoaderPtr MlxPtr UserPtr A Long value, specifying the start address of the XRAM where the data is saved. These values should be taken as a result from MlxcmSaveHexFileInXram method. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 26 - 2 & ! "0 : 9 %7 % 7 $' : ! $ This method compares the data stored in PTC04’s XRAM with that into a MelexCM device. Note that the range [0x2000; 0x2400) is not verified. Syntax Visual Basic: Sub MlxcmVerifyWithXram (Mem1Ptr As Long, Mem2Ptr As Long) C++: HRESULT MlxcmVerifyWithXram ([in] long Mem1Ptr, [in] long Mem2Ptr); Parameters Mem1Ptr Mem2Ptr A Long value, specifying the start address of the XRAM where the data is saved. These values should be taken as a result from MlxcmSaveHexFileInXram method and normally are the MlxPtr and UserPtr. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 + ( % This is a boolean property, which enables or disables logging of MelexCM loader commands. The default value for this property is False. Syntax Visual Basic: Property LoaderLog as Boolean C++: HRESULT get_LoaderLog(/*[out][retval]*/ VARIANT_BOOL * pValue); HRESULT set_LoaderLog(/*[in]*/ VARIANT_BOOL Value); Parameters pValue An address of Boolean variable that receives current value of the property. Value A Boolean specifying new value for the property. Return value PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 27 - C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 2 ! "0 : - :8 " # 0 " ! $ This method uploads NVRAM data from a .HEX file into a MelexCM device. The valid address range, specified in the HEX file is within 0 to 127. All data outside that region will be ignored. Syntax Visual Basic: Sub MlxcmNvramUploadHexFile(Filename as String, Options as NvramOptionCodes) C++: HRESULT MlxcmNvramUploadHexFile([in] BSTR Filename, [in] NvramOptionCodes Options); Parameters Filename A String specifying the full path to .HEX file. Options A combination (sum or bitwise OR) of NvramOptionCodes, setting the required options. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 4 ! "0 : - :, " # 0 " ! $ This method reads data from NVRAM of a MelexCM device and saves it into a .HEX file. Syntax Visual Basic: Function MlxcmNvramDownloadHexFile(Filename as String) as Boolean C++: PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 28 - HRESULT MlxcmNvramDownloadHexFile([in] BSTR Filename, [out,retval] VARIANT_BOOL* pRes); Parameters Filename A String specifying the full path to .HEX file. pRes An address of VARIANT_BOOL variable, receiving the result of NVRAM validity check. If the checksum of data is correct, the result is true otherwise it is false. Return value Visual Basic: A Boolean value, containing the result of NVRAM validity check. If the checksum of data is correct, the result is true otherwise it is false. C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 5 ! "0 : - :8 " ! $ This method uploads NVRAM data into a MelexCM device. Syntax Visual Basic: Sub MlxcmNvramUpload (Format as Long, Data as Variant, Options as NvramOptionCodes) C++: HRESULT MlxcmNvramUpload( [in] long Format, [in] TVariantInParam Data, [in] NvramOptionCodes Options); Parameters Format A Long specifying the format of the data in Data. Possible values are: Value Format 1 Data is an array of bytes. This is the preferred format for Visual Basic applications. 2 Data is an ANSI string packed in bstrVal member of *pvarID. This is the preferred format for C++ applications because of the best performance. It is a binary data so the string can contain zeroes and may not be zero terminated. Callers can get its real length by calling SysStringByteLen API on bstrVal member. Data A Variant containing the data to be uploaded. Only the first 128 bytes are meaningful. PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 29 - Options A combination (sum or bitwise OR) of NvramOptionCodes, setting the required options. Return value C++: The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 2 6 ! "0 : - :, " ! $ This method reads NVRAM data from a MelexCM device. Syntax Visual Basic: Function MlxcmNvramDownload (Format as Long, Byref pData as Variant) as Boolean C++: HRESULT MlxcmNvramDownload [in] long Format, [out] TVariant* pData, [out,retval] VARIANT_BOOL* pRes); Parameters Format A Long specifying the format of the returned data in pData. Possible values are: Value 1 2 Format Return value is an array of bytes. This is the preferred format for Visual Basic applications. Return value is an ANSI string packed in bstrVal member of *pvarID. This is the preferred format for C++ applications because of the best performance. It is a binary data so the string can contain zeroes and may not be zero terminated. Callers can get its real length by calling SysStringByteLen API on bstrVal member. pData An address of VARIANT variable that will receive the data read from the device. The caller is responsible to call VariantClear on that variable when it is no longer needed. pRes An address of VARIANT_BOOL variable, receiving the result of NVRAM validity check. If the checksum of data is correct, the result is true otherwise it is false. Return value Visual Basic: A Boolean value, containing the result of NVRAM validity check. If the checksum of data is correct, the result is true otherwise it is false. C++: PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 30 - The return value obtained from the returned HRESULT is one of the following: Return value Meaning S_OK The operation completed successfully. Any other error code The operation failed. Quick Info Header: Declared in PSFPTCLINAAMLXModule_TLB.h. 4 / : 4 ( : The following constants specify different settings. They are used by GetSetting and SetSetting methods. " " % . ! $ ( + - # ' / ! ) % * % % & ,& # " % * / 0 1/2 ( 3) 3 % 1 4 % ' 5 % % , % ! ' . /6 7 % ) /% / ' % % !+ ( % ( ! /% 2 8) 9 : 9 4' . ' % . /' / % % % /) ) * ;<= ) /) 3 > ) % * 3) )3 3 . )' # 3 ) ' % * # % * 3 ) ' % # ) % * % # ) ' $ /' 2 ( /? ' ) % ! / % + # ) " 9 2" 3 ) + /6 /' " ' % 4 PTC04-LIN PSF Library Object Model Ver.1.10 # 3 ) 3) ' 2009-02-19 - 31 - 4 " : The following constants specify encoding types of the protocol to be used when uploading and downloading memory. They are used in ConfigureMlxcmLoader method. % % % % % 4 1 1 1 1 1 % * ' ' 3 - : ! $ ( 1 @ % * @ ' ' ' 3A % * : The following constants specify different options (MlxcmNvramUploadHexFile and MlxcmNvramUpload). 6 @ # # 3 )' 3 )1?" 2 2 PTC04-LIN PSF Library Object Model Ver.1.10 ! ( used by NVRAM upload functions 3 /) 3 68" ) > 3 @ 3 2009-02-19 - 32 - 5 , " : Devices sold by Melexis are covered by the warranty and patent indemnification provisions appearing in its Term of Sale. Melexis makes no warranty, express, statutory, implied, or by description regarding the information set forth herein or regarding the freedom of the described devices from patent infringement. Melexis reserves the right to change specifications and prices at any time and without notice. Therefore, prior to designing this product into a system, it is necessary to check with Melexis for current information. This product is intended for use in normal commercial applications. Applications requiring extended temperature range, unusual environmental requirements, or high reliability applications, such as military, medical life-support or life-sustaining equipment are specifically not recommended without additional processing by Melexis for each application. The information furnished by Melexis is believed to be correct and accurate. However, Melexis shall not be liable to recipient or any third party for any damages, including but not limited to personal injury, property damage, loss of profits, loss of use, interrupt of business or indirect, special incidental or consequential damages, of any kind, in connection with or arising out of the furnishing, performance or use of the technical data herein. No obligation or liability to recipient or any third party shall arise or flow out of Melexis’ rendering of technical or other services. © 2004 Melexis NV. All rights reserved. website at: www.melexis.com Or for additional information contact Melexis Direct: Europe and Japan: Phone: +32 13 67 04 95 E-mail: [email protected] All other locations: Phone: +1 603 223 2362 E-mail: [email protected] QS9000, VDA6.1 and ISO14001 Certified PTC04-LIN PSF Library Object Model Ver.1.10 2009-02-19 - 33 -