When using the ISO 15765-4 protocol, only SingleFrame messages can be transmitted without a matching flow control filter. Also, PCI bytes are transparently added by the API. See PassThruStartMsgFilter and Appendix A for a discussion of flow control filters. PassThruReadMsgs This function reads messages and indications from the receive buffer. All messages and indications shall be read in the order that they occurred on the bus. If a transmit message generated a loopback message and TxDone indication, the TxDone indication shall always be queued first. Except for loopback messages and indications, no messages shall be queued for reception without matching a PASS_FILTER (for non-ISO 15765) or FLOW_CONTROL filter (for ISO 15765). On ISO 15765, PCI bytes are transparently removed by the API. If the function is successful, a value of STATUS_NOERROR is returned. PassThruWriteMsgs Write timeout (in milliseconds). When a value of 0 is specified, the function queues as many of the specified messages as possible and returns immediately. When a value greater than 0 is specified, the function will block until the Timeout has expired, an error has occurred, or the desired number of messages have been transmitted on the vehicle network. Even if the device can buffer only one packet at a time, this function shall be able to send an arbitrary number of packets if a Timeout value is supplied. Since the function returns early if all the messages have been sent, there is normally no penalty for having a large timeout (several seconds). If the number of messages requested have been written, the function shall not return ERR_TIMEOUT, even if the timeout value is zero. When an ERR_TIMEOUT is returned, only the number of messages that were sent on the vehicle network is known. The number of messages queued is unknown. Application writers should avoid this ambiguity by using a Timeout value large enough to work on slow devices and networks with arbitration delays. PassThruStartPeriodicMsg This function will immediately queue the specified message for transmission, and repeat at the specified interval. Periodic messages are limited in length to a single frame message of 12 bytes or less, including header or CAN ID. Periodic messages shall have priority over messages queued with PassThruWriteMsgs, but periodic messages must not violate bus idle timing parameters (e.g. P3_MIN). Periodic messages shall generate TxDone indications (ISO 15765) and loopback messages (on any protocol, if enabled). On ISO 15765, periodic messages can be sent during a multi-frame transmission or reception. If the function is successful, a value of STATUS_NOERROR is returned. The Pass-Thru device must support a minimum of ten periodic messages. PassThruDisconnect shall delete all periodic messages on that channel. PassThruClose shall delete all periodic messages on all channels for the device. All periodic messages will be stopped on a PassThruDisconnect for the associated protocol or a PassThruClose for the device. PASSTHRUSTARTMSGFILTER This function starts filtering of incoming messages. If the function is successful, a value of STATUS_NOERROR is returned. A minimum of ten message filters shall be supported by the interface for each supported protocol. PassThruDisconnect shall delete all message filters on that channel. PassThruClose shall delete all filters on all channels for the device. Pattern and Mask messages shall follow the protocol formats specified in Section 8. However, only the first twelve (12) bytes, including header or CAN ID, are used by the filter. ERR_INVALID_MSG shall be returned if the filter length exceeds 12. Note that this function does not clear any messages that may have been received and queued before the filter was set. Users are cautioned to consider performing a CLEAR_RX_BUFFER after starting a message filter to be sure that unwanted frames are purged from any receive buffers. FILTER RELATED STUFF For all protocols except ISO 15765: • PASS_FILTERs and BLOCK_FILTERs will be applied to all received messages. They shall not be applied to indications or loopback messages • FLOW_CONTROL_FILTERs must not be used and shall cause the interface to return ERR_INVALID_FILTER_ID • Both pMaskMsg and pPatternMsg must have the same DataSize and TxFlags. Otherwise, the interface shall return ERR_INVALID_MSG • The default filter behavior after PassThruConnect is to block all messages, which means no messages will be placed in the receive queue until a PASS_FILTER has been set. Messages that match a PASS_FILTER can still be blocked by a BLOCK_FILTER • Figure 16 and Figure 17 show how the message filtering mechanism operates For ISO 15765: • PASS_FILTERs and BLOCK_FILTERs must not be used and shall cause the interface to return ERR_INVALID_FILTER_ID • Filters shall not be applied to indications or loopback messages. When loopback is on, the original message shall be copied to the receive queue upon the last segment being transmitted on the bus. • Non-segmented messages do not need to match a FLOW_CONTROL_FILTER. • No segmented messages can be transmitted without matching an appropriate FLOW_CONTROL_FILTER. An appropriate filter is one in which the pFlowControlMsg CAN ID matches the messages to be transmitted. Also, the ISO 15765_ADDR_TYPE (reference TxFlags in Section 8.7.3) bits must match. If that bit is set, the first byte after the CAN IDs (the extended address) must match too. • No message (segmented or unsegmented) shall be received without matching an appropriate FLOW_CONTROL_FILTER. An appropriate filter is one in which the pPatternMsg CAN ID matches the incoming message ID. If the ISO 15765_ADDR_TYPE (reference TxFlags in Section 8.7.3) bit is set in the filter, the first byte after the CAN IDs (the extended address) must match too. • All 3 message pointers must have the same DataSize and TxFlags. Otherwise, the interface shall return ERR_INVALID_MSG. • Both the pFlowControlMsg ID and the pPatternMsg ID must be unique (not match any IDs in any other filters). The only exception is that pPatternMsg can equal pFlowControlMsg to allow for receiving functionally addressed messages. In this case, only non-segmented messages can be received. • See Appendix A for a detailed description of flow control filter usage. 8.4 Format Checks for Messages Passed to the API The vendor DLL shall validate all PASSTHRU_MSG structures, and return an ERR_INVALID_MSG in the following cases: • DataSize violates Min Tx or Max Tx columns in Figure 42 • Source address (Data[3]) is different from the Node ID (Ioctl SET_CONFIG, Parameter NODE_ADDRESS) on J1850PWM • The header length field is incorrect for the number of bytes in the message on ISO14230 • The CAN_29_BIT flag of the message does not match the CAN_29_BIT flag passed to PassThruConnect, unless the CAN_ID_BOTH bit was set on connect The vendor DLL shall return ERR_MSG_PROTOCOL_ID when the ProtocolID field in the message does not match the Protocol ID specified when opening the channel. 8.5 Conventions for Returning Messages from the API When returning a message in PassThruReadMsg: – DataSize shall tell the application how many bytes in the Data array are valid. ExtraDataIndex will be the (non-zero) index of the last byte of the message. If ExtraDataIndex is not equal to DataSize there are extra data bytes after the message. If loopback is on, RxStatus must be consulted to tell if the message came via loopback. – DataSize will be in the range shown in the Min Rx and Max Rx columns of Figure 42. If the device receives a message from the vehicle bus that is too long or too short, the message shall be discarded with no error. – For received messages, ExtraDataIndex shall be equal to DataSize, except when the interface is returning SAE J1850 PWM IFR bytes. In no case shall ExtraDataIndex be larger than DataSize. – When receiving a message on an SAE J1850 PWM channel, the message shall have any IFR bytes appended. In this case, ExtraDataIndex shall be the index of the first IFR byte, and DataSize shall be the total length of the original message plus all IFR bytes. For example, if there are two IFR bytes, DataSize will be incremented by two, and ExtraDataIndex will be DataSize - 2. When loopback is on, the loopback message shall contain any IFR bytes. 8.6 Conventions for Retuning Indications from the API When returning an indication in PassThruReadMsg: – ExtraDataIndex must be zero – DataSize shall tell the application how many bytes in the Data array are valid – RxStatus must be consulted to determine the indication type (See Section 8.4). – A TxDone indication (ISO 15765 only) is generated by the DLL after a SingleFrame message is sent, or the last frame of a multi-segment transmission is sent. DataSize shall be 4 (or 5 when the message was using Extended Addressing). Data shall contain the CAN ID (and possible Extended Address) of the message just sent. If loopback is on, the TxDone indication shall precede the loopback message in the receive queue. – An RxBreak indication (SAE J2610/SCI and SAE J1850VPW only) is generated by the DLL if a break is received. – An RxStart indication is generated by the DLL when starting to receive a message on ISO9141 or ISO14230, or when receiving the FirstFrame signal of a multi-segment ISO 15765 message. 9.1 Naming of Files Each vendor will provide a different name implementation of the API DLL and a number of these implementations could simultaneously reside on the same PC. No vendor shall name its implementation “J2534.DLL”. All implementations shall have the string “32” suffixed to end of the name of the API DLL to indicate 32-bit. For example, if the company name is “Vendor X” the name could be VENDRX32.DLL. For simplicity, an API DLL shall be named in accordance with the file allocation table (FAT) file system naming convention (which allows up to eight characters for the file name and three characters for the extension with no spaces anywhere). Note that, given this criteria, the major name of an API DLL can be no greater than six characters. The OEM application can determine the name of the appropriate vendor’s DLL using the Win32 Registry mechanism described in this section. A.1 Flow Control Overview ISO 15765-2 was designed to send blocks of up to 4095 bytes on top of the limited 8-byte payload of raw CAN frames. If the data is small enough, it can fit in a single frame and be transmitted like a raw CAN message with additional headers. Otherwise, the block is broken up into segments and becomes a segmented transmission, generating CAN frames in both directions. For flexibility, the receiver of the segments can control the rate at which the segments are sent. Each transmission is actually part of a conversation between two nodes. There is no discovery mechanism for conversation partners. Therefore, each desired conversation must be pre-defined on each side before the conversation can start. Conversations are symmetric, meaning that either side can send a block of data to the other. A conversation can only have one transfer (in one direction) in progress at a time. One transfer must complete before the next transfer (in the same or in a different direction) can start. The device must support multiple transfers at once, as long as each one is part of a different conversation. Raw CAN frames are not allowed when using ISO15765-2. A key feature of a conversation is that each side has a unique CAN ID, and each side uses their unique CAN ID for all transmissions during the conversation. No other CAN IDs are part of the conversation. Even though the useful data is only flowing in one direction, both sides are transmitting. One side is sending the flow control message to pace the segments of data coming from the other side. For example, during OBD communication, a pass-thru device and an ECU might have a conversation. The pass-thru device will use the "Tester1" physical CAN ID ($241), and the first ECU will use the "ECU1" physical CAN ID ($641). During a multi-segment transfer, both sides will be transmitting using only their respective IDs. It does not matter if the data is being sent by the ECU or by the Tester, the IDs remain the same. It is important to understand the difference between OBD Requests/Responses and ISO 15765-2 transfers. The OBD Request is transmitted from the Tester to the ECU using functional addressing. Because segmented transfer is not possible on functional addresses, the message must fit in a single frame. The OBD Response is a message from the ECU to the Tester using physical addressing. Unlike other protocols, the responses are not sequential. In fact, the responses can overlap, as if each ECU were having a private conversation with the Tester. Some of the responses may fit in a single frame, while others will require a segmented transfer from the ECU to the tester. A.2 Transmitting a Segmented Message When PassThruWrite is called, the API will search the list of flow control filters, looking for a pFlowControlMsg that matches the CAN ID (and possible extended address) of the message being sent. Upon matching a filter, the pass-thru device will: • Start the ISO 15765 transfer by sending a FirstFrame on the bus. The CAN ID of this segment was specified in both the message and the matching pFlowControlMsg. In our example, this is $241. • Wait for a FlowControl frame from the conversation partner. The CAN ID to look for is specified in the corresponding pPatternMsg. In our example, this is $641. • Transmit the message data in ConsecutiveFrames according to the FlowControl frame’s instructions for BS (BlockSize) and STmin (SeparationTime minimum). Again, the pass-thru device transmits using CAN ID specified in pFlowControlMsg. In our example, this is $241. • Repeat the previous two steps as required. • When finished, the pass-thru device will place a TxDone indication in the API receive queue. The data will contain the CAN ID specified in pFlowControlMsg. In our example, this is $241. • If loopback is on, the entire message sent will appear in the API receive queue with the TX_MSG_TYPE bit set to 1 in RxStatus. The loopback shall not precede the TxDone indication. Before any multi-segment transfer can take place, the conversation must be set up on both sides. It’s assumed that the ECU is already setup. The application is responsible for setting up the pass-thru device. This setup must be done once (and only once) per conversation. The setup involves a single call to PassThruStartMsgFilter, with the following parameters: A.2.2 Data Transmission Once the conversation is set up, any number of messages (to the conversation partner) can be transmitted using PassThruWriteMsg. The interface shall handle all aspects of the transfer, including pacing (slowing) the transmission to the requirements of the receiver. When there are multiple conversations setup, the pass-thru device will search all of the flow control filters for a matching pFlowControlMsg. If there is no match, the message cannot be sent because the pass- thru device doesn’t know which partner will be pacing the conversation. When doing blocking writes, it is important to pick a timeout long enough to cover entire transfer, even if the ECU is pacing things slowly. Otherwise PassThruWriteMsg will return with a timeout, even though the transmission is proceeding normally. A.3 Transmitting an Unsegmented Message As a special case, transfers that fit in a single frame can be transmitted without setting up a conversation. This is useful during an OBD Request, which is a functionally addressed message that is broadcast to all ECUs. This message must be small enough to fit into a single frame (including headers) because it is not possible to do one segmented transfer to multiple ECUs. When using functional addressing for an OBD Request, it is important to remember that there can be no direct reply. Instead, each ECU will send their OBD Response using physical addressing to their conversation partner (e.g. ECU1 to Tester1, ECU2 to Tester2) as defined by ISO 15765-4. The OBD Response may be a segmented transfer, or it may be a single frame. In this case, no conversation setup is necessary. The call to PassThruWriteMsg is the same as above, except that the DataSize must be 7 bytes or less (6 bytes or less if extended addressing is turned on). The pass-thru device will automatically insert a PCI byte before transmission. A.4 Receiving a Segmented Message Message reception is asynchronous to the application. When a FirstFrame is seen on the bus, the pass- thru device will search the list of flow control filters, looking for a pPatternMsg message with the same CAN ID (and possible extended address) as the FirstFrame. Upon matching a filter, the pass-thru device will: • Place an RxStart indication in the API receive queue. This indication has the START_OF_MESSAGE bit set in RxFlags. The message data will contain the CAN ID of the sender. In our example, this is $641. DataSize will be 4 bytes (5 with extended addressing), and ExtraDataIndex will be zero. • Send a FlowControl frame to the conversation partner. The FlowStatus field shall be set to ontinueToSend. The CAN ID of this segment comes from the filter’s corresponding pFlowControlMsg. In our example, this CAN ID is $241. The BS (BlockSize) and STmin (SeparationTime minimum) parameters default to zero, but can be changed with the SET_CONFIGIoctl. • Wait for the conversation partner to send C onsecutiveFrames containing the actual data. The partner’s CAN ID is specified in pPatternMsg. In our example, this CAN ID is $641. • Repeat as necessary until the entire block has been received. When finished, the pass-thru device will put the assembled message into the API receive queue. The CAN ID of the assembled message will be the CAN ID of the sender. In our example, this CAN ID is $641. If the FirstFrame does not match any flow control filters, then the message must be ignored by the device. Segmented messages cause the API to generate an RxStart indication. This lets the application know that the device has started message reception. It may take a while before message reception is complete, especially if the application has increased BS and STmin. Once the transfer is complete, the entire message can be read like on any other protocol. Usually, applications will call PassThruReadMsg again immediately after getting an RxStart indication. Application writers should not assume that the complete message will always follow the RxStart indication. If multiple conversations are setup, indications and messages from other conversations can be received in between the RxStart indication and the actual message. The parameters for PassThruReadMsg are exactly the same as in the previous section. The only difference is that the DataSize will be larger and ExtraDataIndex will be non-zero. A.5 Receiving an Unsegmented Message No messages can be received until a conversation is setup. Each conversation setup will receive messages from exactly one CAN ID (and extended address if present). Because setup is bi-directional, the same PassThruStartMsgFilter call used for transmission will allow for message reception. When a SingleFrame is seen on the bus, the pass-thru device will search the list of flow control filters, looking for a pPatternMsg message with the same C AN ID (and possible extended address) as the SingleFrame. Upon matching a filter, the pass-thru device will strip the PCI byte and queue the packet for reception. If the SingleFrame does not match a flow control filter, it must be discarded. The only difference between the previous cases is that single-frame messages do not generate an RxStart indication.