Update docs in README.

1 files changed, 44 insertions, 14 deletions

diff --git a/README.mkd b/README.mkd
index d374c358..1e2c29aa 100644
--- a/README.mkd
+++ b/README.mkd
@@ -1,32 +1,63 @@
 ISO-TP (ISO 15765-2) Support Library in C
 ================================
 
-## API
+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:
 
-First, set up some shim functions to your lower level system:
+>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.
 
-    void debug(const char* format, ...) {
-        ...
-    }
+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)) {
         ...
     }
 
-Then, set up a callback and send an ISO-TP message:
+With your shims in place, create an IsoTpShim object to pass them around:
+
+    IsoTpShim shims = isotp_init_shims(debug, send_can, set_timer);
+
+### API
+
+With your shims in hand, send an ISO-TP message:
 
-    // this is your callback for when the message is completely sent - it's
-    // optional
+    // Optiona: 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.
     }
 
-    IsoTpShim shims = isotp_init_shims(debug, send_can, set_timer);
     IsoTpHandle handle = isotp_send(&shims, 0x100, NULL, 0, message_sent);
 
     if(handle.completed) {
@@ -57,9 +88,10 @@ Then, set up a callback and send an ISO-TP message:
 
 Finally, receive an ISO-TP message:
 
-    // This is your callback for when a complete ISO-TP message is received at
-    // the arbitration ID you specify - it's optional. The completed message is
-    // also returned by isotp_receive_can_frame
+    // 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_receive_can_frame, which can sometimes be more
+    // useful since you have more context.
     void message_received(const IsoTpMessage* message) {
     }
 
@@ -84,8 +116,6 @@ Finally, receive an ISO-TP message:
         }
     }
 
-// TODO add an optional dispatcher to handle multiple open requests
-
 ## Testing
 
 The library includes a test suite that uses the `check` C unit test library.