openpilot_comma/panda/drivers/windows/docs/other notes.txt

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<EFBFBD>. All implementations shall have the string <EFBFBD>32<EFBFBD> suffixed to end of the name of the API DLL to
indicate 32-bit. For example, if the company name is <EFBFBD>Vendor X<EFBFBD> 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<EFBFBD>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<EFBFBD>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<EFBFBD>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<EFBFBD>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<EFBFBD>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.