Recommended Practice: Windows™ Communication Api

Recommended Practice
Proposed RP 1210C(T) VMRS 053
WINDOWS™ COMMUNICATION API

TABLE OF CONTENTS
1. PREFACE.................................................................................................................................................6
2. PURPOSE AND SCOPE........................................................................................................................... 6
2.1 TECHNICAL DISCLAIMER.................................................................................................................................6
3. RP 1210 BACKGROUND......................................................................................................................... 6
3.1 BACKWARDS COMPATIBILITY.........................................................................................................................6
3.2. OPERATING SYSTEM SUPPORT....................................................................................................................6
3.3 DOCUMENT CONVENTIONS............................................................................................................................6
4. RP 1210 COMPLIANCE DEFINED........................................................................................................... 6
4.1. RP 1210C-Compliant VDA (Single/Multi-Application)........................................................................7
4.2. RP1210C-Compliant Application.............................................................................................................7
4.3. RP1210C-Compliant Application and Supported VDA’s..................................................................7
4.4. ONGOING EFFORTS REGARDING RP 1210 Compliancy..........................................................................7
5. HIGH-LEVEL RP 1210 INTERFACE CONCEPT AND DESIGN.............................................................. 7
5.1 DESIGN..............................................................................................................................................................8
6. FUNCTIONAL SPECIFICATION............................................................................................................... 8
6.1 REQUIRED HIGH-LEVEL FUNCTIONALITY (SINGLE APPLICATION).............................................................8
6.2 API FILE NAMING CONVENTIONS...................................................................................................................9
7. RP 1210 OVERVIEW FOR THE APPLICATION DEVELOPER............................................................... 9
7.1 API INTERFACE AT A GLANCE..........................................................................................................................9
7.2 STEP 1—APPLICATION PARSING OF THE RP1210 INI FILES......................................................................9
7.3 STEP 2—Asking User Which Adapter to Use (or Auto-Detecting)............................................9
7.4 STEP 3—OPENING DLL and Getting Function Pointers.................................................................10
7.6 Step 5—Allow Reception of Messages............................................................................................ 11
7.7 Step 6—Read a Message..........................................................................................................................11
7.8 Step 7—Send a Message..........................................................................................................................12
7.9 Step 8—Closing the Interface and Freeing Resources...........................................................12
8. RP 1210 Variables and Initial States........................................................................................ 12
8.1 Echo Mode....................................................................................................................................................13
8.2. J1708Mode and RP 1210B Enhancements............................................................................................13
8.3. ISO9141/KWP2000 Mode..............................................................................................................................13
8.4. FilterStates................................................................................................................................................13
8.5. Blocking Mode...........................................................................................................................................13
8.6. Blocking Timeout......................................................................................................................................13
9. RP 1210 REQUIRED FUNCTIONS......................................................................................................... 13
10. VDA AND Application Developer NOTES................................................................................. 14
10.1 Unexpected Vehicle Interface Adapter Disconnect................................................................14
10.2. Error Code 142 and Backwards Compatibility............................................................................14
10.3. Notes on CAN/J1939 and ISO15765 Coexistence.............................................................................15
10.3.1. RP1210B and ISO15765 Compatibility Issue....................................................................................................... 15
10.4. Notes on Wireless VDAs and Time/Code-Sensitive Applications.........................................16
10.5. Notes on Windows 64-bit Machines and INI Files........................................................................16
10.6. The “Name” Parameter in the “VendorInformation” INI Section...........................................16
10.7. Notes on CAN and CAN-Based Protocols (e.g., SAE J2284).......................................................17
10.8. Notes on J1939 Address Claim (Single Application)...................................................................17
10.8.1. Possible Transport Protocol Layer Conflict and Resolution.................................................................................. 18
10.9. Notes on J1939 at 500k (J1939-14) and Auto Speed Detection...................................................18
10.10. Applications Doing Auto-VDA-Detection (Not Recommended)............................................19
10.11. Blocking/Non-Blocking Considerations for App Developers...........................................19
10.12. Queue Full Characteristics for VDA Developers..................................................................20
10.12.1. Err_Tx_Queue_Full............................................................................................................................................. 20
10.12.2. Err_Rx_Queue_Full............................................................................................................................................ 20
10.13. Filter State Ambiguities..................................................................................................................20
©2011—TMC/ATA Issued 4/1997

Proposed RP 1210C(T) Ballot Version — Revised x/xxxx
10.14. Filter Clarifications – More Than 1 Per SendCommand() Call........................................20
10.14.1. J1708/J1587 Parameter ID (PID) Filtering.......................................................................................................... 20
10.14.2. Inclusive and Exclusive Filtering......................................................................................................................... 20
10.15. “Least Common Denominator” Development ........................................................................21
10.16. INI File Versus Registry and XML....................................................................................................21
10.17. nIsAppPacketizingIncomingMsgs and J1939 Transport Protocol....................................21
10.18. RP 1210 Compliancy Testing “Application”...................................................................................21
10.19. Windows Vista/Windows 7 and RP 1210-Compliancy.................................................................21
10.19.1. Compliancy for VDA Vendors and Windows Vista/7........................................................................................... 21
10.19.2. Compliancy for Application Developers and Windows Vista/7............................................................................ 21
11. Compliance for API/VDA Vendors........................................................................................... 22
11.1. Standard Functions..............................................................................................................................22
11.2. RP1210_SendCommand Functions......................................................................................................23
12. RP1210_ClientConnect................................................................................................................. 24
12.1. RP1210_ClientConnect Prototype...................................................................................................24
12.2. RP1210_ClientConnect Parameters................................................................................................24
12.3. RP1210_Clientconnect Return Value.............................................................................................25
12.4. RP1210_ClientConnect Notes............................................................................................................26
12.4.1. Multiple CAN Protocols on One CAN Channel; Multiple Baud Rates (J1939/J1708)........................................... 26
12.5. RP1210_Clientconnect Protocol Connection String.............................................................26
12.5.1. Example................................................................................................................................................................ 27
12.5.2. Device-Centric Versus Protocol-Centric................................................................................................................ 27
12.5.3. RP 1210B/C-Compliance: INI File Shall be Device-Centric with No Invented Protocols...................................... 27
12.6. Using TCP/IP and DNS as a Transport Layer for a Protocol..................................................28
12.7. Using a Modem as a Transport Layer for a Protocol.............................................................28
12.8. SETTING CAN BAUD RATE on RP1210_ClientConnect..................................................................... 28
12.8.1. Setting CAN Baud Rate – Format 1...................................................................................................................... 29
12.8.2. Setting CAN Baud Rate – Format 2 ..................................................................................................................... 29
12.8.3. Setting CAN Baud Rate – Format 3 ..................................................................................................................... 29
12.8.4. Setting CAN Baud Rate – Format 4 – Default . .................................................................................................... 29
12.8.5. Setting CAN Baud Rate – Format 5 .................................................................................................................... 29
12.9. Setting CAN/J1939/ISO15765 Channel on RP1210_ClientConnect............................................ 29
12.10. SETTING J1708 BAUD RATE on RP1210_ClientConnect................................................................. 30
12.10.1. Setting J1708 Baud Rate – Format 1.................................................................................................................. 30
12.10.2. Setting J1708 Baud Rate – Format 2 – Default ................................................................................................. 30
12.11. SETTING J1939 BAUD RATE on RP1210_ClientConnect................................................................. 30
12.11.1.Setting J1939 Baud Rate – Format 1................................................................................................................... 30
12.11.2. Setting J1939 Baud Rate – Format 2 – Default . ................................................................................................ 30
12.11.4. Setting J1939 Baud Rate – Format 4 ................................................................................................................ 31
12.12. SETTING ISO15765-2 BAUD RATE on RP1210_ClientConnect....................................................... 31
12.12.1. Setting ISO15765 Baud Rate – Format 1........................................................................................................... 31
12.12.2. Setting ISO15765 Baud Rate – Format 2 – Default ........................................................................................... 31
12.13. Multiple RP1210_ClientConnect Strings....................................................................................31
13. RP1210_ClientDisconnect.......................................................................................................... 31
13.1. RP1210_ClientDisconnect Prototype.............................................................................................32
13.2. RP1210_ClientDisconnect Parameters..........................................................................................32
13.3. RP1210_ClientDisconnect Return Value.......................................................................................32
13.4. RP1210_ClientDisconnect Notes......................................................................................................32
14. RP1210_SendMessage.................................................................................................................. 32
14.1. Note to Application Vendors............................................................................................................33
14.2. RP1210_SendMessage Prototype.....................................................................................................33
14.3. RP1210_SendMessage Parameters...................................................................................................33
14.4. RP1210_SendMessage Return Value................................................................................................33
14.5. Formatting a J1708/PLC Message for RP1210_SendMessage................................................... 34
14.6. Formatting a J1939 Message for RP1210_SendMessage........................................................... 34
14.7. Formatting a CAN/J2284 Message for RP1210_SendMessage.................................................. 35
14.8. Formatting a J1850 Message for RP1210_SendMessage........................................................... 35
14.9. Formatting an ISO15765 Message for RP1210_SendMessage.................................................. 36
14.10. Formatting a KWP2000/ISO9141 Message for RP1210_SendMessage................................... 37
15. RP1210_ReadMessage.................................................................................................................. 37
15.1. RP1210_ReadMessage Prototype.....................................................................................................37
15.2. RP1210_ReadMessage Parameters...................................................................................................37
15.3. RP1210_ReadMessage Return Value................................................................................................38
15.4. The J1708/PLC Message from RP1210_ReadMessage................................................................... 38
©2011—TMC/ATA
Proposed RP 1210C(T) Ballot Version —
15.5. The J1939 Message from RP1210_ReadMessage........................................................................... 39
15.6. The CAN/J2284 Message from RP1210_ReadMessage................................................................... 40
15.7. The J1850 Message from RP1210_ReadMessage........................................................................... 41
15.8. The ISO15765 Message from RP1210_ReadMessage..................................................................... 41
15.9. The KWP2000/ISO9141 Message from RP1210_ReadMessage ....................................................43
16. RP1210_ReadVersion.................................................................................................................... 43
16.1. RP1210_ReadVersion Prototype.......................................................................................................43
16.2. RP1210_ReadVersion Parameters.....................................................................................................44
16.3. RP1210_ReadVersion Return Value..................................................................................................44
17. RP1210_ReadDetailed Version.................................................................................................. 44
17.1. RP1210_ReadDetailed Version Prototype.....................................................................................44
17.2. RP1210_ReadDetailed Version Parameters..................................................................................44
17.3. RP1210_ReadDetailed Version Return Value...............................................................................45
18. RP1210_GetErrorMsg.................................................................................................................. 45
18.1. RP1210_GetError Msg Prototype....................................................................................................45
18.2. RP1210_GetErrorMsg Parameters..................................................................................................45
18.3 RP1210_GetErrorMsg Return Value................................................................................................45
19. RP1210_GetLastErrorMsg......................................................................................................... 45
19.1. RP1210_GetLastErrorMsg Prototype............................................................................................46
19.2. RP1210_GetLastErrorMsg Parameters.........................................................................................46
19.3. RP1210_GetLastErrorMsg Return Value......................................................................................46
20. RP1210_GetHardwareStatus..................................................................................................... 46
20.1. Fall 2010 TASK FORCE Discussions—Background Notes..........................................................46
20.2. Changes New to RP 1210C.....................................................................................................................47
20.2.1. nBlockOnRequest is Now Ignored........................................................................................................................ 47
20.2.2. nInfoSize Changed to 64 Bytes............................................................................................................................. 47
20.2.3. VDAs to Return Success and Only Populate Number of Bytes
The Application Requested....................................................................................................................................... 47
20.2.4. Application Developer Notes................................................................................................................................. 47
20.2.5. VDA Vendor and Application Developer Notes on the fpchClientInfo Buffer......................................................... 47
20.3. RP1210_GetHardwareStatus Prototype.......................................................................................48
20.4. RP1210_GetHardwareStatus Parameters.....................................................................................48
20.5. RP1210_GetHardwareStatus Return Value..................................................................................48
20.6. Information Returned in fpchClientInfo.....................................................................................48
20.6.1. Hardware Status (Bytes 0-1)................................................................................................................................. 49
20.6.2. J1939 (Bytes 2-3).................................................................................................................................................. 49
20.6.3. J1708 (Bytes 4-5).................................................................................................................................................. 49
20.6.4. CAN (Bytes 6-7).................................................................................................................................................... 49
20.6.5. J1850 (Bytes 8-9).................................................................................................................................................. 49
20.6.6. Vendor 1, 2, 3 (Bytes 10/11, 12/13, 14/15)............................................................................................................ 49
20.6.7. ISO15765 (Bytes 16-17) ...................................................................................................................................... 50
20.6.8. ISO9141 (Bytes 18-19) ........................................................................................................................................ 50
20.6.9. KWP2000 (Bytes 20-21) ...................................................................................................................................... 50
20.6.10. GM_ALDL (Bytes 22-23)—reserved For Future ALDL Implementation.............................................................. 50
21. RP1210_SendCommand................................................................................................................. 50
21.1. RP1210_SendCommand Prototype....................................................................................................51
21.2. RP1210_SendCommand Parameters..................................................................................................51
21.3. RP1210_SendCommand Return Value...............................................................................................51
21.4. Values for the nCommandNumber Parameter ..........................................................................51
21.5. RP1210_ Reset_Device............................................................................................................................52
21.5.1. RP1210_ Reset_Device Return Value.................................................................................................................. 53
21.6. RP1210_Set_All_Filters_States_To_Pass....................................................................................... 53
21.6.1. RP1210_ Set_All_Filter_States_To_Pass Return Value ...................................................................................... 53
21.7. RP1210_Set_Message_Filtering_For_J1939.................................................................................... 53
21.7.1. J1939 Filter Parameter Frame.............................................................................................................................. 54
21.7.2. RP1210_Set_Message_Filtering_For_J1939 Return Value ................................................................................ 54
21.8. RP1210_Set_Message_Filtering_For_CAN...................................................................................... 54
21.8.1. CAN Filter Parameter Frame................................................................................................................................ 55
21.8.2. Standard CAN (11-bit Identifier) Example............................................................................................................. 55
21.8.3. RP1210_Set_Message_Filtering_For_CAN Return Value . ................................................................................. 55
21.9. RP1210_Set_Message_Filtering_For_J1708.................................................................................... 55
21.9.1. RP1210_Set_Message_Filtering_For_J1708 Return Value ................................................................................ 56
21.10. RP1210_Set_Message_Filtering_For_J1850.................................................................................. 56
21.10.1. RP1210_Set_Message_Filtering_For_J1850 Return Value .............................................................................. 57
21.11. RP1210_Set_Message_Filtering_For_ISO15765........................................................................... 57
21.11.1. ISO15765 Filter Parameter Frame...................................................................................................................... 57
21.11.2. RP1210_Set_Message_Filtering_For_ISO15765 Return Value ........................................................................ 58
©2011—TMC/ATA
21.12. RP1210_Generic_Driver_Command.................................................................................................58
21.12.1. RP1210_Generic_Driver_Command Return Value . .......................................................................................... 58
21.13. RP1210_Set_J1708_Mode.......................................................................................................................58
21.13.1. RP1210_Set_J1708_Mode Return Value .......................................................................................................... 59
21.14. RP1210_Set_ISO9141KWP2000_Mode..................................................................................................59
21.14.1. RP1210_Set_ISO9141KWP2000_Mode Return Value . .................................................................................... 59
21.15. RP1210_Echo_Transmitted_Messages.........................................................................................60
21.15.1. RP1210_Echo_Transmitted_Messages Return Value ....................................................................................... 60
21.16. RP1210_Set_All_Filters_States_to_Discard.............................................................................. 60
21.16.1. RP1210_Set_All_Filter_States_To_Discard Return Value ................................................................................. 60
21.17. RP1210_Set_Message_Receive..........................................................................................................60
21.17.1. RP1210_Set_Message_Receive Return Value ................................................................................................. 61
21.18. RP1210_Protect_J1939_Address......................................................................................................61
21.18.1. Behavior When Connecting to a Network Without Other Controllers Transmitting............................................. 61
21.18.2. J1939 Address Claim Frame............................................................................................................................... 62
21.18.3. RP1210_ Protect_J1939_Address Return Value ............................................................................................... 62
21.19. RP1210_Release_J1939_Address......................................................................................................63
21.19.1. J1939 Address Release Frame........................................................................................................................... 63
21.19.2. RP1210_ Release_J1939_Address Return Value ............................................................................................. 63
21.20. RP1210_Set_Broadcast_For Protocol .......................................................................................63
21.20.1. Broadcast List Entry (fpchClientCommand)........................................................................................................ 64
21.20.2. MESSAGE_TIME_TUPLE Record . ................................................................................................................. 65
21.20.3. List Behaviors . .................................................................................................................................................. 65
21.20.4. Return Value, All Function Calls.......................................................................................................................... 65
21.21. RP1210_Set_BlockTimeout.................................................................................................................65
21.21.1. RP1210_Set_BlockTimeout Return Value ......................................................................................................... 66
21.22. RP1210_Set_J1708_Baud.......................................................................................................................66
21.22.1. RP1210_Set_J1708_Baud Return Value ........................................................................................................... 66
21.23. RP1210_Set_J1939_Baud.......................................................................................................................66
21.23.1. RP1210_Set_J1939_Baud Return Value ........................................................................................................... 67
21.24. RP1210_Set_CAN_Baud..........................................................................................................................67
21.24.1. RP1210_Set_CAN_Baud Return Value ............................................................................................................. 67
21.25. RP1210_Set_ISO15765_Baud.................................................................................................................68
21.25.1. RP1210_Set_ISO15765_Baud Return Value .................................................................................................... 68
21.26. RP1210_Set_ Protocol Filter_Type................................................................................................68
21.26.1. RP1210_Set_J1708/J1939/J1850/ISO15765/CAN_Filter_Type Return Value .................................................. 69
21.26.2. Example (RP1210A = Inclusive).......................................................................................................................... 69
21.26.3. Example (RP1210B/C = Exclusive)..................................................................................................................... 69
21.27. RP1210_Set_J1939_Interpacket_Time .............................................................................................69
21.27.1. RP1210_Set_J1939_Interpacket_Time Return Value ....................................................................................... 70
21.28. RP1210_Set_MaxErrorMsgSize .......................................................................................................70
21.28.1. RP1210_Set_MaxErrorMsgSize Return Value .................................................................................................. 70
21.29. RP1210_Disallow_Further_Connections ...................................................................................70
21.29.1. RP1210_Disallow_Further_Connections Return Value...................................................................................... 71
21.30. RP1210_Set_ISO15765_Flow_Control.............................................................................................71
21.30.1. ISO15765 Flow Control Parameter Frame.......................................................................................................... 72
21.30.2. RP1210_Set_ISO15765_Flow_Control Return Value . ...................................................................................... 72
21.31. RP1210_Clear_ISO15765_Flow_Control .......................................................................................72
21.31.1. RP1210_Clear_ISO15765_Flow_Control Return Value .................................................................................... 73
21.32. RP1210_Flush_Tx_Rx_Buffers .........................................................................................................73
21.32.1. RP1210_Flush_Tx_Rx_Buffers Return Value .................................................................................................... 73
21.33. RP1210_Get_Protocol_Connection_Speed................................................................................ 73
21.33.1. RP1210_Get_Protocol_Connection_Speed Return Value ................................................................................. 74
21.34. RP1210_Get_Wireless_State.............................................................................................................74
21.34.1. RP1210_Get_Wireless_State Return Value ...................................................................................................... 74
22. RP1210_Ioctl.................................................................................................................................... 75
22.1. RP1210_Ioctl Prototype.......................................................................................................................75
22.2. RP1210_ Ioctl Parameters...................................................................................................................75
22.3. RP1210_ Ioctl Return Values..............................................................................................................75
22.4. Ioctl ID Values.........................................................................................................................................75
22.5. Ioctl Section............................................................................................................................................76
22.5.1. GET_CONFIG....................................................................................................................................................... 76
22.5.2. SET_CONFIG....................................................................................................................................................... 77
22.5.3. FIVE_BAUD_INIT.................................................................................................................................................. 78
22.5.4. FAST_INIT............................................................................................................................................................. 79
22.5.4.1 ISO9141 Connection – Default Configuration................................................................................................. 80
22.5.4.2. KWP2000 Connection – User Specified Configuration.................................................................................. 80
22.6. ISO9141_K_LINE_ONLY...............................................................................................................................81
22.6.1 RP1210_ Ioctl Return Values................................................................................................................................. 82
©2011—TMC/ATA
23. INI File Format................................................................................................................................ 82
23.1. Case Sensitivity.......................................................................................................................................82
23.2. INI File Text Encoding............................................................................................................................82
23.3. The File Format and Parsing of the RP1210 INI Files..................................................................82
23.4. Mangled RP121032.INI — Detecting and Correcting.................................................................83
23.5. API Installation Program Instructions and Notes..................................................................83
23.5.1. Step 1. Check for RP121032.INI File, Create if Non-Existent.............................................................................. 83
23.5.2. Step 2. Append Your Entry to APIImplementations.............................................................................................. 84
23.5.3. Step 3. Clean Up the INI File............................................................................................................................... 84
23.5.4. Notes:.................................................................................................................................................................... 84
23.5.5. Using and/or Creating the Vendor INI File............................................................................................................ 84
23.6. The [VendorInformation] Section of the Vendor INI File.......................................................84
23.7. The [DeviceInformationdx] Section of the INI File...............................................................87
23.8. The [ProtocolInformationpx] Section of the INI File..............................................................88
23.9. Example VDA Vendor INI File...............................................................................................................89
23.10. API Vendor Header File...................................................................................................................93
24. Debug File Format........................................................................................................................ 97
25. Multi-Application Addendum..................................................................................................... 98
25.1. RP 1210 Compliant — Multi-Application/Multi-Client (MA/MC)..................................................99
25.2. RP 1210 Compliant - Single-Application/Multi-Client (SA/MC)..................................................99
25.3. RP 1210 Compliant — Single-Application/Single-Client (SA/SC)..............................................99
26. Non-Windows Cross Platform Addendum........................................................................... 99
26.1. RP1210 Is Essentially Platform Independent..............................................................................99
26.2. Microsoft Windows CE........................................................................................................................99
26.2.1. File Placement...................................................................................................................................................... 99
26.2.2. System APIs.......................................................................................................................................................... 99
26.2.3. API Changes......................................................................................................................................................... 99
26.3. UNIX and Linux.........................................................................................................................................100
26.3.1. Accounts, Groups, Files, and Permissions.......................................................................................................... 100
26.3.2. System APIs........................................................................................................................................................ 100
26.3.3. API Changes....................................................................................................................................................... 100
26.3.4. RP1210 SO (Shared Object) Files...................................................................................................................... 101
26.3.5. RP1210 Includes, Type Definitions, and Function Declarations For UNIX......................................................... 101
27. Changes TO RP 1210B BY TASK FORCE SINCE PUBLICATION IN 2007.................................. 102
28. TERMINOLOGY.................................................................................................................................. 103
29. REFERENCES.................................................................................................................................... 106
©2011—TMC/ATA
1. PREFACE The most significant change that this version includes
The following Recommended Practice is subject to is the addition of ISO9141 and KWP2000 (ISO14230)
the Disclaimer at the front of TMC’s Recommended as well as J2284 (CAN @500k baud). This document
Engineering Practices Manual. Users are urged to also starts addressing the J1939 protocol running at
read the Disclaimer before considering adoption of 500k (J1939-14) which is likely to appear in model
any portion of this Recommended Practice. year 2013 vehicles.
2. PURPOSE AND SCOPE 3.1 BACKWARDS COMPATIBILITY

This document describes a standardized application RP 1210C is backward compatible with RP 1210B.
program interface (API) for personal computer (PC) RP 1210C is mostly backward compatible with RP
to onboard vehicle ECU communications under the 1210A. However, future versions may not preserve
Microsoft Windows™ family of operating systems. backward compatibility.
It establishes a standard API interface between the
physical datalink (i.e., CAN/J1939), a VDA, and 3.2. OPERATING SYSTEM SUPPORT
Windows™-based software applications running At the time of this writing, the following Windows™
on a PC. operating systems are commonly used in mainte-
nance/service operations:
Current and future hardware requirements have been • Windows XP
carefully considered in developing this software API. • Windows Vista (32 and 64-bit)
This promotes the development of software applica- • Windows 7 (32 and 64-bit)
tions for fleet maintenance, ECU reprogramming,
and vehicle diagnostics using a standard common Manufacturers of software applications and VDAs
software interface. Anyone is welcome to employ may — but are not required to — support any specific
this RP in implementing software systems for ECU combination of the above operating systems. Consult
communications or VDA devices. your software application and vehicle datalink adapter
manual for which operating systems are supported.
A list of terms and accompanying definitions used in Please note:
this document appears in Section 13. • Windows 3.1 and all functionalities associated
specifically with it have been removed from
2.1 TECHNICAL DISCLAIMER this RP.
This RP in no way endorses, recommends, approves, • Even as of 2011, some diagnostic software still
promotes, or favors the preferential treatment of uses the Windows 3.1 HWND parameter.
one vendor (VDA or PC application provider) over • Microsoft has dropped support for Windows
another. Likewise, any mention of diagnostic applica- 2000, effective July 2010.
tion names or brands is not meant to recommend/ • Microsoft is scheduled to drop support for XP
favor one over the other. These are just “common” sometime in 2011.
diagnostic applications available in the marketplace,
and these names are being used to add clarity. For 3.3 DOCUMENT CONVENTIONS
example, it is much easier to understand the termi- Anything related to actual software code (i.e. ex-
nology of a diagnostic application by saying “Detroit amples and code snippets) or INI files will be in the
Diesel Diagnostic Link (DDDL)” and “Allison DOC” Courier New font. The following is an example:
instead of saying “Diagnostic Application 1” and
“Diagnostic Application 2”. Note that most, or all, of if ( ( hRP1210DLL = LoadLibrary( szDLLName ) ) == NULL )
these software names carry some sort of trademark {
printf("Error: LoadLibrary( %s ) failed! \n", szDLLName );
or copyright by their parent companies. exit(1);
}
3. RP 1210 BACKGROUND
4. RP 1210 COMPLIANCE DEFINED
This RP has undergone three prior revisions, the
In versions prior to RP 1210B, no mention was given
original RP 1210, RP 1210A and RP 1210 B (revised
to the term “RP 1210 compliant.” This ultimately lead
6/2007). This revision, called RP1210C, presents
to some confusion in the marketplace as to what
mostly enhancements and additions to RP 1210B
the term actually meant. This section defines what
as requested by OEMs, software development firms
it means to be an RP 1210B- or 1210C-compliant
specializing in onboard vehicle communications, as
VDA and what it means to have an RP 1210B- or
well as manufacturers of VDAs.
1210C-compliant software application.
©2011—TMC/ATA
In general, any RP 1210B/C-compliant application plete” list of adapters installed, any compliant
should work with any RP 1210B/C-compliant vehicle application “shall allow” a user to use any of
interface adapter for their commonly supported oper- those adapters.
ating systems and protocols without needing “work • Some applications only have a select few
around code” in an application or in a VDA API to adapters that they “allow”, thereby reducing
deal with application/VDA eccentricities (non-compli- VDA marketplace competition.
ance). This allows:
• VDA’s to be totally transparent to different 4.3. RP1210C-Compliant Application and
applications. Supported VDA’s
• Applications to function reliably and consis- As mentioned in the previous section, some ap-
tently between VDA’s. plications listed themselves as RP1210-compliant,
but only “supported” a certain few adapters. The
4.1. RP 1210C-Compliant VDA reason for this was “technical support dollars.” Does
(Single/Multi-Application) RP1210-compliancy mean that an application “has
An RP 1210C-compliant VDA is any VDA that imple- to support” (meaning doing extensive testing and
ments and specifically follows the API presented validation of) all adapters? The answer is “no,” they
herein for that vendor’s supported operating systems only have to allow the selection and “attempted” use
and protocols without any exceptions for a single of all the adapters. The application developer can
application. get around having to spend an enormous amount
on testing and support by clearly stating that they
An RP 1210C-compliant Multi-Application VDA is will only “support” a specific list of adapters. If an
any VDA that implements and specifically follows “outside-the-list” adapter does not work, then they
the API presented herein for that vendor’s supported tell the user to get one of the supported adapters or
operating systems and protocols without any excep- tell them to call that specific VDA vendor.
tions, including those defined in the Multi-Application
Addendum to RP1210C. 4.4. ONGOING EFFORTS REGARDING
RP 1210 Compliancy
4.2. RP1210C-Compliant Application In September 2007, TMC created a task force within
An RP1210C-compliant software application is: its S.12 Onboard Vehicle Electronics Study Group
• Any software application that implements and to develop an RP 1210 “compliancy worksheet” for
specifically follows the API presented herein both VDA's and applications. Work is progressing
for that vendor’s supported operating systems toward that end, but is not yet complete. Contact
and protocols without any exceptions. TMC offices for more information on this effort.
• The application shall present to the user a
“complete” list of adapters installed. 5. HIGH-LEVEL RP 1210 INTERFACE CONCEPT
• In the past, applications failed to read past AND DESIGN
the first several or all of the entries, or failed Figure 5-1 illustrates how the RP 1210 model is
to read the INI file correctly if it had multiple implemented.
commas or spaces in it (mangled INI file). • The RP 1210 software developer is interested
• In addition to presenting the user with a “com- in only the “RP1210 Application” box.
Fig. 5-1: TMC RP 1210 Interface Concept Implementation Model
©2011—TMC/ATA
• The RP1210 VDA manufacturer is responsible this feature, a new variable [VendorInformation]->
for the API, the DLL (which is ultimately re- J1939Addresses=X is present. This variable should
sponsible for changing the vehicle protocol into not exist (not known), or should be 16 or greater if
API command/responses), the VDA Drivers, the VDA vendor has implemented this feature.
and the physical interface device (VDA).
Automatic Bit Rate Detection on CAN Related
5.1 DESIGN Protocols—The VDA API shall support automatic
The API is implemented as a Windows™ Dynamic baud rate detection for all CAN-related protocols
Link Library or DLL (hereafter referred to casually as when a client connects using “Protocol:Baud=Auto”
the “API” or “DLL”). The main purpose of this DLL/API (i.e., “J1939:Baud=Auto”). When doing the automatic
is to provide a generalized procedure-call interface baud detection, the VDA may not cause error frames
between any hardware-specific drivers on the PC to appear on the CAN bus.
and the applications running on that PC.
Send/Receive Message Buffering—Since Microsoft
Each vendor implementation must have built-in Windows™ is event-driven; an API satisfying this
interface(s) with the underlying physical layers (hard- RP must support this feature. There must be implicit
ware) supported by the particular vendor. Information support for asynchronous communication. Blocking
about the vendor DLLs present as well as the protocols (synchronous) requirements have been removed
and devices supported by each implementation can from all functions except RP1210_ReadMessage()
be retrieved through INI files. in RP1210C.
The end-user (or sometimes the application pro- Initialization/Reset—The application software must
gram) will choose the adapter to be used. Then the be able to initialize and reset the hardware through
application will load that DLL through the use of the API-supplied functions at any time. If the hardware
Windows™ LoadLibrary() function, and will locate does not support this, the API-supplied function shall
the specific functions (defined herein) through calls provide a return value to this effect.
to the Windows™ GetProcAddress() function.
Time-Stamping of Messages—Since messages
6. FUNCTIONAL SPECIFICATION received from the vehicle datalink are buffered by
the API, there must be a time-stamp associated with
6.1 REQUIRED HIGH-LEVEL FUNCTIONALITY each message to resolve ambiguity and establish
(SINGLE APPLICATION) an order of precedence between successive mes-
sages. The timestamp is four bytes in length and is
Single Application—The VDA API shall support a in Big Endian (MSB) or Motorola format. See the
minimum of one executable application using the RP1210_ReadMessage function for the definition
VDA at a time (Single Application). This application and layout of the timestamp. The resolution of the
can spawn sub-processes, threads, applets, ActiveX timestamp is implementation-dependent and is given
controls, etc that share the databus connection. From in the API vendor’s INI file.
that single application, the VDA API shall allow up
to 16 RP1210_ClientConnect() calls to any number Version Reporting—The API shall be able to report
of protocols, or the same protocol. Each client will its software version information. In RP1210C, there
have its’ own filter sets and RP1210 variables, al- is a more detailed function called RP1210_Read-
lowing each client to be complete separate from DetailedVersion.
one another.
Message Filtering—The API must support mes-
Supporting 16 J1939 Addresses—The VDA API sage filtering as specified in the definition of the
shall support the protection of 16 different J1939 ad- RP1210_SendCommand function. An implementa-
dresses, including handling of RTS/CTS messages tion of the API shall provide each client with exactly
for those 16 addresses. These addresses can be those messages as are specified in its filter speci-
claimed from one or more clients, and the VDA API fication. Each client gets their own separate set of
will respond with address/NAME data for each upon message filters that are completely independent from
request. This is an RP1210C addition. In order for all other clients.
an application to know if an API has implemented
©2011—TMC/ATA
6.2 API FILE NAMING CONVENTIONS
Each vendor will provide a different name implementation of the API as a number of these implementations
could simultaneously reside on the same PC. No vendor shall name its implementation “RP121032”. Each
vendor will have a name of at least four characters for the filename prefixes listed below. Although long file
names are supported by all of the operating systems mentioned herein, an API DLL shall still be named in
accordance with the file allocation table (FAT) file system naming convention (up to eight characters for the
file name and three characters for the extension).
Implementations will follow the following format (using VENDRX for a vendor name):
File Type Install Directory Resultant File Name

