Code Review
/
apps
/
agl-service-can-low-level.git
/ commitdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
| commitdiff |
review
|
tree
raw
|
patch
|
inline
| side by side (parent:
cf5710b
)
Update docs in README.
author
Christopher Peplin
<chris.peplin@rhubarbtech.com>
Fri, 3 Jan 2014 18:18:06 +0000
(13:18 -0500)
committer
Christopher Peplin
<chris.peplin@rhubarbtech.com>
Fri, 3 Jan 2014 18:18:06 +0000
(13:18 -0500)
README.mkd
patch
|
blob
|
history
diff --git
a/README.mkd
b/README.mkd
index
d374c35
..
1e2c29a
100644
(file)
--- a/
README.mkd
+++ b/
README.mkd
@@
-1,32
+1,63
@@
ISO-TP (ISO 15765-2) Support Library in C
================================
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) {
...
}
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)) {
...
}
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.
}
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) {
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:
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) {
}
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.
## Testing
The library includes a test suite that uses the `check` C unit test library.