Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add syntax highlighting to readme #15

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add syntax highlighting to readme #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 82 additions & 74 deletions README.mkd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,100 +24,108 @@ additional work before it can support sending larger messages.
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.
bool send_can(const uint32_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
bool set_timer(uint16_t time_ms, void (*callback)) {
...
}
```c
// 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.
bool send_can(const uint32_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
bool 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);
```c
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.
}
```c
// 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);
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
}
if(handle.completed) {
if(!handle.success) {
// something happened and it already failed - possibly we aren't able to
// send CAN messages
return;
} 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!
}
// 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.
}
```c
// 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

Expand Down