INI File GetSystemWindowsDirectory() VENDRX32.ini
DLL File GetSystemDirectory() VENDRX32.dll
Each VDA vendor’s implementation will have, and install, both of the aforementioned file types (INI/DLL).
The directory to install the INI file to is found using the Windows API call GetSystemWindowsDirectory(),and
the directory where the DLL gets installed would be that directory found using GetSystemDirectory(). The
GetSystemDirectory() call also covers the 64-bit OS file locations (syswow64).
7. RP 1210 OVERVIEW FOR THE APPLICATION DEVELOPER

The following sections step the application developer through what is necessary to get their application up
and going quickly.
7.1 API INTERFACE AT A GLANCE

TMC’s RP1210 API provides a defined INI file and a set of functions so that PC applications can perform
send and receive operations through the DLL, to and from the vehicles’ ECU’s. In simplistic terms, the API
provides an “open/read/write/close”, interface. The following provides a simple look at what is required to
send and read messages using the API interface:
Function Name Description

GetPrivateProfileString (…) Parse the INI files for vendor, device, protocols supported information.
LoadLibrary (…) Open the VDA API’s DLL.
GetProcAddress(…) Get pointers to the RP1210 functions within the VDA API’s DLL.
RP1210_ClientConnect (…) Get a “logical” connection to the vehicle databus.
RP1210_SendCommand(…) Allow messages to pass through the API.
RP1210_SendMessage (…) Send a message.
RP1210_ReadMessage (…) Read a message.
RP1210_ClientDisconnect (…) Close the logical connection to the databus.
FreeLibrary(…) Close the VDA API’s DLL.
7.2 STEP 1—APPLICATION PARSING OF THE RP1210 INI FILES

The first step that an application must perform is the parsing of the RP1210 INI files to find:
• Which vendors and adapters are installed.
• Which of those vendor devices support the protocol(s) and protocol speed(s) needed.
7.3 STEP 2—Asking User Which Adapter to Use (or Auto-Detecting)

The second step that an application must perform is either asking the user which adapter to use, or going
through an auto-detect process to determine which adapter is present.
©2011—TMC/ATA
Although auto-detection is a nice feature for an application to have, TMC recommends that the application
initially bring up a VDA selection dialog box allowing the user to select the adapter. This information should
include (at a minimum) the following dialog box items (see paragraph above on the “Name” parameter in
the “[VendorInformation]” section of the vendor INI file):
• DLL Name and Vendor Name
• Adapter (Device Number, Description, COM Port)
• Protocol*** (see paragraph below)
As J1587 makes way for J1939, applications have started using the J1939 protocol in conjunction with the
J1587 protocol. Applications have been presenting users the choice of protocol to use, which has caused
confusion and technical support calls when a VDA does not work with the application because the wrong
protocol was selected.
If an application can use different protocols, we ask that the application pre-screen (not display) an adapter
if it does not support “at least” their “primary/default” protocol. The application would then look to see if
the primary is the correct protocol for the component, and if not, check if the adapter selected supports the
secondary protocol. If the adapter supports the secondary protocol, automatically switch to that protocol.
If the secondary protocol is not supported, alert the user. This keeps down the number of “selections” that
a technician has to make, resulting in less confusion.
7.4 STEP 3—OPENING DLL and Getting Function Pointers

The third step that an application must perform, after asking the user to choose the VDA, is to load the ap-
propriate API DLL and resolve references to the DLL supplied functions. This is accomplished by using the
Window API functions, LoadLibrary, GetProcAddress and FreeLibrary. If developing a 32-bit Visual Basic Ap-
plication, the names defined should be as the Alias in the appropriate Public Declare Function statement.
Below is a simple example of loading the DLL and getting pointers to the RP 1210-defined functions:
typedef short (WINAPI *fxRP1210_ClientConnect) ( HWND , short, char*, long , long, short );
typedef short (WINAPI *fxRP1210_ClientDisconnect) ( short );
typedef short (WINAPI *fxRP1210_SendMessage) ( short, char*, short, short, short );
typedef short (WINAPI *fxRP1210_ReadMessage) ( short, char*, short, short );
typedef short (WINAPI *fxRP1210_SendCommand) ( short, short, char*, short );
typedef void (WINAPI *fxRP1210_ReadVersion) ( char*, char*, char*, char* );
typedef short (WINAPI *fxRP1210_GetErrorMsg) ( short, char* );
typedef short (WINAPI *fxRP1210_GetLastErrorMsg) ( short, int* , char*, short );
typedef short (WINAPI *fxRP1210_GetHardwareStatus) ( short, char*, short, short );
typedef short (WINAPI *fxRP1210_ReadVersion ) ( char*, char*, char*, char* );
typedef short (WINAPI *fxRP1210_ReadDetailedVersion)( short, char*, char*, char* );
typedef short (WINAPI *fxRP1210_Ioctl) ( short, long , void*, void* );
/*GLOBAL VARIABLE*/ fxRP1210_ClientConnect pRP1210_ClientConnect = NULL;

/*GLOBAL VARIABLE*/ fxRP1210_ClientDisconnect pRP1210_ClientDisconnect = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_ReadMessage pRP1210_ReadMessage = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_SendMessage pRP1210_SendMessage = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_SendCommand pRP1210_SendCommand = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_ReadVersion pRP1210_ReadVersion = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_GetErrorMsg pRP1210_GetErrorMsg = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_GetLastErrorMsg pRP1210_GetLastErrorMsg = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_GetHardwareStatus pRP1210_GetHardwareStatus = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_ReadVersion pRP1210_ReadVersion = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_ReadDetailedVersion pRP1210_ReadDetailedVersion = NULL;
/*GLOBAL VARIABLE*/ fxRP1210_Ioctl pRP1210_Ioctl = NULL;
/*GLOBAL VARIABLE*/ HANDLE hRP1210DLL = NULL;
if ( ( hRP1210DLL = LoadLibrary( szDLLName ) ) == NULL )

{
exit(1);
}
©2011—TMC/ATA
Proposed RP 1210C(T) Ballot Version — 10
pRP1210_ClientConnect = (fxRP1210_ClientConnect)(
GetProcAddress(
hRP1210DLL,
"RP1210_ClientConnect"
)
);
if ( pRP1210_ClientConnect == NULL )
{
printf("Error: Could not find procedure \"%s\" in DLL!\n", "RP1210_ClientConnect" );
exit(1);
}
7.5 Step 4— Connecting to the DATABUS

The last step that an application must perform, after loading all of the functions, is to connect through the
VDA to the and allow messages to be read. Below is a snippet of code:
nClientID = pRP1210_ClientConnect( NULL_WINDOW, nUserDevice, szProtocol, 0, 0, 0 );
if ( ( nClientID >= 0 ) && ( nClientID <= 127 ) )

{
printf("Connect OK. DLL [%s] Device [%d] Protocol [%s] ID = %d\n",
szDLLName,nUserDevice, szProtocol, nClientID );
}
else
{
PrintRP1210Error( "RP1210_ClientConnect", nClientID );
exit(1);
}
7.6 Step 5—Allow Reception of Messages

After successfully connecting to the VDA, the next step is to enable reception of messages. When the call to
RP1210_ClientConnect is made, the API does not allow messages to come through. This gives applications
time to spin their read/write threads, etc. Below is a snippet of code that allows messages to pass:
nRetVal = pRP1210_SendCommand(RP1210_Set_All_Filters_States_to_Pass, nClientID, NULL, 0 );
if( nRetVal != 0 )
{
PrintRP1210Error( "RP1210_Set_All_Filters_States_to_Pass", nRetVal );
}
else
{
printf("RP1210_Set_All_Filters_States_to_Pass OK \n" );
}
7.7 Step 6—Read a Message

After successfully setting filters to allow messages, the application may now read messages. Below is a
snippet of code that reads a message:
nRetVal = pRP1210_ReadMessage( nClientID,(char*) &ucTxRxBuffer[0], sizeof(ucTxRxBuffer),

NON_BLOCKING_IO );
if( nRetVal < 0 )

{
PrintRP1210Error( "RP1210_ReadMessage", (short) -nRetVal );
}
else if( nRetVal == 0 )
{
// No message available
}
else
{
// Process the message
}
©2011—TMC/ATA
7.8 Step 7—Send a Message
After the RP1210_ClientConnect, the application may also send messages. Below is a snippet of code that
sends a J1708 message:
nRetVal = pRP1210_SendMessage( nClientID,(char *) &ucTxRxBuffer[0], nMessageSize, 0,

NON_BLOCKING_IO );
if( nRetVal != 0 )
{
PrintRP1210Error( "RP1210_SendMessage", nRetVal );
}
else
{
printf("Message sent successfully!\n");
}
7.9 Step 8—Closing the Interface and Freeing Resources

When the program is finished and ready to exit, the application must close the interface and free the DLL.
Below is a snippet of code that does that:
if ( pRP1210_ClientDisconnect( nClientID ) != 0 )
{
PrintRP1210Error( "RP1210_ClientDisconnect", (short) nRetVal );
}
if ( FreeLibrary( (HMODULE) hRP1210DLL ) == 0 )

