348 lines
19 KiB
Plaintext
348 lines
19 KiB
Plaintext
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:
|
||
<EFBFBD> PASS_FILTERs and BLOCK_FILTERs will be applied to all received messages. They shall not be
|
||
applied to indications or loopback messages
|
||
|
||
<EFBFBD> FLOW_CONTROL_FILTERs must not be used and shall cause the interface to return
|
||
ERR_INVALID_FILTER_ID
|
||
|
||
<EFBFBD> Both pMaskMsg and pPatternMsg must have the same DataSize and TxFlags. Otherwise, the
|
||
interface shall return ERR_INVALID_MSG
|
||
|
||
<EFBFBD> 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
|
||
|
||
<EFBFBD> Figure 16 and Figure 17 show how the message filtering mechanism operates
|
||
|
||
For ISO 15765:
|
||
<EFBFBD> PASS_FILTERs and BLOCK_FILTERs must not be used and shall cause the interface to return
|
||
ERR_INVALID_FILTER_ID
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> Non-segmented messages do not need to match a FLOW_CONTROL_FILTER.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> All 3 message pointers must have the same DataSize and TxFlags. Otherwise, the interface shall
|
||
return ERR_INVALID_MSG.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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:
|
||
<EFBFBD> DataSize violates Min Tx or Max Tx columns in Figure 42
|
||
|
||
<EFBFBD> Source address (Data[3]) is different from the Node ID (Ioctl SET_CONFIG, Parameter NODE_ADDRESS) on J1850PWM
|
||
|
||
<EFBFBD> The header length field is incorrect for the number of bytes in the message on ISO14230
|
||
|
||
<EFBFBD> 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:
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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:
|
||
<EFBFBD> ExtraDataIndex must be zero
|
||
|
||
<EFBFBD> DataSize shall tell the application how many bytes in the Data array are valid
|
||
|
||
<EFBFBD> RxStatus must be consulted to determine the indication type (See Section 8.4).
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> An RxBreak indication (SAE J2610/SCI and SAE J1850VPW only) is generated by the DLL if a break
|
||
is received.
|
||
|
||
<EFBFBD> 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
|
||
<EFBFBD>J2534.DLL<4C>. All implementations shall have the string <20>32<33> suffixed to end of the name of the API DLL to
|
||
indicate 32-bit. For example, if the company name is <20>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<6F>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:
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> Transmit the message data in ConsecutiveFrames according to the FlowControl frame<6D>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.
|
||
|
||
<EFBFBD> Repeat the previous two steps as required.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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<49>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<73>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:
|
||
|
||
<EFBFBD> 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.
|
||
|
||
<EFBFBD> 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<65>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.
|
||
|
||
<EFBFBD> Wait for the conversation partner to send C
|
||
onsecutiveFrames containing the actual data. The
|
||
partner<EFBFBD>s CAN ID is specified in pPatternMsg. In our example, this CAN ID is $641.
|
||
|
||
<EFBFBD> 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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|