Document how to run coverage.

[apps/agl-service-can-low-level.git] / README.mkd

diff --git a/README.mkd b/README.mkd
index 530ebad..d374c35 100644 (file)
--- a/README.mkd
+++ b/README.mkd
@@ -3,14 +3,88 @@ ISO-TP (ISO 15765-2) Support Library in C
 
 ## API
 
-    IspTpHandler handler = isotp_init(42, NULL, NULL, NULL);
-    isotp_send(const uint8_t* payload, uint16_t payload_size);
-    while(true) {
-        isotp_handle_can_frame(42, data, 8);
+First, set up some shim functions to your lower level system:
+
+    void debug(const char* format, ...) {
+        ...
+    }
+
+    void send_can(const uint16_t arbitration_id, const uint8_t* data,
+            const uint8_t size) {
+        ...
+    }
+
+    void set_timer(uint16_t time_ms, void (*callback)) {
+        ...
+    }
+
+Then, set up a callback and send an ISO-TP message:
+
+    // this is your callback for when the message is completely sent - it's
+    // optional
+    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) {
+        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
+            bool complete = isotp_receive_can_frame(&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:
+
+    // 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
+    void message_received(const IsoTpMessage* message) {
     }
-    isotp_destroy(&handler);
 
-// TODO should handlers take a context? depends on how we want to use this
+    IsoTpHandle 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
+            IsoTp message = isotp_receive_can_frame(&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.
+                }
+            }
+        }
+    }
+
+// TODO add an optional dispatcher to handle multiple open requests
 
 ## Testing
 
@@ -18,6 +92,11 @@ 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