diff --git a/README.mkd b/README.mkd index aa0d7fd..1a6502a 100644 --- a/README.mkd +++ b/README.mkd @@ -16,136 +16,144 @@ give you complete control. 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)) { - ... - } +```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 +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); +```c +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 - } +```c +// 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 { - 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. - } + // 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 - } +```c +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 { - 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); + // 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 { - // Some other fatal error ocurred - we weren't able to send - // the request or receive the response. The CAN connection - // may be down. - } + } 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