-OBD-II Support Library in C
-=============================
+Unified Diagnostic Services (UDS) Support Library in C
+======================================================
-## API
+This is a platform agnostic C library that implements the Unified Diagnostics
+Services protocol for automotive electronics. UDS is documented in ISO 14229 and
+is the underpinning for the more well-known On-board Diagnostics (OBD) standard.
+The library currently supports UDS running over CAN (ISO 15765-4), which uses
+the ISO-TP (ISO 15765-2) protocol for message framing.
+
+This library doesn't assume anything about the source of your diagnostic message
+requests or underlying interface to the CAN bus. It uses dependency injection to
+give you complete control.
+
+## 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.
+ 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
+ void set_timer(uint16_t time_ms, void (*callback)) {
+ ...
+ }
+
+With your shims in place, create a `DiagnosticShims` object to pass them around:
+
+ DiagnosticShims shims = diagnostic_init_shims(debug, send_can, set_timer);
+
+With your shims in hand, send a simple PID request to the standard broadcast
+address, `0x7df` (we use the constant `OBD2_FUNCTIONAL_BROADCAST_ID` here):
+
+ // Optional: This is your callback that will be called the response to your
+ // diagnostic request is received.
+ void response_received_handler(const DiagnosticResponse* response) {
+ // You received a response! Do something with it.
+ }
+
+ DiagnosticRequestHandle handle = diagnostic_request_pid(&shims,
+ DIAGNOSTIC_STANDARD_PID, // this is a standard PID request, not an extended or enhanced one
+ OBD2_FUNCTIONAL_BROADCAST_ID, // the request is going out to the broadcast arbitration ID
+ 0x2, // we want PID 0x2
+ response_received_handler); // our callback (optional, use NULL if you don't have one)
+
+ if(handle.completed) {
+ if(!handle.success) {
+ // something happened and it already failed - possibly we aren't
+ // able to send CAN messages
+ return;
+ } else {
+ // this should never occur right away - you need to receive a fresh
+ // CAN message first
+ }
+ } else {
+ while(true) {
+ // Continue to read from CAN, passing off each message to the handle.
+ // This will return a 'completed' DiagnosticResponse when the when
+ // the request is completely sent and the response is received
+ // (which may take more than 1 CAN frames)
+ DiagnosticResponse response = diagnostic_receive_can_frame(&shims,
+ &handle, can_message_id, can_data, sizeof(can_data));
+
+ if(response.completed && handle.completed) {
+ if(handle.success) {
+ if(response.success) {
+ // The request was sent successfully, the response was
+ // received successfully, and it was a positive response - we
+ // got back some data!
+ } else {
+ // The request was sent successfully, the response was
+ // received successfully, BUT it was a negative response
+ // from the other node.
+ printf("This is the error code: %d", response.negative_response_code);
+ }
+ } else {
+ // Some other fatal error ocurred - we weren't able to send
+ // the request or receive the response. The CAN connection
+ // may be down.
+ }
+ }
+ }
+ }
+
+### Requests for other modes
+
+If you want to do more besides PID requests on mode 0x1 and 0x22, there's a
+lower level API you can use. Here's how to make a mode 3 request to get DTCs.
+
+ DiagnosticRequest request = {
+ arbitration_id: OBD2_FUNCTIONAL_BROADCAST_ID,
+ mode: OBD2_MODE_EMISSIONS_DTC_REQUEST
+ };
+ DiagnosticRequestHandle handle = diagnostic_request(&SHIMS, &request, NULL);
+
+ if(handle.completed) {
+ if(!handle.success) {
+ // something happened and it already failed - possibly we aren't
+ // able to send CAN messages
+ return;
+ } else {
+ // this should never occur right away - you need to receive a fresh
+ // CAN message first
+ }
+ } else {
+ while(true) {
+ // Continue to read from CAN, passing off each message to the handle.
+ // This will return a 'completed' DiagnosticResponse when the when
+ // the request is completely sent and the response is received
+ // (which may take more than 1 CAN frames)
+ DiagnosticResponse response = diagnostic_receive_can_frame(&shims,
+ &handle, can_message_id, can_data, sizeof(can_data));
+
+ if(response.completed && handle.completed) {
+ if(handle.success) {
+ if(response.success) {
+ // The request was sent successfully, the response was
+ // received successfully, and it was a positive response - we
+ // got back some data!
+ printf("The DTCs are: ");
+ for(int i = 0; i < response.payload_length; i++) {
+ printf("0x%x ", response.payload[i]);
+ }
+ } else {
+ // The request was sent successfully, the response was
+ // received successfully, BUT it was a negative response
+ // from the other node.
+ printf("This is the error code: %d", response.negative_response_code);
+ }
+ } else {
+ // Some other fatal error ocurred - we weren't able to send
+ // the request or receive the response. The CAN connection
+ // may be down.
+ }
+ }
+ }
+ }
+
+## Dependencies
+
+This library requires 2 dependencies:
+
+* [isotp-c](https://github.com/openxc/isotp-c)
+* [bitfield-c](https://github.com/openxc/bitfield-c)
## Testing
$ 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
+
+## OBD-II Basics
+
+TODO diagram out a request, response and error response
+
+* store the request arb id, mode, pid, and payload locally
+* send a can message
+* get all new can messages passed to it
+* Check the incoming can message to see if it matches one of the standard ECU
+ response IDs, or our arb ID + 0x8
+* if it matches, parse the diagnostic response and call the callback
+
+
+## Future Notes
+
+you're going to request a few PIDs over and over again at some frequency
+you're going to request DTCs once and read the response
+you're going to clear DTCs once
+
+we need another layer on top of that to handle the repeated requests.
+
## Authors
Chris Peplin cpeplin@ford.com
Code Review / apps / agl-service-can-low-level.git / blobdiff