libs/isotp-c/README.mkd

   1 ISO-TP (ISO 15765-2) Support Library in C
   2 ================================
   3
   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:
   6
   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.
  13
  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
  16 complete control.
  17
  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.
  21
  22 ## Usage
  23
  24 First, create some shim functions to let this library use your lower level
  25 system:
  26
  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
  29     // bytes.
  30     void send_can(const uint16_t arbitration_id, const uint8_t* data,
  31             const uint8_t size) {
  32         ...
  33     }
  34
  35     // optional, provide to receive debugging log messages
  36     void debug(const char* format, ...) {
  37         ...
  38     }
  39
  40
  41     // not used in the current version
  42     void set_timer(uint16_t time_ms, void (*callback)) {
  43         ...
  44     }
  45
  46 With your shims in place, create an IsoTpShims object to pass them around:
  47
  48     IsoTpShims shims = isotp_init_shims(debug, send_can, set_timer);
  49
  50 ### API
  51
  52 With your shims in hand, send an ISO-TP message:
  53
  54     // Optional: 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.
  59     }
  60
  61     IsoTpSendHandle handle = isotp_send(&shims, 0x100, NULL, 0, message_sent);
  62
  63     if(handle.completed) {
  64         if(!handle.success) {
  65             // something happened and it already failed - possibly we aren't able to
  66             // send CAN messages
  67             return;
  68         } else {
  69             // If the message fit in a single frame, it's already been sent
  70             // and you're done
  71         }
  72     } else {
  73         while(true) {
  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);
  79
  80             if(complete && handle.completed) {
  81                 if(handle.success) {
  82                     // All frames of the message have now been sent, following
  83                     // whatever flow control feedback it got from the receiver
  84                 } else {
  85                     // the message was unable to be sent and we bailed - fatal
  86                     // error!
  87                 }
  88             }
  89         }
  90     }
  91
  92 Finally, receive an ISO-TP message:
  93
  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) {
  99     }
 100
 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
 104         // send CAN messages
 105     } else {
 106         while(true) {
 107             // Continue to read from CAN, passing off each message to the handle
 108             IsoTpMessage message = isotp_continue_receive(&shims, &handle, 0x100, data, size);
 109
 110             if(message.completed && handle.completed) {
 111                 if(handle.success) {
 112                     // A message has been received successfully
 113                 } else {
 114                     // Fatal error - we weren't able to receive a message and
 115                     // gave up trying. A message using flow control may have
 116                     // timed out.
 117                 }
 118             }
 119         }
 120     }
 121
 122 ## Testing
 123
 124 The library includes a test suite that uses the `check` C unit test library.
 125
 126     $ make test
 127
 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:
 130
 131     $ BROWSER=google-chrome-stable make coverage
 132
 133 ## Authors
 134
 135 * Chris Peplin cpeplin@ford.com
 136 * David Boll dboll2@ford.com (the inspiration for the library's API is from David)
 137
 138 ## License
 139
 140 Copyright (c) 2013 Ford Motor Company
 141
 142 Licensed under the BSD license.