{
printf( "FreeLibrary() call fails.\n”);
}
8. RP 1210 Variables and Initial States

The following is a table of variables that describe the RP1210 connection. To be considered RP1210B/C-
compliant, each VDA vendor will implement each variable with its initial state as defined (if that particular
protocol is supported). Different interpretations of the original RP1210 and RP1210A by VDA vendors have
caused problems for application developers.
Also, each application must call RP1210_ClientConnect before issuing any commands to the API via
RP1210_SendCommand.
Variable/Topic Initial State on Connect Description

Echo Mode Off See Echo Mode paragraph.
J1708Mode Converted Mode See J1708Mode paragraph.
ISO9141/KWP2000Mode Converted Mode See ISO9141/KWP2000 Mode paragraph.
FilterStates All Filters to Discard See FilterStates paragraph.
MessageReceive On See FilterStates paragraph.
BlockingMode Non-Blocking See BlockingMode paragraph.
BlockingTimeout Non-Blocking See BlockingTimeout paragraph.
J1939Packetize On API packetizes J1939 transport protocol
messages.
J1708FilterMode Inclusive See Inclusive/Exclusive Filtering paragraph.
CANFilterMode Inclusive See Inclusive/Exclusive Filtering paragraph.
ISO15765FilterMode Inclusive See Inclusive/Exclusive Filtering paragraph.
©2011—TMC/ATA
8.1 Echo Mode
RP1210A VDA vendors have implemented Echo Mode differently (which affects the “Echo Byte” on received
messages). Some vendors thought that “any” message sent should be treated as a “generic message ap-
pearing on the datalink” and therefore should be returned during a call to RP1210_ReadMessage. Other
vendors only returned a sent message when Echo Mode was turned on (ensuring the message had an
ECHO byte of ‘1’). Since the majority of vendors only return the sent message when Echo Mode=1, any RP
1210- compliant API will only return a message sent by RP1210_SendMessage to the application when Echo
Mode is on and will include the echo byte in the message set to ‘1’. If an application turns Echo Mode on, all
messages that are echoed back to the application will pass through all filters that have been set. Therefore,
if an application is interested in reading its own messages, it can turn Echo Mode to the on position.
8.2. J1708Mode and RP 1210B Enhancements

The default J1708Mode is in “Converted” Mode. In ConvertedMode multiple clients (connections) can be
established. New to RP 1210B was that an RP 1210B-compliant API will allow multiple client connections in
“Raw” mode. A survey taken of API vendors show that the “raw” mode restriction (of RP 1210/RP 1210A)
was not really in place. Therefore, multiple client connections can be connected to J1708 in both RawMode
or ConvertedMode simultaneously with no restriction.
8.3. ISO9141/KWP2000 Mode

The default ISO9141/KWP2000Mode is ConvertedMode. Behavior is exactly the same as with
J1708Mode.
8.4. FilterStates
Upon RP1210_ClientConnect, some API/VDA vendors have FilterStates to “PassAll.” Vendors should
initialize with FilterStates to “Discard” since some applications do not want to receive messages before
the entire application is fully ready to handle the message traffic. This means that no messages should be
available to the application until filter commands are issued or FilterStates are set to “PassAll.”
8.5. Blocking Mode

All blocking calls except to the RP1210_ReadMessage() function have been removed in RP 1210C.
8.6. Blocking Timeout

All blocking calls except to the RP1210_ReadMessage() function have been removed in RP 1210C. Block-
ing Timeout would still apply to that function..
9. RP 1210 REQUIRED FUNCTIONS

This section describes the required functions of the RP1210 API. Note that an implementation claiming
to conform to this API shall minimally support these functions without deviating in name (case-sensitivity
preserved), type, or argument list.
Implementations may exceed the minimal functionality listed here, as long as the functionality provided by
the given set of functions below is rigidly maintained. Even though an API may not support a particular
function, it still needs to have the function in the DLL (i.e. RP1210_Ioctl, even though it is used mainly for
automotive protocols such as ISO9141, and ISO15765). The DLL would return ERR_INVALID_COMMAND
if it does not support the call.
The required functionality is constituted by the following set of functions:

Function Name Brief Description
RP1210_ClientConnect Establishes a logical client connection with the API DLL.
RP1210_ClientDisconnect Disconnects the logical client application from the API DLL.
RP1210_SendCommand Sends a command to the API DLL for things like filtering, etc.
©2011—TMC/ATA
RP1210_SendMessage Sends a message to the API DLL.
RP1210_ReadMessage Reads a message from the API DLL.
RP1210_ReadVersion Reads version information from the API, about the API.
RP1210_ReadDetailedVersion Newer more comprehensive version information command. This command is now
preferred over the RP1210_ReadVersion call.
RP1210_GetErrorMsg Translates an RP1210 error code into a textual description of the error.
RP1210_GetLastErrorMsg Translates an RP1210 error code into a more detailed error code and textual de-
scription.
RP1210_GetHardwareStatus Returns information state of the connection and datalink.
RP1210_Ioctl Used to modify the state of vehicle communications. This was new to RP1210B,
and is only used by RP1210 at this time by ISO9141 and KWP2000 communica-
tions. This function allows for future development in RP1210 with regards to more
automotive type protocols.
10. VDA AND Application Developer NOTES
10.1 Unexpected Vehicle Interface Adapter Disconnect

There are differences in how an adapter disconnect is managed among VDA vendors. RP1210 indicates
that the API should return Error Code “142 ERR_HARDWARE_NOT_RESPONDING” to the calling applica-
tion whenever a hardware error occurs. However, the reaction of VDA API’s differ greatly when hardware
is accidentally disconnected.
In severe cases the client application may be required to do the following:

• Notify the user of the problem and ask the user to re-instate the hardware.
• Disconnect from the API by using RP1210_ClientDisconnect().
• Continue calling RP1210_ClientConnect() until successful.
• Set up all RP1210 variables and filters again.
• Reclaim J1939 addresses (if using J1939).
Vendor APIs that require no intervention retain all client identification and filter states and will verify owner-
ship of all previously J1939-claimed addresses upon correction of the disconnect. This type of API does not
require the recovery method described above. See also the RP1210 function RP1210_GetLastErrorMsg
and Section 10.2.
10.2. Error Code 142 and Backwards Compatibility

Between the release of RP1210A and RP1210B, VDA vendors made remarkable progress in adapter tech-
nology (USB, wireless, etc.) and some adapters are now powered by the PC (i.e., USB). Some adapters
can be powered by other means such as an internal battery, alternating current (AC), etc. These types of
“non-traditional” powered adapters caused some concerns within TMC’s RP1210 Update Task Force. The
question/issue that was dealt with is:
• On a non-vehicle-battery-powered device, how does an API handle the case where the “physical” con-
nection disappears (the link to the truck) but the “virtual” connection persists (VDA-to-PC application
link)? Does TMC create another error code in addition to “142 ERR_HARDWARE_NOT_RESPOND-
ING”, or does TMC work something else into the specification?
Some of the points raised during discussions on this question included:

• Many RP1210A applications are “keyed in” to getting a 142 Error Code back stating that something
outside of the PC has gone wrong. Adding another error code could possibly cause confusion for
RP1210A-compliant applications that are running on RP1210B (or later) VDAs.
• There needs to be a way to tell the user, in more detail, what is going on in an RP1210B/C-compliant
application running on top of an RP1210B/C-compliant VDA.
©2011—TMC/ATA
TMC resolved the issue as follows:
• Error Code 142 will remain the primary error code associated with hardware problems. This way,
RP1210A-compliant applications will continue to function as normal (no need for porting or re-
write).
• A new function call called “RP1210_GetLastErrorMsg” was added. This command will allow RP1210B/C
compliant applications to get extended error information from the RP1210B/C-compliant API’s about
the specific reason a 142 (or any other code) was returned.
The following paragraph deals with RP1210B/C applications:

• An application can determine whether it is physically connected to the databus by repeatedly calling
RP1210_GetHardwareStatus and checking the correct bits to determine if the link has been active
within the past one second (note the RP1210C changes to the RP1210_GetHardwareStatus func-
tion). If you are an RP1210B/C application working with an RP1210A adapter, the operation of this
is vendor specific because it was implemented differently among RP1210A VDA vendors.
• RP1210B/C applications should no longer depend solely on receiving the 142 Error Code and should
use the RP1210_GetHardwareStatus function.
Also refer to Section 18 on RP1210_GetLastErrorMsg.
10.3. Notes on CAN/J1939 and ISO15765 Coexistence

An application should be able to connect to CAN/J1939/ISO15765 at the same time, as long as the baud
rates are the same. Therefore, a VDA shall allow a client to connect to CAN, another connect to J1939 and
another to ISO15765.
RP1210B added support ISO15765-2 messages that appear either on a generic-CAN bus or on a J1939
datalink. Note that:
• Applications connected to a CAN/J1939 datalink need to know the link could contain ISO15765-2
traffic.
- The application should use the RP1210 filtering mechanism should it not wish to receive ISO15765
traffic on that client connection.
• Applications connected to an ISO15765 datalink need to know the link could contain CAN/J1939
traffic.
- The application should use the RP1210 filtering mechanism should it not wish to receive J1939
traffic on that client connection.
The RP1210 API will not be responsible for automatically filtering ISO15765 messages from a J1939 proto-
col connection, and vice versa. Also, the RP1210_SendCommand (Set_ISO15765_Link_Type) has been
removed. These are major changes from RP1210B as it was balloted and accepted.
The PGNs that ISO15765 uses are 52480, 52736, 55808, 56064 (KW1, KW2, KW3, KW4). For more infor-
mation on protocol coexistence information, see the ISO15765 or J1939 documentation.
10.3.1. RP1210B and ISO15765 Compatibility Issue

TMC’s RP 1210 Update Task Force created an unknown backwards compatibility issue with adding ISO15765
to RP1210B. It succeeded in making the buses “separate” from each other; however it created a problem
with an ECU that was sending J1939 PGNs (that ended up being adopted as the “ISO15765 PGNs”) and
an application that was trying to read them. In short:
• RP1210B said that VDA vendors should keep the J1939/ISO15765 databuses separate.
• VDA vendors kept the buses separate.
• ECU sends PGNs defined by ISO15765 on J1939 datalink.
• VDA API filters them out of J1939 traffic.
• Application does not see messages
©2011—TMC/ATA
10.4. Notes on Wireless VDAs and Time/Code-Sensitive Applications
Presently, it appears that wireless VDA devices abound (802.11, 802.15, Bluetooth). TMC does not recom-
mend using a VDA in any type of wireless mode for any “sensitive” application function like reprogramming
or downloading of a calibration.
An RP1210_SendCommand (RP1210_Get_Wireless_State) has been added so that if an application has

a non-recoverable action to perform, it can check whether they are in wireless mode and ask the user to
reconnect with a wired connection before performing that operation.
10.5. Notes on Windows 64-bit Machines and INI Files

Note that as of this revision, the Windows Vista and Windows 7 64-bit operating systems are becoming more
prevalent. Even though RP 1210C went to an INI file called “RP121032.INI” as a way of distinguishing an
old 16-bit machine/processor (RP1210.INI) from a more “current” 32-bit architecture, RP 1210C will not be
going from “RP121032.INI” to “RP121064.INI”.
Doing this would require an application to detect what type of operating system they were installed on,
and then open the correct INI file. Doing this would also keep legacy applications that open “RP121032.
INI” from opening legacy adapters that install their name to the “RP121032.INI” file. Keeping the current
GetSystemWindowsDirectory() + “\RP121032.INI” structure makes more sense.
10.6. The “Name” Parameter in the “VendorInformation” INI Section

The “Name” parameter in the “[VendorInformation]” section of the vendor INI file should somehow indicate
the adapter that the API represents/supports (what appears on the VDA label). This was not the intended
purpose of this parameter. The intended purpose was to provide quick information for an application to pres-
ent to the user if the user needed to call the VDA vendor (e.g., name, phone number, fax number, address,
etc). Some VDA vendors have already made this adjustment.
The reason the VDA vendor should include the adapter name comes from some RP1210 applications not
showing the Vendor Name along with either the DLL name, or the devices supported by that particular API
“on the same screen.” This has caused issues with VDA vendors with multiple adapters. For example, an
application only showing the “Name” (of the company) could present the user with the following list. For
example, McLovin Systems has three different adapters, each one having a separate API:
• McLovin Systems
• See Three Peo Communications
• McLovin Systems
• Wayne and Garth Technologies
• McLovin Systems
Although “programming practice” is not the nature of this document, it is suggested that at a minimum, an
application should show:
• The DLL name and the Name parameter from the [VendorInformation] section in some sort of combo
box:
MCLOVIN - McLovin Systems Lightsaber Adapter
• Device numbers with the DeviceName from the DeviceInformationXXX section and COM port in a
combo box:
101 – McLovin Lightsaber – USB
Doing this will keep down technical support calls to both application developers and VDA vendors because
end-users will not be wondering which of the three McLovin Systems adapters to choose.
©2011—TMC/ATA
Below is an example screen snapshot that leaves no doubt in the user’s mind as to which API to select for
the device the end user just plugged into their USB port (the McLovin Lightsaber USB adapter).
10.7. Notes on CAN and CAN-Based Protocols (e.g., SAE J2284)

All CAN ID’s are assumed to be in Big Endian (MSB) format unless otherwise specified. All filtering of J2284
is done using the same commands as for the generic CAN datalink.
10.8. Notes on J1939 Address Claim (Single Application)

In 2010, many questions were raised about address claim, including how to “release” an address (of which
no process exists within the J1939 specification) and how the API/VDA handles multiple addresses (more
importantly – multiple RTS/CTS Transport Protocol sessions for multiple addresses). These questions led to
an incorrect solution statement (although never making into a balloted version) by asking that the API/VDA
drop any previously held address when the Protect_J1939_Address command was issued. This incorrect
solution implied that a VDA would only “handshake” for one set of TP messages destined for a single ad-
dress that had been claimed by the VDA. This could have caused major application issues if a client wanted
to use multiple J1939 addresses. For example, someone may want to write an engine/transmission/ABS
simulator program (Addresses 0, 3, 11) that supports RTS/CTS on each address.
As mentioned in Required High-Level Functionality (Single Application), a VDA shall support the protec-
tion/claiming of 16 different addresses (from one or more clients) and the handling of RTS/CTS messages
for those addresses.
The following text describes the correct handling of address claiming situations:
1. On startup, a VDA will not handshake for an RTS/CTS session, nor receive a BAM message for any
address that has not been claimed/protected by a client (per J1939/81). Attempting to send any TP
message (RTS/CTS or BAM) without claiming will result in the error ERR_ADDRESS_NEVER_CLAIMED
being returned on the call to RP1210_SendMessage. This was always implied in all versions of TMC
RP 1210.
2. Separate clients can protect the same address (most use 249 or 250 anyway), resulting in those
clients receiving all TP messages destined for that address (or the global address 255). It is up to
the application to process or ignore these messages and determine if it was the correct recipient.
a. If the NAME for any subsequent claims of the same address has a higher priority, then the API/VDA
will use that NAME and go through the claim process again. This will not cause any “bumping”
of PC client addresses (ERR_ADDRESS_LOST) because “IT IS” a shared address situation.
b. On success, the API/VDA will handshake for TP messages destined to that address or the global
address.
c. The VDA will respond to the address request message with the address and NAME of the highest
priority NAME for each address it has protected.
3. An API/VDA will maintain a list of 16 J1939 addresses/NAMEs that the API/VDA will handshake TP
messages for “simultaneously” (one for RTS/CTS and one for BAM). Any claim attempts over 16
would result in ERR_ADDRESS_CLAIM_FAILED.
4. An application/client can release a J1939 address by using the RP1210_SendCommand (RP1210_Re-
lease_J1939_Address).
a. If this is the last instance/usage of that address by a client, then the VDA stops handshaking
or transmitting of any messages for that address (this was also assumed in all prior versions of
RP1210). The node appears to have “just gone away.”
©2011—TMC/ATA
b. If it is not the last instance, then the VDA sends the address claim messages using the next high-
est priority NAME.
c. When a client disconnects, the “reference count” for all addresses claimed will be decremented.
If this was the last instance, see Item 4a above.
Since this is a relatively new concept, applications that are going to perform a critical function such as
reflashing should prevent other clients and/or applications from connecting to the databus through the call
to RP1210_SendCommand (RP1210_Disallow_Further_Connections). They should also alert the user to
disconnect any other applications that may be already running.
A new variable [VendorInformation]->J1939Addresses has been created in the vendor INI file. This will
allow applications to know if the VDA API supports only one (INI variable not found), or 16.
10.8.1. Possible Transport Protocol Layer Conflict and Resolution

• Application A makes a J1939 connection and claims address 0xF9
• Application B makes a J1939 connection and claims address 0xF9
• Application A starts sending a long transport protocol message to address 0x00 (Engine)
• Application B starts sending a long transport protocol message to address 0x00 (Engine) but Applica-
tion A’s message is still in progress.
The RP1210 API must now know to block sending of Application B’s transport message until Application A’s
message has finished. This conflict can easily occur, especially when the RP1210 API is being used in a
Multi-application environment.
10.9. Notes on J1939 at 500k (J1939-14) and Auto Speed Detection

At the time of this writing, SAE has approved the definition of the J1939 protocol running at 500k, and it is
in the J1939-14 document. The idea was that this new protocol speed would be completely invisible to the
application and the end-user. To make this transition easier, VDAs will be doing automatic speed detection
between 250k/500k (and other common CAN speeds 125, 1Mb). Also, service tools (RP1210/SAE J2534,
hand-held devices, etc) will be using special cables with Deutsch 9-pin connectors in the color green to
denote this the cable is meant for a J1939 Type 2 connector (see J1939-13, or RP 1202) and can handle
the 500k baud rate. Just a note that the Type 2 connector will also fit into the Type 1 Deutsch 9-pin socket
to which we are accustomed, however a Type 1 (assumed to be 250k) will not fit onto a Type 2.
NOTE: Wording from J1939-13 (diagnostic connector) states specifically that “… an adapter that supports
automatic speed detection will do so without causing error frames on the vehicle network due to baud rate
mismatch.” This statement was added because of the adverse affect that could be caused by CAN error
frames on the network, especially if the user connected while the vehicle was in motion.
To denote that an adapter can do automatic speed sensing for a protocol (we will not limit automatic speed
detection to just one protocol), the VDA vendor will place the string “Auto" in the ProtocolSpeed parameter
in the ProtocolInformation section of all protocols that the vendor can detect automatically. If the applica-
tion wants to know what speed they did connect at, they can issue an RP1210_SendCommand() using the
RP1210_Get_Protocol_Connection_Speed mnemonic. Automatic speed detection for CAN based protocols
is mandatory for RP1210-compliance. Implementation for non-CAN protocols is optional.
If autobaud initially fails (i.e., ignition key off), the VDA should continue to do autobaud detection unless told
by the API to stop and disconnect. The RP1210_ClientConnect() call will return success even if the VDA fails
to autobaud. Calls to SendMessage() and ReadMessage() will return an error. A call to RP1210_Get_Pro-
tocol_Connection_Speed would return a string of “0” to indicate that the baud has not been set. When the
VDA does detect a baud rate, calls to SendMessage, ReadMessage, and RP1210_Get_Protocol_Con-
nection_Speed would go to normal. This will allow an application to put up a box showing that the datalink
is not active until a baud rate is determined.
©2011—TMC/ATA
Below is an INI file section showing that both 250k, 500k, and 1Mb speeds are supported for both CAN and
J1939, and that the adapter is capable of doing automatic speed detection. Also shown is the example for
CAN which supports 125, 250, 500 and 1MB.
[ProtocolInformationXXX]
ProtocolDescription=SAE J1939 Protocol
ProtocolString=J1939
ProtocolSpeed=250,500,1000,Auto
ProtocolParams=
Devices=[x,y,z...]
[ProtocolInformationXXX]
ProtocolDescription=CAN Network Protocol
ProtocolString=CAN
ProtocolSpeed=125,250,500,1000,Auto
ProtocolParams=
Devices=[x,y,z...]
If an application knows that there is a possibility that it might be used on a vehicle with a 500k J1939 con-
nection, that application should warn the user that connecting the VDA to a 500k databus may cause ad-
verse affects if the keyword “Auto” is not in the CAN or J1939 ProtocolSpeed parameter. The application
would then prompt the user for the speed to connect at based on the speeds supported by that VDA (250k
is default).
NOTE: Applications should never issue a RP1210_ClientConnect( "Protocol:Baud=XXX" ) to a CAN/J1939

databus unless XXX is the known baud rate. Developers must be diligent in application coding when it is
known that there is a possibility that an application could flood the databus with CAN error frames.
A new variable [VendorInformation]->CANAutoBaud=[TRUE/FALSE] has been created in the vendor INI

file. This will allow applications to know if the VDA API supports auto baud detect.
10.10. Applications Doing Auto-VDA-Detection (Not Recommended)

Some application vendors have attempted, and failed, in algorithms to automatically detect the adapter that
is physically attached to the computer (resulting in VDA vendor technical support calls). Some API’s are
just not capable of validating a specific device is connected to the PC and some require that the VDA be
powered up and connected to the vehicle prior to performing an RP1210_ClientConnect.
• A new variable will be present in a vendor INI file that will tell the application developer whether or not
that the associated API devices in that INI file are capable of being “auto-detected”. See the “Auto-
DetectCapable” variable in the INI file section of this document. This was an RP1210B addition.
• If you are writing an application and this variable is not present in an INI file, then it is highly recom-
mended not trying to go through the auto-detect process with devices from that INI file.
• Auto-detection is strongly discouraged and it should only happen at the explicit action of a user. Query
messages sent by autodetect functions scanning all interfaces can upset unrelated devices connected
to the computer.
10.11. Blocking/Non-Blocking Considerations for App Developers

In 2010, much discussion took place at TMC about blocking and non-blocking in regards to reading and
sending messages. The issues stemmed from having multiple client connections. If Client A loaded up
the VDA send queue with 1000 “long” J1587 messages using non-blocking, and then Client B did a block-
ing J1587 send, Client B may have to wait five or six seconds for all of those queued messages to clear,
and then the message would be sent. One can easily see that this could cause application message time-
outs and other unnatural consequences. Therefore, BLOCKING_IO is no longer supported except in the
RP1210_ReadMessage() function.
©2011—TMC/ATA
10.12. Queue Full Characteristics for VDA Developers
In 2010, much discussion took place at TMC about what happens when a transmit or receive queue becomes
full (the error codes ERR_TX_QUEUE_FULL and ERR_RX_QUEUE_FULL).
10.12.1. Err_Tx_Queue_Full
If a transmit queue is full, a call to RP1210_SendMessage() will return this mnemonic and the message will
not be queued. No messages in the queue are destroyed
10.12.2. Err_Rx_Queue_Full
If the receive queue becomes full, and this mnemonic is returned from an RP1210_ReadMessage, the
complete receive buffer queue is destroyed in favor of “catching back up in time” for the application. Trans-
port Protocol sessions that are ongoing will not be stopped. Application authors should strongly consider
increasing the number of retries because of this possible condition. TMC strongly suggests setting filters to
only receive the messages you want to see. If an application is servicing the VDA fast enough this is not
usually seen.
10.13. Filter State Ambiguities

Differences exist among vehicle interface adapter manufacturers in their handling of filters:
• Setting “All Filter States to Pass” is a temporary condition canceled when issuing specific filter
requests.
• If you set specific filters, issuing a “Set All Filter States To Pass” cancels all specific filters and allows
all messages to pass.
• Each client has its own filter list independent of any other applications or clients.
10.14. Filter Clarifications – More Than 1 Per SendCommand() Call

Users can send in more than one filter per RP1210_SendCommand call. This allows a programmer to
send in an array of filters. Some vendors had previously only acknowledged the first one. The API DLL is
responsible for maintaining a table of at least 64 filters per client/protocol.
Additional calls to RP1210_SendCommand to set a filter will add to the list. This way, the application does
not have to send an updated “entire list” of filter parameters. The filter list is cleared only on VDA reset, or
by setting all filter states to discard.
A change from RP1210B: Some VDAs handle the J1939 transport protocol “on the physical device” when
the nIsAppPacketizing flag is FALSE (this is much faster than having the individual packets come back to
the DLL for it to maintain the transport session). It is no longer required that a VDA handle a J1939 request
with the nIsAppPacketizing flag set to FALSE and then allow the application to set filters to allow “both” the
complete messages and individual packets to be read. Doing this is more for engineering-oriented applica-
tions, not service-bay diagnostic applications.
10.14.1. J1708/J1587 Parameter ID (PID) Filtering

PID filtering in the API was discussed in the update committee, however it was deemed too difficult because
of variable length messages, packed PID messages, etc. Any PID filtering will be done in the software ap-
plication.
10.14.2. Inclusive and Exclusive Filtering

Currently, RP1210A filtering is set to “inclusive.” This type of filtering forces the application to “ask” the API
for each MID, PGN, or CANID that it wants to see. With “FilterStates=AllFilterStatesToPass”, it forces
the application to handle all filtering.
In RP1210B, a new filter mechanism called “exclusive” was added. This allows the application to say, “I
want to see all messages, except from the engine, except this PGN, etc.” See RP1210_SendCommand
for more details.
©2011—TMC/ATA
10.15. “Least Common Denominator” Development
If the deployment of a software application requires potential compatibility with more than one VDA, then the
application must be designed based upon the lowest common denominator of adapter performance. Even
though serial ports have all but disappeared from laptop PCs, application developers should still use a serial
port adapter as their secondary test bed because there are still thousands of VDAs in the marketplace using
the serial port. USB adapters have been popular for six to seven years; however, USB is more forgiving and
the developer is much less likely to see message timeouts, dropped messages or other common serial port
anomalies that are seen in the field. If an application can be written to work for a serial port adapter, there
should be little doubt that the application will have problems on the more modern USB adapters. It should
be noted that when connected to a wireless VDA, timeouts should be extended and more retries attempted
due to network latency, packet loss, and interference.
10.16. INI File Versus Registry and XML

During the past several years, with the operating systems specified in this document, the use of the Windows
registry has become the de-facto standard way of storing variables, as opposed to the old way of using INI
files. With Windows Vista, Microsoft started recommending XML files to replace both INI and registry files.
TMC’s RP 1210 Update Task Force recognized and discussed these methods; however, with many variables
in-place at the moment (knowledge of the end-user, various vendors, OEM, INI file legacy, etc), it was decided
to stick with INI files. Also, see the section on “Windows Vista/Windows 7 and RP 1210-Compliancy.”
10.17. nIsAppPacketizingIncomingMsgs and J1939 Transport Protocol

Each VDA should packetize/de-packetize (both in and out, BAM and RTS_CTS) and not send the individual TP
packets back to the application if the nIsAppPacketizing is set to FALSE on RP1210_ClientConnect(). If the
nIsAppPacketizing is set to TRUE (1) on ClientConnect, the VDA should not packetize/de-packetize at all
(in or out, BAM or RTS_CTS). A VDA does not ever have to pass both packets and complete messages.
10.18. RP 1210 Compliancy Testing “Application”

It was recommended to TMC that there should be an application developed for “proving” an API is RP 1210-
compliant for the operating systems and protocols that it supports. No such application exists at this time.
Should someone wish to offer this service at no charge, please contact TMC.
10.19. Windows Vista/Windows 7 and RP 1210-Compliancy

Microsoft’s deployment of Windows Vista™ and Windows 7™ has raised concern within TMC’s RP 1210
Update Task Force. With Vista/7, Microsoft has basically “virtualized” the “C:\WINDOWS” and “C:\Program
Files” directories, calling these “compatibility files.” Microsoft Vista/7 makes the PC more friendly and se-
cure for multiple users on the same PC. For example, the UNIX/VMS equivalent would be allowing users to
install their own programs in $HOME/bin, $HOME/lib, etc. Much of the task force’s discussion on this has
centered on either going to the registry, or to XML files. It was determined that neither would be required if
the following two things were done:
10.19.1. Compliancy for VDA Vendors and Windows Vista/7

To be considered RP1210B/C-compliant on Vista/7:
• VDA vendors will require that the person who installs the drivers on a Windows Vista machine be
logged in specifically as "Administrator". This means that the install program is manifested to “re-
quireAdministrator”.
• VDA vendors will install their drivers for “ALL USERS”, not just the current user.
10.19.2. Compliancy for Application Developers and Windows Vista/7

To be considered RP1210B/C-compliant:
• Application developers will also require that the person who installs their applications on a Windows
Vista machine are logged in specifically as "Administrator". This also means that the application install
program is manifested to “requireAdministrator”.
• Application developers will require applications be installed for “ALL USERS”, not just the current
user.
©2011—TMC/ATA
If all VDA and all application developers cooperate, the industry will reduce the frequency of unnecessary
technical support calls, as there could be five or six (even more) copies of the same driver, RP121032.INI, or
application on a single PC. What is worse is that they could be at different versions. A simple example:
• Technician1 installs VDA Vendor1 drivers at version 1.0, and Technician2 installs VDA Vendor1 drivers
at version 2.0 (a release that included “major” bug fixes from version 1.0).
• Technician1 encounters a problem with Application1 (and “buggy” VDA drivers at version 1.0). He
asks Technician2 to try the application and it works perfectly (wasting time for the technician and
costing the fleet money).
• Technician1 calls the technical support line for Application1, and the people responsible for Applica-
tion1 spend hours trying to track down the problem. This costs both the fleet money, as well as the
developers of Application1, not to mention VDA Vendor1 if the problem gets escalated to them!
11. Compliance for API/VDA Vendors

This section outlines the required features of RP1210B/C for a vendor to signify RP1210B/C-compliance.
11.1. Standard Functions

Standard Commands (All commands marked “X” must be implemented):
J1708/PLC
ISO15765
KWP2000
ISO9141
J1850
J1939
CAN
Function Name
RP1210_ClientConnect X X X X X X X
Multiple CAN-Based Protocol Channels
(channel not specified, defaults to 1) X X X X
Multiple CAN-Based Protocol Channels
(Channel=X) NO NO NO NO
J1708 Baud (9600 – Format 2) X
J1708 Baud (19200) NO
J1708 Baud (38400) NO
J1708 Baud (57600) NO
J1708 Automatic Speed Detection NO
Multiple CAN Bauds (Format 1) NO
Multiple CAN Bauds (250k - Format 4) X
CAN Automatic Speed Detection X
Multiple J1939 Bauds (Format 1) NO
Multiple J1939 Bauds (250k - Format 2) X
J1939 Automatic Speed Detection X
Multiple ISO15765 Bauds (Format 1) NO
Multiple ISO15765 Bauds (Format 2) X
ISO15765 Automatic Speed Detection X
J1850 Baud Rate (10.4k) X
J1850 Baud Rate (41.6k) NO
J1850 Automatic Speed Detection NO
©2011—TMC/ATA
RP1210_ClientDisconnect X X X X X X X
RP1210_SendMessage X X X X X X X
RP1210_ReadMessage X X X X X X X
RP1210_ReadVersion X X X X X X X
RP1210_ReadDetailedVersion X X X X X X X
RP1210_GetErrorMsg X X X X X X X
RP1210_GetLastErrorMsg X X X X X X X
RP1210_GetHardwareStatus X X X X X X X
RP1210_Ioctl X X X X X X X
INI File Debug Support NO NO NO NO NO NO NO
11.2. RP1210_SendCommand Functions

The following lists which RP1210_SendCommand functions must be implemented (mandatory) to signify
RP1210B/C-compliance:
J1708/PLC
ISO15765
KWP2000
ISO9141
J1850
J1939
CAN
RP1210_SendCommand Parameter
RP1210_Reset_Device X X X X X X X
RP1210_Set_All_Filters_States_to_Pass X X X X X X X
RP1210_Set_Message_Filtering_For_J1939 X
RP1210_Set_Message_Filtering_For_CAN X
RP1210_Set_Message_Filtering_For_ISO15765 X
RP1210_Generic_Driver_Command NO NO NO NO NO NO NO
RP1210_Set_J1708_Mode X
RP1210_Set_ISO9141KWP2000_Mode X X
RP1210_Echo_Transmitted_Messages X X X X X X X
RP1210_Set_All_Filters_States_to_Discard X X X X X X X
RP1210_Set_Message_Receive X X X X X X X
RP1210_Protect_J1939_Address X
RP1210_Set_Broadcast_For_J1708 X
RP1210_Set_Broadcast_For_CAN X
RP1210_Set_Broadcast_For_ISO15765 X
RP1210_Set_Broadcast_For_KWP2000 X
RP1210_Set_BlockTimeout NO NO NO NO NO NO NO
RP1210_Set_J1708_Baud NO
RP1210_Set_J1708_Filter_Type X
RP1210_Set_J1939_Filter_Type X
RP1210_Set_CAN_Filter_Type X
©2011—TMC/ATA
RP1210_Set_ISO15765_Filter_Type X
RP1210_Set_J1939_Interpacket_Time NO
RP1210_Set_ISO15765_Flow_Control X
RP1210_Clear_ISO15765_Flow_Control X
RP1210_Set_J1939_Baud NO
RP1210_Set_CAN_Baud NO
RP1210_Set_ISO15765_Baud NO
RP1210_Flush_Tx_Rx_Buffers X X X X X X X
RP1210_Get_Protocol_Connection_Speed X X X X X X X
RP1210_Get_Wireless_State X X X X X X X
12. RP1210_ClientConnect
This function is the first function called by an application seeking a connection with a vehicle network. Inside
the API’s DLL, a call to this function allocates and initializes any client data structures, loads, initializes, or
activates any device drivers (virtual or otherwise) to communicate with the hardware and sets all RP1210
client application variables to their defaults (Echo Mode, FilterStates, etc). If the connection is successful,
the function shall return a unique identifier, corresponding to the ID of the client application, as assigned by
the API DLL.
If a VDA is capable of automatically detecting the baud rate of the protocol being connected to, the VDA
will determine the correct speed and connect the application at that speed if the string “:Baud=Auto” is ap-
pended to the protocol name string. See the section entitled Notes on J1939 at 500k (J1939-14) and Auto
Speed Detection.
12.1. RP1210_ClientConnect Prototype

Language Prototype
C/C++ short __declspec (dll export) WINAPI RP1210_ClientConnect
(
HWND hwndClient,
short nDeviceID,
const char *fpchProtocol,
long lTxBufferSize,
long lRcvBufferSize,
short nIsAppPacketizingIncomingMsgs
);
Visual Basic Declare Function RP1210_ClientConnect Lib “VENDRX32.DLL”...
(
ByVal hwndClient As Long,
ByVal nDeviceID As Integer,
ByVal fpchProtocol As String,
ByVal lTxBufferSize As Long,
ByVal lRcvBufferSize As Long,
ByVal nIsAppPacketizingIncomingMsgs As Integer
) As Integer
12.2. RP1210_ClientConnect Parameters

Parameter Description
This parameter is no longer necessary and is unused (Windows 3.1). The
hwndClient
value should be set to NULL (0x00).
nDeviceID The device to which the client application is requesting connection.
Pointer to a null-terminated string of the protocol name to be used by the
fpchProtocol device designated in the previous parameter. (See Protocol Connect String
section for protocol strings and variations below.)
©2011—TMC/ATA
A long integer for the requested size (in bytes) of the client transmit buffer
to be allocated by the API for the queuing of messages sought to be trans-
lTxBufferSize mitted by the client application. Should be passed as 0 if the application
does not want to dictate the buffer size and the API DLL default of 8K is
acceptable.
A long integer for the requested size (in bytes) of the client receive buffer to
be allocated by the API for the queuing of messages meant to be received by
lRcvBufferSize
the client application. Should be passed as 0 if the application does not want
to dictate the buffer size and the API DLL default of 8K is acceptable.
A flag relevant only for J1939. Should be set to zero if the application wants
the lower-level components to perform the tasks of fragmenting the mes-
sage into packets and return complete messages assembled from packets
received. Should be set to 1 in the rare case where the application itself
will perform the packetizing of message fragments.
nIsAppPacketizingIncomingMsgs
See the section on nIsAppPacketizingIncomingMsgs and the J1939
Transport Protocol for more details.
12.3. RP1210_Clientconnect Return Value

If the connection is successful, then the function returns a value between 0 and 127, corresponding to the
client identifier that the application program is assigned by the API DLL. The application program must
save this return value in order to conduct future transactions with the DLL. If the connection is unsuccess-
ful, then an error code is returned that corresponds to a number greater than 127. The typical error codes
are described below. An API may return a more descriptive or proprietary code as long as the numerical
equivalent is greater than 192, and is clearly documented by the vendor.
Mnemonic Description
ERR_CLIENT_ALREADY_CONNECTED A client is already connected to the specified device.
ERR_CLIENT_AREA_FULL The maximum number of connections has been reached.
ERR_CONNECT_NOT_ALLOWED Only one connection is allowed in the requested Mode.
ERR_INVALID_COMMAND A command parameter is not supported.
The specified device is already in use and does not have the ability
ERR_DEVICE_IN_USE
to maintain connections with multiple clients simultaneously.
ERR_DLL_NOT_INITIALIZED The API DLL was not initialized.
ERR_HARDWARE_NOT_RESPONDING The device is not responding.
ERR_INVALID_DEVICE The specified device ID is invalid.
The specified protocol is invalid or unsupported or the extended
ERR_INVALID_PROTOCOL
connect string (fpchProtocol) was incorrect or unsupported.
The API DLL could not allocate enough memory to create the
ERR_NOT_ENOUGH_MEMORY
client.
ERR_J1708_BAUD_SET_NONSTANDARD See Section 12.4. RP1210_ClientConnect Notes
ERR_J1939_BAUD_SET_NONSTANDARD See Section 12.4. RP1210_ClientConnect Notes
ERR_CAN_BAUD_SET_NONSTANDARD See Section 12.4. RP1210_ClientConnect Notes
ERR_ISO15765_BAUD_SET_NONSTANDARD See Section 12.4. RP1210_ClientConnect Notes
ERR_MULTIPLE_CONNECTIONS_NOT_ALLOWED_NOW See Section 12.4. RP1210_ClientConnect Notes
©2011—TMC/ATA
12.4. RP1210_ClientConnect Notes
For an application program to call any other functions within the API DLL, the application must first receive
and recognize a successful return value (a ClientID) from this function.
If multiple J1939 applications are connected through the same device and any of them changes the nIsApp-
PacketizingIncomingMsgs flag, then the client attempting to change this flag shall receive the ERROR_
CONNECTION_NOT_ALLOWED return code. In other words, as long as there exist one or more J1939
connections to a given device that have set the nIsAppPacketizingIncomingMsgs flag, all applications
issuing this command must also set this flag in a similar fashion, or they will receive the ERROR_CONNEC-
TION_NOT_ALLOWED. Even though we are trying to “virtualize” the VDA, the VDA hardware/firmware is
usually the limiting factor, and having the VDA packetize or not to packetize is typically something that cannot
be virtualized. The J1939 transport protocol has long been a rough place for VDAs, but it is still recommended
that the application set this flag to 0 and let the VDA handle the TP layer.
When an application establishes a connection, no filters are set and the drivers do not allow any messages
to pass. Only after filters have been set, or all filter states have been set to pass by the RP1210_SendCom-
mand function can the application start receiving messages.
Applications using ISO15765 that wish to communicate long (segmented) messages must additionally es-
tablish a flow control association between the incoming (device) CAN ID and the outgoing (tester) CAN ID
with the RP1210_Set_ISO15765_Flow_Control command, before such messages can be sent to or received
from that device. Single Frame (short) messages – such as broadcast messages - can be sent to or received
from a device without recourse to the RP1210_Set_ISO15765_Flow_Control command.
12.4.1. Multiple CAN Protocols on One CAN Channel; Multiple Baud Rates (J1939/J1708)
Most VDA manufacturers only have one CAN chip in their hardware. This chip can only be initialized at one
particular speed. RP1210C allows the flexibility of connecting at multiple CAN baud rates. This can create
a problem where a user wants to crank up multiple CAN-based protocols with different speeds. Therefore,
if an application has the baud rate on the CAN chip set at anything other than 250k (J1939, and RP1210A
default), the following newly introduced error will be returned on future tries to connect to the CAN bus.
• ERR_CAN_BAUD_SET_NONSTANDARD (454)
It is recommended that when the application needs to do something like this, that it prevents other applica-
tions from connecting to the databus through the following call:
RP1210_SendCommand (RP1210_Disallow_Further_Connections)
Note that any further attempts to connect would then come back with the new RP1210C error code:
• ERR_MULTIPLE_CONNECTIONS_NOT_ALLOWED_NOW (455)
This also affects all other protocol connections that allow a non-standard baud rate.
12.5. RP1210_Clientconnect Protocol Connection String

TMC has added several new protocols and features to extend the functionality of RP1210_ClientConnect.
fpchProtocol/ProtocolString Protocol Description/ProtocolDescription
CAN CAN Network Protocol
J2284 SAE J2284 Network Protocol (CAN @500k Baud)
J1939 SAE J1939 Protocol
ISO15765 ISO15765 Vehicle Protocol
©2011—TMC/ATA
PLC Power Line Carrier (PLC4TRUCKS) Protocol
J1850_104k SAE J1850 Vehicle Protocol (Baud Rate of 10.4k)
ISO9141 Generic ISO9141
KWP2000 Keyword Protocol 2000 over ISO9141
In the vendor INI file, the ProtocolString parameter should match EXACTLY what is listed above in the
fpchProtocol parameter and the ProtocolDescription parameter should match EXACTLY what is in the
Protocol Description field. These issues have been a bone of contention amongst users for quite some time
when it comes to selecting the correct protocol.
Generic protocol example:
[ProtocolInformation1]
ProtocolSpeed=9600,57600
ProtocolParams=xxx,xxx
Devices=zzz,zzz
ProtocolString=CAN
ProtocolSpeed=125,250,500,1000,Auto
ProtocolParams=xxx,xxx
Devices=zzz,zzz
12.5.1. Example
Here is an example where the user selects the correct
vendor (MCLOVIN – McLovin Systems Lightsaber
Adapter) and then selects the “generic” protocol “CAN”.
The device list is then populated with the devices that
support the generic protocol “CAN”. Note that in the
device description field it shows at what speeds that
device supports. For example, the McLovin Light-
saber supports CAN at 125k, 250k (default), 500k,
and 1MB.
12.5.2. Device-Centric Versus Protocol-Centric

The example in Section 12.5.1 shows what is called
a “Device-Centric” INI file (meaning that the DEVICE
is where you choose “options” for a protocol). This is the preferred way for a VDA vendor to structure their
INI file because it leads to the “least” confusion for end-users. In the past, VDA vendors have “invented” RP
1210 protocols such as “CAN500 Using McLovin USB Adapter”, etc. VDA end-users are having a difficult
time enough choosing the generic protocols (J1708, J1939), and adding “invented” protocol names makes
it even more difficult.
12.5.3. RP 1210B/C-Compliance: INI File Shall be Device-Centric with No Invented Protocols

To be RP 1210B/C-compliant, a vendor INI file shall not have any “invented/home-grown” protocols such as
“J1939 Using XXX-Link Adapter”, and the API INI file will be written “device-centric” to keep down end-user
confusion.
©2011—TMC/ATA
Any protocol variant of J1708, CAN, J1939, or ISO15765 like “J170857600”, “CAN125”, “J1939500”, or
“J1939@500k Using XXX-Link Adapter” would be considered to have been “invented and/or home-grown”
and therefore not allowed.
The only exceptions are protocols that are under discussion by TMC’s RP 1210 Task Force (e.g., GM_UART).
All protocols should be approved by TMC’s RP 1210 Task Force so that all VDA vendors can be on the same
page as new protocols emerge.
12.6. Using TCP/IP and DNS as a Transport Layer for a Protocol

Several new devices have been made available since RP1210A was written. One uses TCP/IP as a transport
for the protocols defined in the table above. Therefore, if a user wants to use a TCP/IP address or a DNS
name as a transport for the protocol, the user can add the following string to the fpchProtocol parameter.
• “Transport=TCPIPaddress=xxx.xxx.xxx.xxx,TCPIPport=xx”
• “Transport=MACaddress=xx-xx-xx-xx-xx-xx,TCPIPport=xx”
• “Transport=DNSName=xxxxxxxx”
This can be used, even in addition to the following sections dealing with specialty features of the fpchPro-
tocol parameter.
Example (the VDA is at address 192.198.22.33:90):
• “J1708:Transport=TCPIPaddress=192.198.22.33,TCPIPport=90”
12.7. Using a Modem as a Transport Layer for a Protocol

Another transport mechanism has been provided for the RP1210 protocols, a modem. Therefore, if a user
wants to use a modem as a transport for the protocol, the user can append the following string to the fpch-
Protocol parameter.
• “Transport=ModemTelno=sssss”
This can be used, even in addition to the following sections dealing with specialty features of the fpchPro-
tocol parameter.
Example:
• “J1708:Transport=ModemTelno=1-859-923-4100”
12.8. SETTING CAN BAUD RATE on RP1210_ClientConnect

The default CAN baud rate on RP1210_ClientConnect is 250k, however some applications may require
different baud rates. The following paragraphs deal with connecting at a different baud rate. For specifics
on the setting of CAN baud rates, refer to J1939-11 section 3.14 “CAN Bit Timing Requirements.”
There is an INI variable “CANFormatsSupported” that shows which formats that an API supports.
To correctly set the baud rate on CAN the user uses the crystal frequency of the hardware to set the follow-
ing parameters:
• PROP_SEG is programmable (1-8)
• PHASE_SEG1 is programmable (1-8)
• PHASE_SEG2 is programmable and must be < PHASE_SEG1
• Resynchronization jump width is either 1 or 3
• Identifier size 11 or 29 or “B” (equals both 11 and 29)
©2011—TMC/ATA
12.8.1. Setting CAN Baud Rate – Format 1
Driver uses the sample location to calculate PROP_SEG, PHASE_SEG1, and PHASE_SEG2.
• fpchProtocol = “CAN:Baud=X,SampleLocation=Y,SJW=Z,IDSize=S”
- Baud (X) may be between 1 and 1M (1-1000000).
- SampleLocation (Y) is between 50 and 95 (percent %)
- SJW (Z) may be 1 or 3
- IDSize (S) may be 11 or 29 or “B” (equals both 11 and 29)

Formula derived directly from the BOSCH CAN specification.
• fpchProtocol=“CAN:Baud=X,PROP_SEG=A,PHASE_SEG1=B,PHASE
SEG2=C,SJW=Z,IDSize=S”
- PROP_SEG (A) is between 1 and 8
- PHASE_SEG1(B) is between 1 and 8
- PHASE_SEG2(C) is must be less than PHASE_SEG1
- SJW(Z) may be 1 or 3
- IDSize(S) may be 11 or 29 or “B” (equals both 11 and 29)

Formula for baud derived from Intel implementations.
• fpchProtocol=“CAN:Baud=X,TSEG1=D,TSEG2=E,SampleTimes=Y,SJW=Z,IDSize=S”
- TSEG1 (D) is between 2 and 15
- TSEG2 (E) is between 1 and 7 and must be less than TSEG1
- SampleTimes (Y) is 1 or 3
- IDSize may be 11 or 29 or “B” (equals both 11 and 29)
12.8.4. Setting CAN Baud Rate – Format 4 – Default

Default Format (CAN baud rate defaults to 250k)
• fpchProtocol=“CAN”

General Format for selecting CAN and letting drivers choose register settings
• fpchProtocol=“CAN:Baud=X”
- Baud (X) may be specified as a KBaud value: “125”, “250”, “500”, “1000”
- Or, Baud (X) may be specified as a Baud rate between 1001 and 1M (1001-1000000).
- Or, Baud (X) may be specified as “Auto”.
12.9. Setting CAN/J1939/ISO15765 Channel on RP1210_ClientConnect

CAN and J1939 have become more prevalent and their buses have become “cluttered.” There have been
some OEM efforts to split the control and non-control features on vehicles. This has led to the need for mul-
tiple (possibly simultaneous) CAN/J1939 and ISO15765 connections in diagnostic applications. This need
has prompted the inclusion of an additional RP1210_ClientConnect “fpchProtocol”, called “Channel=X”.
The variable X indicates which CAN/J1939 channel to connect to (if a VDA supports multiple channels). If
not given, the first (Channel=1) is assumed.
Notes:
• Each connection requires a separate RP1210_ClientConnect, and, therefore, its own ClientID.
The “Channel” variable can be anywhere in the fpchProtocol string, except after “Transport=”.
©2011—TMC/ATA
Example:
• fpchProtocol=”CAN:Baud=500,Channel=3”
• fpchProtocol=“CAN:Channel=1”
• fpchProtocol=“ISO15765:Channel=1,Baud=X”
• fpchProtocol=“J1939:Baud=X,Channel=3”
• fpchProtocol=“J1939:Baud=X,Channel=3”
12.10. SETTING J1708 BAUD RATE on RP1210_ClientConnect

Some vendors and applications have set the J1708 datalink to values other than 9600 in an effort to speed
end-of-line programming or code/parameter downloads. This section deals with connecting at a different
baud rate. There is also another way of setting the J1708 baud rate after calling RP1210_ClientConnect;
see the RP1210_SendCommand documentation.
There is an INI variable “J1708FormatsSupported” that shows which formats that an API supports.
12.10.1. Setting J1708 Baud Rate – Format 1

This is the new format for setting of the J1708 baud rate.
• fpchProtocol = “J1708:Baud=X”
- Baud (X) may be “9600”, “19200”, “38400”, “57600”, or “Auto”
12.10.2. Setting J1708 Baud Rate – Format 2 – Default

This is the general, default for J1708 (9600 baud).
• fpchProtocol=“J1708”
12.11. SETTING J1939 BAUD RATE on RP1210_ClientConnect

Some vendors and applications have set the J1939 datalink to values other than 250k in an effort to speed
end-of-line programming or code/parameter downloads. This section deals with connecting at a different
baud rate. There is also another way of setting the J1939 baud rate after calling RP1210_ClientConnect;
see the RP1210_SendCommand documentation. This command was added to allow for the CM features
of J1939, but at a much higher baud rate. In 2010, due to numerous requests, 250k and 500k will no longer
be the only connection speeds. An application may now treat the J1939 link exactly like a CAN link and
connect at non-standard speeds and use different register settings. Also the string “Auto” was added to
Format 1 for the upcoming 500k J1939.
There is an INI variable “J1939FormatsSupported” that shows which formats that an API supports.

This is the new format for variable J1939 baud rate.
• fpchProtocol = “J1939:Baud=X”
- Baud (X) may be “125”, “250”, “500”, “1000” or “Auto”
12.11.2. Setting J1939 Baud Rate – Format 2 – Default

This is the general, default for J1939 (250k baud).
• fpchProtocol=“J1939”

Driver uses the sample location to calculate PROP_SEG, PHASE_SEG1, and PHASE_SEG2.
• fpchProtocol = “J1939:Baud=X,SampleLocation=Y,SJW=Z,IDSize=S”
- SampleLocation (Y) is between 50 and 95 (percent %)
©2011—TMC/ATA
- SJW (Z) may be 1 or 3
- IDSize (S) may be ONLY 29

Formula derived directly from the BOSCH CAN specification.
• fpchProtocol=“J1939:Baud=X,PROP_SEG=A,PHASE_SEG1=B,PHASE
SEG2=C,SJW=Z,IDSize=S”
- PROP_SEG (A) is between 1 and 8
- PHASE_SEG1(B) is between 1 and 8
- PHASE_SEG2(C) is must be less than PHASE_SEG1
- IDSize(S) may be ONLY 29

Formula for baud derived from Intel implementations.
• fpchProtocol=“J1939:Baud=X,TSEG1=D,TSEG2=E,SampleTimes=Y,SJW=Z,IDSize=S”
- TSEG1 (D) is between 2 and 15
- TSEG2 (E) is between 1 and 7 and must be less than TSEG1
- SampleTimes (Y) is 1 or 3
- IDSize may be ONLY 29
12.12. SETTING ISO15765-2 BAUD RATE on RP1210_ClientConnect

The default ISO15765-2 baud rate on RP1210_ClientConnect is 250k (same as J1939); however, some
applications may require different ISO15765-2 baud rates. To set the baud rate on ISO15765-2 the user
can use the following values for the protocol connection string:
There is an INI variable “ISO15765FormatsSupported” that shows which formats that an API supports.
12.12.1. Setting ISO15765 Baud Rate – Format 1

This is the new format for variable ISO15765 baud rate.
• fpchProtocol=“ISO15765:Baud=X”
- Baud (X) may be between 1 and 1M (1-1000000) or “Auto”
12.12.2. Setting ISO15765 Baud Rate – Format 2 – Default

This is the general, default for ISO15765 (250k baud).
• fpchProtocol=“ISO15765”
12.13. Multiple RP1210_ClientConnect Strings

If the OEM application wishes to use several connect strings (i.e., J1939:Baud=x and Transport=TCPIPad
dress=xxx.xxx.xxx.xxx,TCPIPport=xx ) together, the command separator can be a comma or a semicolon.
The resulting string would be:
J1939:Baud=x;Transport=TCPIPaddress=xxx.xxx.xxx.xxx,TCPIPport=xx;Channel=2
13. RP1210_ClientDisconnect
This function is called by the client application seeking to terminate its connection with the databus to which
it is connected. The API DLL will then de-allocates any client data structures and disables any active filters
associated with this client. If this client was the last client connected to the API, the DLL will also deactivate
any device drivers (virtual or otherwise) that communicate with the hardware.
©2011—TMC/ATA
13.1. RP1210_ClientDisconnect Prototype
Language Prototype
short __declspec (dll export) WINAPI RP1210_ClientDisconnect
(
C/C++ short nClientID
);
Declare Function RP1210_ClientDisconnect Lib “VENDRX32.DLL”...
(
Visual Basic ByVal nClientID As Integer
) As Integer
13.2. RP1210_ClientDisconnect Parameters

nClientID The client identifier for the client that needs to be disconnected.
13.3. RP1210_ClientDisconnect Return Value

If the disconnect is successful, then the function returns 0. Otherwise, a value greater than 127 is returned,
corresponding to the code for the error that was registered in the processing of this function call. The typi-
cal error codes are described below. More descriptive or proprietary codes may be returned by individual
vendor implementations as long as the numerical equivalents of these return values are greater than 192,
and the descriptions are clearly documented by the vendor.
ERR_FREE_MEMORY An error occurred in the process of memory de-allocation.
ERR_INVALID_CLIENT_ID The identifier for the client to be disconnected was invalid.
13.4. RP1210_ClientDisconnect Notes

This function can only be called only after a connection has been successfully established with the API.
The parameter passed to this function is the identifier for the connected client to be disconnected. Typically,
a call to this function will be made in the clean-up code of the client application, when it is closing. It is the
responsibility of the user application to terminate all of its threads that it has created to perform the IO.
If the API DLL calls RP1210_ClientDisconnect, any future calls to RP1210_ReadMessage or RP1210_Send-
Message will return with error value ERR_CLIENT_DISCONNECTED. This method will give a client ap-
plication the ability to gracefully stop any threads. Any additional disconnect information concerning thread
shut down is passed back in the call to RP1210_GetHardwareStatus. There is also no restriction on order
of disconnect if an app has made multiple connections.
14. RP1210_SendMessage
This function is called by the client application seeking to send a message to the databus to which it is
connected.
Due to NON_BLOCKING_IO and BLOCKING_IO conversations, the nBlockOnSend parameter will now be
ignored and NON_BLOCKING_IO will only be used by a VDA API. The problem with NON_BLOCKING_IO
and BLOCKING_IO in a SendMessage type of call with mixtures of blocking can be problematic, especially
in a multi-application environment. If one application/client fills up the queue using NON_BLOCKING_IO,
and then a second application (or client) uses BLOCKING_IO, there is a possibility that the second app/cli-
ent will have to wait a long time before the API clears the queue of the first applications' messages. This
can cause applications timeouts.
©2011—TMC/ATA
14.1. Note to Application Vendors
Although changes should not affect application vendors significantly, vendors should ensure that they don't
call this function too often and end up overloading the queue. TMC suggests vendors should make the call
NON_BLOCKING_IO to ensure that if one is working with an old API, one gets the same behavior as what
will happen in the future because of this change. It is suggested to call Sleep( x ) after a SendMessage with
"x" equal to the number of milliseconds per byte multiplied by the number of bytes sent.
14.2. RP1210_SendMessage Prototype

Language Prototype
short __declspec (dll export) WINAPI RP1210_SendMessage
(
short nClientID,
char *fpchClientMessage,
C/C++ short nMessageSize,
short nNotifyStatusOnTx,
short nBlockOnSend,
)
Declare Function RP1210_SendMessage Lib “VENDRX32.DLL”...
(
ByVal nClientID As Integer,
ByVal fpchClientMessage As String,
Visual Basic ByVal nMessageSize As Integer,
ByVal nNotifyStatusOnTx As Integer,
ByVal nBlockOnSend As Integer
) As Integer
14.3. RP1210_SendMessage Parameters

nClientID The client identifier for the client that wants to send a message.
A pointer to the buffer (allocated by the client application) that contains the message
fpchClientMessage to be sent. The protocol-specific message formats must be in conformance with those
specified below.
The size of the entire message in bytes (including any identifier, echo byte, checksum,
nMessageSize
or other qualifier bytes).
This is a Windows 3.1 legacy parameter and will be ignored. New applications should
nNotifyStatusOnTx
pass in the value of zero.
nBlockOnSend This flag is now ignored and NON_BLOCKING_IO will be used by the API.
14.4. RP1210_SendMessage Return Value

The function will always return a value of 0 for successful queuing of the message for transmission. In the
event of an error in queuing the message for transmission, an error code, corresponding to a value of greater
than 127 is return ed. The typical error codes are described below. More descriptive or proprietary codes
may be returned by individual vendor implementations as long as the numerical equivalents of these return
values are greater than 192, and the descriptions are clearly documented by the vendor.
The API was forced to concede the address to another node on
ERR_ADDRESS_LOST
the J1939 network. This return code is for J1939 only.
J1939 client never protected an address. This return code is
ERR_ADDRESS_NEVER_CLAIMED
for J1939 only.
ERR_BLOCK_NOT_ALLOWED This was a legacy Windows 3.1 return code.
Indicates RP1210_ClientDisconnect was called on
ERR_CLIENT_DISCONNECTED
the nClientID.
ERR_DLL_NOT_INITIALIZED Indicates that the API DLL was not initialized.
©2011—TMC/ATA
The device hardware interface, through which the message is
ERR_HARDWARE_NOT_RESPONDING
routed, is not responding.
The identifier for the client that is seeking message transmission
ERR_INVALID_CLIENT_ID
is invalid or unrecognized.
ERR_MESSAGE_NOT_SENT Returned if an error has occurred queuing the message.
ERR_MESSAGE_TOO_LONG The message being sought to be transmitted is too long.
ERR_TX_QUEUE_CORRUPT The API DLL’s receive message queue is corrupt.
ERR_TX_QUEUE_FULL The API DLL’s transmit message queue is full.
14.5. Formatting a J1708/PLC Message for RP1210_SendMessage

The nMessageSize parameter should reflect the size of the entire message, including the message priority
byte and checksum (if in RAW MODE). The double asterisks (**) indicate an optional parameter.
Priority One byte identifying what J1708 priority the message should be transmitted at.
MID The J1708/J1587 Message Identifier (MID).
Message Data This field includes all message data and may be between 1 and 504 bytes.
If the API is in RAW MODE, then the application would have to add the check-
sum and the nMessageSize parameter would be incremented by one to show
Checksum** the checksum byte. It is the responsibility of the API to add a checksum byte to
the message before sending the J1708 message to the datalink if the API DLL
is in Converted Mode.
A post-RP1210B clarification: J1708 does not specify the maximum length other than the 21 bytes key-
on/engine-running. In RP1210A and RP1210B, there is an inconsistency in the actual number of message
bytes that could be sent from an application. The maximum message sizes for RP1210_SendMessage of
a J1708/PLC message are as follows:
J1708 Mode Description

CONVERTED_MODE Max message length = 507 (Pri=1, MID=1, DATA=504)
RAW_MODE Max message length = 508 (Pri=1, MID=1, DATA=504, CHECKSUM=1)
The #define constant “MAX_J1708_MESSAGE_LENGTH” in the “API Vendor Header File” section has been
adjusted to “512” to reflect the maximum size of a RP1210_ReadMessage of J1708.
14.6. Formatting a J1939 Message for RP1210_SendMessage
P arameter G roup How/ S ource Des tination Mes s age Data

Number P riority Addres s Addres s (0 - 1785)
3 B ytes 1 B yte 1 B yte 1 B yte 0-1785 B ytes
The nMessageSize parameter should reflect the size of the entire message.
Parameter Group Number Three bytes in length and is in Little Endian (LSB)/Intel format.
©2011—TMC/ATA
A bit field, one byte (eight bits) in length. The higher order bit, bit 7, deter-
mines the J1939 transport type to use for data field lengths greater than
eight bytes. A value of one in the high order bit will cause the lower level
driver to use the Broadcast Announcement Message (BAM) transport, a
value of zero will enable the Connection Management (RTS/CTS) trans-
How To Send/Priority
port facilities (reference SAE J1939/21). If this bit is not set (indicating
RTS/CTS) and the global address is used, then BAM will be used as
transport (this is a clarification from RP 1210A). The lower three bits
(bits 0-2) determine the message priority. The other bits (bits 3-6) are
reserved for future use and should be set to zero.
One byte in length and contains the originating nodes address. If the
Source Address field contains an address that has not been claimed,
Source Address
the API will still send the message if the message is 8 bytes or less (see
Section A3.5, Protect J1939 Address).
One byte in length and contains the address of the node for which the
Destination Address
packet is bound.
Contains all the data elements of the message. The API DLL, or its as-
sociated drivers, is required to break down long messages and transmit
Data
multi-packet message fragments in accordance with the J1939 transport
protocol detailed in Section 3.10 of SAE J1939/21.
14.7. Formatting a CAN/J2284 Message for RP1210_SendMessage
The nMessageSize parameter for a CAN transmit message should include the byte count for the message
type as well as the CAN Identifier and Message Data.
Standard CAN message = 0x00 (11-bit identifier)
Message Type
Extended CAN message = 0x01 (29-bit identifier)
CAN ID for Standard CAN message is two bytes (Big Endian (MSB) format).
CAN Identifier (CAN ID)
CAN ID for Extended CAN message is four bytes (Big Endian (MSB) format).
Message Data Message data from 0 to 8 bytes.
14.8. Formatting a J1850 Message for RP1210_SendMessage
The nMessageSize parameter for a J1850 transmit message should include the byte count for the entire
message including header and data bytes.
©2011—TMC/ATA
Header Bytes 3 Bytes for the message header.
From 0-4096 data bytes (12 bytes max in “Normal Mode” and 4096 bytes max
Data Bytes
in “Block Mode”.
14.9. Formatting an ISO15765 Message for RP1210_SendMessage
The nMessageSize parameter for an ISO15765 transmit message should also include the byte count for
the message type, CAN Identifier, Extended Address Byte and Message Data.
Before sending long (segmented) messages, the application must:

1. Configure the filtering such that messages will be accepted from the incoming (device) CAN-ID with
either the RP1210_Set_Message_Filtering_For_ISO15765 or the RP1210_Set_All_Filters_States_
to_Pass command, and
2. Establish a flow control association between the incoming (device) CAN ID and the outgoing (tester)
CAN ID with the RP1210_Set_ISO15765_Flow_Control command.
The API DLL, or its associated drivers, is required to break down long messages and communicate multi-
packet message fragments in accordance with the protocol detailed in ISO15765-2.
It is not necessary to establish a flow control association to be able to send short (Single Frame) messages
to a device.
Standard (11-bit) CAN message = STANDARD_CAN (0x00)
Extended (29-bit) CAN message = EXTENDED_CAN (0x01)
Standard (11-bit) CAN message with ISO15765 extended address byte = STANDARD_
Message Type CAN_ISO15765_EXTENDED (0x02)
Extended (29-bit) CAN message with ISO15765 extended address byte = EXTENDED_
CAN_ISO15765_EXTENDED (0x03)
Mixed addressing (11-bit) CAN message = STANDARD_MIXED_CAN_ISO15765 (0x04)
CAN Identifier Byte order is Big Endian (MSB).
(CAN ID)
To stay generic, four bytes are used for the CAN identifier regardless of whether Standard
or Extended CAN is used. In the case of Standard CAN, only the low (last) two bytes would
be used.
If the message type is STANDARD_CAN_ISO15765_EXTENDED (0x02) or EXTEND-
ED_CAN_ISO15765_EXTENDED (0x03), this byte will specify the ISO15765 extended
Extended
address byte. If the message type is STANDARD_MIXED_CAN_ISO15765 this byte will
Address
specify the ISO15765 network address extension. Otherwise, this field must be present,
but is ignored.
©2011—TMC/ATA
14.10. Formatting a KWP2000/ISO9141 Message for RP1210_SendMessage
The nMessageSize parameter should reflect the size of the entire message, including the checksum byte
if in Raw Mode. The double asterisks(**) indicate an optional parameter.
Number of Header Bytes The number of bytes in the header (1-4).
Header 1 to 4 bytes of message header.
If the API is in Raw Mode, then the application would have to add the checksum and the
nMessageSize parameter would be incremented by one to show the checksum byte.
Checksum
It is the responsibility of the API to add checksum byte to the message before sending
the KWP2000 message to the datalink if the API DLL is in Converted Mode.
15. RP1210_ReadMessage
This function is called by the client application to read a message from the device and protocol associated with it.
15.1. RP1210_ReadMessage Prototype

Language Prototype
short declspec (dll export) WINAPI RP1210_ReadMessage
(
short nClientID,
C/C++ char *fpchAPIMessage,
short nBufferSize,
short nBlockOnRead
)
Declare Function RP1210_ReadMessage Lib “VENDRX32.DLL”
(
Visual Basic ByVal fpchAPIMessage As String
ByVal nBufferSize As Integer,
ByVal nBlockOnRead As Integer
) As Integer
15.2. RP1210_ReadMessage Parameters

nClientID The client identifier for the client that wants to read a message.
A pointer to the buffer (allocated by the client application) to where the transfer of the
message is sought. If a message is correctly received, then the first four bytes of the
fpchAPIMessage message represents the timestamp of the message (the resolution of this timestamp
is implementation-specific, and can be retrieved from the vendor-supplied INI file).
The bytes following the timestamp are protocol-specific as detailed below.
The size of the message in bytes (including any identifier or other qualifier bytes
nBufferSize
preceding the actual message data).
nBlockOnRead NON_BLOCKING_IO or BLOCKING_IO
©2011—TMC/ATA
15.3. RP1210_ReadMessage Return Value
If the read is successful, then the function returns the number of bytes read including the four bytes for
timestamp. If no message is present, then the function returns 0. If an error occurred, then a value, cor-
responding to the additive inverse of the error code, is returned. The typical error codes are described
below. More descriptive or proprietary codes may be returned by individual vendor implementations as long
as the numerical equivalents of these return values are greater than 192, and the descriptions are clearly
documented by the vendor.
ERR_CLIENT_DISCONNECTED Indicates RP1210_ClientDisconnect was called on nClientID.
ERR_DLL_NOT_INITIALIZED Indicates that the API DLL was not initialized.
The device hardware interface, through which the message is routed, is not
responding.
The identifier for the client that is seeking message transmission is invalid
or unrecognized.
ERR_MESSAGE_TOO_LONG The message being sought to be received is too long for the user’s buffer.
ERR_RX_QUEUE_CORRUPT The API DLL’s receive message queue is corrupt.
ERR_RX_QUEUE_FULL The API DLL’s receive message queue is full.
15.4. The J1708/PLC Message from RP1210_ReadMessage

If the message is correctly received, the return value from RP1210_ReadMessage will specify the size of
the entire message, including the four timestamp bytes, the entire message; echo and checksum bytes (if
applicable**). This field has a maximum size of 511 bytes.
The timestamp is four bytes in length and is in Big Endian (MSB) or Motorola format. The
Timestamp
resolution of the timestamp is implementation-dependent and is given in the INI file.
If the command Set Echo Transmitted Messages has configured the API to echo trans-
mitted messages, this field is set to 0x01 if the received message originated at the API’s
client application. If the received message did not originate at the client application, this
Echo Byte**
byte is set to 0x00.
If ECHO MODE is off, this field will not appear in the message.
MID The J1708/J1587 Message Identifier (MID).
Data This is the actual message in accordance with the J1708 (or J1587) standard.
If the API were in RAW MODE, then the application would receive a checksum byte.
Checksum** NOTE: If there is a databus collision and both senders back off on the first character, then
the message will only be one byte long. The one byte goes in Message Data field, so
there is a special case in Raw Mode where there is no checksum byte.
A post-RP1210B clarification: J1708 does not specify the maximum length other than the 21 bytes key-
on/engine-running. In RP1210A and RP1210B, there is an inconsistency in the actual number of message
©2011—TMC/ATA
bytes that could be send from an application. The maximum message sizes for RP1210_ReadMessage of
a J1708/PLC message are as follows:
J1708 Mode Description

CONVERTED_MODE Max message length = 510 (TS=4, EchoByte=1, MID=1, DATA=504)
RAW_MODE Max message length = 511 (TS=4, EchoByte=1, MID=1, DATA=504, CHECKSUM=1)
The #define constant “MAX_J1708_MESSAGE_LENGTH” in the “API Vendor Header File” section has been
adjusted to “512” to reflect four bytes for a timestamp, one byte for the echo byte (if on), one byte for the
MID, the maximum size of a received data (504), one byte for the checksum, plus an additional byte for a
NULL character.
15.5. The J1939 Message from RP1210_ReadMessage

the entire message, including the four timestamp bytes, the entire message; and echo byte (if applicable**).
This field has a maximum size of 1796 bytes.
In accordance with Section 5.2.1 of J1939/21, the priority should be masked off by the VDA and set to zero.
However VDA vendors can send back the actual message priority if they so desire. Because the priority
may or may not be provided by the VDA, applications should function correctly regardless of the presence
of the priority information.
The timestamp is four bytes in length and is in Big Endian (MSB) or Motorola
format. The resolution of the timestamp is implementation-dependent and is
Timestamp
given in the INI file. For Messages greater that eight bytes, the TimeStamp
field will contain the time that the last packet is received.
If the command Set Echo Transmitted Messages has configured the API
to echo transmitted messages, this field is set to 0x01 if the received mes-
sage originated at the API’s client application. If the received message did
Echo Byte**
not originate at the client application, this byte is set to 0x00.
If Echo Mode is off, this field will not appear in the message.
Parameter Group Number (PGN) Three bytes in length and is in Little Endian (LSB)/Intel format.
The higher order bit 7 determines the J1939 transport type that was used to
transport the data if the message is greater than eight bytes. A value of one
in the high order bit, shows that BAM was used and a value of zero shows
How To Send/Priority that RTS/CTS was used. The lower three bits (bits 0-2) were previously des-
ignated as the message priority. The VDA can either pass the actual priority
of the message or can mask them off and set them to 0. The other bits (bits
3- 6) are unused and should be set to zero.
©2011—TMC/ATA
One byte in length and contains the origination address of the message.
This shall always be the origination node address for the message (CANID
Source Address
byte 0) regardless of PDU Format (PF) type of PDU1=Destination Specific,
or PDU2=Group Extension.
One byte in length and contains the destination address of the message.
On a PDU2=Group Extension, this byte shall be set to 0xFF (global J1939
Destination Address address). On an RTS/CTS message, this will be the address that the VDA
has claimed (i.e. 249 – Offboard PC), and with a BAM message, this byte
shall be set to 0xFF (global J1939 address).
Data Contains all the data elements of the message.
Application Notes:
The forthcoming J1939-21 is going to be using the Data Page bit and the Reserved bit to allow ISO15765
messages to be transported across a J1939 bus. Current RP1210A drivers let these ISO15765 messages
come through because nobody was checking the reserved bit. The field format cannot be changed without
breaking backwards compatibility so TMC adds that these messages will always be passed back to the ap-
plication, even when the user has connected to “J1939”.
15.6. The CAN/J2284 Message from RP1210_ReadMessage

the entire message, including the four timestamp bytes and echo byte (if applicable**).
T ime S tamp **E cho Mes s age T ype C AN ID Mes s age

Data
4 0/1 1 2 or 4 0-8
The timestamp is four bytes in length and is in Big Endian (MSB) or Motorola
Timestamp format. The resolution of the timestamp is implementation-dependent and is given
in the INI file.
If the command Set Echo Transmitted Messages has configured the API to echo
transmitted messages, this field is set to 0x01 if the received message originated
at the API’s client application. If the received message did not originate at the cli-
Echo Byte**
ent application, this byte is set to 0x00.
Standard CAN message = 0x00 (11-bit identifier)
Message Type
Extended CAN message = 0x01 (29-bit identifier)
CAN ID for Standard CAN message is two bytes (Big Endian (MSB) format).
CAN Identifier
CAN ID for Extended CAN message is four bytes (Big Endian (MSB) format).
©2011—TMC/ATA
15.7. The J1850 Message from RP1210_ReadMessage
the entire message including the four timestamp bytes and echo byte (if applicable**).
The timestamp is four bytes in length and is in Big Endian (MSB) or Motorola format. The
Timestamp
resolution of the timestamp is implementation-dependent and is given in the INI file.
transmitted messages, this field is set to 0x01 if the received message originated at
Echo Byte** the API’s client application. If the received message did not originate at the client ap-
plication, this byte is set to 0x00.
The number of data bytes that will appear in the message data. (in Big Endian (MSB)
Number of Data Bytes
or Motorola format)
Header Bytes Message header, 3-bytes.
Message data, from 0-4096 bytes. “Normal Mode” in J1850 allows for 12 bytes of data
Data Bytes
and “Block Mode” allows up to 4096 bytes.
15.8. The ISO15765 Message from RP1210_ReadMessage

the entire message, including the four timestamp bytes, and echo byte (if applicable**).
Long (segmented) messages can only be received from a given device if the application has:
• Configured the filtering such that messages will be accepted from the incoming (device) CAN-ID with
either the RP1210_Set_Message_Filtering_For_ISO15765 or the RP1210_Set_All_Filters_States_
to_Pass commands, and
• Established a flow control association between the incoming (device) CAN ID and the outgoing (tester)
CAN ID with the RP1210_Set_ISO15765_Flow_Control command.
The API DLL, or its associated drivers, is required to construct long messages and communicate multi-packet
message fragments in accordance with the protocol detailed in ISO15765-2.
It is not necessary to establish a flow control association to be able to receive short (Single Frame) mes-
sages from a device.
©2011—TMC/ATA
The timestamp is four bytes in length and is in Big Endian (MSB) or Motorola format.
The resolution of the timestamp is implementation-dependent and is given in the INI file.
Timestamp
For complete segmented messages, the Timestamp field will contain the time that the
last packet is received.
transmitted messages, this field is set to 0x01 if the received message originated at the
API’s client application. If the received message did not originate at the client application,
Echo Byte**
this byte is set to 0x00.
The ISO15765 indication status of the message.
• Actual message data = ISO15765_ACTUAL_MESSAGE (0x00)
• ISO15765 Confirm = ISO15765_CONFIRM (0x01). This indicates that a single
frame message or the last frame of a multi-frame segmented message has been
transmitted, or, if the message failed to transmit, the error that occurred. (see
ISO15765-2 N_USData.confirm).
Indication Status
• ISO15765 FF (First Frame) indication = ISO15765_FF_INDICATION (0x02).This
indicates that the first frame of a multi-frame segmented message has been
received. (see ISO15765-2 N_USData_FF.indication).
• ISO15765 receive error indication = ISO15765_RX_ERROR_INDICATION (0x03).
This indicates that there was some problem with the reception of the message
(see ISO15765-2 N_USData.indication).
Standard (11-bit) CAN message = STANDARD_CAN (0x00)
Extended (29-bit) CAN message = EXTENDED_CAN (0x01)
Standard (11-bit) CAN message with ISO15765 extended address byte =
STANDARD_CAN_ISO15765_EXTENDED (0x02)
Message Type
Extended (29-bit) CAN message with ISO15765 extended address byte =
EXTENDED_CAN_ISO15765_EXTENDED (0x03)
Mixed addressing (11-bit) CAN message =
STANDARD_MIXED_CAN_ISO15765 (0x04)
Byte order is Big Endian (MSB).
CAN Identifier
To stay generic, four bytes are used for the CAN identifier regardless of whether Standard
(CAN ID) or Extended CAN is used. In the case of Standard CAN, only the low (last) two bytes
would be used.
If the message type is STANDARD_CAN_ISO15765_EXTENDED (0x02) or EXTEND-
ED_CAN_ISO15765_EXTENDED (0x03), this byte will specify the ISO15765 extended
Extended Address address byte. If the message type is STANDARD_MIXED_CAN_ISO15765 this byte will
specify the ISO15765 network address extension. Otherwise, this field will be present,
but must be ignored.
Message data from 0 to 4096 bytes.
Actual message data is only available when the ISO15765 Indication byte is set to zero.
When the ISO15765 Indication byte is set to 0x01 (“confirm”) or 0x03 (“indication error”),
the first byte of the message data will contain the result of the transmission (N_Result).
This is as defined in ISO15765-2:
• N_OK = 0x00
• N_TIMEOUT_A = 0x01
Message Data • N_TIMEOUT_Bs = 0x02
• N_TIMEOUT_Cr = 0x03
• N_WRONG_SN: = 0x04
• N_INVALID_FS = 0x05
• N_UNEXP_PDU = 0x06
• N_WFT_OVRN = 0x07
• N_BUFFER_OVERFLOW = 0x08
• N_ERROR = 0x09
©2011—TMC/ATA
15.9. The KWP2000/ISO9141 Message from RP1210_ReadMessage
the entire message, including the four timestamp bytes, the entire message; and echo byte (if applicable**).
This field has a maximum size of 4139 bytes.
The timestamp is four bytes in length and is in Big Endian (MSB) or Motorola format.
The resolution of the timestamp is implementation-dependent and is given in the INI
Timestamp
file. For Messages greater that eight bytes, the TimeStamp field will contain the time
that the last packet is received.
transmitted messages, this field is set to 0x01 if the received message originated at
the API’s client application. If the received message did not originate at the client ap-
Echo Byte**
plication, this byte is set to 0x00.
Number Header Bytes This field represents the number of bytes in the header.
Header Message header from 1 to 4 bytes.
Checksum If the API were in RAW MODE, then the application would receive a checksum byte.
16. RP1210_ReadVersion
This function is called by the client application to read the version information for the API DLL. This function has
been superseded by RP1210_ReadDetailedVersion, although it will remain for backwards compatibility.
16.1. RP1210_ReadVersion Prototype

Language Prototype
void __declspec (dll export) WINAPI RP1210_ReadVersion
(
char *fpchDLLMajorVersion,
C/C++ char *fpchDLLMinorVersion,
char *fpchAPIMajorVersion,
char *fpchAPIMinorVersion
);
Declare Sub RP1210_ReadVersion Lib “VENDRX32.DLL”
(
ByVal fpchDLLMajorVersion As String,
Visual Basic ByVal fpchDLLMinorVersion As String,
ByVal fpchAPIMajorVersion As String,
ByVal fpchAPIMinorVersion As String
)
©2011—TMC/ATA
16.2. RP1210_ReadVersion Parameters
A pointer to a character (a string in Visual Basic), which the API DLL fills with
fpchDLLMajorVersion
the major version of the DLL that corresponds to its implementation.
A pointer to a character (a string in Visual Basic), which the API DLL fills with
fpchDLLMinorVersion
the minor version of the DLL that corresponds to its implementation.
A pointer to a character (a string in Visual Basic), that corresponds to the
fpchAPIMajorVersion major version of the TMC-produced API document with which the DLL
conforms. This version’s ACSII character is “3.”
A pointer to a character (a string in Visual Basic), that corresponds to the
fpchAPIMinorVersion minor version of the TMC-produced API document with which the DLL
conforms. This version’s ACSII character is “0.”
16.3. RP1210_ReadVersion Return Value

This call is listed as a subroutine and does not return a value.
17. RP1210_ReadDetailed Version

This function is called by the client application seeking to get detailed information about the vendor API
and/or firmware of the device to which it is connected. This function returns an API vendor-specific string that
is oftentimes helpful when debugging an application or a field installation problem. This is a new function to
RP1210C because RP1210_ReadVersion did not provide information about the firmware that an adapter may
have. Developers should call this function instead of the RP1210_ReadVersion because it provides more data
about the API/DLL and firmware. If an API is requested to process this request and does not have firmware
associated with the device, the fpchFWVersionInfo parameter will be returned as a NULL string.
For example, a vendor may need to know more than just the major/minor information of their API. A couple
of examples are: “2.5.02”, “2.5”, “3.22.A.109b” and “” (the NULL string).
17.1. RP1210_ReadDetailed Version Prototype

Language Prototype
short __declspec (dll export) WINAPI RP1210_ReadDetailedVer-
sion
(
short nClientID,
C/C++ char *fpchAPIVersionInfo,
char *fpchDLLVersionInfo,
char *fpchFWVersionInfo
);
Declare Function RP1210_ReadDetailedVersion Lib “VENDRX32.
DLL”...
(
Visual Basic ByVal fpchAPIVersionInfo as String,
ByVal fpchDLLVersionInfo as String,
ByVal fpchFWVersionInfo as String,
) As Integer
17.2. RP1210_ReadDetailed Version Parameters

nClientID The client identifier for the client that wants hardware status info.
Pointer to a buffer that is 17 bytes long. The API may return up to 16 bytes in
fpchAPIVersionInfo
this field (with NULL terminator) to describe the version of the API interface.
fpchDLLVersionInfo
this field (with NULL terminator) to describe the version of the DLL.
©2011—TMC/ATA
this field (with NULL terminator) to describe the version of the firmware that is
fpchFWVersionInfo
present in the device. A NULL string is also a valid return if the VDA does not
have associated firmware.
17.3. RP1210_ReadDetailed Version Return Value

The device hardware interface, through which the message is routed,
is not responding.
ERR_INVALID_CLIENT_ID The identifier for the client was invalid.
18. RP1210_GetErrorMsg
This function is called by the client application to get a textual representation of the last error code that
occurred by that client in an application. In RP 1210B, the nClientID parameter was removed. It was not
supposed to be in this function, but in the GetLastErrorMsg function.
18.1. RP1210_GetError Msg Prototype

Language Prototype
short __declspec (dll export) WINAPI RP1210_GetErrorMsg
(
C/C++ short ErrorCode,
char *fpchDescription
)
Declare Function RP1210_GetErrorMsg Lib “VENDRX32.DLL”
(
Visual Basic ByVal ErrorCode As Integer,
ByVal fpchDescription as String
) As Integer
18.2. RP1210_GetErrorMsg Parameters

ErrorCode Numerical value for the last error which occurred.
A pointer to the buffer (allocated by the client application) of 80 bytes, used
to return the error message associated with the error code. The returned
string length should be no greater than 80 bytes unless an RP1210_Send-
fpchDescription
Command of RP1210_Set_MaxErrorMsgSize stating that the application can
handle longer lengths. Remember that in the C language, a NULL character
will also be included.
18.3 RP1210_GetErrorMsg Return Value

If the function was able to successfully convert the given error code to a useful description, a value of 0 will
be returned. If the function could not convert the error into a description an error code will be returned.
The error code provided does not have an associated textual representation
ERR_CODE_NOT_FOUND
associated with it.
19. RP1210_GetLastErrorMsg
Added to RP1210B, this function is called to get a more descriptive subordinate error code and textual repre-
sentation of the last error code for a particular ClientID. The application/thread/process passes the last error
code received (in the ErrorCode parameter) and the function returns a more descriptive subordinate error
©2011—TMC/ATA
code (in the SubErrorCode parameter) along with a textual message that can be delivered to the end-user
(in the fpchDescription parameter).
• This function is not intended to supersede the RP1210_GetErrorMsg function. RP1210_GetErrorMsg
can be called at any time, whereas this function is intended to be called immediately after a failed API
call like the Windows API call GetLastError().
• The subordinate error code should be a #define in the VDA API’s header file, with a meaningful com-
ment.
• For more information on why this function was added, see the section entitled Error Code 142 “ERR
HARDWARE NOT RESPONDING” and Backwards Compatibility.
19.1. RP1210_GetLastErrorMsg Prototype

Language Prototype
short __declspec (dll export) WINAPI RP1210_GetLastEr-
rorMsg
(
short ErrorCode,
C/C++ int *SubErrorCode,
char *fpchDescription,
short nClientID
)
Declare Function RP1210_GetLastErrorMsg Lib “VENDRX32.
DLL”
(
ByVal ErrorCode As Integer,
Visual Basic ByRef SubErrorCode As Integer,
ByVal fpchDescription as String
ByVal nClientID As Integer
) As Integer
19.2. RP1210_GetLastErrorMsg Parameters

ErrorCode Numerical value for the last error which occurred.
A pointer to a 32-bit integer that will receive the subordinate error code de-
SubErrorCode
scription, or -1 if no subordinate error code is available.
A pointer to a buffer (allocated by the client application) of 80 bytes that is
used to return a detailed error message associated with the error code (and
fpchDescription
subordinate code if available). The returned string length should be no greater
than 79 bytes in length and will have a NULL (0x00) terminator.
nClientID The client identifier for the client that wants the last error message.
19.3. RP1210_GetLastErrorMsg Return Value

If the function was able to successfully convert the given error code to a useful description, a value of 0 will
be returned. If the function could not convert the error into a description an error code will be returned.
The error code provided does not have an associated textual represen-
ERR_CODE_NOT_FOUND
tation associated with it.
20. RP1210_GetHardwareStatus
This function is called by the client application to determine the hardware interface status and whether the
VDA device is physically connected or not and whether traffic has been seen on databus links in the past
second.
20.1. Fall 2010 TASK FORCE Discussions—Background Notes

At TMC’s 2010 TMC Fall Meeting, the RP 1210 Update Task Force recommended changing this function
somewhat because the Task Force was looking more closely at multi-application capable VDA devices and
©2011—TMC/ATA
the issues involved with that capability. The topic of BLOCKING_IO versus NON_BLOCKING_IO was the
biggest topic, leading to the change of this function. The Task Force also discussed changing the nInfoSize
parameter to something that does not have to be changed again.
In RP1210A, if you read the specification closely, if you called with BLOCKING_IO set, the VDA drivers would
not come back unless there was a change in the low byte for the protocol the client was connected to (the
"activated/traffic-detected 'ever'/BUS_OFF" byte). This meant that only if the bus status had changed, would
the function return. An application could call this with BLOCKING_IO and it would never return unless the
adapter was disconnected or reconnected. Since this was before the "threading model" became popular,
most apps just called it with NON_BLOCKING_IO in a polling fashion.
In RP1210B, if you called with BLOCKING_IO set, the VDA drivers would abide by the "BLOCKING TIMEOUT"
variable (infinite was assumed), but the low protocol bytes were changed to indicate if traffic had been seen
in the past second (instead of traffic 'ever' having been seen). This meant that only if traffic was detected one
second and not the next, or the VDA was unplugged and re-plugged in, would the function return. Threading
was popular when this was balloted, but most applications kept calling it as NON_BLOCKING_IO in a polling
fashion while some VDA vendors just implemented it as NON_BLOCKING_IO anyway.
20.2. Changes New to RP 1210C
20.2.1. nBlockOnRequest is Now Ignored

The short nBlockOnRequest parameter will now be ignored by the VDA drivers and NON_BLOCKING_IO
will be assumed. VDA drivers will no longer block when this function is called.
20.2.2. nInfoSize Changed to 64 Bytes

The short nInfoSize parameter will now be set to 64 bytes, and should not change again. The unused bytes
will be ignored until they are defined by TMC’s RP1210 Task Force.
20.2.3. VDAs to Return Success and Only Populate Number of Bytes The Application Requested
Some applications are calling VDA APIs with values in nInfoSize other than what was balloted in RP 1210A
(16) and RP 1210B (18). Some VDA APIs are returning ERR_INVALID_COMMAND or other errors (non
zero) and the applications are not able to process the values.
One of the first things a VDA API will do when this command is issued is to set the first "nInfoSize" bytes of
"fpchClientInfo" to 0x00. The API will then return "nInfoSize" bytes as requested. If a VDA API does not
support all protocols requested, then those bytes are just left at 0x00.
The VDA API will always return 0 indicating success unless ERR_CLIENT_DISCONNECTED or ERR_IN-
VALID_CLIENT_ID apply. This allows any RP1210 application (A/B/C) calling with "any" nInfoSize value
to get a valid return and not have to error out to the user.
20.2.4. Application Developer Notes

In your next software revision, you should change the fpchClientInfo array to 64 bytes and set each byte to
0x00 before calling this function (do not rely on the API to do this for you). You should then set the nInfoS-
ize parameter to 64. If 64 does not work and you receive an error, you should set the nInfoSize value to a
decreasing multiple of two until you get an API to return a success “0” value. Your application should now
work for any VDA on the market. Most people only use J1708 and J1939, so 16 should be all you need
anyway.
20.2.5. VDA Vendor and Application Developer Notes on the fpchClientInfo Buffer
If your VDA API is using any type of proprietary bit in the fpchClientInfo returned values of this function,
please stop doing this or bring it to TMC’s RP 1210 Update Task Force for consideration. You are causing
RP1210-compliant VDA devices to not work with certain applications, and the applications that are having
issues are not easily changed.
©2011—TMC/ATA
If your application is expecting proprietary bit values on a return from this function, you should check to see
if it is the non-RP1210-compliant VDA you are expecting (by using the vendor’s DLL name) when checking
the returned values in the fpchClientInfo array. This allows the RP1210-compliant VDA devices on the
market to work with your application without those VDA vendors having to implement proprietary bit values
that they do not understand.
20.3. RP1210_GetHardwareStatus Prototype

Language Prototype
short __declspec (dll export) WINAPI RP1210_GetHardwareStatus
(
short nClientID,
C/C++ char *fpchClientInfo,
short nInfoSize,
short nBlockOnRequest
);
Declare Function RP1210_GetHardwareStatus Lib “VENDRX32.DLL”
(
Visual Basic ByVal fpchClientInfo As String,
ByVal nInfoSize As Integer,
ByVal nBlockOnRequest As Integer
) As Integer
20.4. RP1210_GetHardwareStatus Parameters

nClientID The client identifier for the client that wants hardware status info.
A pointer to the buffer (allocated by the client application) where hardware status
information is to be placed. The format of this buffer is pairs of bytes. The low byte of
fpchClientInfo each pair represents the status of the hardware/protocol. The high byte of each pair
indicates the number of clients currently connected to the hardware/protocol. This
buffer should be at least 64 bytes in length.
Set by the application to a value of up to 64 bytes. This value shall be greater or
equal to 16 (RP1210A) and a multiple of 2. API vendors will set “nInfoSize” bytes
nInfoSize of fpchClientInfo to 0x00 before filling the fpchClientInfo buffer with “nInfoSize”
bytes. The API will not return an error unless the client is disconnected or is invalid
See more from the notes above.
nBlockOnRequest This parameter is now ignored and NON_BLOCKING_IO will be used by the API.
20.5. RP1210_GetHardwareStatus Return Value

If the function determines that the hardware interface is present and functioning, then the function returns
a value of 0. Otherwise, an error code, corresponding to a value of greater than 127 is returned. If no error
occurs, the function also places datalink information in the client application provided buffer.
Indicates that the identifier for the client that is requesting the hardware status
is invalid.
20.6. Information Returned in fpchClientInfo
©2011—TMC/ATA
20.6.1. Hardware Status (Bytes 0-1)
Byte 0
Bit 0 is set if the hardware device has been located.
Bit 1 is set if the located hardware is an internal device.
Bit 2 is set if the located hardware is an external device.
Bit 3 reserved for future RP1210 use (set to 0).
Bits 4-7 are available for vendor specific use.
Byte 1
Indicates the current number of clients connected to this device.
20.6.2. J1939 (Bytes 2-3)

Byte 2
Bit 0 is set if the J1939 link has been activated.
Bit 1 is set if traffic has been detected on this link within the last 1 second.
Bit 2 is set if CAN controller reports a BUS_OFF status.
Byte 3
Indicates the current number of clients connected to this link.
20.6.3. J1708 (Bytes 4-5)

Byte 4
Bits 2-3 reserved for future RP1210 use (set to 0).
Byte 5
20.6.4. CAN (Bytes 6-7)

Byte 6
Bit 0 is set if the CAN link has been activated.
Byte 7
20.6.5. J1850 (Bytes 8-9)

Byte 8
Bit 2 is reserved for future RP1210 use (set to 0).
Bit 3 is reserved for future RP1210 use (set to 0).
Byte 9
20.6.6. Vendor 1, 2, 3 (Bytes 10/11, 12/13, 14/15)

These bytes are all vendor specific. Information about the data format for them can be obtained from the
vendor of the VDA.
©2011—TMC/ATA
20.6.7. ISO15765 (Bytes 16-17)
Byte 16
Bit 0 is set if the ISO15765 link has been activated.
Byte 17
20.6.8. ISO9141 (Bytes 18-19)

Byte 18
Bit 0 is set if the ISO9141 link has been activated.
Byte 19
20.6.9. KWP2000 (Bytes 20-21)

Byte 20
Bit 0 is set if the KWP2000 link has been activated.
Byte 21
20.6.10. GM_ALDL (Bytes 22-23)—reserved For Future ALDL Implementation

Byte 22
Bit 0 is set if the GM_ALDL link has been activated.
Byte 23
21. RP1210_SendCommand
This function is called by the client application to send a command to the device driver. The command is
typically intercepted by the driver and processed according to the command number. The definition of the
fpchClientCommand character buffer is dependent upon the nCommandNumber parameter.
If these commands are successful, then the function returns a value of 0 (unless otherwise specified for a
specific command). Otherwise, an error code, corresponding to a value of greater than 127 is returned. The
specific error codes for each function are described in each section.
©2011—TMC/ATA
21.1. RP1210_SendCommand Prototype
Language Prototype
short __declspec (dll export) WINAPI RP1210_SendCommand
(
short nCommandNumber,
C/C++ short nClientID,
char *fpchClientCommand,
short nMessageSize
);
Declare Function RP1210_SendCommand Lib “VENDRX32.DLL”
(
ByVal nCommandNumber As Integer,
Visual Basic ByVal nClientID As Integer,
ByVal fpchClientCommand As String,
ByVal nMessageSize As Integer
) As Integer
21.2. RP1210_SendCommand Parameters

The command number, specified below for different functions defined as part of
nCommandNumber the TMC standard. Proprietary commands should be greater than 255 (but not
equal to 305 which is the Set J1708 Baud command.
The client identifier for the client that wants to transmit the command to its cor-
nClientID
responding driver(s).
A pointer to the buffer (allocated by the client application). This buffer is defined
fpchClientCommand
based on the command number.
nMessageSize The total number of bytes in the fpchClientCommand buffer.
21.3. RP1210_SendCommand Return Value

Each specific function (nCommandNumber) will have a different return value. These values are in each
nCommandNumber section.
21.4. Values for the nCommandNumber Parameter

TMC has reserved some values for the nCommandNumber parameter to support functionality considered
required functionality. This section defines, in detail, the structure and constitution of these commands. The
table below summarizes the send commands defined in this RP.
Command Mnemonic (Defined in API Header File) Value

Reset Device RP1210_Reset_Device 0
Set All Filter States to Pass RP1210_Set_All_Filters_States_to_Pass 3
Set Message Filtering for J1939 RP1210_Set_Message_Filtering_For_J1939 4
Set Message Filtering for CAN RP1210_Set_Message_Filtering_For_CAN 5
Set Message Filtering for ISO15765 RP1210_Set_Message_Filtering_For_ISO15765 9
Generic Driver Command RP1210_Generic_Driver_Command 14
Set J1708 Mode RP1210_Set_J1708_Mode 15
Set Echo Transmitted Messages RP1210_Echo_Transmitted_Messages 16
Set All Filter States to Discard RP1210_Set_All_Filters_States_to_Discard 17
Set Message Receive RP1210_Set_Message_Receive 18
Protect J1939 Address RP1210_Protect_J1939_Address 19
Set Broadcast List for J1708 RP1210_Set_Broadcast_For_J1708 20
Set Broadcast List for CAN RP1210_Set_Broadcast_For_CAN 21
©2011—TMC/ATA
Set J1708 Filter Type RP1210_Set_J1708_Filter_Type 24
Set CAN Filter Type RP1210_Set_CAN_Filter_Type 26
Set J1939 Broadcast Interpacket Timing RP1210_Set_J1939_Interpacket_Time 27
Set Max Error Message Return Size RP1210_SetMaxErrorMsgSize 28
Disallow Further Client Connections RP1210_Disallow_Further_Connections 29
Release a J1939 Address RP1210_Release_J1939_Address 31
Set ISO15765 Filter Type RP1210_Set_ISO15765_Filter_Type 32
Set Broadcast List for ISO15765 RP1210_Set_Broadcast_For_ISO15765 33
Set ISO15765 Flow Control RP1210_Set_ISO15765_Flow_Control 34
Clear ISO15765 Flow Control RP1210_Clear_ISO15765_Flow_Control 35
Set J1939 Baud Rate RP1210_Set_J1939_Baud 37
Set ISO15765 Baud Rate RP1210_Set_ISO15765_Baud 38
Set Blocking Timeout RP1210_Set_BlockTimeout 215
Set J1708 Baud Rate RP1210_Set_J1708_Baud 305
Flush the Send/Receive Buffers RP1210_Flush_Tx_Rx_Buffers 39
Intentionally Skipped Previously used and antiquated. 40
Set Broadcast List for KWP2000 RP1210_Set_Broadcast_For_KWP2000 41
Set Broadcast List for ISO9141 RP1210_Set_Broadcast_For_ISO9141 42
What Speed Did the VDA Connect? RP1210_Get_Protocol_Connection_Speed 45
Set ISO9141/KWP2000 Mode RP1210_Set_ISO9141KWP2000_Mode 46
Set CAN Baud Rate RP1210_Set_CAN_Baud 47
Is the VDA operating in a wireless mode? RP1210_Get_Wireless_State 48
21.5. RP1210_ Reset_Device

This API command allows the user to attempt to reset the physical device. This command is allowed only
when one client is actively connected. If more than one client is connected, this command will return an
ERR_MULTIPLE_CLIENTS_CONNECTED error. Any requests pending by the user will be closed and the
API will close the last connection prior to returning to the user. The user must reconnect after calling this
API function by issuing an RP1210_ClientConnect call. This support is required for all implementations of
the RP1210 API. If the hardware device supports a “reset,” then the hardware device will be reset. Either
way, the affect of this command is the same as RP1210_ClientDisconnect and the RP1210 variables return
to their default value.
nCommandNumber RP1210_Reset_Device
nClientID The client identifier for the client that wants to issue the command.
fpchClientCommand Empty buffer, ignored and should be set to NULL.
NMessageSize 0
©2011—TMC/ATA
21.5.1. RP1210_ Reset_Device Return Value
ERR_HARDWARE_NOT_RESPONDING The device is unable to perform a reset.
The API was not able to reset the device because more than one client
ERR_MULTIPLE_CLIENTS_CONNECTED
is connected.
21.6. RP1210_Set_All_Filters_States_To_Pass
By commanding “set all filter states to pass” it is implied that the API will allow all messages meant for the
application to pass through (clearing all active filters). This support is required for all implementations of the
RP1210 API.
nCommandNumber RP1210_Set_All_Filter_States_To_Pass
nMessageSize 0
21.6.1. RP1210_ Set_All_Filter_States_To_Pass Return Value

21.7. RP1210_Set_Message_Filtering_For_J1939
The API can set up a message filter or enable the lower-level components to set up a message filter, through
this particular configuration of the RP1210_SendCommand function. This support is required for all implemen-
tations of the RP1210 API that provide a J1939 interface. See also the command RP1210_SendCommand
(RP1210_Set_J1939_Filter_Type) that sets filters to either inclusive or exclusive; also see the section on
Inclusive and Exclusive Filtering. The filter takes effect once the DLL’s J1939 receive buffer is empty.
Successive calls to the RP1210_SendCommand function with this nCommandNumber would augment,
rather than replace, the set of currently active J1939 filters. The lower-level layers will discard all incoming
messages except those that match the associated filter parameters.
nCommandNumber RP1210_Set_Message_Filtering_For_J1939
A byte array specifying the filtering parameters. A J1939 filter parameter
fpchClientCommand
frame is shown below.
The number of bytes in fpchClientCommand. Should be a multiple of
nMessageSize
seven.
©2011—TMC/ATA
21.7.1. J1939 Filter Parameter Frame
Bytes Length Item Description
The filter flag (bit field) indicates which of the possible
fields in this frame that should be used for filtering.
Filtering is affected by matching the appropriate fields
to the corresponding fields in the incoming message.
The valid values are shown in the table below and can
be logically OR’d together.
Byte 1 1 byte Filter Flag
FILTER_PGN
- Use PGN value for filtering
FILTER_SOURCE
- Use source address for filtering
FILTER_DESTINATION
- Use destination address for filtering
The PGN that needs to be filtered. This value is used
only if the flag specifies FILTER_PGN option. This
Bytes 2-4 3 bytes PGN
value is three bytes in length and is in Little Endian
(LSB)/Intel format.
No longer used (FILTER_PRIORITY was removed)
Byte 5 1 byte Priority
and is ignored.
The source address of the messages that need to be
Byte 6 1 byte Source Address filtered. This value is only used if the flag specifies the
FILTER_SOURCE option.
The destination address of the messages that need to
Byte 7 1 byte Destination Address be filtered. This value is only used if the flag specifies
the FILTER_DESTINATION option.
21.7.2. RP1210_Set_Message_Filtering_For_J1939 Return Value

Indicates that the command number or the parameters associated with it are
ERR_INVALID_COMMAND
wrongly specified.
21.8. RP1210_Set_Message_Filtering_For_CAN
this particular configuration of the RP1210_SendCommand function. This support is required for all imple-
mentations of the RP1210 API that provide a CAN interface. See also the command RP1210_SendCom-
mand (RP1210_Set_CAN_Filter_Type) that sets filters to either inclusive or exclusive; also see the section
on Inclusive and Exclusive Filtering. Filtering for J2284 is also done with this command using the same
mnemonic.
The filter takes effect once the receive buffer is empty.
rather than replace, the set of currently active CAN filters. The lower-level layers will discard all incoming
nCommandNumber RP1210_Set_Message_Filtering_For_CAN
fpchClientCommand A byte array specifying the filtering parameters. A CAN filter parameter frame is
shown below.
nMessageSize The number of bytes in fpchClientCommand. Should be a multiple of nine.
©2011—TMC/ATA
21.8.1. CAN Filter Parameter Frame
Byte 1 1 byte CAN Type STANDARD_CAN = 11-bit identifier
EXTENDED_CAN = 29-bit identifier
Bytes 2-5 4 bytes MASK The mask indicates which bits in the header need to be matched. A
“1” means that the value of the bit is important; a “0” means that the
value is unimportant. This will be in Big Endian (MSB) format.
Byte 5 4 byte Header The Header indicates what value is required for each bit of inter-
est. To stay generic here, four bytes are used for both the mask
and header regardless of whether Standard or Extended CAN is
used. In the case of Standard CAN, only the low two bytes in both
the mask and header would be used. This will be in Big Endian
(MSB) format.
21.8.2. Standard CAN (11-bit Identifier) Example

Header 0481h=10010000001
Mask 0183h=110000011
The bit pattern is as follows:

Bit 12-32 11 10 9 8 7 6 5 4 3 2 1
Header N/A 1 0 0 1 0 0 0 0 0 0 1
Mask N/A 0 0 1 1 0 0 0 0 0 1 1
This means that bits 1, 2, 8, and 9 are the only bits of interest in the header of the incoming message; the
other bit values are ignored. Furthermore, the bit values of interest must match the mask exactly, to satisfy
the filter condition:
Bit 1 = 1
Bit 2 = 0
Bit 8 = 1
Bit 9 = 0
(Notice that the “1” in bit 11 of Header has no effect)
Now with this setting if we receive 4 messages with message headers 681h, 689h, 609h and 9h respectively,
only the first two messages will pass through.
21.8.3. RP1210_Set_Message_Filtering_For_CAN Return Value

ERR_INVALID_COMMAND
wrongly specified.
this particular configuration of the RP1210_SendCommand function. This support is required for all imple-
mentations of the RP1210 API that provide a J1708/J1587 interface. See also the command RP1210_Send-
Command (RP1210_Set_J1708_Filter_Type) that sets filters to either inclusive or exclusive; also see the
section on Inclusive and Exclusive Filtering.
©2011—TMC/ATA
The filter will be set up by supplying a list of module IDs (MIDs) in the fpchClientCommand. The lower-level
layers will discard all incoming messages except for the ones that are associated with the MIDs supplied
in this list.
As a clarification for RP1210C, note that the application may pass in an array of MIDs that will all be added
to the list.
rather than replace, the set of currently active J1708 filters. The lower-level layers will discard all incoming
The filter takes effect once the DLL’s J1708 receive buffer is empty.
fpchClientCommand A byte array specifying the MIDs to filter on. An array of MIDs may be provided.
nMessageSize The number of bytes in fpchClientCommand.

ERR_INVALID_COMMAND
wrongly specified.
3-B yte Mas k 3-B yte Header
High Low High Low
3 3
The API can set up message filters or enable their lower-level components to set up message filters, through
the particlar configuration of the RP1210_SendCommand function. This support is required for all imple-
mentations of the RP1210 API that provide J1850 interface.
The filter takes effect once the receive buffer is empty. Successive calls to the RP1210_SendCommand
function with this nCommandNumber would augment, rather than replace, the set of currently active J1850
filters. The lower-level layers will discard all incoming messages except those that match the associated
filter parameters.
fpchClientCommand A byte array specifing the filtern parameters.
nMessageSize Number of bytes in fpchClientCommand. It should be a multiple of 6 bytes.
©2011—TMC/ATA
Indicates that the command number or the parameters associated with it
ERR_INVALID_COMMAND
are wrongly specified.
21.11. RP1210_Set_Message_Filtering_For_ISO15765
The API can set up message filter or enable the lower-level components to set up a message filter, through
their particlar configuration of the RP1210_SendCommand function. This support is required for all imple-
mentations of the RP1210(B) API that provide an ISO15765 interface.
The filter takes effect once the receive buffer is empty. Successive calls to the RP1210_SendCommand
function with this nCommandNumber would augment, rather than replace, the set of currently active
ISO15765 filters. The lower-level layers will discard all incoming messages except those that match the
associated filter parameters.
nCommandNumber RP1210_Set_Message_Filtering_For_ISO15765
A byte array specifying the filtering parameters. An ISO15765 filter parameter frame
fpchClientCommand
is shown below.
nMessageSize The number of bytes in fpchClientCommand. Should be a multiple of 11.
21.11.1. ISO15765 Filter Parameter Frame

STANDARD_CAN = 11-bit identifier
STANDARD_CAN_ISO15765_EXTENDED = 11-bit identifier with ISO15765
CAN / extended
Byte 1 1 byte extended address
address Type
EXTENDED_CAN_ISO15765_EXTENDED = 29-bit identifier with ISO15765
extended address
STANDARD_MIXED_CAN_ISO15765 = 11-bit identifier with mixed addressing
The mask indicates which bits in the header need to be matched. A “1” means
Bytes 2-5 4 bytes MASK that the value of the bit is important; a “0” means that the value is unimportant.
Values are big-endian.
Extended address The extended address mask indicates which bits in the extended address
Byte 6 1 byte
MASK header need to be matched.
The Header indicates what value is required for each bit of interest. To stay
generic here, four bytes are used for both the mask and header regardless
Byte 7-10 4 byte Header of whether Standard or Extended CAN is used. In the case of Standard CAN,
only the low two bytes in both the mask and header would be used. Values
are big-endian.
The extended address header indicates what value is required for each bit of
interest. To stay generic one byte is used for both the mask and header, but
Extended address
Byte 11 1 byte is only used when the CAN / extended address type is set to STANDARD_
header
CAN_ISO15765_EXTENDED or EXTENDED_CAN_ISO15765_EXTENDED
or STANDARD_MIXED_CAN_ISO15765.
©2011—TMC/ATA
21.11.2. RP1210_Set_Message_Filtering_For_ISO15765 Return Value
ERR_INVALID_COMMAND
wrongly specified.
21.12. RP1210_Generic_Driver_Command
This command allows the client application to send a generic message to its drivers. The API simply passes
the message in the fpchClientCommand buffer down to the driver(s), if any, associated with the device
hardware without intercepting or interpreting it. This support is optional for implementations of the RP1210
API.
nCommandNumber RP1210_Generic_Driver_Command
fpchClientCommand A free form buffer of bytes to be interpreted by the associated driver(s).
nMessageSize The number of bytes in fpchClientCommand buffer.
21.12.1. RP1210_Generic_Driver_Command Return Value

ERR_COMMAND_NOT_SUPPORTED The command number is not supported by the API DLL.
ERR_INVALID_COMMAND
21.13. RP1210_Set_J1708_Mode
The API can toggle the mode of the J1708 interface from Converted Mode to Raw Mode. When a J1708
link is established, the link, by default, is in Converted Mode.
Converted Mode is defined as follows: When a J1708 data packet is received; the lower level interface is
verifying the checksum byte of the message, stripping off the checksum byte, and passing only validated
messages to the client application. When the client application is sending a data packet, the lower level
interface calculates the checksum byte and adds the byte to the trailer of the data packet.
Raw Mode is defined as follows: When a J1708 data packet is received; the lower level driver passes the
complete message (including checksum), to the application. The checksum byte would neither be inspected
nor removed. When the client application is sending a data packet, the application would be responsible for
calculating and adding the checksum byte. This mode would expand the diagnostic capabilities of the API
by giving a client application the ability to inspect the entire protocol and all J1708 bus traffic.
Starting with RP1210B, multiple clients may be connected in Raw Mode. It was shown that the majority of
VDA vendors did not have this limitation anyway. Whenever this command is called to switch either to Raw
or Converted Mode, the send and receive buffers allocated at RP1210_ClientConnect are cleared.
This support is required for all implementations of the RP1210 API that provide a J1708 interface.
©2011—TMC/ATA
nCommandNumber RP1210_Set_J1708_Mode
fpchClientCommand fpchClientCommand[0] = CONVERTED_MODE/RAW_MODE
nMessageSize 1
21.13.1. RP1210_Set_J1708_Mode Return Value

Indicates that the command number or the parameters associated with
ERR_INVALID_COMMAND
it are wrongly specified.
21.14. RP1210_Set_ISO9141KWP2000_Mode
The API can toggle the mode of the ISO9141/KWP2000 interface from Converted Mode to Raw Mode.
When a link is established, the link, by default, is in Converted Mode.
Converted Mode is defined as follows: When a data packet is received; the lower level interface is verifying
the checksum byte of the message, stripping off the checksum byte, and passing only validated messages
to the client application. When the client application is sending a data packet, the lower level interface cal-
culates the checksum byte and adds the byte to the trailer of the data packet.
Raw Mode is defined as follows: When a data packet is received; the lower level driver passes the com-
plete message (including checksum), to the application. The checksum byte would neither be inspected
nor removed. When the client application is sending a data packet, the application would be responsible for
calculating and adding the checksum byte. This mode would expand the diagnostic capabilities of the API
by giving a client application the ability to inspect the entire protocol and all bus traffic.
Multiple clients may be connected in Raw Mode. Whenever this command is called to switch either to Raw
or Converted Mode, the send and receive buffers allocated at RP1210_ClientConnect are cleared.
This support is required for all implementations of the RP1210 API that provide a ISO9141 or KWP2000
interface.
nCommandNumber RP1210_Set_ISO9141KWP2000_Mode
fpchClientCommand fpchClientCommand[0] = CONVERTED_MODE/RAW_MODE
nMessageSize 1
21.14.1. RP1210_Set_ISO9141KWP2000_Mode Return Value

ERR_INVALID_COMMAND
wrongly specified.
©2011—TMC/ATA
21.15. RP1210_Echo_Transmitted_Messages
The API can toggle the lower level interface to echo transmitted messages back to the client application.
See the section on Echo Mode. Note that “if and only if, Echo Mode is on” will a send message be read
back by the same application’s call to RP1210_ReadMessage. This support is required for all implementa-
tions of the RP1210 API.
When Echo Mode is turned on, the send and receive buffers allocated at RP1210_ClientConnect will be
cleared.
Turning Echo on introduces a new byte into each incoming message that will indicate to the client whether
the incoming message was the result of an echo or was an incoming message. This byte is only available
when echo is turned on so the client must remember that all incoming messages will have an extra byte.
nCommandNumber RP1210_Echo_Transmitted_Messages
fpchClientCommand fpchClientCommand[0] = ECHO_ON/ECHO_OFF
nMessageSize 1
21.15.1. RP1210_Echo_Transmitted_Messages Return Value

ERR_INVALID_COMMAND
21.16. RP1210_Set_All_Filters_States_to_Discard
The API can set all message filter states to discard through this configuration of the RP1210_SendCommand
function. By “setting all filter states to discard,” it is implied that the API will not allow any messages to go
through. This support is required for all implementations of the RP1210 API.
nCommandNumber RP1210_Set_All_Filters_States_to_Discard
nMessageSize 0
21.16.1. RP1210_Set_All_Filter_States_To_Discard Return Value

21.17. RP1210_Set_Message_Receive
This command is used to enable or disable reception of messages from the specified client. By default a
newly created connection has message receive turned on, but the filter state is set to “discard”, so the ap-
plication will not receive messages.
If the client is already receiving messages turning it on (again) has no effect. The client can stop receiving
messages by calling this function and turning reception off. If reception has already stopped then the call
©2011—TMC/ATA
will have no effect. When this command is issued and a change of state occurs (off to on, on to off) all mes-
sages not already claimed by the application will be lost.
nCommandNumber RP1210_Set_Message_Receive
fpchClientCommand fpchClientCommand[0] = RECEIVE_ON/RECEIVE_OFF
nMessageSize 1
21.17.1. RP1210_Set_Message_Receive Return Value

21.18. RP1210_Protect_J1939_Address
The API has the ability to claim/protect and handshake for TP sessions for at least 16 J1939 addresses
on the vehicle network. These claim attempts can originate from one or more client connections (see the
section Notes on J1939 Address Claim). When this command is issued, the API will attempt to claim the
address that the application has requested. If the address is successfully claimed, the API will continue to
protect the address and respond to address claim requests as per J1939/81.
If the API is forced to concede the address to another node on the network, the next call to RP1210_Re-
adMessage() or RP1210_SendMessage() function will return an error indicating that the address has been
lost. The API will also cease to handshake for RTS/CTS transport sessions to the lost address. After the
application has been notified of the lost address, the application should attempt to claim another address.
The application must perform an address claim before the API can send or receive RTS/CTS messages.
Once an address has been successfully claimed, the API may begin to handshake for J1939 RTS/CTS
sessions to the protected address if nIsAppPacketizingIncomingMsgs was set to 0 on RP1210_Client-
Connect(). The API shall not handshake for any TP messages that are not destined to an address that it is
not protecting. Upon the loss of a protected/claimed address, it is the duty of the API to abort current J1939
transport sessions, and perform necessary cleanup prior to the notification of the client application.
A VDA/API will not shake for any RTS/CTS TP sessions until an application specifically claims an address.
This was always implied before 2010, but with the changes to J1939 address claim, this is being explicitly
stated. It is not required that the application send this command. The default setting when a J1939 client
is connected is for Network Management (TP sessions) to be off. If this command is never called, the ap-
plication will be able to send and receive single CAN frame messages (8 bytes or less) to/from any address
on the J1939 vehicle network.
Even if the client application is protecting an address, the API will allow the application to send from any
address, determined by the source address passed to the RP1210_SendMessage() function.
There is no real J1939 method for releasing a claimed address. An address will no longer be “used” by the
VDA/API if the application using it disconnects or uses the RP1210_Release_J1939_Address, and no other
clients have protected that address and are using it.
21.18.1. Behavior When Connecting to a Network Without Other Controllers Transmitting

There are times when an application may connect to a VDA on the J1939 databus before other nodes are
active on that bus (i.e., prior to a "key on" event). If this is the case, the RP1210_SendCommand( Pro-
tect_J1939_Address ) documentation has been unclear what the API should return under that circumstance.
©2011—TMC/ATA
According to J1939-81, after transmitting your address claim message and you are not challenged for 250ms,
then your claim has been approved.
When an RP1210 API is asked to connect to a VDA through the J1939 databus, and no other nodes are on
that bus, the API shall return success to the RP1210_SendCommand( Protect_J1939_Address ) command.
If other nodes come online (i.e. a "key on" event) and claim the same address with a higher priority name,
then the API would return the value ERR_ADDRESS_LOST on the next call to SendMessage, ReadMes-
sage, or SendCommand. The VDA, as always, will respond with address and NAME when the address
request message is sent by other controllers.
nCommandNumber RP1210_Protect_J1939_Address
nClientID The client identifier for the client that wants to claim a J1939 address.
A pointer to the buffer (allocated by the client application), containing a J1939
fpchClientCommand
Address Claim Frame as described below.
nMessageSize 10
21.18.2. J1939 Address Claim Frame

The 8-bit address that the client wishes to attempt to claim
Byte 1 1 byte Address to Claim on the J1939 bus. This address is not limited to the service
tool addresses.
The next 8 bytes contain the 8-byte name of the client on the
network. This name must be in compliance with the J1939
Bytes 2-9 8 bytes Network Mgt Name
network management standard and is the responsibility of
the client application to assemble.
This byte contains the requested status byte for the protect
address command. The status request byte is set by the ap-
Byte 10 1 byte Status Byte plication and can set to the following values:
BLOCK_UNTIL_DONE 0
RETURN_BEFORE_COMPLETION 2
21.18.3. RP1210_ Protect_J1939_Address Return Value

Note: If the Status Byte is set to BLOCK_UNTIL_DONE, this command will not return until the driver has
completed the J1939 address claim procedure.
ERR_HARDWARE_NOT_RESPONDING The device is unavailable.
ERR_ADDRESS_CLAIM_FAILED The API was not able to claim the requested address.
The API was forced to concede the address to another node on
ERR_ADDRESS_LOST
the network.
The API was not able to transmit a CAN packet due to the CAN
ERR_BUS_OFF
hardware being in a BUS_OFF condition.
ERR_COULD_NOT_TX_ADDRESS_CLAIMED The API was not able to request an address.
©2011—TMC/ATA
21.19. RP1210_Release_J1939_Address
There is no real J1939 method for releasing a claimed/protected address in J1939. An address will no longer
be “used” by the VDA/API if the application using it disconnects or uses the RP1210_Release_J1939_Ad-
dress, and no other clients have protected that address and are using it. When this command is issued,
the API will stop using the claimed address, if and only if, no other clients are using it. This means that the
VDA/API will no longer handshake for RTS/CTS sessions.
When a protected address is released, it is the duty of the API to abort current outgoing or incoming J1939
transport sessions if another client is not using that address. If an outgoing J1939 transport session is
aborted by this command, then RP1210_SendMessage () will return an error code.
nCommandNumber RP1210_Release_J1939_Address
nClientID The client identifier for the client that wants to release a J1939 address.
A pointer to the buffer (allocated by the client application), containing a
fpchClientCommand
J1939 Address as described below.
nMessageSize 1
21.19.1. J1939 Address Release Frame

The 8-bit address that the client wishes to release on the
Byte 1 1 byte Address to Release J1939 bus. This address is limited to a previously claimed
address.
21.19.2. RP1210_ Release_J1939_Address Return Value

ERR_HARDWARE_NOT_RESPONDING The device is unavailable.
ERR_ADDRESS_RELEASE_FAILED The API was not able to release the requested address.
The API was not able to transmit a CAN packet due to the CAN hard-
ERR_BUS_OFF
ware being in a BUS_OFF condition.
21.20. RP1210_Set_Broadcast_For Protocol

TMC’s RP 1210 Update Task Force identified a need to have the API maintain a “broadcast” list of messages.
These messages would be broadcasted periodically based on the applications’ needs. Normally, the user
application maintains a broadcast list; however, having one in the API makes life for the application much
easier by not having to set timers to ensure that a “keep-alive” or recurring message is being transmitted
on-time.
The broadcast list will be treated like an abstracted programming array. There is a maximum of 16 entries
(per client) with entry indexes running from 0 to 15, and there are operations to:
• View an entry in the list of messages.
• Destroy the list entirely.
• Add to the list (append).
• Remove an entry from the list.
Each entry will be made up of:

• A message in the exact format that would be sent to RP1210_SendMessage.
• A timer entry in milliseconds for when the message needs to be broadcasted periodically.
©2011—TMC/ATA
NOTE: In J1708, PLC, ISO9141 or KWP2000, RAW_MODE or CONVERTED_MODE play a part in the
ability of the message to be a valid message on the databus. It is suggested that the user application build
the broadcast list for a specific mode, and not to change modes (which may result in an invalid message).
The API cannot guarantee that the message will be sent repeatedly within the requested time-frame. Therefore,
the application should give plenty of leeway in the value of the “time” parameter for a broadcast message.
See below for return values for all functions.
RP1210_Set_Broadcast_For_J1708
RP1210_Set_Broadcast_For_CAN
RP1210_Set_Broadcast_For_J1939
nCommandNumber RP1210_Set_Broadcast_For_J1850
RP1210_Set_Broadcast_For_ISO15765
RP1210_Set_Broadcast_For_ISO9141
RP1210_Set_Broadcast_For_KWP2000
The client identifier for the client that wants to issue the
nClientID
command.
fpchClientCommand A complete broadcast list entry as described below.
nMessageSize The number of bytes in fpchClientCommand.
21.20.1. Broadcast List Entry (fpchClientCommand)

Byte Function Description
The function to perform.
Mnemonic and Function
• ADD_LIST
- Add a message to the list.
• VIEW_B_LIST
- View an entry in the list.
Byte 1 Function to Perform
• DESTROY_LIST
- Remove all entries in the list.
• REMOVE_ENTRY
- Remove a specific entry from the list.
• LIST_LENGTH
- Returns number of items in list.
fpchClientCommand[2..n] = MESSAGE_TIME_TUPLE record(sent)
Bytes 2..n Byte 1 = ADD_LIST
fpchClientCommand[1] = Entry number where message added (returned)
0xff indicates failure in adding entry to list.
fpchClientCommand[2] = Number of list entry to view [0..15] (sent)
Byte 1 = fpchClientCommand[1] = Valid List Entry (0x00) or

Bytes 2..n
VIEW_B_LIST List Entry Does Not Exist (0x01) (returned)
fpchClientCommand[2..n] = MESSAGE_TIME_TUPLE record (returned)

fpchClientCommand[2] = Unused (sent)
Byte 1 =
Bytes 2..n
DESTROY_LIST
fpchClientCommand[1] = Number of entries deleted (returned)
fpchClientCommand[2] = Number of list entry to remove [0..15] (sent)
Bytes 2..n Byte 1 = REMOVE_ENTRY
fpchClientCommand[1] = Success (0x00) or Failure (0x01) (returned)
fpchClientCommand[2] = Unused (sent)
Bytes 2..n Byte 1 = LIST_LENGTH
fpchClientCommand[1] = Number of entries in list [0..15] (returned)
©2011—TMC/ATA
21.20.2. MESSAGE_TIME_TUPLE Record
Bytes Function
Time interval in milliseconds for this message to be broadcast (periodically, see notes).
Field is a 16-bit integer in Little Endian (LSB)/Intel format [0..65535].
Bytes 1, 2
NOTE: Anything below 5 milliseconds on a PC can get very difficult to maintain depending
on the device’s architecture. Also this has the potential to flood the bus at anything under
5 milliseconds for CAN and 10 milliseconds for J1850 or J1587.
Length of Message (16-bit integer in Little Endian (LSB)/Intel format). This would be the
Bytes 3, 4
value that was given to RP1210_SendMessage in the nMessageSize parameter.
An entire Message as would be presented to RP1210_SendMessage in the
Bytes 5..n
fpchClientCommand parameter.
21.20.3. List Behaviors

Mnemonic Behaviours of the List
ADD_LIST Adds an entry to the end of the list.
VIEW_B_LIST Views a specific entry in the list (returns a MESSAGE_TIME_TUPLE).
DESTROY_LIST Removes all entries from the list.
REMOVE_ENTRY Removes a specific entry from the list. Trailing list items are moved up in the list.
LIST_LENGTH Returns the number of items currently in the list.
21.20.4. Return Value, All Function Calls

Indicates that something was wrong with the command and/or param-
ERR_INVALID_COMMAND eters. Check the value returned in the fpchClientCommand buffer
based upon the “Function to Perform” parameter.
NOTE: There is no sanity checking of the values that are passed in, so if you tell J1587 to broadcast 100
times a second a 10 byte message, it’s not going to return an error that the bus’s capacity was exceeded.
21.21. RP1210_Set_BlockTimeout
Added to RP1210B was the ability to set a value to the amount of time that the user would like a command
issued with BLOCKING_IO to timeout. This particular function has already been implemented by several API
vendors. The first and second byte of the fpchClientCommand will be multiplied together to get a timeout
value (in milliseconds). For example, if the user wanted 200 milliseconds, they would send any combination
in the first to bytes to provide a value of 200. To set an infinite timeout, the user would transmit either byte
(multiplicand) as a zero. This block should fail if the user disconnects the client.
The command only applies to the current client and future calls to:
• RP1210_ReadMessage
nCommandNumber RP1210_Set_BlockTimeout
fpchClientCommand fpchClientCommand[0] = 8-bit unsigned value, 0 = infinite block
fpchClientCommand[1] = 8-bit unsigned value, 0 = infinite block
nMessageSize 2
©2011—TMC/ATA
21.21.1. RP1210_Set_BlockTimeout Return Value
ERR_INVALID_COMMAND Indicates that the command number or the parameters associated with it
21.22. RP1210_Set_J1708_Baud
Added to RP1210B was the ability to set the J1708 baud rate to a value other than 9600. This assists
and speeds the downloading of code, parameters and end-of-line data. This function has already been
implemented by several VDA vendors at the request of several OEM’s (with this nCommandNumber
value). The function was implemented in a way that the API can either change the baud rate immediately
(CHANGE_BAUD_NOW), or after the receipt of the next message to the ECU to be communicated with
before the change of rate (MSG_FIRST_CHANGE_BAUD).
This command will not be allowed if another client is already connected to the J1708 databus. The error
message ERR_MULTIPLE_CLIENTS_CONNECTED will be returned.
Note that this function is potentially disruptive to ECU’s on the databus that does not understand anything
other than 9600 baud. Use this function only in a controlled environment.
nCommandNumber RP1210_Set_J1708_Baud
fpchClientCommand fpchClientCommand[0] = CHANGE_BAUD_NOW/MSG_FIRST_CHANGE_BAUD
fpchClientCommand[1] = RP1210_BAUD_9600/RP1210_BAUD_19200/RP1210_BAUD_
38400/RP1210_BAUD_57600
nMessageSize 2
21.22.1. RP1210_Set_J1708_Baud Return Value

ERR_INVALID_COMMAND Indicates that the command number or the parameters associated with
it are wrongly specified or command is not supported.
ERR_J1708_BAUD_SET_NONSTANDARD Another application already has the baud rate set non-standard.
21.23. RP1210_Set_J1939_Baud
Added to RP1210B was the ability to set the J1939 baud rate to a value other than 250k. This assists and
speeds the downloading of code, parameters and end-of-line data. The function is implemented in a way that
the API can either change the baud rate immediately, or send a message to the ECU to be communicated
with before the change of rate.
This command will not be allowed if another client is already connected to the J1939 databus. The error
other than 250k baud. Use this function only in a controlled environment.
©2011—TMC/ATA
nCommandNumber RP1210_Set_J1939_Baud
fpchClientCommand[0] = CHANGE_BAUD_NOW/MSG_FIRST_CHANGE_BAUD
fpchClientCommand
fpchClientCommand[1] = RP1210_BAUD_125k/RP1210_BAUD_250k/RP1210_BAUD_
500k/RP1210_BAUD_1000k
nMessageSize 2
21.23.1. RP1210_Set_J1939_Baud Return Value

ERR_INVALID_COMMAND
are wrongly specified or command is not supported.
ERR_J1939_BAUD_SET_NONSTANDARD Another application already has the baud rate set non-standard.
21.24. RP1210_Set_CAN_Baud
New to RP1210C is the ability to set the CAN baud rate to a value other than 250k. This assists and speeds
the downloading of code, parameters and end-of-line data. The function is implemented in a way that the
API can either change the baud rate immediately, or send a message to the ECU to be communicated with
before the change of rate.
This command will not be allowed if another client is already connected to the CAN databus. The error mes-
sage ERR_MULTIPLE_CLIENTS_CONNECTED will be returned.
other than 250k baud. Use this function only in a controlled environment.
nCommandNumber RP1210_Set_CAN_Baud
fpchClientCommand[0] = CHANGE_BAUD_NOW/MSG_FIRST_CHANGE_BAU
D
fpchClientCommand
500k/RP1210_BAUD_1000k
nMessageSize 2
21.24.1. RP1210_Set_CAN_Baud Return Value

ERR_INVALID_COMMAND
wrongly specified or command is not supported.
ERR_CAN_BAUD_SET_NONSTANDARD Another application already has the baud rate set non-standard.
©2011—TMC/ATA
21.25. RP1210_Set_ISO15765_Baud
Added to RP1210B was the ability to set the ISO15765 baud rate to a value other than 250k standard through
RP1210_SendCommand. The ability to set the baud in the call RP1210_ClientConnect (format 1) exists,
but this method may be needed to communicate with ECU’s that need to have a message at the standard
250k baud that says “go to a higher/lower baud”, much the same as J1708, CAN, and J1939. The function
is implemented in a way that the API can either change the baud rate immediately, or send a message to
the ECU to be communicated with before the change of rate.
This command will not be allowed if another client is already connected to the ISO15765 databus. The error
Note that this function is potentially disruptive to ECU’s on the databus that do not understand anything other
than 250k baud. Use this function only in a controlled environment.
nCommandNumber RP1210_Set_ISO15765_Baud
fpchClientCommand fpchClientCommand[0] = CHANGE_BAUD_NOW/MSG_FIRST_CHANGE_BAUD
500k/RP1210_BAUD_1000k
nMessageSize 2
21.25.1. RP1210_Set_ISO15765_Baud Return Value

Indicates that the command number or the parameters associated
ERR_INVALID_COMMAND
with it are wrongly specified or command is not supported.
ERR_ISO15765_BAUD_SET_NONSTANDARD Another application already has the baud rate set non-standard.
21.26. RP1210_Set_ Protocol Filter_Type

Added to RP1210B was the ability to set filtering to inclusive or exclusive. RP1210A filtering is only “inclu-
sive”. Inclusive filtering forces the application to “ask” the API for each MID, PGN, or CANID that it wants to
see. However, with “FilterStates=AllFilterStatesToPass”, it forces the application to handle all filtering.
In RP1210B, a new filter mechanism called “exclusive” was added. This allowed the application to say, “I
want to see all messages, except from the engine, etc”.
• RP1210_SendCommand (RP1210_Set_J1708_Filter_Type, FILTER_INCLUSIVE/FILTER_EXCLUSIVE)
• RP1210_SendCommand (RP1210_Set_CAN_Filter_Type, FILTER_INCLUSIVE/FILTER_EXCLUSIVE)
• RP1210_SendCommand (RP1210_Set_ISO15765_Filter_Type, FILTER_INCLUSIVE/FILTER_EXCLUSIVE)
This variable is per client connection and is per protocol. This means that in a multi-protocol/multi-thread
environment, each client would have to issue this command. J1708 filtering also applies if connected to
a PLC network. Any filters that have previously been set for the given client connection would be cleared
after this call, requiring the client to re-establish new filters as needed.
See also the RP1210_SendCommand () calls for RP1210_Set_Message_Filtering_For_xxxx.
©2011—TMC/ATA
RP1210_Set_J1708_Filter_Type
nCommandNumber RP1210_Set_CAN_Filter_Type
RP1210_Set_ISO15765_Filter_Type
fpchClientCommand fpchClientCommand[0] = FILTER_INCLUSIVE/FILTER_EXCLUSIVE
nMessageSize 1
21.26.1. RP1210_Set_J1708/J1939/J1850/ISO15765/CAN_Filter_Type Return Value

ERR_INVALID_COMMAND
21.26.2. Example (RP1210A = Inclusive)
fpchClientCommand[0] = 128;
RP1210_SendCommand (RP1210_Set_Message_Filtering_For_J1708, nClientID, fpchClientCommand, 1);
This tells the API that it wants to see messages from MID 128 (Engine #1). If the application wanted to
see messages from Transmission #1, it would have to issue another call. The same call would need to be
issued for Tractor ABS, Trailer 1 ABS, etc.
21.26.3. Example (RP1210B/C = Exclusive)
fpchClientCommand[0] = FILTER_EXCLUSIVE;
RP1210_SendCommand (RP1210_Set_J1708_Filter_Type, nClientID, fpchClientCommand, 1);
fpchClientCommand[0] = 128;
RP1210_SendCommand (RP1210_Set_Message_Filtering_For_J1708, nClientID, fpchClientCommand, 1);
This tells the API that it wants to see everything except from MID 128 (Engine #1).
21.27. RP1210_Set_J1939_Interpacket_Time
Added to RP1210B was the ability to set the inter-packet time on J1939 Connection Management (RTS/CTS
and BAM) messages. Currently, the inter-packet times are standard J1939; however some applications
(mostly engineering applications) would like to speed up the inter-packet timing parameters for download-
ing of new code, configurations, etc. Zero is an acceptable value, meaning that the VDA will send packets
as quickly as it can process them.
nCommandNumber RP1210_Set_J1939_Interpacket_Time
fpchClientCommand[0,1,2,3] = Value in milliseconds for the CM facilities
(RTS/CTS;BAM) to set the inter-packet timing. This value is four bytes in
fpchClientCommand
length and is in Little Endian (LSB)/Intel format and is unsigned with no
offset value.
nMessageSize 4
©2011—TMC/ATA
21.27.1. RP1210_Set_J1939_Interpacket_Time Return Value
ERR_INVALID_COMMAND
it are wrongly specified or the command is not supported.
21.28. RP1210_Set_MaxErrorMsgSize
Added to RP1210B was the ability to set the maximum return buffer size for a call to RP1210_GetErrorMsg
and RP1210_GetLastErrorMsg. In RP1210A, the default and maximum size was 80. This command al-
lows the API to return a longer and possibly better explanation as to what happened and what the error
code meant. The default is still be 80; however the application can tell the API that it is capable of receiving
messages that are longer. Note that the application cannot ask for values lower than 80. This function call
is “per-client” connection and is not “session-wide”.
nCommandNumber RP1210_SetMaxErrorMsgSize
fpchClientCommand fpchClientCommand[0,1] = Value in bytes that the application has room for in a call
to RP1210_GetErrorMsg (81-65535). This value is in Little Endian (LSB) format
and is unsigned.
nMessageSize 2
21.28.1. RP1210_Set_MaxErrorMsgSize Return Value

Indicates that the command number or the parameters associated
ERR_INVALID_COMMAND
with it are wrongly specified or the command is not supported.
21.29. RP1210_Disallow_Further_Connections
Added to RP1210B was the ability to disallow another applications or clients from issuing a client connec-
tion through the vehicle adapter. This allows time-sensitive applications or applications that “must” be the
only application/client with a connection to the databus to operate unimpeded by other applications/clients.
This command can only be issued if there are no other applications using the specified databus. Once this
client connection terminates, other clients will be allowed to connect. This command would be common
in end-of-line programming stations. Note that any further client connect calls would come back with the
RP1210 error code:
ERR_MULTIPLE_CONNECTIONS_NOT_ALLOWED_NOW (455)
nCommandNumber RP1210_Disallow_Further_Connections
nMessageSize 0
©2011—TMC/ATA
21.29.1. RP1210_Disallow_Further_Connections Return Value
ERR_INVALID_COMMAND Indicates that the command number or the parameters associated with
ERR_MULTIPLE_CLIENTS_CONNECTED The API was not able to “disallow other connections” because another
application is using the VDA.
21.30. RP1210_Set_ISO15765_Flow_Control
Before long (segmented) messages can be communicated using the ISO15765-2 protocol, this command
must be called to indicate the parameters used during flow control communication to one or more devices.
For each device, the parameters indicate an association between an incoming (device) CAN-ID (with op-
tional extended address) and an outgoing (tester) CAN-ID (with optional extended address), the values that
are transmitted for BS (block size) and STmin (separation time min.), and the separation time used when
transmitting segmented messages to the vehicle (as an override for the requested value from the vehicle).
When receiving long messages, the outgoing CAN-ID (and optional extended address) is used for the FC
(flow control) message that is sent when the interface is receiving a segmented message from the incoming
CAN-ID. When transmitting long messages, FC messages received on the incoming CAN-ID (and optional
extended address) are matched to the transmission via the outgoing CAN-ID.
For messages to be communicated, the application must also configure the filtering such that messages
from the incoming CAN-ID will be accepted.
Single Frame (short) messages – such as broadcast messages - can be sent to or received from a device
without recourse to the RP1210_Set_ISO15765_Flow_Control command. Successive calls to this RP1210_
SendCommand function would augment, rather than replace the list of flow control associations.
nCommandNumber RP1210_Set_ISO15765_Flow_Control
fpchClientCommand A byte array specifying the flow control response parameters.
nMessageSize The number of bytes in fpchClientCommand. Should be a multiple of 15.
©2011—TMC/ATA
21.30.1. ISO15765 Flow Control Parameter Frame
STANDARD_CAN = 11-bit identifier
STANDARD_MIXED_CAN_ISO15765 = 11-bit identifier with mixed
CAN / extended addressing
Byte 1 1 byte
address Type STANDARD_CAN_ISO15765_EXTENDED = 11-bit identifier with
ISO15765 extended address
EXTENDED_CAN_ISO15765_EXTENDED = 29-bit identifier with
ISO15765 extended address
The Incoming CAN ID indicates the CAN-ID that a flow control response
is triggered by (during long message receive) or received on (during long
Incoming (device) message transmit). To stay generic here, four bytes are used for both
Bytes 2-5 4 bytes
CANID incoming and outgoing ID regardless of whether Standard or Extended
CAN is used. In the case of Standard CAN, only the low (last) two bytes
in both incoming and outgoing ID would be used.
If the CAN / extended address type is set to STANDARD_CAN_
ISO15765_EXTENDED or EXTENDED_CAN_ISO15765_EXTENDED or
Incoming (device)
Byte 6 1 byte STANDARD_MIXED_CAN_ISO15765, this byte specifies the extended
extended address
address byte or ISO15765 network address extension that is associated
with the incoming CAN ID. Otherwise, this byte is ignored.
The Outgoing CAN ID indicates the CAN ID (and, optionally, extended
Outgoing (tester)
Byte 7-10 4 bytes address byte) used in the outgoing flow control message (during long mes-
CANID
sage receive) or outgoing packets (during long message transmit).
If the CAN / extended address type is set to STANDARD_CAN_ISO15765_
EXTENDED or EXTENDED_CAN_ISO15765_EXTENDED, this byte
Outgoing (tester)
Byte 11 1 byte specifies the extended address byte or ISO15765 network address
extended address
extension that is associated with the outgoing CAN ID. Otherwise, this
byte is zero.
The block size reported to the ECU in the outgoing flow control message
Byte 12 1 byte BS
when receiving segmented transfers. (see ISO15765-2)
The separation time reported to the ECU in the outgoing flow control
Byte 13 1 byte STmin
message when receiving segmented transfers. (see ISO15765-2)
This sets the separation time the interface should use to transmit seg-
mented messages to the vehicle. The interface adapter will use the
Byte 14-15 2 byte STMIN_TX greater value of that specified by this parameter and that specified by
ECU for transmit flow control. If value is 0xFFFF, use the value reported
by the vehicle.
21.30.2. RP1210_Set_ISO15765_Flow_Control Return Value

ERR_INVALID_COMMAND
wrongly specified or the command is not supported.
21.31. RP1210_Clear_ISO15765_Flow_Control
This command causes the list of flow control associations previously defined by calls to the RP1210_Set_
ISO15765_Flow_Control command to be cleared. If this command is executed while a long (segmented)
message is being communicated, the command will take effect once that communication is complete.
After this command is executed, long messages cannot be sent to or received from any device, until
RP1210_Set_ISO15765_Flow_Control is called again.
©2011—TMC/ATA
nCommandNumber RP1210_Clear_ISO15765_Flow_Control
nMessageSize 0
21.31.1. RP1210_Clear_ISO15765_Flow_Control Return Value

Indicates that the command number or the parameters as-
ERR_INVALID_COMMAND sociated with it are wrongly specified or the command is not
supported.
21.32. RP1210_Flush_Tx_Rx_Buffers
New to RP 1210C, this command causes the VDA to clear all transmit and receive buffers for the specific
client. There may be times in an application where it needs to clean all of the messages out of the buffers
before starting the message pumps again. This applies to any and all buffers/queues in the VDA hardware
or API.
nCommandNumber RP1210_Flush_Tx_Rx_Buffers
nMessageSize 0
21.32.1. RP1210_Flush_Tx_Rx_Buffers Return Value

ERR_INVALID_COMMAND
21.33. RP1210_Get_Protocol_Connection_Speed
Since a CAN-based link can be running at any speed and RP1210 protocol adapters can automatically
detect the correct speed for various protocols, application developers may want to know what speed they
actually connected at. In order to make the automatic speed detection as generic as possible, this command
will apply to any protocol supported by a vendor. For example, even if connecting to the “generic J1708”
protocol, this function would return “9600”.
This support is required for all implementations of the RP1210 API, regardless of whether they support
automatic baud rate detection.
©2011—TMC/ATA
nCommandNumber RP1210_Get_Protocol_Connection_Speed(45)
fpchClientCommand Pointer to a character buffer that is 17 bytes long.
nMessageSize 17
21.33.1. RP1210_Get_Protocol_Connection_Speed Return Value

The value returned, if the function is successful will be a maximum 16-byte string with a null terminator in the
fpchClientCommand variable. As an example, if you are calling this command while using 1939 connected
at 500k, this function would returned “500000”. If calling this function using “generic J1708”, this function
would return “9600”. If calling this function with CAN at 1MB, the function would return “1000000”.
ERR_INVALID_COMMAND
21.34. RP1210_Get_Wireless_State
Since an application might need to know if it is connected wirelessly before entering into a critical section
of code, this command has been added to RP 1210C. Some applications may want to know that they are
connected wirelessly and issue a directive to the user to connect via a wired connection.
This support is required for all implementations of the RP1210 API.
nCommandNumber RP1210_Get_Wireless_State(48)
fpchClientCommand NULL pointer
nMessageSize 0
21.34.1. RP1210_Get_Wireless_State Return Value

The value returned will be one of the following mnemonics.
CONNECTED_WIRELESS (0x01) The client is connected in a wireless mode.
CONNECTED_WIRED (0x00) The client is not connected in a wireless mode.
ERR_COMMAND_NOT_SUPPORTED This command is not supported for this VDA.
©2011—TMC/ATA
22. RP1210_Ioctl
New to RP 1210C, this function is called by the client application seeking to read and/or write hardware
and software configuration and status parameters. If the function is successful, the return value is 0. See
RP1210_Ioctl Return Values table for possible return values for this function. The structures pointed to by
pInput and pOutput are determined by the IoctlID passed into the function. See Ioctl Section for details
on Ioctl structures.
22.1. RP1210_Ioctl Prototype

C/C++ short __declspec (dll export) WINAPI RP1210_Ioctl
(
short nClientID,
long nIoctlID,
void *pInput,
void *pOutput
);
22.2. RP1210_ Ioctl Parameters

nClientID The client identifier assigned by RP1210_ClientConnect function.
nIoctlID ID of requested Ioctl operation (see Ioctl Section)
pInput Pointer to input Ioctl structure (see Ioctl Section)
pOutput Pointer to output Ioctl structure (see Ioctl Section)
22.3. RP1210_ Ioctl Return Values

ERR_DLL_NOT_INITIALIZED The API DLL was not initialised.
ERR_HARDWARE_NOT_RESPONDING The device hardware interface through which the message is routed is
not responding.
ERR_INVALID_CLIENT_ID The identifier for the client that is being sought is invalid.
ERR_INVALID_IOCTL_ID The identifier for the requested Ioctl operation is invalid.
ERR_NULL_PARAMETER NULL pointer supplied where a valid pointer is required.
ERR_COMMAND_NOT_SUPPORTED Invalid or unsupported parameter or operation.
ERR_HARDWARE_NOT_SUPPORTED The API will return this value if hardware is not supported for that com-
mand.
22.4. Ioctl ID Values

Definition Value
GET_CONFIG 0x01
SET_CONFIG 0x02
FIVE_BAUD_INIT 0x04
FAST_INIT 0x05
ISO9141_K_LINE_ONLY 0x06
Reserved for TMC 0x03, 0x07-0xFFFF
Vendor Specific 0x10000-0xFFFFFFFF
©2011—TMC/ATA
22.5. Ioctl Section
This section provides details on the IOCTLs available through RP1210_Ioctl function:
IoctlID Value pInput represents pOutput represents Description
GET_CONFIG Pointer to SCONFIG_LIST NULL pointer To get the vehicle
network configuration
of the VDA
SET_CONFIG Pointer to SCONFIG_LIST NULL pointer To set the vehicle
network configuration
of the VDA
FIVE_BAUD_INIT Pointer to SBYTE_ARRAY Pointer to SBYTE_ARRAY To direct the VDA to
perform a 5 baud ini-
tialization sequence
(ISO9141/KWP2000)
FAST_INIT NULL or Pointer to SBYTE_ NULL or Pointer to To direct the VDA to
ARRAY SBYTE_ARRAY perform a fast ini-
tialization sequence
(KWP2000)
ISO9141_K_LINE_ONLY Pointer to ISO9141 Flag NULL Configure K and L lines
for ISO9141/KWP2000
22.5.1. GET_CONFIG
The IoctlID value of GET_CONFIG is used to obtain the vehicle network configuration of the VDA. The
calling application is responsible for allocating and initializing the associated parameters described in Sec-
tion 22.2. When the function is successfully completed, the corresponding parameter value(s) indicated in
Section 22.4 will be placed in each Value field.
nClientID Client ID assigned during RP1210_ClientConnect
nIoctlID Is set to the define GET_CONFIG
pInput Points to structure SCONFIG_LIST, which is defined as follows:
typedef struct
{
unsigned long NumOfParams; /*number of SCONFIG elements*/
SCONFIG *pConfig; /*array of SCONFIG elements*/
}SCONFIG_LIST;
Where:
NumOfParams is an INPUT, which contains the number of SCONFIG elements in the

array pointed to by pConfig.
pConfig is a pointer to an array of SCONFIG structures.
The structure SCONFIG is defined as follows:
typedef struct
{
unsigned long Parameter; /*name of parameter*/
unsigned long Value; /*value of the parameter*/
}SCONFIG;
Where:
Parameter is an INPUT that represents the parameter to be obtained (see Sec-

tion 22.2 for a list of valid Parameters).
Value is an OUTPUT that represents the value of Parameter (see Section 22.4
for a list of valid Values).
pOutput NULL pointer, parameter is not used.
©2011—TMC/ATA
22.5.2. SET_CONFIG
The IoctlID value of SET_CONFIG is used to set the vehicle network configuration of the VDA. The calling
application is responsible for allocating and initializing the associated parameters described below. When
the function is successfully completed, the corresponding parameter(s) and value(s) indicated will be placed
in effect.
nIoctlID Is set to the define SET_CONFIG
pInput Points to structure SCONFIG_LIST, which is defined as follows:
typedef struct
{
}SCONFIG_LIST;
Where:
NumOfParams is an INPUT, which contains the number of SCONFIG elements in

the array pointed to by pConfig.
pConfig is a pointer to an array of SCONFIG structures.
The structure SCONFIG is defined as follows:
typedef struct
{
}SCONFIG;
where:
Parameter is an INPUT that represents the parameter to be set (see Section
22.2 for a list of valid Parameters).
Value is an INPUT that represents the value of Parameter (see Section 22.4
for a list of valid Values).
pOutput NULL pointer, parameter is not used.
Parameter ID Value Valid Parameter Values Default Value Description

P1_MAX 0x07 0x01-0xFFFF 40 For ISO9141KWP2000 protocols,
(.5mS per bit) (20mS) this sets the maximum inter-byte
time for ECU responses
P3_MIN 0x0A 0x00-0xFFFF 110 For ISO9141/KWP2000 protocols,
(.5mS per bit) (55mS) this sets the minimum time be-
tween end of ECU response and
start of new tester request
P4_MIN 0x0C 0x00-0xFFFF 10 For ISO9141/KWP2000 protocols,
(.5mS per bit) (5mS) this sets the minimum inter-byte
time for a tester request
W0 0x19 0x00-0xFFFF 300 For ISO9141 protocol, this sets
(1mS per bit) the minimum bus idle time before
the tester starts to transmit the
address byte
W1 0x0E 0x00-0xFFFF 300 For ISO9141/KWP2000 protocols,
(1mS per bit) this sets the maximum time from
the end of the address byte to
the start of the synchronization
pattern
©2011—TMC/ATA
W2 0x0F 0x00-0xFFFF 20 For ISO9141/KWP2000 protocols,
(1mS per bit) this sets the maximum time from
the end o fthe synchronization
pattern to the start of key byte 1
W3 0x10 0x00-0xFFFF 20 For ISO9141/KWP2000 protocols,
(1mS per bit) this sets the maximum time be-
tween key byte 1 and key byte 2
(1mS per bit) this sets the minimum time be-
tween key byte 2 and its inver-
sion from the tester
(1mS per bit) this sets the minimum idle bus
time before the tester starts to
transmit the address byte
TIDLE 0x13 0x00-0xFFFF 300 For KWP2000 protocol, this sets
(1mS per bit) the minimum amount of bus idle
time that is needed before a fast
initialization sequence will begin
TINIL 0x14 0x00-0xFFFF 25 For KWP2000 protocols, this sets
(1mS per bit) the duration for the low pulse in
fast initialization
TWUP 0x15 0x00-0xFFFF 50 For KWP2000 protocols, this sets
(1mS per bit) the duration of the wake-up pulse
in fast initialization
PARITY 0x16 0(NO_PARITY) 0 For ISO9141/KWP2000 protocols only
1(ODD_PARITY)
2(EVEN_PARITY)
DATA_BITS 0x20 0(8 data bits) 0 For ISO9141/KWP2000 protocols only
1(7 data bits)
FIVE_BAUD_MOD 0x21 0 – Initialization 0 For ISO9141/KWP2000 protocols
as defined in ISO only.
9141-2 and ISO
14230-4 Initialization for ISO 9141-2 and
ISO 14230-4 include the initial-
1 – ISO 9141 ization sequence as defined in ISO
initialization 9141 plus inverted key byte #2
followed by sent from the tester to the ECU
interface sending and inverted address sent from
inverted Key Byte 2 the ECU to the tester.
2 – ISO 9141 This parameter allows either ISO

initialization 9141 initialization sequence,
followed by ECU ISO 9141-2/ISO 14230 initializa-
sending inverted tion sequence, or hybrid versions
address which include only one of the
extra bytes defined for ISO 9141-2
3 – Initialization and ISO 14230.
as defined in ISO
9141
Reserved 0x00-0xFFFF Reserved for TMC (where not al-
ready defined in this document)
Reserved 0x10000- Vendor Specific Vendor Specific
0xFFFFFFFF
22.5.3. FIVE_BAUD_INIT
The IoctlID value of FIVE_BAUD_INIT is used to initiate a five-baud initialization sequence from the VDA.
The ISO 9141 five baud initialization sequence includes the five baud address sent from the tester to the
ECU, followed by the synchronization byte and two key bytes sent from the ECU to the tester. The ISO
9141-2 and KWP2000 (ISO 14230) five baud initialization includes the ISO 9141 initialization sequence, but
adds the inverted key byte 2 value sent from the tester to the ECU, and the inverted initialization address
sent from the ECU to the tester. The FIVE_BAUD_MOD parameter in SET_CONFIG IoctlID allows the
©2011—TMC/ATA
application to selectively include or exclude the two additional bytes defined in the ISO 14230 initialization
sequence.
The calling application is responsible for allocating and initializing the associated parameters described
below. When the function is successfully completed, the key words will be placed in structure pointed to by
pOutput. This support only applies to ISO9141/KWP2000 protocols.
nIoctlID Is set to the define FIVE_BAUD_INIT
pInput Points to instance of structure SBYTE_ARRAY, which is defined as follows:
typedef struct
{
unsigned long NumOfBytes; /*number of bytes in the array*/
unsigned char *pBytes; /*array of bytes*/
}SBYTE_ARRAY;
Where:
NumOfBytes is an INPUT that must be set to 1, indicating the number of bytes

in the array pBytes.
pBytes[0] is an INPUT that contains the target address.

Any remaining elements in pBytes are not used
pOutput Points to instance of structure SBYTE_ARRAY defined above, where
NumOfBytes is an INPUT which indicates the maximum size of the array pBytes
and an OUTPUT which indicates the number of returned bytes in the array
pBytes, must be 2 or less.
pBytes[0] is an OUTPUT that contains Key Word 1 from the ECU

pBytes[1] is an OUTPUT that contains Key Word 2 from the ECU
Any remaining elements in pBytes are not used
22.5.4. FAST_INIT
The IoctlID value of FAST_INIT is used to initiate a fast initialization sequence from the VDA. The calling
application is responsible for allocating and initializing the associated parameters described below. When
the function is successfully completed, the response message will be placed in the structure pointed to by
pOutput. This support only applies to KWP2000 protocol. Only in the case of successful initialization will
pOutput contain valid data.
nIoctlID Is set to the define FAST_INIT
pInput Points to instance of structure SBYTE_ARRAY, which is defined as follows:
typedef struct
{
}SBYTE_ARRAY;
where:
NumOfBytes is an INPUT indicating the number of bytes in the array pBytes.
pBytes contains the message to be sent, in RP1210B format for RP1210_SendMessage.
This can be a Start Communication Request Message as defined by ISO 14230, or any
other ISO 9141 or ISO 14230 message specified by the application. If NULL, then
no message is transmitted on the bus as part of the fast init sequence
©2011—TMC/ATA
pOutput Points to instance of structure SBYTE_ARRAY defined above,
Where:
NumOfBytes is an INPUT which indicates the maximum size of the array pBytes and
an OUTPUT which indicates the number of returned bytes in the array pBytes.
pBytes contains the response to the Start Communication Request Message. If a

response is not received in the time allowed by ISO 14230 then the Fast Initial-
ization is deemed to have failed, and the contents of pBytes will be indetermi-
nate. If NULL, then no response is expected
Two examples of ISO 9141 bus connection are provided in Sections 22.5.4.1 and 22.5.4.2. The first example
is for the simplest case, “ISO9141” client connection with default baud rate (10.4k) and bus configuration
parameters, and no five baud init required. The second example is for “KWP2000” connection with multiple
user-defined configuration parameters and fast init specified.
22.5.4.1 ISO9141 Connection – Default Configuration

For both ISO9141 and KWP2000, on first client connect the baud rate is automatically set for 10.4k, with
all configuration parameters set to defaults as indicated in this document. For case of ISO 9141 connec-
tion with no requirement for Five Baud Init sequence and no need for modification of default configuration
parameters, normal communications can proceed immediately after RP1210_ClientConnect, e.g.:
nClientID = pRP1210_ClientConnect(
NULL_WINDOW,
n9141Device,
"ISO9141",
0,
0,
0);
22.5.4.2. KWP2000 Connection – User Specified Configuration

This example indicates client initialization sequence for setting up KWP2000 connection using Fast Init, and
specifying modified values for five of the supported bus configuration parameters:
//IOCTL IDs
#define SET_CONFIG 0x02
#define FAST_INIT 0x05
//IOCTL Parameter IDs

#define P3_MIN 0x0A
#define P4_MIN 0x0C
#define TIDLE 0x13
#define TINIL 0x14
#define TWUP 0x15
//See SET_CONFIG section for definitions of SCONFIG and SCONFIG_LIST structures

SCONFIG KwConfigs[5];
SCONFIG_LIST KwConfigList;
//Set up KWP2000 configuration parameters for RP1210_Ioctl call

KwConfigs[0].Parameter = P3_MIN;
KwConfigs[0].Value = 80; //40mS (.5mS per bit)
KwConfigs[1].Paramter = P4_MIN;
KwConfigs[1].Value = 6; //3mS (.5mS per bit)
KwConfigs[2].Parameter = TIDLE;
KwConfigs[2].Value = 500; //500mS (1mS per bit)
KwConfigs[3].Parameter = TINIL;
KwConfigs[4].Parameter = TWUP;
KwConfigList.NumOfParams = sizeof(KwConfigs) / sizeof(SCONFIG);
KwConfigList.pConfig = KwConfigs;
//Define a FAST_INIT transmit message in RP1210B format

//See FAST_INIT section for definitions of SBYTE_ARRAY sructure
//
©2011—TMC/ATA
//NOTE: RP1210B format for ISO9141/KWP2000 messages pending at this time, sample
// indicated has following format:
// [# of Header Bytes] [Header (3)] [Data (1)]
unsigned char fastInitTx[] = {0x03, 0x81, 0x13, 0xf0, 0x81};

unsigned char fastInitRx[16] = {0};
SBYTE_ARRAY fastInitRequest;
SBYTE_ARRAY fastInitResponse;
//Set up FAST_INIT request/response structures

fastInitRequest.NumOfBytes = sizeof(fastInitTx);
fastInit.pBytes = fastInitTx;
fastInitResponse.NumOfBytes = sizeof(fastInitRx);
fastInitResponse.pBytes = fastInitRx;
//KWP2000 client connect defaults to 10.4K with default configurations specified // in RP1210B
nClientID = pRP1210_ClientConnect(
NULL_WINDOW
nKWP2000Device,
"KWP2000",
0,
0,
0);
//Client updating configuration parameters

nRetVal = pRP1210_Ioctl(
nClientID,
SET_CONFIG,
&KwConfigList,
NULL); //pOutput not used for SET_CONFIG
//Client specifying ISO Fast Init

nRetVal = pRP1210_Ioctl(
nClientID,
FAST_INIT,
&fastInitRequest,
&fastInitResponse); //Will be populated with response message if appli-
cable
if(nRetVal == 0)
{
if(fastInitResponse.NumOfBytes > 0)
{
//Process FAST_INIT response message...
}
}
22.6. ISO9141_K_LINE_ONLY
The IoctlID value of ISO9141_K_LINE_ONLY is used to define the physical layer of the ISO9141/KWP2000
link for the VDA. Some VDA’s do not have support for ISO-9141 or L line if the application tries to configure
the VDA for a unsupported feature the return value will be ERR_HARDWARE_NOT_SUPPORTED.
nIoctlID Is set to ISO9141_K_LINE_ONLY
pInput Pointer to SBYTE_ARRAY
SBYTE_ARRAY consists of one byte with the following definition:
0x00 = TX/RX on K line only
0x01 = TX/RX on L line only
0x02 = TX on K and L line, RX on K line only
pOutput NULL
©2011—TMC/ATA
22.6.1 RP1210_ Ioctl Return Values
ERR_DLL_NOT_INITIALIZED The API DLL was not initialised.
ERR_HARDWARE_NOT_RESPONDING The device hardware interface through which the message is routed is not
responding.
ERR_INVALID_CLIENT_ID The identifier for the client that is being sought is invalid.
ERR_INVALID_IOCTL_ID The identifier for the requested Ioctl operation is invalid.
ERR_NULL_PARAMETER NULL pointer supplied where a valid pointer is required.
ERR_COMMAND_NOT_SUPPORTED Invalid or unsupported parameter or operation.
ERR_HARDWARE_NOT_SUPPORTED The API will return this value if hardware is not supported for that com-
mand.
23. INI File Format
23.1. Case Sensitivity

Variables and strings in the main and vendor INI files are not case sensitive. Therefore, the word
“Auto” is equivalent to “auto” or “AUTO”. If there is a chance a variable may be presented to a user,
i.e., [VendorInformation].Name, the VDA vendor should user proper capitalization and grammar (i.e.,
McLovin instead of MCLOVIN).
23.2. INI File Text Encoding

INI files are in ASCII format with DOS CR/LF characters indicating the end of line.
23.3. The File Format and Parsing of the RP1210 INI Files
The following is how the RP1210 INI structure works:
Mas ter/P rimary INI F ile

P ointers to Vendor INI F iles
R P 121032.INI
[RP1210_Support]
APIImplementations=AAARP32, BBBRP32
AAAR P 32.INI B B B R P 32.INI
[VendorInformation]
Vendor INI F ile(s ) [VendorInformation]
Name=AAA Systems Name=BBB Programming
... ...
Vendor DLL F ile(s )

AAAR P 32.DLL B B B R P 32.DLL

Note that there is a “primary” or “master” INI file. This file is called RP121032.INI. The section [RP1210_Sup-
port] and the INI variable “APIImplementations” points to all installed RP1210 API’s on the PC. Note that
the DLL name is the same as the INI file name (except the extension).
©2011—TMC/ATA
The format of the RP121032.INI file is as follows:
[RP1210Support]
APIImplementations=[string1],[string2],...,[stringn]
Each stringi identifies the name of the INI-DLL tuple associated with the vendor’s API
An example of the RP121032.INI file would, then, look like:

[RP1210Support]
APIImplementations=AAARP32,BBBRP32,CCCRP32
NOTE: In the Windows 3.1 environment, the file RP1210.INI existed with the same format as the RP121032.
INI file. This file can safely be ignored except on legacy VDA’s supporting Windows 3.1 under RP1210A or
the original RP 1210.
23.4. Mangled RP121032.INI — Detecting and Correcting

In 2007, it was reported to TMC by several VDA vendors that they have been spending a lot of time doing
technical support because VDA vendors were leaving multiple commas or spaces in the RP121032.INI file
during an install or uninstall. These spaces or commas have caused OEM application developer’s issues
by not seeing all VDA entries in the file. Accordingly, when an end-user installed an adapter (“any adapter”)
and was not allowed to select it, that adapter manufacturer received a tech support call even though it was
not their problem. Also, there are some problems that exist when installing drivers to an INI file that has
more than one APIImplementations line in it (even though it is commented out).
VDA vendors shall ensure that when their drivers are installed or uninstalled, that there are no stray com-
mas or spaces remaining in the RP121032.INI file and they should ensure that the INI file is not “mangled”
in any way. If spaces are stray commas are seen, the VDA installation application (on a successful install)
will fix them, not leave them there for someone else’s tech support department to find.
Application developers should ensure that when they parse the RP121032.INI file that they completely parse
the entire line and not just the first x number of entries. Also the application developer should be aware that
multiple commas and potentially spaces could be left in the file. Please ensure that your application can
handle the following example:
================================================================
[RP1210Support]
APIImplementations=xxxxxx32,yyyyyy32,, ,zzzzzz32, ,aaaaaa32
; ;;APIImplementations=xxxxxx32,yyyyyy32,, ,zzzzzz32, ,aaaaaa32
================================================================
23.5. API Installation Program Instructions and Notes

The installation program for each vendor-provided INI/DLL tuple would go through the following steps (tak-
ing AAARP32 as an example):
23.5.1. Step 1. Check for RP121032.INI File, Create if Non-Existent

The first step in setting up the RP121032.INI file for your application is to check and see if the RP121032.
INI file exists in the directory where the Windows™ operating system is installed. The Windows directory
can be obtained via the Windows API call GetSystemWindowsDirectory().
If it does not exist, create the file (“RP121032.INI”), and write it as:
[RP1210Support]
APIImplementations=AAARP32
©2011—TMC/ATA
23.5.2. Step 2. Append Your Entry to APIImplementations
If the file does exist, retrieve the string for the key APIImplementations using the GetPrivateProfileString()
function. Scan the returned string to check if it contains “AAARP32”. If it does not, then append the string
“,AAARP32” to the end of the string that was returned and overwrite the APIImplementations key value
with the newly appended string. Proceed to the next section on the Vendor INI file.
23.5.3. Step 3. Clean Up the INI File

If the file does exist, the uninstall or install will detect any errors (commas, spaces) and correct them (see
above).
23.5.4. Notes:
• Never, at any time, is it acceptable for the installation program to overwrite an existing RP121032.
INI file. This has happened, and has plagued RP1210 application developers, VDA vendors, and
end-users.
• If you are adding your INI/DLL tuple to the APIImplementations variable, it shall be entered at the
end of the string. Some INI/DLL tuples have proven only to work at the beginning or at the end of the
string. The INI/DLL installation program as well as the PC applications should be intelligent enough
to work with the tuple name anywhere in the string.
• Since the RP121032.INI file is one that may, possibly, be written by a number of vendors, it is impor-
tant that extreme care be taken in the modification of this file by any installation program. An incor-
rect modification introduced by one installation program could jeopardize the function of the API DLL
implementation of another.
• There should be no leading spaces between a “=” and an entry. For example:
- “ProtocolDescription = J1708” is incorrect.
- “ProtocolDescription=J1708” is correct.
23.5.5. Using and/or Creating the Vendor INI File

Each vendor providing an API DLL implementation of the RP1210 API shall also provide an associated INI
file. This file would contain information on the hardware devices and protocols supported by the vendor and
would be updated every time the vendor’s implementation of the RP1210 API is changed to accommodate a
new device or protocol. Application programs will parse a vendor-provided INI file for the required connection
parameters. This file may also (optionally) contain information to contact the vendor. The file resides in the
same directory as the RP121032.INI file. The file format is described in Section 23.6.
23.6. The [VendorInformation] Section of the Vendor INI File

Table entries in light blue/light green shading are optional.
[VendorInformation] Indicates the start of the VendorInformation section. Field must

not be empty.
Name=[string] Name of vendor, and VDA being supported. Field must not be empty.
Address1=[string] First line of vendor mailing address. Field must not be empty.
Address2=[string] Second line of vendor mailing address. Field must not be empty.
City=[string] City of vendor mailing address. Field must not be empty.
State=[string] State of vendor mailing address. Field must not be empty.
Country=[string] Country of vendor mailing address. Field must not be empty.
Postal=[string] Postal or zipcode of vendor mailing address. Field must not be empty.
Telephone=[string] Telephone number to reach support. Field must not be empty.
Fax=[string] Fax number of vendor. Field can be empty.
VendorURL=[string] HTML link to vendor web site. Field can be empty.
MessageString=[string] Unique message string for the vendor DLL. Field can be empty.
ErrorString=[string] Unique error string for the vendor DLL. Field can be empty.
©2011—TMC/ATA
TimestampWeight=[number] Weight, per bit, in microseconds of the timestamp. Field must not
be empty.
AutoDetectCapable=[yes/no] If API were capable of validating that the devices in this INI
file are physically attached to the computer, the string would be
“yes”. Most APIs are capable of this feature. Field must not be
empty.
Version=[string] Where string reports the API version installed. This is in any
format that the VDA vendor wants (i.e. Major.Minor.Subrelease-
Build). This does not mark the version of RP1210 supported. Not
being able to “mark” or “version” an INI file has resulted in in-
compatibility problems. Field must not be empty.
RP1210=[string] Where string denotes the latest version of RP1210 supported
[0,A,B]. If this parameter is present, the developer can assume
at least RP1210B is supported. Field must not be empty.
DebugLevel=[number] This is an optional feature for a DLL provider. If the DLL does
not have the capability of initializing in debugging mode, then
DebugLevel=-1 would be stated. This allows the API to be ini-
tialised in debugging/logging mode without having to re-compile
and re-link source code for an application. This is very useful
when an application seems to be misbehaving. The values to be
logged depend on the #:
-1 = Debugging is not supported by this API.
0 = No debugging to be accomplished.
1 = Only Connect/Disconnect/Error Messages
2 = Add RP1210_SendCommand calls
3 = Add all Sent Messages (with filtering)
4 = Add all Received Messages (with filtering)
See the RP1210 section on Debug File Format.
This field must not be empty.
DebugFile=[string] When DebugLevel is greater than zero, the API will write debug-
ging/log information to the file mentioned in this variable. The
absolute path (disk/directory) for this file will be included in
this variable. The file name should be unique as not to overwrite
the log file of anyone else. Field can be empty if DebugLevel is
set to -1.
DebugMode=[number] When DebugLevel is greater than zero, this variable describes how
the DebugFile is to be written to:
0 = Overwrite (completely destroying previous contents)
1 = Append (write to the end of the file, keeping any previous con-
tents)
Field can be empty if DebugLevel is set to -1.
DebugFileSize=[X] Maximum size in kilobytes that the debug file should be. The de-
fault shall be 1024 (1 megabyte) if this variable is not defined.
Field can be empty if DebugLevel is set to -1.
NumberOfRTSCTSSessions=[X] An integer representing the number of concurrent RTS/CTS transport
sessions that the API supports per client. This is above and be-
yond the 1 BAM, 1 RTS/CTS that J1939 calls for. The default will
be the J1939 default of 1. Field must not be empty.
CANFormatsSupport- This adapter allows the user to connect to the CAN data bus using
ed=[1],[2],[3],[4],[5] the connection formats as defined in RP1210_ClientConnect. Field
must not be empty.
J1939FormatsSup- This adapter allows the user to connect to the J1939 data bus us-
ported=[1],[2],[3],[4],[5] ing the connection formats as defined in RP1210_ClientConnect.
Field must not be empty.
J1939Addresses=[X] How many J1939 addresses does the API support. This indicates
that an API can claim, maintain, and handshake for X (integer)
number of RTS/CTS TP sessions. If this variable does not exist,
an application should assume the API can only support one J1939
address. Field must not be empty.
©2011—TMC/ATA
CANAutoBaud=[TRUE|FALSE] If the API is capable of handling CAN automatic bit rate detec-
tion using the RP1210_ClientConnect(“PROTOCOL:Baud=Auto”) connect
format. If this variable does not exist, the application should
assume the API cannot detect baud rate and the app should query
the user for what speed to connect at. Field must not be empty.
J1708FormatsSup- This adapter allows the user to connect to the J1708 data bus us-
ported=[1],[2] ing the connection formats as defined in RP1210_ClientConnect.
ISO15765For- This adapter allows the user to connect to the ISO15765 data bus
matsSupported=[1],[2] using the connection formats as defined in RP1210_ClientConnect.
Devices=[d1],[d2],...,[dn] The d’s represent the device IDs for the devices supported by this
vendor API; each d is a number between 0 and 255; the device IDs
are delimited by commas with no spaces in between. Field must not
be empty. Each entry must point to a valid DeviceInformationXXX
section.
Protocols=[p1],[p2],...,[ The p’s represents the identifiers for the protocols supported
pm] by this vendor; each protocol identifier is a number between 0
and 255; the protocol identifiers are delimited by commas with no
spaces in between. Note that, unlike the device IDs, the protocol
identifiers have no significance in the application software other
than to concoct unique tokens for the different protocols support-
ed by the vendor. Field must not be empty. Each entry must point
to a valid ProtocolInformationXXX section.
©2011—TMC/ATA
23.7. The [DeviceInformationdx] Section of the INI File
For each device listed in the [VendorInformation->Devices] section of the Vendor INI file, the following
table describes each of the parameters that will be found in the [DeviceInformationdx] section of the
Vendor INI file:
[DeviceInformationdx] Indicates the start of the [DeviceInformationdx] section for

device dx. Field must not be empty.
DeviceID=[number] Where [number] represents a value ranging between 0 and 255
to identify the device. Field must not be empty.
DeviceDescription=[string,p] Where [string] represents a description of the device. This
description is normally the name of the product listed on
the device. When the device can be connected to several
ports, the value of [p] is also specified after a comma. The
letter [p] represents the port the device is connected to.
The table below lists the acceptable values for p. In the
DeviceDescription part of the “string”, there can be no com-
mas except for the comma delimiting the COM port (p). Field
must not be empty.
[p] Description
COM1 Computers first serial port
COM2 Computers second serial port
COMn Computers Nth serial port
LPT1 Computers first parallel port
LPT1 Computers second parallel port
LPTn Computers Nth parallel port
PCMCIA PCMCIA Card Device
USB USB Device
TCP/IP Device uses TCP/IP as a transport
MODEM Device uses a Modem as a transport
WIRELESS Device is wireless (802.11, Bluetooth,
RF, etc.
Auto API automatically detects port VDA is on.
DeviceName=[string] Where [string] represents the vendor-specific device name.

Typically this has been the DeviceDescription without the
“,” and the port (p). Field must not be empty.
DeviceParams=[string] Where [string] represents vendor-specific parameters, if any.
Field can be empty. This field is for VDA vendors to set de-
vice parameters to modify the device connection.
MultiCANChannels=[integer] The number of simultaneous CAN channels supported for this
device. If device supports CAN, but not multiple CAN chan-
nels, default this to 1. If device does not support CAN,
default to zero. Field must not be empty.
MultiJ1939Channels=[integer] The number of simultaneous J1939 channels supported for this
device. If device supports J1939, but not multiple J1939
channels, default this to 1. If device does not support
J1939, default to zero. Field must not be empty.
MultiISO15765Channels=[integer] The number of simultaneous ISO15765 channels supported for
this device. If device supports ISO15765, but not multiple
ISO15765 channels, default this to 1. If device does not
support ISO15765, default to zero. Field must not be empty.
©2011—TMC/ATA
23.8. The [ProtocolInformationpx] Section of the INI File
For each protocol listed in the [VendorInformation->Protocols] section of the Vendor INI file, the following
table describes each of the parameters that will be found in that section of the Vendor INI file:
[ProtocolInformationpx] Indicates the start of the [ProtocolInformationpx] section

for protocol px. Field must not be empty.
ProtocolDescription=[string] Where [string] represents a description of the protocol
defined in the ProtocolString variable. Field must not be
empty and follows the string defined in the RP1210_ClientCon-
nect section of this document.
ProtocolSpeed=[string1, stringn] Where string[1] through string[n] represents a speed that
the protocol can be used at. The following are the strings
associated with this entry. Implementation of these speeds
is up to the VDA manufacturer and not all adapters will sup-
port all speeds. Field must not be empty.
String Description
All Protocol can be configured for any speed (i.e. CAN registers).
4800 Common for ISO9141/KWP2000
9600 Common for J1708
19200 Common for J1708 and ISO9141/KWP2000
115200 Common for J1708 and ISO9141/KWP2000
10.4 Common for J1850, ISO9141, or KWP2000/ISO14230
41.6 Common for J1850
125 125k CAN/J1939
250 250k CAN/J1939
500 500k CAN/J1939/J2284
1000 1 megabyte CAN/J1939
Auto VDA can automatically detect protocol speed.
ProtocolString=[string] Where [string] represents the protocol string expected by

the RP_1210ClientConnect function. Field must not be empty.
String Protocol Description/ProtocolDescription

CAN CAN Network Protocol
J2284 SAE J2284 Network Protocol (CAN @500k Baud)
ISO15765 ISO15765 Vehicle Protocol
PLC Power Line Carrier (PLC4TRUCKS) Protocol
ISO9141 Generic ISO9141
KWP2000 Keyword Protocol 2000 over ISO9141
©2011—TMC/ATA
ProtocolParams=[string] Where [string] represents vendor-specific parameters, if
any, associated with the protocol—optional. Field must not
be empty.
Devices=[k1,k2,...,kt] Where [k1,k2,...,kt] represents the list of devices associat-
ed with this protocol--each ki is a DeviceID and the list is
comma-delimited (without any spaces in between). Field must
not be empty. Entry must point to a valid DeviceInformation-
XXX section.
23.9. Example VDA Vendor INI File

The following example shows a very simple VDA vendor INI file that supports all of the protocols at all of the
RP1210 defined speeds with four devices.
[VendorInformation]
;===============================================================================
;McLovin Systems, Inc. - RP1210C Vendor INI File
;-------------------------------------------------------------------------------
;
; Author: Dr. Ladiesman McLovin
; Date: December 15, 2011
; Version: 8.1
;
;-------------------------------------------------------------------------------
Name=McLovin Systems Lightsaber Adapter
Address1=6996 Nova Road
Address2=
City=Wrightsville Beach
State=NC
Country=USA
Postal=99999
Telephone=910-283-9211
Fax=910-283-9213
VendorURL=http://www.mclovin.com
MessageString=MS1210_MSG
ErrorString=MS1210_ERR
;-------------------------------------------------------------------------------
; Each McLovin product produces a timestamp weight of 1000 microseconds (1ms)
TimestampWeight=1000
;-------------------------------------------------------------------------------
; Each McLovin device defined in this INI file is "auto-detect" capable
AutoDetectCapable=Yes
;-------------------------------------------------------------------------------
; This INI file version/revision
Version=8.1
;-------------------------------------------------------------------------------
; This INI file is RP1210C-compliant
RP1210=C
;-------------------------------------------------------------------------------
;McLovin Supports API Level Debugging (Levels 0 - 4)
;
; To use API level debugging, modify the DebugLevel variable to:
;
; 0 = No debugging to be accomplished (default).
; 1 = Only Connect/Disconnect/Error Messages.
; 2 = Add RP1210_SendCommand calls.
; 3 = Add all Sent Messages (with filtering).
; 4 = Add all Received Messages (with filtering).
;
; The variable DebugFile is the file where you want to write the information.
;
; The DebugFileSize variable is how many 1k chunks you will allow the API to
; write before it begins to write over previously written entries. A value
; of 1024 is 1 megabyte (default).
;
; The DebugMode variable describes how the API will interact with the DebugFile.
; Should it overwrite (value = 0) any previous entries or should it append
; entries (value = 1) to the end of the file.
;-------------------------------------------------------------------------------
©2011—TMC/ATA
DebugLevel=0
DebugFile=c:\mclovin1210.txt
DebugMode=1
DebugFileSize=1024
;-------------------------------------------------------------------------------
; McLovin Supports 1 concurrent RTS/CTS session and BAM session per each client.
NumberOfRTSCTSSessions=1
;-------------------------------------------------------------------------------
; McLovin Supports all 5 CAN connect formats (see RP1210C documentation)
;
; Also supports "Channel=" parameter, where allowed.
;
; Format 1 =
; fpchProtocol="CAN:Baud=X,SampleLocation=Y,SJW=Z,IDSize=S"
; Format 2 =
; fpchProtocol="CAN:Baud=X,PROP_SEG=A,PHASE_SEG1=B,PHASE_SEG2=C,SJW=Z,IDSize=SS"
; Format 3 =
; fpchProtocol="CAN:Baud=X,TSEG1=D,TSEG2=E,SJW=Z,IDSize=SS"
; Format 4 =
; fpchProtocol="CAN"
; Format 5 =
; fpchProtocol="CAN:Baud=X"
;-------------------------------------------------------------------------------
CANFormatsSupported=1,2,3,4,5
;-------------------------------------------------------------------------------
; McLovin Supports all 5 J1939 connect formats (see RP1210C documentation)
;
; Also supports "Channel=" parameter, where allowed.
;
; Format 1 =
; fpchProtocol="J1939:Baud=X"
; Format 2 =
; fpchProtocol="J1939"
; Format 3 =
; fpchProtocol="J1939:Baud=X,SampleLocation=Y,SJW=Z,IDSize=S"
; Format 4 =
; fpchProtocol="J1939:Baud=X,PROP_SEG=A,PHASE_SEG1=B,PHASE_SEG2=C,SJW=Z,IDSize=SS"
; Format 5 =
; fpchProtocol="J1939:Baud=X,TSEG1=D,TSEG2=E,SJW=Z,IDSize=SS"
;-------------------------------------------------------------------------------
J1939FormatsSupported=1,2,3,4,5
;-------------------------------------------------------------------------------
; McLovin supports protection of 16 J1939 addresses.
J1939Addresses=16
;-------------------------------------------------------------------------------
; This API supports CAN auto baud rate detection.
CANAutoBaud=TRUE
;-------------------------------------------------------------------------------
; McLovin Supports all 2 J1708 connect formats (see RP1210C documentation)
;
; Format 1 =
; fpchProtocol="J1708:Baud=X"
; Format 2 =
; fpchProtocol="J1708"
;-------------------------------------------------------------------------------
J1708FormatsSupported=1,2
;-------------------------------------------------------------------------------
;McLovin Supports all 2 ISO15765 connect formats (see RP1210C documentation)
;
; Format 1 =
; fpchProtocol="ISO15765:Baud=X"
; Format 2 =
; fpchProtocol="ISO15765"
;-------------------------------------------------------------------------------
ISO15765FormatsSupported=1,2
;-------------------------------------------------------------------------------
;McLovin Has 2 Devices That Support Various Protocols (1=USB, 2=Bluetooth)
;-------------------------------------------------------------------------------
Devices=1,2
;-------------------------------------------------------------------------------
;McLovin Supports all 10 RP1210C Protocols at various speeds.
©2011—TMC/ATA
;-------------------------------------------------------------------------------
Protocols=1,2,3,4,5,6,7,8,9,10
;
;
;===============================================================================
;McLovin Has 2 Devices (USB, Bluetooth)
;
; 1 McLovin Lovin Touchin Squeezin Adapter, USB
; 2 McLovin Lovin Touchin Squeezin Adapter, Wireless (Bluetooth)
;
; Each device supports 2 CAN channels.
;-------------------------------------------------------------------------------
;
[DeviceInformation1]
DeviceID=1
DeviceDescription=McLovin Touchin Squeezin Adapter,USB
DeviceName=McLovin Touchin Squeezin Adapter (USB Mode)
DeviceParams=USB
MultiCANChannels=2
MultiJ1939Channels=2
MultiISO15765Channels=2
;
[DeviceInformation2]
DeviceID=2
DeviceDescription=McLovin Touchin Squeezin Adapter,Wireless
DeviceName=McLovin Touchin Squeezin Adapter (Bluetooth Mode)
DeviceParams=444-555-888
MultiCANChannels=2
MultiJ1939Channels=2
MultiISO15765Channels=2
;
;
;===============================================================================
;McLovin Supports all RP1210C Protocols and Each One at the Listed Speeds
;
; 1=CAN at 125k, 250k, 500k, 1000k, Auto Bitrate Detect, All bit rates
; 2=J2284 at 125k, 250k, 500k, 1000k, Auto Bitrate Detect, All bit rates
; 3=J1939 at 125k, 250k, 500k, 1000k, Auto Bitrate Detect, All bit rates
; 4=ISO15765 at 125k, 250k, 500k, 1000k, Auto Bitrate Detect, All bit rates
; 5=J1708 at 9600, 19200, 38400, 57600, 115200, All bit rates
; 6=PLC at 9600
; 7=J1850_104k at 10.4k
; 8=J1850_416k at 41.6k
; 9=ISO9141 at all speeds commonly used
; 10=KWP2000 at all speeds commonly used
;
;-------------------------------------------------------------------------------
;
ProtocolString=CAN
ProtocolSpeed=125,250,500,1000,All,Auto
ProtocolParams=
Devices=1,2
;
ProtocolDescription=SAE J2284 Network Protocol (CAN @500k Baud)
ProtocolParams=
Devices=1,2
;
ProtocolParams=
Devices=1,2
;
ProtocolString=ISO15765
©2011—TMC/ATA
ProtocolDescription=ISO15765 Vehicle Protocol
ProtocolParams=
Devices=1,2
;
ProtocolSpeed=9600,19200,38400,57600,115200,All
ProtocolParams=
Devices=1,2
;
ProtocolString=PLC
ProtocolDescription=Power Line Carrier (PLC4TRUCKS) Protocol
ProtocolSpeed=9600
ProtocolParams=
Devices=1,2
;
ProtocolString=J1850_104k
ProtocolDescription=SAE J1850 Vehicle Protocol (Baud Rate of 10.4k)
ProtocolSpeed=10.4
ProtocolParams=
Devices=1,2
;
ProtocolString=J1850_416k
ProtocolDescription=SAE J1850 Vehicle Protocol (Baud Rate of 41.6k)
ProtocolSpeed=41.6
ProtocolParams=
Devices=1,2
;
ProtocolString=ISO9141
ProtocolDescription=Generic ISO9141
ProtocolSpeed=4800,9600,9615,9800,1000,10.4,10870,11905,12500,13158,13889,14706,15625,19200,11520
0,All
ProtocolParams=
Devices=1,2
;
ProtocolString=KWP2000
ProtocolDescription=Keyword Protocol 2000 over ISO9141
ProtocolSpeed=4800,9600,9615,9800,1000,10.4,10870,11905,12500,13158,13889,14706,15625,19200,11520
0,All
ProtocolParams=
Devices=1,2
;
;-------------------------------------------------------------------------------
;McLovin Systems, Incorporated - RP1210C Vendor INI File
;-------------------------------------------------------------------------------
©2011—TMC/ATA
23.10. API Vendor Header File
The following is the minimal amount of information that should be present in a Vendor API developer header file.
//--------------------------------------------------------------
// RP1210A/RP1210B/RP1210C RP1210_SendCommand Defines
//--------------------------------------------------------------
typedef unsigned char U8;
#define RP1210_Reset_Device 0
#define RP1210_Set_All_Filters_States_to_Pass 3
#define RP1210_Set_Message_Filtering_For_J1939 4
#define RP1210_Set_Message_Filtering_For_CAN 5
#define RP1210_Set_Message_Filtering_For_ISO15765 9
#define RP1210_Generic_Driver_Command 14
#define RP1210_Set_J1708_Mode 15
#define RP1210_Echo_Transmitted_Messages 16
#define RP1210_Set_All_Filters_States_to_Discard 17
#define RP1210_Set_Message_Receive 18
#define RP1210_Protect_J1939_Address 19
#define RP1210_Set_Broadcast_For_J1708 20
#define RP1210_Set_Broadcast_For_CAN 21
#define RP1210_Set_J1708_Filter_Type 24
#define RP1210_Set_CAN_Filter_Type 26
#define RP1210_Set_J1939_Interpacket_Time 27
#define RP1210_SetMaxErrorMsgSize 28
#define RP1210_Disallow_Further_Connections 29
#define RP1210_Release_J1939_Address 31
#define RP1210_Set_ISO15765_Filter_Type 32
#define RP1210_Set_Broadcast_For_ISO15765 33
#define RP1210_Set_ISO15765_Flow_Control 34
#define RP1210_Clear_ISO15765_Flow_Control 35
#define RP1210_Set_J1939_Baud 37
#define RP1210_Set_ISO15765_Baud 38
#define RP1210_Set_BlockTimeout 215
#define RP1210_Set_J1708_Baud 305
#define RP1210_Flush_Tx_Rx_Buffers 39
#define Previously used and antiquated. 40
#define RP1210_Set_Broadcast_For_KWP2000 41
#define RP1210_Set_Broadcast_For_ISO9141 42
#define RP1210_Get_Protocol_Connection_Speed 45
#define RP1210_Set_ISO9141KWP2000_Mode 46
#define RP1210_Set_CAN_Baud 47
#define RP1210_Get_Wireless_State 48
//--------------------------------------------------------------
// RP1210C Constants
//--------------------------------------------------------------
#define CONNECTED_WIRED 0
#define CONNECTED_WIRELESS 1
#define BIT0 1 // Bit 0 - Used for masking bits

/*======================================================================
* Defined used to help in unpacking Motorola format numbers.
*======================================================================*/
#define HIWORD_OF_INT4( x ) ( ( x >> 16 ) & 0xFFFF )
©2011—TMC/ATA
#define LOWORD_OF_INT4( x ) ( x & 0x0000FFFF )
#define HIBYTE_OF_WORD( x ) ( ( x >> 8 ) & 0xFF )
#define LOBYTE_OF_WORD( x ) ( x & 0x00FF )
#define HINIBBLE_OF_CHAR( x ) ( ( x & 0xF0 ) >> 4 )
#define LONIBBLE_OF_CHAR( x ) ( x & 0x0F )
#define BYTE0_OF_INT4( x ) LOBYTE_OF_WORD( LOWORD_OF_INT4( x ) )
#define BYTE1_OF_INT4( x ) HIBYTE_OF_WORD( LOWORD_OF_INT4( x ) )
#define BYTE2_OF_INT4( x ) LOBYTE_OF_WORD( HIWORD_OF_INT4( x ) )
#define BYTE3_OF_INT4( x ) HIBYTE_OF_WORD( HIWORD_OF_INT4( x ) )
#define CONNECTED 1 // Current connection state = Connected

#define NOT_CONNECTED -1 // Current connection state = Disconnected
#define FILTER_PASS_NONE 0 // Current filter state = DISCARD ALL MESSAGES
#define FILTER_PASS_SOME 1 // Current filter state = PASS SOME (some filters set)
#define FILTER_PASS_ALL 2 // Current filter state = PASS ALL
#define NULL_WINDOW 0 // Windows 3.1 is no longer supported.
#define BLOCKING_IO 1 // For Blocking calls to send/read.

#define NON_BLOCKING_IO 0 // For Non-Blocking calls to send/read.
#define BLOCK_INFINITE 0 // For Non-Blocking calls to send/read.
#define BLOCK_UNTIL_DONE 0
#define RETURN_BEFORE_COMPLETION 2
#define CONVERTED_MODE 1 // RP1210Mode="Converted"
#define RAW_MODE 0 // RP1210Mode="Raw"
#define MAX_J1708_MESSAGE_LENGTH 512 // Maximum size a J1708 message can be (+1)

#define MAX_J1939_MESSAGE_LENGTH 1796 // Maximum size a J1939 message can be (+1)
#define MAX_ISO15765_MESSAGE_LENGTH 4108 // Maximum size an ISO15765 message can be (+1)
#define ECHO_OFF 0x00 // EchoMode

#define ECHO_ON 0x01 // EchoMode
#define RECEIVE_ON 0x01 // Set Message Receive

#define RECEIVE_OFF 0x00 // Set Message Receive
#define ADD_LIST 0x01 // Add a message to the list.

#define VIEW_B_LIST 0x02 // View an entry in the list.
#define DESTROY_LIST 0x03 // Remove all entries in the list.
#define REMOVE_ENTRY 0x04 // Remove a specific entry from the list.
#define LIST_LENGTH 0x05 // Returns number of items in list.
#define FILTER_PGN 0x00000001 // Setting of J1939 filters

#define FILTER_SOURCE 0x00000004 // Setting of J1939 filters
#define FILTER_DESTINATION 0x00000008 // Setting of J1939 filters
#define FILTER_INCLUSIVE 0x00 // FilterMode
#define FILTER_EXCLUSIVE 0x01 // FilterMode
#define SILENT_J1939_CLAIM 0x00 // Claim J1939 Address

#define PASS_J1939_CLAIM_MESSAGES 0x01 // Claim J1939 Address
#define CHANGE_BAUD_NOW 0x00 // Change Baud

#define MSG_FIRST_CHANGE_BAUD 0x01 // Change Baud
#define RP1210_BAUD_9600 0x00 // Change Baud
#define RP1210_BAUD_125k 0x04 // Change Baud
#define STANDARD_CAN 0x00 // Filters

#define EXTENDED_CAN 0x01 // Filters
#define STANDARD_CAN_ISO15765_EXTENDED 0x02 // 11-bit with ISO15765 extended address
#define EXTENDED_CAN_ISO15765_EXTENDED 0x03 // 29-bit with ISO15765 extended address
#define STANDARD_MIXED_CAN_ISO15765 0x04 // 11-bit identifier with mixed addressing
#define ISO15765_ACTUAL_MESSAGE 0x00 // ISO15765 ReadMessage - type of data

#define ISO15765_CONFIRM 0x01 // ISO15765 ReadMessage - type of data
#define ISO15765_FF_INDICATION 0x02 // ISO15765 ReadMessage - type of data
©2011—TMC/ATA
#define ISO15765_RX_ERROR_INDICATION 0x03 // ISO15765 ReadMessage - Type of data
#define N_OK 0x00

#define N_TIMEOUT_A 0x01
#define N_TIMEOUT_Bs 0x02
#define N_TIMEOUT_C 0x03
#define N_WRONG_SN 0x04
#define N_INVALID_FS 0x05
#define N_UNEXP_PDU x06
#define N_WFT_OVRN 0x07
#define N_BUFFER_OVERFLOW 0x08
#define N_ERROR 0x09
#ifndef TRUE
#define TRUE 0x01
#define FALSE 0x00
#endif
//--------------------------------------------------------------
// RP1210C Return Definitions
//--------------------------------------------------------------
#define NO_ERRORS 0
#define ERR_DLL_NOT_INITIALIZED 128
#define ERR_INVALID_CLIENT_ID 129
#define ERR_CLIENT_ALREADY_CONNECTED 130
#define ERR_CLIENT_AREA_FULL 131
#define ERR_FREE_MEMORY 132
#define ERR_NOT_ENOUGH_MEMORY 133
#define ERR_INVALID_DEVICE 134
#define ERR_DEVICE_IN_USE 135
#define ERR_INVALID_PROTOCOL 136
#define ERR_TX_QUEUE_FULL 137
#define ERR_TX_QUEUE_CORRUPT 138
#define ERR_RX_QUEUE_FULL 139
#define ERR_RX_QUEUE_CORRUPT 140
#define ERR_MESSAGE_TOO_LONG 141
#define ERR_HARDWARE_NOT_RESPONDING 142
#define ERR_COMMAND_NOT_SUPPORTED 143
#define ERR_INVALID_COMMAND 144
#define ERR_TXMESSAGE_STATUS 145
#define ERR_ADDRESS_CLAIM_FAILED 146
#define ERR_CANNOT_SET_PRIORITY 147
#define ERR_CLIENT_DISCONNECTED 148
#define ERR_CONNECT_NOT_ALLOWED 149
#define ERR_CHANGE_MODE_FAILED 150
#define ERR_BUS_OFF 151
#define ERR_COULD_NOT_TX_ADDRESS_CLAIMED 152
#define ERR_ADDRESS_LOST 153
#define ERR_CODE_NOT_FOUND 154
#define ERR_BLOCK_NOT_ALLOWED 155
#define ERR_MULTIPLE_CLIENTS_CONNECTED 156
#define ERR_ADDRESS_NEVER_CLAIMED 157
#define ERR_WINDOW_HANDLE_REQUIRED 158
#define ERR_MESSAGE_NOT_SENT 159
#define ERR_MAX_NOTIFY_EXCEEDED 160
#define ERR_MAX_FILTERS_EXCEEDED 161
#define ERR_HARDWARE_STATUS_CHANGE 162
#define ERR_INI_FILE_NOT_IN_WIN_DIR 202
#define ERR_INI_SECTION_NOT_FOUND 204
#define ERR_INI_KEY_NOT_FOUND 205
#define ERR_INVALID_KEY_STRING 206
#define ERR_DEVICE_NOT_SUPPORTED 207
#define ERR_INVALID_PORT_PARAM 208
#define ERR_COMMAND_TIMED_OUT 213
#define ERR_OS_NOT_SUPPORTED 220

#define ERR_COMMAND_QUEUE_IS_FULL 222
#define ERR_CANNOT_SET_CAN_BAUDRATE 224
#define ERR_CANNOT_CLAIM_BROADCAST_ADDRESS 225
#define ERR_OUT_OF_ADDRESS_RESOURCES 226
#define ERR_ADDRESS_RELEASE_FAILED 227
#define ERR_COMM_DEVICE_IN_USE 230
©2011—TMC/ATA
#define ERR_DATA_LINK_CONFLICT 441
#define ERR_ADAPTER_NOT_RESPONDING 453
#define ERR_CAN_BAUD_SET_NONSTANDARD 454
#define ERR_MULTIPLE_CONNECTIONS_NOT_ALLOWED_NOW 455
#define ERR_J1708_BAUD_SET_NONSTANDARD 456
#define ERR_J1939_BAUD_SET_NONSTANDARD 457
#define ERR_ISO15765_BAUD_SET_NONSTANDARD 458
#define ERR_INVALID_IOCTL_ID 600
#define ERR_NULL_PARAMETER 601
#define ERR_HARDWARE_NOT_SUPPORTED 602
#define GET_CONFIG 0x01
#define SET_CONFIG 0x02
#define FIVE_BAUD_INIT 0x04
#define FAST_INIT 0x05
// ISO9141/KWP2000 Ioctl values reserved 0x03, 0x06-0xFFFF

// Ioctl values that are vendor specific 0x10000-0xFFFFFFFF
typedef struct
{
}SCONFIG;
typedef struct
{
}SCONFIG_LIST;
typedef struct
{
}SBYTE_ARRAY;
//--------------------------------------------------------------
// TMC RP1210C Defined Function Prototypes
//--------------------------------------------------------------
#define DLLEXPORT __declspec(dllexport)
#ifdef __cplusplus
extern "C" {
#endif
short DLLEXPORT WINAPI RP1210_ClientConnect(
HWND hwndClient,
short nDeviceId,
char *fpchProtocol,
long lSendBuffer,
long lReceiveBuffer,
short nIsAppPacketizingIncomingMsgs );
short DLLEXPORT WINAPI RP1210_ClientDisconnect( short nClientID );
short DLLEXPORT WINAPI RP1210_SendMessage(

short nClientID,
char *fpchClientMessage,
short nMessageSize,
short nNotifyStatusOnTx,
short nBlockOnSend );
short DLLEXPORT WINAPI RP1210_ReadMessage(

short nClientID,
char *fpchAPIMessage,
short nBufferSize,
short nBlockOnSend );
short DLLEXPORT WINAPI RP1210_SendCommand(

short nCommandNumber,
©2011—TMC/ATA
short nClientID,
char *fpchClientCommand,
short nMessageSize );
void DLLEXPORT WINAPI RP1210_ReadVersion(

char *fpchDLLMajorVersion,
char *fpchDLLMinorVersion,
char *fpchAPIMajorVersion,
char *fpchAPIMinorVersion );
short DLLEXPORT WINAPI RP1210_ReadDetailedVersion(

short nClientID,
char *fpchAPIVersionInfo,
char *fpchDLLVersionInfo,
char *fpchFWVersionInfo );
short DLLEXPORT WINAPI RP1210_GetHardwareStatus(

short nClientID,
char *fpchClientInfo,
short nInfoSize,
short nBlockOnRequest);
short DLLEXPORT WINAPI RP1210_GetErrorMsg(

short err_code,
char *fpchMessage);
short DLLEXPORT WINAPI RP1210_GetLastErrorMsg(

short err_code,
int *SubErrorCode,
char *fpchMessage );
#ifdef __cplusplus
}
#endif
24. Debug File Format

If the API supports debugging (not a mandatory feature), the API is completely responsible for the format
of the debug file.
Notes Concerning Debug File Format:

• The API vendor should completely document the format of the file so that the end-user can readily
assist in debugging of a possible application or API problem.
• The file shall be in standard ASCII format readable by “notepad.exe” or “wordpad.exe” and should
contain line breaks (CR/LF) at the end of each entry.
• The information should be delineated such that it can be imported into a spreadsheet or program-
matically parsed with relative ease.
• Comments in the INI file will help the user to understand what levels of debugging that the API is
capable of.
If an API vendor does not support debugging, then the vendor should initialize the INI file variable “Debug-
Level” to -1. If an API vendor does support debugging, then the vendor should initialize the INI file variable
“DebugLevel” to 0.
It is assumed that if an API supports debugging that it only checks the variable on the first client connection
and does not check the variable with each additional client. Therefore, to initialize debugging:
1. All client applications would need to disconnect.
2. The user changes the DebugLevel variable.
3. The user reinitializes the application to debug.
4. The user creates the anomaly (while the API writes to the debug file).
5. The user then assists the appropriate technical support staff to debug.
©2011—TMC/ATA
25. Multi-Application Addendum
The reason this section has been added to RP1210C is that some VDA vendors have implemented different
levels of support for “applications” and “clients”. If a fleet does not use more than one OEM diagnostic ap-
plication running at a time, then this does not make a major difference, as most shops only run one diagnostic
application at a time. To date, most of the OEM applications only require the SA/MC standard (see below),
which is one EXE and a client for each protocol they wish to communicate with .
There are three types of RP1210-compliant VDA devices on the market, listed below starting at the high-
est to the least level of functionality. It is expected that in the future, VDA vendors will list their adapters at
one of these levels, and OEM applications would list that they required a VDA of “at least RP1210B” level
of functionality.
25.1. RP 1210 Compliant — Multi-Application/Multi-Client (MA/MC)

These adapters can have multiple applications running “simultaneously” (i.e., CAT ET, Eaton ServiceRanger,
Bendix ACOM), and will allow a combination of at least 16 total client connections.
25.2. RP 1210 Compliant - Single-Application/Multi-Client (SA/MC)

These adapters can have a single application running and will allow at least 16 client connections from that
application.
25.3. RP 1210 Compliant — Single-Application/Single-Client (SA/SC)

These adapters can have a single application with a single client connection. These are mainly purpose
built adapters for a single protocol connection (i.e., J1939 only).
TMC’s RP 1210 Update Task Force is not trying to promote any particular type of VDA. This is only an at-
tempt to provide clarification so that the end-user/fleet can make an informed decision when it comes to
purchasing an RP 1210 adapter.
NOTE TO END-USERS: If the end-user decides to run multiple applications simultaneously, it is their re-
sponsibility to confirm that these applications have been validated by the respective OEMs to co-exist and
share VDA resources with the other applications that they want to run simultaneously. It is highly unlikely
that most OEMs will support a user running more than one diagnostic application at the same time as their
application.
NOTE TO OEM APPLICATION VENDORS: Reprogramming or diagnostic applications that have time or
code critical functions should call the RP1210_SendCommand(RP1210_Disallow_Further_Connections) so
that no other application/client can share VDA resources, as this could create a longer than usual message
latency issue.
TMC’s RP 1210 Update Task Force cannot guarantee that two OEM diagnostic applications can be ran si-
multaneously, and we discourage this practice. TMC sees MA/MC as a great way to run an OEM diagnostic
application and a data logger to investigate application specific issues.
26. Non-Windows Cross Platform Addendum

This RP was originally conceived for the Microsoft Windows 3.1 platform. This RP has matured alongside
the Windows operating systems, adding support for new versions of Windows and even shedding support
for the original Windows 3.1 version. As the industry moves forward, the need for a common API driver
solution on non-Windows platforms has grown to the point that we need to expand RP1210 support to non-
Windows computing platforms.
UNIX variants (especially the Linux kernel), are becoming more and more prevalent on today’s computing
platforms and for several years TMC’s RP 1210 Update Task Force has discussed a UNIX-hosted RP1210
standard. The goal of this addendum is to identify how RP 1210 will work on common non-Windows based
systems. The goal is not to create “yet another API” or expand upon the existing API, just to port what is
©2011—TMC/ATA
done with minimal changes for the VDA vendor and application developer to support RP 1210 on these non-
Windows platform. Application vendors would like to reuse their software investments on various platforms
to provide applications in every market and OEMs would like to reuse their existing wireless VDA devices
with the new breed of applications.
26.1. RP1210 Is Essentially Platform Independent

The RP 1210 API is essentially platform independent already. The various programming language interface
syntax and semantics contain abstract concepts which are easily ported to other platforms, provided the
platform has the computing power to support RP 1210 communications at the rates defined. The reason
for the independence lies in the decisions made originally by TMC’s RP1210 Update Task Force by deploy-
ing RP 1210 using Windows DLLs and INI files. These concepts are easily ported to a variety of operating
systems.
In addition to specifying the deployment mechanism the RP defines non-Windows specific placement of
the required files and file naming conventions for that OS. For example, on case-sensitive systems, all RP
1210 files (main INI, vendor INI, and SO), along with directory names, will be in all lower case letters. For
example, “Rp121032.INI” and “RP121032.INI” are different files, so “rp121032.ini” will be the name of the
main INI file.
Finally, there are implied dependencies on system APIs. On the Windows platform, both the VDA driver and
the application can reasonably assume the presence of the Win32 API on all modern Windows PCs. On
alternate platforms the assumptions about existing system resources may not be as clear. Any requirements
or packages a VDA or application vendor require will be discussed in their specific user documentation, and
is not within the scope of this document.
This addendum is divided into a section for each platform, each of which addresses the portability issues.
All function calls, all return values, all parameters and all other functional related items from Windows
RP1210 are the same and will not change. Type definitions that do not map from Windows (i.e., to UNIX)
will be noted (i.e., HWND -> unsigned long). The RP1210 API is unchanged on all platforms in terms of
syntax and semantics. All functional requirements in the main portion of the document remain in effect on
all platforms.
26.2. Microsoft Windows CE

Windows CE is a Microsoft operating system for embedded and handheld devices. It provides a subset of
the Win32 API and supports a range of hardware and communications options. The Windows CE deploy-
ment model is identical to Windows PC platforms, namely dynamic link libraries (DLL) compiled for the
Windows CE platform architecture. Vendors may provide drivers for ARM or other architectures as the
market demands.
26.2.1. File Placement

File placement on Windows CE is slightly different when compared to the Windows PC platform. The
RP121032.ini, vendor INI, and vendor DLL file should all be placed in “\Windows”.
26.2.2. System APIs

Microsoft defines a subset of the Win32 API that is available on all WinCE platforms. Vendors can rely on
these services when implementing the VDA driver for WinCE.
26.2.3. API Changes

For Windows CE, no changes to the RP 1210 API are required.
©2011—TMC/ATA
26.3. UNIX and Linux
Since UNIX is a case-sensitive system, all RP 1210 files (main INI, vendor INI, and SO), along with directory
names, will be in all lower case letters. The DOS FAT file naming convention will also apply (file names with
8 characters in front of the period and 3 characters after the period).
Each VDA vendor will provide an installation script or program. If the installation is an executable file, there
are no constraints. If the installation is a script, or calls a script file, the script will be written to the most
commonly found scripting language on each system, the Bourne Shell (/bin/sh).
26.3.1. Accounts, Groups, Files, and Permissions

• The UNIX administrator must create a user account on the UNIX machine called “rp1210”.
• The UNIX administrator must create a group account on the UNIX machine called “rp1210”.
• Each user of RP1210 must be in the group “rp1210” so that they can read and modify the INI files.
- Users not part of the group “rp1210” can read the INI files, but cannot modify them.
• Root permission will be required for all application and VDA installations so that if the /rp1210 direc-
tories and /rp1210/rp121032.ini file do not exist, they can be created.
• All files will have the following permissions:
- /rp1210 (main RP1210 directory)
* Owner = rp1210
* Perms: User=RWX, Group = RWX, Others = RX
- /rp1210/so (RP1210 shared objects directory)
* Owner = rp1210
- /rp1210/so/aaaaaaaa.so (RP1210 shared object/DLL for vendor “aaaaaaaa”)
* Owner = rp1210
* Perms: User=RX, Group = RX, Others = RX
- /rp1210/aaaaaaaa (directory for vendor specific files, if necessary)
* Owner = rp1210
* NOTE: If vendor “aaaaaaaa” does not need this, it does not have to be created. The vendor
controls the files and subdirectories in this top-level directory, of which manuals or utility
applications can be installed.
- /rp1210/rp121032.ini (main RP1210 INI file)
* Owner = rp1210
* Perms: User=RW, Group = RW, Others = R
- /rp1210/aaaaaaaa.ini (Vendor INI file for vendor “aaaaaaaa”)
* Owner = rp1210
* Perms: User=RW, Group = RW, Others = R
26.3.2. System APIs
• Since there is no common “MessageBox” function in UNIX, all error text from the VDA SO or applica-
tion executable will be sent to the FILE pointer “stderr” which can be redirected when a program is
started.
• There is not a need for user environment variables at this point.
26.3.3. API Changes

1. The most notable of the changes are that the Windows call GetPrivateProfileString() is not present
on a UNIX machine, meaning INI file processing routines must be written.
2. Also, dlopen(), dlsym(), and dlclose() will take the place of the Windows LoadLibrary(), GetProcAd-
dress(), and FreeLibrary() calls.
3. Instead of CR/LF (ASCII 0x0D/0x0A) line endings which are seen on DOS/Windows, the line ending
character for INI files will be a single LF character (ASCII 0x0A) commonly called a “newline” char-
acter.
4. RP1210 INI section names and variable names are not case sensitive. Application RP1210 INI file
parsing can take care of this, just like the Windows call GetPrivateProfileString() did.
©2011—TMC/ATA
26.3.4. RP1210 SO (Shared Object) Files
Where Windows had Dynamic Link Libraries (DLL files), UNIX systems have Shared Object files (SO files).
The UNIX system has calls similar to LoadLibrary() and GetProcAddress() and these will be shown in some
code snippets later in this section.
26.3.5. RP1210 Includes, Type Definitions, and Function Declarations For UNIX
The following are the function declarations that are for RP 1210 on UNIX along with snippets of code show-
ing an application developer how to load an SO and get the function pointers from it.
#include <dlfcn.h>
typedef HWND unsigned long;

typedef HANDLE void *;
typedef short (*fxRP1210_ClientConnect) ( HWND, short, char*, long,long, short );

typedef short (*fxRP1210_ClientDisconnect) ( short );
typedef short (*fxRP1210_SendMessage) ( short, char*, short, short, short );
typedef short (*fxRP1210_ReadMessage) ( short, char*, short, short );
typedef short (*fxRP1210_SendCommand) ( short, short, char*, short );
typedef void (*fxRP1210_ReadVersion) ( char*, char*, char*, char* );
typedef short (*fxRP1210_GetErrorMsg) ( short, char*, short );
typedef short (*fxRP1210_GetLastErrorMsg) ( short, int *, char*, short );
typedef short (*fxRP1210_GetHardwareStatus) ( short, char*, short, short );
typedef short (*fxRP1210_ReadDetailedVersion) ( short, char*, char*, char* );
fxRP1210_ClientConnect pRP1210_ClientConnect = NULL;

fxRP1210_ClientDisconnect pRP1210_ClientDisconnect = NULL;
fxRP1210_ReadMessage pRP1210_ReadMessage = NULL;
fxRP1210_SendMessage pRP1210_SendMessage = NULL;
fxRP1210_SendCommand pRP1210_SendCommand = NULL;
fxRP1210_ReadVersion pRP1210_ReadVersion = NULL;
fxRP1210_GetErrorMsg pRP1210_GetErrorMsg = NULL;
fxRP1210_GetLastErrorMsg pRP1210_GetLastErrorMsg = NULL;
fxRP1210_GetHardwareStatus pRP1210_GetHardwareStatus = NULL;
fxRP1210_ReadDetailedVersion pRP1210_ReadDetailedVersion = NULL;
HANDLE hRP1210DLL = NULL;
if ( ( hRP1210DLL = dlopen ( szDLLName, RTLD_LAZY ) ) == NULL )

{
exit(1);
}
pRP1210_ClientConnect = (fxRP1210_ClientConnect)(
dlsym (
hRP1210DLL,
"RP1210_ClientConnect"
)
);
if ( pRP1210_ClientConnect == NULL )
{
printf("Error: Could not find procedure \"%s\" in DLL!\n", "RP1210_ClientConnect" );
exit(1);
}
dlclose( hRP1210DLL );
©2011—TMC/ATA
27. Changes TO RP 1210B BY TASK FORCE SINCE PUBLICATION IN 2007
• Defined what is a “Single Application” and “Multi Application” VDA API . Also defined the three
different “types” of VDA devices that are out there (MA/MC, SA/MC, SA/SC).
• Added a Non-Windows RP1210 Addendum (support for UNIX and Windows CE).
• Added automatic bit rate detection as mandatory for CAN protocols (i.e., “CAN:Baud=Auto”).
i Also added an RP1210_SendCommand(RP1210_Get_Protocol_Connection_Speed) function call
to determine what speed the VDA actually connected at.
• Added ISO9141 and KWP2000.
• Made minor changes to ISO15765.
• Made the support of 16 J1939 addresses and 16 TP sessions (1 RTS/CTS and 1 BAM) for those
addresses mandatory.
• Removed all blocking from functions that used to support blocking except RP1210_ReadMessage().
These functions now ignore blocking requests and appear to an application as NON_BLOCKING_IO.
• Added all support necessary for J1939@500k (J1939-14) including automatic bit rate detection.
• Defined what happens in a queue full scenario (RX and TX queues).
• Added to the “developing and testing using the least common denominator” paragraph. Stated that
OEM diagnostic apps should test with serial VDA devices even though USB has been the norm for many
years. Testing with serial VDAs helps ensure that your application works with all VDA devices.
• Added variable baud rates that a user can connect to on the J1939 network, other than just 250k and
500k.
• Added a protocol name for “J2284” (CAN@500k).
• Added the use of a MAC address and Port for TCP/IP transport instead of just TCP/IP address.
• Fixed CAN connect baud rate issues.
• Replaced GetWindowsDirectory with GetSystemWindowsDirectory. GetWindowsDirectory is now a
per-user/virtual copy of the Windows directory, and does not point to C:\Windows. The GetSystem-
WindowsDirectory call will point to C:\Windows or C:\Winnt.
• Added RP1210_SendCommand( RP1210_Get_Wireless_State (48) ) so that an application knows if
it is connected wirelessly. Also added section to address notes concerning this.
• Task Force decided not going to another INI file for 64-bit operating systems.
• Made changes to ISO15765.
• Added DHCP name to TCP/IP sections.
• Removed FILTER_PRIORITY from RP1210_SendCommand( RP1210_Set_Filtering_For_J1939 ).
• Made note in RP1210_ReadMessage( J1939 ) that the priority should be masked off and set to zero
in accordance with section 5.2.1 of J1939/21. Allowing the API the choice of either passing up the
priority or allowing the API to set to zero.
• Clarified SA and DA on J1939 received messages. On an 8-byte J1939 message (that does not
require use of the CM facilities) that is in the PDU2 range, DA shall be set to 0xFF.
©2011—TMC/ATA
28.TERMINOLOGY
The following table describes the terminology used in this specification:
Abbreviation Description
API Application Programmer’s Interface. A documented methodology
for programming application programs such that they operate
cooperatively with other programs. Software programmers write
applications that conform to one or many API’s.
Application An executable process (or set of related processes/threads) that

have issued one or more connections to the vehicle databus(es)
using RP1210_ClientConnect().
• Single “application” VDA drivers allow only one diagnostic tool

(e.g,. Cummins INSITE) to access the (es) at one time. An ap-
plication can have multiple processes that access/share the single
application VDA driver resource and connections to the (es).
• Multi-“application” VDA drivers would allow two or more diagnos-
tic tools (e.g., CAT ET, Eaton ServiceRanger, MeritorWABCO
Toolbox, etc.) to run simultaneously.
RP1210 has always had a requirement to support at least 16 “clients.”

The intent of these “clients” was to support multiple connections from
one application or a single vendor's suite of cooperating applica-
tions. RP1210 was not intended to support arbitrary simultaneous
connections from multiple vendor’s applications. For example, an
engine diagnostic application may consist of several processes
connecting to the VDA because these processes are designed to
work together. RP1210 does not intend to “require” the support of
an engine, transmission and ABS diagnostic application running
simultaneously. It is not practical for OEM application developers
or VDA vendors to test this level of interoperability.
Automatic Bit Rate Detection Allows an application to connect through a protocol to a databus
that is running at any commonly defined speed for that protocol.
Therefore, the application does not have to try connecting serially to
the databus at each speed supported by that VDA for that protocol
and worry about causing databus errors (e.g., CAN error frames).
See also J1939-13 which defines the F, G pins of the HD diagnostic
connector and J1939-14 which defines the J1939 protocol at 500k.
(Automatic bit rate detection was included in RP 1210C because
of the implementation of J1939-14—500k J1939 using unshielded
twisted pair.)
Big Endian (MSB)

or Motorola Format Integers Also referred to in the document as the “most significant byte (MSB)
first format.” A format for representing integral bytes of data, con-
ventionally used in Motorola microprocessors, where the bytes are
numbered from left to right. (The Intel format, called Little Endian,
numbers the bytes from right to left. See Little Endian.)
MSB/Motorola 2-Byle Integer Format MSB/Motorola 4-Byte Integer Format

Byte 0 Byte 1 Byte 0 Byte 1 Byte 2 Byte 3
©2011—TMC/ATA
Client A “logical” connection to an onboard vehicle databus provided
through a VDA via a call to RP1210_ClientConnect(). A VDA driver
must support 16 clients connected through their VDA at one time.
In the RP1210 Multi-Application Addendum (extension to RP1210),
these 16 clients can be from these different applications.
DLL Dynamic Link Library. A DLL is an implementation of an API and is

a mechanism to link applications to libraries at run-time instead of
at compile-time. The libraries are separate files and are not copied
into an application’s executable as with static linking. These librar-
ies are called dynamic-link libraries (DLL) to emphasize that they
are linked to an application when it is loaded and executed, rather
than when linked.
ECM Electronic Control Module. Synonymous with ECU. Sometimes

mistakenly referred to as Engine Control Module, which is also
categorized as an ECM/ECU.
ECU Electronic Control Unit. The electronic control that will be com-
municated with (e.g,. engine, brakes, transmission). This term is
used throughout this document. You will see the term TCM/TCU,
BCM/BCU for transmission and body controllers as well as other
flavors of xCM/xCU. They are all categorized as “generic” ECU/
ECM’s.
Event-driven Architecture An operating system architecture that revolves around a messaging

scheme governed by system events (a mouse click, a keyboard
press are all examples of events). When an application receives
an event directed to it, either from the operating system or another
application or driver, it executes the code associated with that event.
Windows™ architecture is modeled on this paradigm.
INI Initialization file. This file contains information about every VDA
vendors’ API, such as protocols supported, communications ports
supported, etc. See the section on INI files for the layout of the INI
files used by the API.
Interface box A legacy term used to refer to hardware components that translate
between the RS-485 J1708 vehicle datalink and an RS-232 port on
a PC or other device. These are sometimes called “dumb boxes,”
as they do nothing but signal shifting. Most new interface boxes are
no longer “dumb boxes”, but specialty devices called VDA’s (see
VDA). However, some still lump VDA into the category of “interface
boxes.”
Little Endian (LSB) or

Intel Format Integers Least significant byte first format. A format for representing integral
bytes of data, conventionally used in Intel microprocessors, where
the bytes are numbered from right to left. (The Motorola format, called
Big Endian, numbers bytes from left to right. See Big Endian.)
LSB/Intel 2-Byle Integer Format LSB/Intel 4-Byte Integer Format

Byte 1 Byte 0 Byte 3 Byte 2 Byte 1 Byte 0
©2011—TMC/ATA
Multitasking operating system An operating system that allows multiple processes to execute at a
given time. Such an operating system divides its time and resources
between the different running processes. Typically, time-slicing
makes it difficult to do dedicated real-time processing with such
systems. Windows™ is an example of such an operating system.
Network Protocol A documented standard for network communications. Examples of

network protocol standards in the automotive industry: SAE J1587,
J1708, J1939, J1850, ISO15765; CAN (Controller Area Network)
Real-time Processing/Communication Computation that requires operations to be performed at a high

speed (often of the order of milliseconds) and, at times, in an un-
conditionally prioritized manner. This kind of processing is typical
of PC to vehicle datalink communications.
RP1210 Specification allowing 16 client connections from one application.

This is referred to as Single Application.
RP1210 Multi-Application Specification allowing 16 client connections from up to 16 different

applications. This is referred to as Multi-Application and is covered
in the Multi-Application Addendum.
RS-232 A term usually used in reference to the communication ports

available on most PCs. Formally defined as the “Recommended
Standard” 232 in the ANSI (American National Standard Institution)
specification as “the interface between data terminal equipment
and data circuit-terminating equipment employing serial binary data
interchange.”
RS-485 A term used in reference to a communication (COM) port available

on some PCs. Formally, “Recommended Standard” 485 in the ANSI
specification that defines a transmission scheme. This standard is
widely utilized in the trucking industry for interfacing with the vehicle
datalink.
TCP/IP Transport Control Protocol/Internet Protocol. Some vehicle adapt-

ers allow connecting to a vehicle using this methodology.
USB Universal Serial Bus. A high-speed serial bus coming into preva-
lence in the PC to peripheral intercommunications market.
VDA Vehicle Datalink Adapter. The physical device, when connected to the
vehicle , provides translation between the and that vendors’ API.
Windows™ A registered trademark (™) of the Microsoft Corporation. This term

will refer to operating systems that will be supported under this RP.
Non-Windows operating system support is covered in the “Non
Windows Cross Platform Addendum”.
©2011—TMC/ATA
29. REFERENCES
• ISO/FDIS 15765-2 “Road vehicles – Diagnostics on Controller Area Networks – Part 2 – Network layer
services”
• ISO 14230, “Road Vehicles - Diagnostic Systems – Keyword.”
• ISO 9141, “Road Vehicles – Diagnostic Systems.”
• SAE J1708, “Serial Data Communications Between Microcomputer Systems in Heavy-Duty Vehicle
Applications.”
• SAE J1587, “Joint SAE/TMC Electronic Data Interchange Between Microcomputer Systems in Heavy-
Duty Vehicle Applications.”
• SAE J1850, “Class B Data Communications Network Interface.”
• SAE J1939, “A Series of Practices relating to a Serial Control and Communications Vehicle Network.”
• SAE J2534, “Recommended Practice for Pass-Thru Vehicle Programming.”
• TMC RP1208C, PC Service Tool: Hardware Selection Guidelines.
©2011—TMC/ATA

Recommended Practice: Windows™ Communication Api

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Recommended Practice: Windows™ Communication Api

Uploaded by

Copyright:

Available Formats

Recommended Practice

Proposed RP 1210C(T) VMRS 053

WINDOWS™ COMMUNICATION API

©2011—TMC/ATA Issued 4/1997

2. PURPOSE AND SCOPE 3.1 BACKWARDS COMPATIBILITY

Fig. 5-1: TMC RP 1210 Interface Concept Implementation Model

File Type Install Directory Resultant File Name

7. RP 1210 OVERVIEW FOR THE APPLICATION DEVELOPER

7.1 API INTERFACE AT A GLANCE

Function Name Description

7.2 STEP 1—APPLICATION PARSING OF THE RP1210 INI FILES

7.3 STEP 2—Asking User Which Adapter to Use (or Auto-Detecting)

7.4 STEP 3—OPENING DLL and Getting Function Pointers

/*GLOBAL VARIABLE*/ fxRP1210_ClientConnect pRP1210_ClientConnect = NULL;

if ( ( hRP1210DLL = LoadLibrary( szDLLName ) ) == NULL )

7.5 Step 4— Connecting to the DATABUS

nClientID = pRP1210_ClientConnect( NULL_WINDOW, nUserDevice, szProtocol, 0, 0, 0 );

if ( ( nClientID >= 0 ) && ( nClientID <= 127 ) )

7.6 Step 5—Allow Reception of Messages

nRetVal = pRP1210_SendCommand(RP1210_Set_All_Filters_States_to_Pass, nClientID, NULL, 0 );

7.7 Step 6—Read a Message

nRetVal = pRP1210_ReadMessage( nClientID,(char*) &ucTxRxBuffer[0], sizeof(ucTxRxBuffer),

if( nRetVal < 0 )

nRetVal = pRP1210_SendMessage( nClientID,(char *) &ucTxRxBuffer[0], nMessageSize, 0,

7.9 Step 8—Closing the Interface and Freeing Resources

if ( FreeLibrary( (HMODULE) hRP1210DLL ) == 0 )

8. RP 1210 Variables and Initial States

Variable/Topic Initial State on Connect Description

8.2. J1708Mode and RP 1210B Enhancements

8.3. ISO9141/KWP2000 Mode

8.5. Blocking Mode

8.6. Blocking Timeout

9. RP 1210 REQUIRED FUNCTIONS

The required functionality is constituted by the following set of functions:

10. VDA AND Application Developer NOTES

10.1 Unexpected Vehicle Interface Adapter Disconnect

In severe cases the client application may be required to do the following:

10.2. Error Code 142 and Backwards Compatibility

Some of the points raised during discussions on this question included:

The following paragraph deals with RP1210B/C applications:

Also refer to Section 18 on RP1210_GetLastErrorMsg.

10.3. Notes on CAN/J1939 and ISO15765 Coexistence

10.3.1. RP1210B and ISO15765 Compatibility Issue

An RP1210_SendCommand (RP1210_Get_Wireless_State) has been added so that if an application has

10.5. Notes on Windows 64-bit Machines and INI Files

10.6. The “Name” Parameter in the “VendorInformation” INI Section

101 – McLovin Lightsaber – USB

10.7. Notes on CAN and CAN-Based Protocols (e.g., SAE J2284)

10.8. Notes on J1939 Address Claim (Single Application)

10.8.1. Possible Transport Protocol Layer Conflict and Resolution

10.9. Notes on J1939 at 500k (J1939-14) and Auto Speed Detection

NOTE: Applications should never issue a RP1210_ClientConnect( "Protocol:Baud=XXX" ) to a CAN/J1939

A new variable [VendorInformation]->CANAutoBaud=[TRUE/FALSE] has been created in the vendor INI

10.10. Applications Doing Auto-VDA-Detection (Not Recommended)

10.11. Blocking/Non-Blocking Considerations for App Developers

10.13. Filter State Ambiguities

10.14. Filter Clarifications – More Than 1 Per SendCommand() Call

10.14.1. J1708/J1587 Parameter ID (PID) Filtering

10.14.2. Inclusive and Exclusive Filtering

10.16. INI File Versus Registry and XML

10.17. nIsAppPacketizingIncomingMsgs and J1939 Transport Protocol

10.18. RP 1210 Compliancy Testing “Application”

10.19. Windows Vista/Windows 7 and RP 1210-Compliancy

/GLOBAL VARIABLE/ fxRP1210_ClientConnect pRP1210_ClientConnect = NULL;