CHAPTER 15 VEHICLE TELEMETRY PLATFORM if(millis() - lastLogWrite > LOG_INTERVAL) { The blue LED indicating that a sample is being written is illuminated, and the position counter for the log buffer is reset. digitalWrite(VDIP_WRITE_LED, HIGH); byte position = 0; The log entry length and the entry itself are sent to the host for debugging purposes. HOST.print(logEntry.length()); HOST.print(": "); HOST.println(logEntry); Now for the interesting bit. A WRF (WRite File) command is sent to the VDIP1 with a single argument that tells it the number of bytes of data to follow in the actual message. Because each log entry will have a newline character appended, we have to take the current logEntry length and add 1 to it to get the actual message length. Note that before doing this, the VDIP1 needs to be initialized, and that process is taken care of by a function that we’ll see in just a moment. VDIP.print("WRF "); VDIP.print(logEntry.length() + 1); VDIP.print(13, BYTE); The position counter is used to walk through the log buffer array one character at a time to send it to the VDIP1. However, the RTS (ready to send) pin on the VDIP1 is checked prior to transmission of each character to make sure the VDIP1 input buffer still has free space. If RTS is low (inactive) it’s clear to send the character and increment the position counter. Otherwise it shouts loudly to the host to notify you that the VDIP1 buffer was full. In production, you probably wouldn’t want the error message being sent to the host, but it can be handy when doing development. while(position < logEntry.length()) { if(digitalRead(VDIP_RTS_PIN) == LOW) { VDIP.print(vdipBuffer[position]); position++; } else { HOST.println("BUFFER FULL"); } } After sending a WRF command to the VDIP1, it will keep accepting data until it has received exactly the number of bytes specified in the WRF argument. The number passed in was one greater than the number of bytes in the buffer, so if nothing else was sent, the Vinculum chip on the VDIP1 would sit patiently waiting for the next character. If a mistake is made calculating the number of bytes to be sent, it’s easy to end up in a situation where you send one byte too few and the Vinculum doesn’t finish reading. Then, your program continues on around the loop and comes back to send more data to the VDIP1 on the next pass through. It then starts sending the WRF command, but because the Vinculum never exited write mode last time around, it sees the “W” character as the final character of the last write, then interprets “RF” is the start of another command. RF is meaningless to it so it will then output an error and you’ll end up with the original entry written to the file with a trailing W and nothing written for the second pass at all. So the moral of the story is to always, always, always check your message length very carefully when preparing data to send to the Vinculum chip. If you send fewer characters than it is expecting, it will remain in write mode waiting for more data; if you send too many characters, it will treat the excess as separate commands. If you’re really unlucky, those excess characters could constitute a command to perform a dangerous action such as deleting a file! 349 CHAPTER 15 VEHICLE TELEMETRY PLATFORM Something that could be done to minimize the risk is to send the characters one at a time and implement a check to look for the prompt response that the Vinculum will send when it finishes writing to the file. If the prompt comes back unexpectedly, it’s better to skip sending the rest of the buffer rather than to keep sending data. If the prompt doesn’t come back after all the characters have been sent, the message could be padded by sending spaces until the prompt returns. In this case, though, we’re just carefully counting characters including the trailing newline, so the program then sends the newline character and turns off the LED that indicates a write is in progress. It then sets the lastLogWrite variable to the number of milliseconds since startup so next time through the loop it can check whether it’s due to record another log entry. VDIP.print(13, BYTE); digitalWrite(VDIP_WRITE_LED, LOW); lastLogWrite = millis(); } } Way back in setup(), we looked at pin change interrupts and the way changes to the menu button states cause an ISR to be invoked. This is the definition of that ISR, and you can see that it uses an #ifdef check to substitute a different version of the function, depending on whether this is a Mega or non-Mega build. The Mega version is attached to PCINT2, and the first thing it does is check whether it has been more than 20 milliseconds since it was last invoked. If not, it’s probably a problem with the physical switch bouncing open and closed rapidly as it settles, so it’s ignored. If it is greater than 20 milliseconds, the buttonState global variable is updated with the value of the PINK register, which reads the value of all the pins in port K. Analog inputs 7 through 13 on a Mega are all part of port K. #ifdef MEGA ISR(PCINT2_vect) { static unsigned long last_millis = 0; unsigned long m = millis(); if (m - last_millis > 20) { buttonState |= ~PINK; } last_millis = m; } The non-Mega version does the same thing but with PCINT1, and reads from the port C register using PINC. #else ISR(PCINT1_vect) { static unsigned long last_millis = 0; unsigned long m = millis(); if (m - last_millis > 20) { buttonState |= ~PINC; } last_millis = m; } 350 CHAPTER 15 VEHICLE TELEMETRY PLATFORM #endif Reading from the ELM327 is pretty much the core function of the OBDuinoMega sketch. Everything else in the sketch is really just life support for a dozen or so lines of code in a function called elm_read() that simply listens to the serial connection until it sees an “\r” character followed by a prompt, indicating that the ELM327 has finished sending its message. The function requires two arguments: a pointer to a character array for the response to be stored in, and a byte indicating how many elements it’s allowed to put in that array. It then defines variables to hold response values and the number of characters read so far. byte elm_read(char *str, byte size) { int b; byte i=0; It loops reading from the serial port until it either sees a prompt character (in which case it knows it got a complete response) or runs out of space in the array. It inserts each character into the array and increments the position counter only if the character is a space character or greater, which is hex value 0x20 in the ASCII table. This excludes any control characters that could be sent through. while((b=OBD2.read())!=PROMPT && i<size) { if(b>=' ') str[i++]=b; } The two possible outcomes at this point are that the number of characters received is less than the array length and therefore the program got a prompt, or that the number of characters reached the array length and therefore the response was probably meaningless. If the counter “i” is not equal to the array size, everything is probably okay, so the last character entered into the array pointer (most likely a carriage return) needs to be replaced with a null character to indicate the end of the string. The function then returns the prompt character to indicate success. Otherwise, the program assumes the response was meaningless and returns the value 1, signified by the DATA placeholder defined at the start of the sketch, to indicate that there is raw data in the buffer. if(i!=size) { str[i]=NUL; return PROMPT; } else return DATA; } The response that comes back from the ELM327 is an ASCII string that represents a hexadecimal number. It may look like hex but don’t be deceived—it’s not! For example, if the ELM327 sends a response of 1AF8 to mean a decimal value of 6904, what we actually receive from the serial port is the ASCII values that represent those individual characters: 0x31 to represent 1, 0x41 to represent A, 0x46 to represent F, and 0x38 to represent 8. This is not at all what we wanted, and if you process the bytes literally, you’ll get an incorrect answer. To make sense of the response value, the sketch really needs it as an actual numeric type rather than a string, so the elm_compact_response() function accepts a raw ELM327 response and turns it into a real hex value stored in a byte array. Because the response from the ELM327 starts with an echo of the mode plus 0x40 and then the PID, the sketch has to skip the first few bytes. For example, if the request 010C was sent, the response would be something like “41 0C 1A F8,“ so the first byte we would actually care about would be the seventh character. The end result that we want is the numeric value 0x1AF8 ready to send back to the calling function. 351 CHAPTER 15 VEHICLE TELEMETRY PLATFORM Note that the call to strtoul (string to unsigned long) passes in a third argument of 16, the base required for the response. Base 16 is hexadecimal. The return value from the function is simply the number of bytes in the converted value. byte elm_compact_response(byte *buf, char *str) { byte i=0; str+=6; while(*str!=NUL) buf[i++]=strtoul(str, &str, 16); return i; } Initializing the serial connection to the ELM327 is quite straightforward. First, the serial port itself is opened at the rate configured at the start of the sketch, then the serial buffer is flushed to ensure there’s no stray data sitting in it. void elm_init() { char str[STRLEN]; OBD2.begin(OBD2_BAUD_RATE); OBD2.flush(); Just in case the ELM327 had already been powered up and had settings changed, it’s then sent a soft-reset command. elm_command(str, PSTR("ATWS\r")); A message is then displayed on the LCD to show progress. If the first character back is an “A,” the program assumes that it’s echoing the command and skips ahead to read the response from the fifth character (position 4) onward. Otherwise, it simply displays the message as is. lcd_gotoXY(0,1); if(str[0]=='A') lcd_print(str+4); else lcd_print(str); lcd_print_P(PSTR(" Init")); To get responses back from the ELM327 a little faster it’s a good idea to turn off command echo, otherwise every response will be bloated with several bytes taken up just repeating the command we sent to it. The ATE0 command suppresses command echo. elm_command(str, PSTR("ATE0\r")); The sketch then goes into a do-while loop trying to verify that the ELM327 is alive and communicating by sending a request for PID 0X0100 (PIDs supported) repeatedly until it gets a response. If you start up the system without putting it into debug mode or connecting it to an ELM327, and it ends up sitting on a screen that reads “Init” forever; this is the loop it’s trapped in. do { elm_command(str, PSTR("0100\r")); delay(1000); } while(elm_check_response("0100", str)!=0); When using the OBD-II interface to communicate with a vehicle’s internal communications bus, there are typically multiple ECUs (electronic control units) sharing that bus. The primary ECU that responds with OBD-II values is identified as ECU #1, and the ELM327 can either direct its requests generally to all devices on the bus or it can direct them to a specific ECU. 352 CHAPTER 15 VEHICLE TELEMETRY PLATFORM By default, the ELM327 shouts its requests to the world, but by modifying the communications header that it sends to the car, it’s possible to make it specifically ask for the primary ECU. This is done by setting a custom header that the ELM327 uses for messages sent to the car, but the format of the header depends on what communications protocol it’s using. Because the ELM327 takes care of all the protocol conversion behind the scenes, the sketch doesn’t generally need to know the details of what’s going on, but to determine the car’s protocol it can send an ATDPN (ATtention: Describe Protocol by Number) command to have the ELM327 report which protocol it has autonegotiated with the car. elm_command(str, PSTR("ATDPN\r")); The OBDuinoMega sketch can then set a custom header specifying that all requests should go to ECU #1 using the appropriate format for that particular protocol. if(str[1]=='1') // PWM elm_command(str, PSTR("ATSHE410F1\r")); else if(str[1]=='2') // VPW elm_command(str, PSTR("ATSHA810F1\r")); else if(str[1]=='3') // ISO 9141 elm_command(str, PSTR("ATSH6810F1\r")); else if(str[1]=='6') // CAN 11 bits elm_command(str, PSTR("ATSH7E0\r")); else if(str[1]=='7') // CAN 29 bits elm_command(str, PSTR("ATSHDA10F1\r")); } All done. The ELM327 should now be running in a reasonably well optimized state, with no command echo and all requests specifically directed to ECU #1. The get_pid() function is called by the display() function to fetch values to display on the LCD, and also in the main loop by the logging code to fetch values to write to the CSV file on the memory stick. The majority of the code in this very long function is a massive switch statement that checks which PID is being requested and then sources the result and processes it appropriately, putting the numeric value in a long pointer and a version formatted for string output into a buffer. The return value of the function indicates whether retrieval of the PID was successful or not, so a simple call to this function and then a check of the response will give access to just about any information accessible by the Vehicle Telemetry Platform. The start of the function takes the requested PID and sets up some variables. boolean get_pid(byte pid, char *retbuf, long *ret) { #ifdef ELM char cmd_str[6]; // to send to ELM char str[STRLEN]; // to receive from ELM #else byte cmd[2]; // to send the command #endif byte i; byte buf[10]; // to receive the result byte reslen; char decs[16]; unsigned long time_now, delta_time; static byte nbpid=0; It then checks if the PID is supported by calling out to another function. If it is not supported, it puts an error message in the return buffer and returns a FALSE value. if(!is_pid_supported(pid, 0)) { 353 CHAPTER 15 VEHICLE TELEMETRY PLATFORM sprintf_P(retbuf, PSTR("%02X N/A"), pid); return false; } Way back at the start of the sketch, each PID was defined along with the number of bytes to expect in response to each one. The sketch then reads the receive length value out of EEPROM by referencing the memory position for that PID. reslen=pgm_read_byte_near(pid_reslen+pid); The request is then sent to the vehicle using one of two methods, depending on whether the system was built using an ELM327 as in our prototype, or uses interface hardware specific to the particular car. The ELM version formats the request by appending the PID to the mode then adding a carriage return at the end, then sends it to the ELM327, and then waits for the response. The response value is checked to make sure there’s no error value. If there is, “ERROR” is put in the return buffer and the function bails out with a FALSE return value. Assuming the response was good and the function didn’t bail out, it then proceeds by sending the value off to be converted from an ASCII string to an actual numeric value using the elm_compact_response() function previously defined. #ifdef ELM sprintf_P(cmd_str, PSTR("01%02X\r"), pid); elm_write(cmd_str); elm_read(str, STRLEN); if(elm_check_response(cmd_str, str)!=0) { sprintf_P(retbuf, PSTR("ERROR")); return false; } elm_compact_response(buf, str); The non-ELM version follows almost exactly the same process, but rather than use calls to ELM functions, it uses equivalent ISO functions. #else cmd[0]=0x01; // ISO cmd 1, get PID cmd[1]=pid; iso_write_data(cmd, 2); if (!iso_read_data(buf, reslen)) { sprintf_P(retbuf, PSTR("ERROR")); return false; } #endif By this point, the sketch has the raw result as a numeric value, but as explained previously most PIDs require a formula to be applied to convert the raw bytes into meaningful values. Because many PIDs use the formula (A * 256) + B, the sketch then calculates the result of that formula no matter what the PID is. The result may be overwritten later if this particular PID is an exception, but determining a default value first, even if it’s thrown away later, saves 40 bytes over conditionally calculating it based on the PID. With the original MPGuino/OBDuino codebases designed to squeeze into smaller ATMega CPUs, every byte counts. *ret=buf[0]*256U+buf[1]; The rest of the function is a huge switch statement that applies the correct formula for the particular PID being requested. We won’t show the whole statement here, but you’ll get the idea by looking at a few examples. The first check is whether the requested PID was the engine RPM. In debug mode it returns a hard- coded value of 1726RPM, and otherwise it takes the return value and divides it by 4. The full formula for 354 CHAPTER 15 VEHICLE TELEMETRY PLATFORM the engine RPM is ((A * 256) + B) / 4, but because the return value was already calculated, the first part of the formula has already been applied and it just needs the division portion. switch(pid) { case ENGINE_RPM: #ifdef DEBUG *ret=1726; #else *ret=*ret/4U; #endif sprintf_P(retbuf, PSTR("%ld RPM"), *ret); break; The Mass Air Flow parameter is similar: return a hard-coded value in debug mode, or take the precalculated value and divide it by 100 as per the required formula. case MAF_AIR_FLOW: #ifdef DEBUG *ret=2048; #endif long_to_dec_str(*ret, decs, 2); sprintf_P(retbuf, PSTR("%s g/s"), decs); break; Vehicle speed is a trivial parameter, and then it gets to the fuel status parameter. Fuel status is a bitmap value, so each bit in the response value is checked in turn by comparing it to a simple binary progression (compared in the code using the hex equivalent value) and the matching label is then returned. In the case of this particular parameter, it’s not really the numeric value that is useful, but the label associated with it. case FUEL_STATUS: #ifdef DEBUG *ret=0x0200; #endif if(buf[0]==0x01) sprintf_P(retbuf, PSTR("OPENLOWT")); // Open due to insufficient engine temperature else if(buf[0]==0x02) sprintf_P(retbuf, PSTR("CLSEOXYS")); // Closed loop, using oxygen sensor feedback to determine fuel mix. Should be almost always this else if(buf[0]==0x04) sprintf_P(retbuf, PSTR("OPENLOAD")); // Open loop due to engine load, can trigger DFCO else if(buf[0]==0x08) sprintf_P(retbuf, PSTR("OPENFAIL")); // Open loop due to system failure else if(buf[0]==0x10) sprintf_P(retbuf, PSTR("CLSEBADF")); // Closed loop, using at least one oxygen sensor but there is a fault in the feedback system else sprintf_P(retbuf, PSTR("%04lX"), *ret); break; A number of parameters require an identical formula of (A * 100) / 255, so they’re all applied in a group. case LOAD_VALUE: case THROTTLE_POS: case REL_THR_POS: 355 CHAPTER 15 VEHICLE TELEMETRY PLATFORM case EGR: case EGR_ERROR: case FUEL_LEVEL: case ABS_THR_POS_B: case CMD_THR_ACTU: #ifdef DEBUG *ret=17; #else *ret=(buf[0]*100U)/255U; #endif sprintf_P(retbuf, PSTR("%ld %%"), *ret); break; The function continues in a similar way for the rest of the PIDs. If you want to see the details of how a particular PID is processed, it’s best to look in the OBDuinoMega source code. Other functions in the main file then provide features such as calculation of current (instant) fuel consumption and the distance that could be traveled, using the fuel remaining in the tank. Once on every pass through the main loop, a call is placed to the accu_trip() function to accumulate data for the current trip by adding current values to trip values. Among other things, it increments the duration of the trip in milliseconds; the distance traveled in centimeters (allowing a trip of up to 42,949km or 26,671mi because the distance is stored in an unsigned long); fuel consumed; and mass air flow. One particularly interesting value it accumulates is “fuel wasted,” which is the amount of fuel that has been consumed while the engine was idling. The display() function takes care of fetching the value associated with a specific PID and displaying it at a nominated location on the LCD. Because the PIDs defined at the start of the sketch can be either real (provided by the engine-management system) or fake (generated by the sketch internally or from some other data source), this function explicitly checks for a number of PIDs that require data to be returned by a specific function. void display(byte location, byte pid) char str[STRLEN]; if(pid==NO_DISPLAY) return; else if(pid==OUTING_COST) get_cost(str, OUTING); else if(pid==TRIP_COST) get_cost(str, TRIP); else if(pid==TANK_COST) get_cost(str, TANK); It goes on in a similar way for dozens of PIDs that it knows about specifically until it falls through to the default behavior, which is to pass the request on to the get_pid() function we just saw. else get_pid(pid, str, &tempLong); The function then sets a null string terminator into the result string at the LCD_split position, which was calculated back at the start of the sketch as half the width of the LCD. This effectively truncates the result at half the display width so that it can’t overwrite an adjacent value. str[LCD_split] = '\0'; It then does some manipulation of the “location” argument that was passed in to determine which row it goes on given that there are two locations per line, then checks if it’s an even number and should therefore go on the left, and finally calculates the start and end character positions for that location. byte row = location / 2; // Two PIDs per line boolean isLeft = location % 2 == 0; // First PID per line is always left 356 CHAPTER 15 VEHICLE TELEMETRY PLATFORM byte textPos = isLeft ? 0 : LCD_width - strlen(str); byte clearStart = isLeft ? strlen(str) : LCD_split; byte clearEnd = isLeft ? LCD_split : textPos; It’s then just a matter of going to that location and printing the string to the LCD. lcd_gotoXY(textPos,row); lcd_print(str); The last thing the function needs to do is get rid of any leading or trailing characters that might still be visible on the LCD after the value was written. This can happen if the previously displayed value used more characters than the current value, and because characters are only replaced if they are explicitly written to, it’s necessary to write spaces into characters we don’t care about. lcd_gotoXY(clearStart,row); for (byte cleanup = clearStart; cleanup < clearEnd; cleanup++) { lcd_dataWrite(' '); } } For maintenance purposes, one of the most important pieces of information available via OBD-II is the response to mode 0x03, “Show diagnostic trouble codes.” It’s also one of the most complex because of the variations in the type of data that it needs to return. Mode 0x03 doesn’t contain any PIDs, so there’s no need to request anything but the mode itself, and it always returns four bytes of data. A typical response could be as follows: 43 17 71 00 00 00 00 The “43” header is because it’s a response to a mode 0x03 request, and response headers always start with the mode plus 0x40. The rest of the message is three pairs of bytes, so this example would be read as 1771, 0000, and 0000. The zero value pairs are empty but are always returned anyway so that the response length is consistent. In this example, the only stored trouble code is 0x1771, so let’s look at how to convert it into something meaningful and figure out what might have gone wrong with the car. The first byte is 0x17 (or binary 00010111), which consists of two digits, 1 and 7. If we split that binary value into two halves (nibbles) we end up with 0001 representing the first digit, 1, and 0111 representing the second digit, 7. The first digit represents the DTC prefix that tells us what type of trouble code it is and whether its meaning is standards-defined or manufacturer-defined. To complicate things a little more, the first digit is in turn divided into two sets of bits, so we can’t just take it at face value. In our example, the first digit is 1, or binary 0001. That needs to be split into a pair of two-bit numbers, so in our case it will be 00 and 01. Each pair can have four possible values, with the first pair representing the section of the car in which the problem occurred, and the second pair specifying whether that DTC is defined by the SAE standards body or the manufacturer. The four possible values for the first pair of bits are shown in Table 15-9. 357 CHAPTER 15 VEHICLE TELEMETRY PLATFORM Table 15-9. DTC location codes Binary Hex Code Meaning 00 0 P Powertrain code 01 1 C Chassis code 10 2 B Body code 11 3 U Network code There are also four possible values for the second pair of bits, but unfortunately their meaning can vary depending on the value of the first pair. These are given in Table 15-10. Table 15-10. DTC definition source Binary Hex Defined By 00 0 SAE 01 1 Manufacturer 10 2 SAE in P, manufacturer in C, B, and U 11 3 Jointly defined in P, reserved in C, B, and U Because the meaning of the second value can vary based on the first value, the easiest way to approach it is so create a big look-up table that maps all 16 possible values of the first four bits (the first character in the response) to its specific meaning. These are given in Table 15-11. Table 15-11. DTC location and definitions combined Binary Hex Prefix Meaning 0000 0 P0 Powertrain, SAE-defined 0001 1 P1 Powertrain, manufacturer-defined 0010 2 P2 Powertrain, SAE-defined 0011 3 P3 Powertrain, jointly defined 0100 4 C0 Chassis, SAE-defined 358 . The full formula for 354 CHAPTER 15 VEHICLE TELEMETRY PLATFORM the engine RPM is ((A * 256) + B) / 4, but because the return value was already calculated, the first part of the formula. sprintf_P(retbuf, PSTR("OPENLOAD")); // Open loop due to engine load, can trigger DFCO else if(buf[0]==0x08) sprintf_P(retbuf, PSTR("OPENFAIL")); // Open loop due to system. which PID is being requested and then sources the result and processes it appropriately, putting the numeric value in a long pointer and a version formatted for string output into a buffer. The