PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
-1-
1
CONTENTS .............................................................................................................................................................. 2
2
INTRODUCTION .................................................................................................................................................... 3
3
SOFTWARE STRUCTURE .................................................................................................................................... 3
3.1
3.2
3.3
4
PSFPTCLINAAMLXMANAGER OBJECT ......................................................................................................... 5
4.1
5
MlxcmUploadHexFile Method ......................................................................................................................... 15
MlxcmVerifyHexFile Method .......................................................................................................................... 16
MlxcmDownloadHexFile Method .................................................................................................................... 17
MlxcmUpload Method...................................................................................................................................... 18
MlxcmDownload Method................................................................................................................................. 19
ConfigureMlxcmLoader Method ...................................................................................................................... 19
ConfigureLinLoader Method ............................................................................................................................ 20
ConfigureFastLoader Method ........................................................................................................................... 21
MlxcmAbortLoader Method ............................................................................................................................. 21
MlxcmSaveHexFileInXram Method................................................................................................................. 22
MlxcmUploadFromXram Method .................................................................................................................... 23
MlxcmVerifyWithXram Method ...................................................................................................................... 24
LoaderLog Property.......................................................................................................................................... 24
ENUMERATION CONSTANTS .......................................................................................................................... 25
7.1
7.2
8
Background......................................................................................................................................................... 6
Logging Property ................................................................................................................................................ 7
PTC04 Property .................................................................................................................................................. 8
Exchange Method ............................................................................................................................................... 8
_Exchange Method ........................................................................................................................................... 10
GetLinBusState Method.................................................................................................................................... 11
GetSetting Method ............................................................................................................................................ 11
OpenProfile Method ......................................................................................................................................... 12
SaveProfile Method .......................................................................................................................................... 12
SaveProfileAs Method ...................................................................................................................................... 13
SendWakeUpPulse Method .............................................................................................................................. 13
SetSetting Method............................................................................................................................................. 14
ValidateId Method ............................................................................................................................................ 15
MELEXCM LOADER METHODS OF PSFPTCLINAAMLXDEVICE.......................................................... 15
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
7
Background......................................................................................................................................................... 5
PSFPTCLINAAMLXDEVICE OBJECT............................................................................................................... 6
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
6
Object Model ...................................................................................................................................................... 3
Object Structure and Hierarchy .......................................................................................................................... 3
Objects with Interfaces ....................................................................................................................................... 4
SettingCodes enumeration ................................................................................................................................ 25
LoaderProtocolCodes enumeration................................................................................................................... 26
DISCLAIMER ........................................................................................................................................................ 27
PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
-2-
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.08
PTC04PSFDevice
2008-06-05
-3-
$
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.08
2008-06-05
-4-
&
&
! '!
'!
)
(
*(
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.08
2008-06-05
-5-
+
+
! ',
', )
*(
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.08
2008-06-05
-6-
' 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.08
2008-06-05
-7-
+
.&
%
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.08
2008-06-05
-8-
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.08
2008-06-05
-9-
++
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.08
2008-06-05
- 10 -
+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.08
2008-06-05
- 11 -
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.08
2008-06-05
- 12 -
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.08
2008-06-05
- 13 -
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.08
2008-06-05
- 14 -
+
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.
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.
2
! "0 : 8 "
# 0 " !
$
This method uploads data from a .HEX file into a MelexCM device.
Syntax
Visual Basic:
Sub MlxcmUploadHexFile(Filename as String, Progress as Object, Hint as Variant,
[StartAddr As Long], [EndAddr As Long = &H7FFFFFFF&])
C++:
HRESULT MlxcmUploadHexFile([in] BSTR Filename, [in] LPDISPATCH Progress,
[in] TVariantInParam Hint, [in,defaultvalue(0)] long StartAddr,
[in,defaultvalue(0x7FFFFFFF)] long EndAddr);
PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
- 15 -
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.
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 : 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.08
2008-06-05
- 16 -
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.
PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
- 17 -
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 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.
PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
- 18 -
2+
! "0 : ,
"
!
$
This method reads data from a MelexCM device.
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.
22
(
! "0 :
!
$
This method configures parameters used in uploading and downloading functions.
PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
- 19 -
Note: These configuration parameters can be get/set via GetSetting and SetSetting methods. This allows they to
be loaded from and stored to a file profile using the corresponding methods.
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 LIN 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.
24
(
!
$
This method configures parameters relevant to LIN protocol used for uploading and downloading.
Note: These configuration parameters can be get/set via GetSetting and SetSetting methods. This allows they to
be loaded from and stored to a file profile using the corresponding methods.
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.
PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
- 20 -
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.
25
(
!
$
This method configures parameters relevant to fast protocol used for uploading and downloading.
Note: These configuration parameters can be get/set via GetSetting and SetSetting methods. This allows they 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.
26
! "0 :
!
$
This method stops uploading or downloading process.
Syntax
PTC04-LIN PSF Library Object Model
Ver.1.08
2008-06-05
- 21 -
Visual Basic:
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.08
2008-06-05
- 22 -
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.08
2008-06-05
- 23 -
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.08
2008-06-05
- 24 -
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.
4 /
:
4
(
:
The following constants specify different settings. They are used by GetSetting and SetSetting methods.
!
%
)
+
$
" (
- .
"
0
,
"
$
5
"
"
*
&
"
'
"
"
4
#
*+
"
$
- .6
7
"
,
&
(
#
(
"
'( ,
.
0.1 %23& 3
,
8& 9
:
9
4$
$ "
.$ . "
"
"
." . $
."
"
1
)
(
"
( ,
,
.&
&
,
&
.&
3 >
3&,
&3
3
&$
"
'
"
'
$
(
(
"
(
,
' ;<=
,
& "
'
(
2
(
)
$
/
)
2
,
3,
&
3,
&
"
,
&,
"
'
"
,
&,
$
!
.$
1
%
.?
$ &
"
.
(
)
.6
"
&
9
1 3
)
&
,
+
.$
$
"
4
PTC04-LIN PSF Library Object Model
Ver.1.08
3
&
3&
$
2008-06-05
- 25 -
4
"
:
The following constants specify encoding types of the protocol to be used when uploading and downloading
memory. They are used in ConfigureMlxcmLoader method.
"
"
"
"
0
0
0
0
,
,"
'
,$
,$
PTC04-LIN PSF Library Object Model
Ver.1.08
!
0 ,
(,
@ "
'( ,
@ $ ( ,
$
, 3 &$
3A "
'
((
2008-06-05
- 26 -
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.08
2008-06-05
- 27 -