README.mkd

   1 ISO-TP (ISO 15765-2) Support Library in C
   2 ================================
   3
   4 ## API
   5
   6 First, set up some shim functions to your lower level system:
   7
   8     void debug(const char* format, ...) {
   9         ...
  10     }
  11
  12     void send_can(const uint16_t arbitration_id, const uint8_t* data,
  13             const uint8_t size) {
  14         ...
  15     }
  16
  17     void set_timer(uint16_t time_ms, void (*callback)) {
  18         ...
  19     }
  20
  21 Then, set up a callback and send an ISO-TP message:
  22
  23     // this is your callback for when the message is completely sent - it's
  24     // optional
  25     void message_sent(const IsoTpMessage* message, const bool success) {
  26         // You received the message! Do something with it.
  27     }
  28
  29     IsoTpShim shims = isotp_init_shims(debug, send_can, set_timer);
  30     IsoTpHandle handle = isotp_send(&shims, 0x100, NULL, 0, message_sent);
  31
  32     if(handle.completed) {
  33         if(!handle.success) {
  34             // something happened and it already failed - possibly we aren't able to
  35             // send CAN messages
  36             return;
  37         } else {
  38             // If the message fit in a single frame, it's already been sent and
  39             you're done
  40         }
  41     } else {
  42         while(true) {
  43             // Continue to read from CAN, passing off each message to the handle
  44             bool complete = isotp_receive_can_frame(&shims, &handle, 0x100, data, size);
  45
  46             if(complete && handle.completed) {
  47                 if(handle.success) {
  48                     // All frames of the message have now been sent, following
  49                     // whatever flow control feedback it got from the receiver
  50                 } else {
  51                     // the message was unable to be sent and we bailed - fatal
  52                     // error!
  53                 }
  54             }
  55         }
  56     }
  57
  58 Finally, receive an ISO-TP message:
  59
  60     // This is your callback for when a complete ISO-TP message is received at
  61     // the arbitration ID you specify - it's optional. The completed message is
  62     // also returned by isotp_receive_can_frame
  63     void message_received(const IsoTpMessage* message) {
  64     }
  65
  66     IsoTpHandle handle = isotp_receive(&shims, 0x100, message_received);
  67     if(!handle.success) {
  68         // something happened and it already failed - possibly we aren't able to
  69         // send CAN messages
  70     } else {
  71         while(true) {
  72             // Continue to read from CAN, passing off each message to the handle
  73             IsoTp message = isotp_receive_can_frame(&shims, &handle, 0x100, data, size);
  74
  75             if(message.completed && handle.completed) {
  76                 if(handle.success) {
  77                     // A message has been received successfully
  78                 } else {
  79                     // Fatal error - we weren't able to receive a message and
  80                     // gave up trying. A message using flow control may have
  81                     // timed out.
  82                 }
  83             }
  84         }
  85     }
  86
  87 // TODO add an optional dispatcher to handle multiple open requests
  88
  89 ## Testing
  90
  91 The library includes a test suite that uses the `check` C unit test library.
  92
  93     $ make test
  94
  95 ## Authors
  96
  97 Chris Peplin cpeplin@ford.com
  98
  99 ## License
 100
 101 Copyright (c) 2013 Ford Motor Company
 102
 103 Licensed under the BSD license.