diff options
Diffstat (limited to 'CAN-binder/libs/isotp-c/README.mkd')
| -rw-r--r-- | CAN-binder/libs/isotp-c/README.mkd | 142 |
1 files changed, 0 insertions, 142 deletions
diff --git a/CAN-binder/libs/isotp-c/README.mkd b/CAN-binder/libs/isotp-c/README.mkd deleted file mode 100644 index 98030483..00000000 --- a/CAN-binder/libs/isotp-c/README.mkd +++ /dev/null @@ -1,142 +0,0 @@ -ISO-TP (ISO 15765-2) Support Library in C -================================ - -This is a platform agnostic C library that implements the ISO 15765-2 (also -known as ISO-TP) protocol, which runs over a CAN bus. Quoting Wikipedia: - ->ISO 15765-2, or ISO-TP, is an international standard for sending data packets ->over a CAN-Bus. The protocol allows for the transport of messages that exceed ->the eight byte maximum payload of CAN frames. ISO-TP segments longer messages ->into multiple frames, adding metadata that allows the interpretation of ->individual frames and reassembly into a complete message packet by the ->recipient. It can carry up to 4095 bytes of payload per message packet. - -This library doesn't assume anything about the source of the ISO-TP messages or -the underlying interface to CAN. It uses dependency injection to give you -complete control. - -The current version supports *only single frame ISO-TP messages*. This is fine -for OBD-II diagnostic messages, for example, but this library needs some -additional work before it can support sending larger messages. - -## Usage - -First, create some shim functions to let this library use your lower level -system: - - // required, this must send a single CAN message with the given arbitration - // ID (i.e. the CAN message ID) and data. The size will never be more than 8 - // bytes. - void send_can(const uint16_t arbitration_id, const uint8_t* data, - const uint8_t size) { - ... - } - - // optional, provide to receive debugging log messages - void debug(const char* format, ...) { - ... - } - - - // not used in the current version - void set_timer(uint16_t time_ms, void (*callback)) { - ... - } - -With your shims in place, create an IsoTpShims object to pass them around: - - IsoTpShims shims = isotp_init_shims(debug, send_can, set_timer); - -### API - -With your shims in hand, send an ISO-TP message: - - // Optional: This is your callback that will be called when the message is - // completely sent. If it was single frame (the only type supported right - // now), this will be called immediately. - void message_sent(const IsoTpMessage* message, const bool success) { - // You received the message! Do something with it. - } - - IsoTpSendHandle handle = isotp_send(&shims, 0x100, NULL, 0, message_sent); - - if(handle.completed) { - if(!handle.success) { - // something happened and it already failed - possibly we aren't able to - // send CAN messages - return; - } else { - // If the message fit in a single frame, it's already been sent - // and you're done - } - } else { - while(true) { - // Continue to read from CAN, passing off each message to the handle - // this will return true when the message is completely sent (which - // may take more than one call if it was multi frame and we're waiting - // on flow control responses from the receiver) - bool complete = isotp_continue_send(&shims, &handle, 0x100, data, size); - - if(complete && handle.completed) { - if(handle.success) { - // All frames of the message have now been sent, following - // whatever flow control feedback it got from the receiver - } else { - // the message was unable to be sent and we bailed - fatal - // error! - } - } - } - } - -Finally, receive an ISO-TP message: - - // Optional: This is your callback for when a complete ISO-TP message is - // received at the arbitration ID you specify. The completed message is - // also returned by isotp_continue_receive, which can sometimes be more - // useful since you have more context. - void message_received(const IsoTpMessage* message) { - } - - IsoTpReceiveHandle handle = isotp_receive(&shims, 0x100, message_received); - if(!handle.success) { - // something happened and it already failed - possibly we aren't able to - // send CAN messages - } else { - while(true) { - // Continue to read from CAN, passing off each message to the handle - IsoTpMessage message = isotp_continue_receive(&shims, &handle, 0x100, data, size); - - if(message.completed && handle.completed) { - if(handle.success) { - // A message has been received successfully - } else { - // Fatal error - we weren't able to receive a message and - // gave up trying. A message using flow control may have - // timed out. - } - } - } - } - -## Testing - -The library includes a test suite that uses the `check` C unit test library. - - $ make test - -You can also see the test coverage if you have `lcov` installed and the -`BROWSER` environment variable set to your choice of web browsers: - - $ BROWSER=google-chrome-stable make coverage - -## Authors - -* Chris Peplin cpeplin@ford.com -* David Boll dboll2@ford.com (the inspiration for the library's API is from David) - -## License - -Copyright (c) 2013 Ford Motor Company - -Licensed under the BSD license. |