1 ISO-TP (ISO 15765-2) Support Library in C
2 ================================
4 This is a platform agnostic C library that implements the ISO 15765-2 (also
5 known as ISO-TP) protocol, which runs over a CAN bus. Quoting Wikipedia:
7 >ISO 15765-2, or ISO-TP, is an international standard for sending data packets
8 >over a CAN-Bus. The protocol allows for the transport of messages that exceed
9 >the eight byte maximum payload of CAN frames. ISO-TP segments longer messages
10 >into multiple frames, adding metadata that allows the interpretation of
11 >individual frames and reassembly into a complete message packet by the
12 >recipient. It can carry up to 4095 bytes of payload per message packet.
14 This library doesn't assume anything about the source of the ISO-TP messages or
15 the underlying interface to CAN. It uses dependency injection to give you
18 The current version supports *only single frame ISO-TP messages*. This is fine
19 for OBD-II diagnostic messages, for example, but this library needs some
20 additional work before it can support sending larger messages.
24 First, create some shim functions to let this library use your lower level
27 // required, this must send a single CAN message with the given arbitration
28 // ID (i.e. the CAN message ID) and data. The size will never be more than 8
30 void send_can(const uint16_t arbitration_id, const uint8_t* data,
35 // optional, provide to receive debugging log messages
36 void debug(const char* format, ...) {
41 // not used in the current version
42 void set_timer(uint16_t time_ms, void (*callback)) {
46 With your shims in place, create an IsoTpShims object to pass them around:
48 IsoTpShims shims = isotp_init_shims(debug, send_can, set_timer);
52 With your shims in hand, send an ISO-TP message:
54 // Optiona: This is your callback that will be called when the message is
55 // completely sent. If it was single frame (the only type supported right
56 // now), this will be called immediately.
57 void message_sent(const IsoTpMessage* message, const bool success) {
58 // You received the message! Do something with it.
61 IsoTpSendHandle handle = isotp_send(&shims, 0x100, NULL, 0, message_sent);
63 if(handle.completed) {
65 // something happened and it already failed - possibly we aren't able to
69 // If the message fit in a single frame, it's already been sent and
74 // Continue to read from CAN, passing off each message to the handle
75 // this will return true when the message is completely sent (which
76 // may take more than one call if it was multi frame and we're waiting
77 // on flow control responses from the receiver)
78 bool complete = isotp_continue_send(&shims, &handle, 0x100, data, size);
80 if(complete && handle.completed) {
82 // All frames of the message have now been sent, following
83 // whatever flow control feedback it got from the receiver
85 // the message was unable to be sent and we bailed - fatal
92 Finally, receive an ISO-TP message:
94 // Optional: This is your callback for when a complete ISO-TP message is
95 // received at the arbitration ID you specify. The completed message is
96 // also returned by isotp_continue_receive, which can sometimes be more
97 // useful since you have more context.
98 void message_received(const IsoTpMessage* message) {
101 IsoTpReceiveHandle handle = isotp_receive(&shims, 0x100, message_received);
102 if(!handle.success) {
103 // something happened and it already failed - possibly we aren't able to
107 // Continue to read from CAN, passing off each message to the handle
108 IsoTpMessage message = isotp_continue_receive(&shims, &handle, 0x100, data, size);
110 if(message.completed && handle.completed) {
112 // A message has been received successfully
114 // Fatal error - we weren't able to receive a message and
115 // gave up trying. A message using flow control may have
124 The library includes a test suite that uses the `check` C unit test library.
128 You can also see the test coverage if you have `lcov` installed and the
129 `BROWSER` environment variable set to your choice of web browsers:
131 $ BROWSER=google-chrome-stable make coverage
135 Chris Peplin cpeplin@ford.com
139 Copyright (c) 2013 Ford Motor Company
141 Licensed under the BSD license.