Innovate Motorsports OT-2 SDK User Manual
1
Innovate Motorsports
OT-1b/2 SDK
Version 1.3
Disclaimer: Information in this document is being provided as-is without any
warranty/guarantee of any kind. Innovate Motorsports has taken all reasonable
measures to ensure the quality, reliability, and accuracy of the information in this
document. But if you corrupt an ECU, melt the casing off your computer, or
experience some other terrible calamity, it is not our problem. Feel free to let us
know, we might enjoy laughing at your misfortune, but please do not sue us. You
have been warned!
2
Table of Contents
Revision History:................................................................................................................. 5
Introduction .........................................................................................................................6
SDK Scope ......................................................................................................................6
Prerequisites ....................................................................................................................8
MTS Basics (or “Serial 2 revisited”)................................................................................... 9
Basic Scheme ..................................................................................................................9
Packets in General .........................................................................................................13
Data Packets ..................................................................................................................14
Aux Channels ............................................................................................................14
‘New’ Lambda/AFR Channels..................................................................................15
‘Old’ (LM-1) Lambda/AFR Channels ......................................................................16
Response Packets ..........................................................................................................17
Commands.....................................................................................................................19
Get to the Good Stuff! .......................................................................................................20
Setup Mode....................................................................................................................20
Setup Mode Commands ................................................................................................22
Command ‘S’ - Get Setup Mode Header ..................................................................23
Command ‘s’ – Exit Setup Mode ..............................................................................23
Command ‘j’ – Get OBD-II Connection Status ........................................................24
Command ‘a’ – Check availability of a ‘normalized’ PID .......................................24
Command ‘k’ – Get OBD-II Diagnostic Trouble Codes (DTCs) .............................25
Command ‘K’ – Clear All OBD-II Diagnostic Trouble Codes (DTCs) ...................25
Command ‘l’ – Get Last OBD-II Loop Time............................................................26
Command ‘v’ – Get Vehicle VIN number ................................................................ 26
Command ‘t’ – Get Basic Emissions Status.............................................................. 27
Command ‘c’ – Get Device Configuration ...............................................................27
Command ‘C’ – Set Device Configuration ...............................................................28
Command ‘M’ – Set ‘My’ (temporary) Device Configuration................................. 29
Command ‘m’ – Clear ‘My’ (temporary) Device Configuration..............................29
Command ‘w’ – Get Wi-Fi Settings..........................................................................30
Command ‘e’ – Enter an Expert Mode .....................................................................30
Command 0xFF – Don’t hang up on me!..................................................................31
Understanding OT-1b/2 Device Configuration................................................................. 32
Benefits of In Band Mode .................................................................................................35
Expert Modes ................................................................................................................36
Overview .......................................................................................................................36
Special Considerations Entering Expert Modes............................................................ 38
Can.................................................................................................................................39
Command ‘R’ – Set the Protocol Rate ......................................................................39
Command ‘r’ – Get the Protocol Rate.......................................................................40
Command ‘F’ – Add a Pass Filter .............................................................................40
Command ‘f’ – Clear all Pass Filters ........................................................................41
Command ‘E’ – Add a Handshake Filter .................................................................. 41
Command ‘e’ – Clear all Handshake Filters .............................................................42
3
Command ‘O’ – Output Data and (optionally) look for input ..................................42
Command ‘I’ – Look for Input Data .........................................................................43
Command ‘L’ – Set the Vehicle LED State ..............................................................43
Command ‘b’ – Get Last MTS Packet passed ..........................................................44
Command ‘s’ – Exit Expert Mode ............................................................................44
Command 0xFF – Don’t hang up on me!..................................................................44
J1850 .............................................................................................................................45
Command ‘R’ – Set the Protocol Rate ......................................................................45
Command ‘r’ – Get the Protocol Rate.......................................................................45
Command ‘F’ – Add a Pass Filter .............................................................................46
Command ‘f’ – Clear all Pass Filters ........................................................................46
Command ‘O’ – Output Data and (optionally) look for input ..................................47
Command ‘I’ – Look for Input Data .........................................................................48
Command ‘L’ – Set the Vehicle LED State ..............................................................48
Command ‘b’ – Get Last MTS Packet passed ..........................................................49
Command ‘s’ – Exit Expert Mode ............................................................................49
Command 0xFF – Don’t hang up on me!..................................................................49
ISO.................................................................................................................................50
Command ‘R’ – Set the Protocol Rate ......................................................................50
Command ‘r’ – Get the Protocol Rate.......................................................................50
Command ‘F’ – Add a Pass Filter .............................................................................51
Command ‘f’ – Clear all Pass Filters ........................................................................51
Command ‘O’ – Output Data and (optionally) look for input ..................................52
Command ‘I’ – Look for Input Data .........................................................................53
Command ‘5’ – Perform standard 5 Baud Initialization ........................................... 54
Command ‘q’ – Perform standard ‘fast’ KWP-2000 initialization ........................... 54
Command ‘L’ – Set the Vehicle LED State ..............................................................55
Command ‘b’ – Get Last MTS Packet passed ..........................................................55
Command ‘s’ – Exit Expert Mode ............................................................................55
Command 0xFF – Don’t hang up on me!..................................................................56
ISO Raw ........................................................................................................................57
Command ‘R’ – Set the Protocol Rate ......................................................................57
Command ‘r’ – Get the Protocol Rate.......................................................................57
Command ‘O’ – Output Data and (optionally) look for input ..................................58
Command ‘I’ – Look for Input Data .........................................................................59
Command ‘5’ – Perform standard 5 Baud Initialization ........................................... 60
Command ‘q’ – Perform standard ‘fast’ KWP-2000 initialization ........................... 60
Command ‘0’ – Send a 00h at 5 baud on the K line .................................................61
Command ‘L’ – Set the Vehicle LED State ..............................................................61
Command ‘b’ – Get Last MTS Packet passed ..........................................................62
Command ‘s’ – Exit Expert Mode ............................................................................62
Command 0xFF – Don’t hang up on me!..................................................................62
But How Do I Connect?!...................................................................................................63
Innovate Transports....................................................................................................... 63
IMS USB .......................................................................................................................63
Technical Details....................................................................................................... 64
4
IMS USB under Windows......................................................................................... 64
Other Platforms .........................................................................................................66
IMS NET (Wi-Fi).......................................................................................................... 66
Special Considerations for Network/Wi-Fi....................................................................... 69
Performance...................................................................................................................69
Debugging .....................................................................................................................70
Samples .............................................................................................................................71
Appendix A: Normalized PIDs .........................................................................................72
Appendix B – Determining Normalized PID Availability................................................ 76
5
Revision History:
Rev Date Author Description
1.0 11/20/09 jjf Initial version
1.1 12/02/09 jjf Structure typo fixes in Setup Mode
1.2 12/13/09 jjf Updated Expert Modes to match version 1.02
Added ‘a’ to Setup Mode command list
Added appendix on determining PID availability
1.3 12/28/09 jjf Added standard IMS input values to App A
Fixed type in ISO Export ‘O’ command
6
Introduction
Welcome to the world of OT-1b/2 Programming! Hopefully, this document and the
accompanying sample applications should make the process trivial… or not…
Seriously, our policy with regards to the OT-1b/2 SDK is full disclosure and an emphasis
on 3rd party support. If there is a question that is not answered here, just ask. Likewise, if
there is a feature that would make the OT-1b/2 work better (or work at all!) for your
application, let us know. We can always be reached at
support@innovatemotorsports.com.
Further, the enclosed is not covered by any form of Non Disclosure Agreement, so feel
free to share information with other developers. But again, the policy here is disclosure.
So, if you find a ‘back door’ which is useful to you, it is best to let us know. That way,
we will not accidentally ‘close it’ in future firmware updates, etc.
SDK Scope
Because Innovate has released various “SDKs” and specifications over the years, it is
probably worth covering where this SDK fits in the overall scheme of things. This will
also introduce you to some long standing Innovate ‘buzz words’. Here is (roughly) the
state of public and not so public information just prior to this SDK:
At the lowest ‘public’ level in the chart above is the “Serial 2” or “MTS” Protocol
specification. Our original product, the LM-1, uses a slightly different serial protocol, but
all other devices, including the OT-1b and OT-2, automatically convert that protocol to
7
MTS when they see it. So, if you are only connecting through an OT-1b/2, you should
never have to worry about the older format.
Although a substantial number of 3rd party developers have made good use of the public
information above, several limitations have gradually emerged. First, just understanding
the basic data packet structure does not give developers direct access to our newer
‘transport layers’ (IMS USB and IMS NET). Applications that use our high level SDK
(MTS SDK) have continued to pick up new transports and devices for ‘free’. For
example, the ‘sample app’ included with that SDK has not been recompiled since it was
first released, but the app ‘understands’ an LM-2 via USB, and can connect wirelessly to
an OT-2, even though both those products (and transports) came much later.
However, developers who are not working in Windows, cannot utilize ActiveX, or
simply need a more seamless connection to our hardware, have been left a bit behind.
The devices still ‘speak’ MTS, but the developers do not now how to properly ‘listen’, or
access the data stream.
Second, up to now, device configuration has (mostly) been closed (accessed by LM
Programmer only, even LogWorks, our own data acquisition application, does not
directly configure hardware). We have given out bits and pieces of information on how to
configure individual devices, but have, in general, been reluctant to release this
information. To be frank, part of the reluctance has been pragmatic. It is possible to put
some of the devices into strange, non-working configurations. And, if the product stops
working, the manufacturer, not the 3rd party vendor, gets the support call. But part of the
reason has been complexity. The MTS protocol does have a mechanism for getting and
setting configuration information for specific devices in a chain, but it was not properly
implemented in the first MTS devices deployed. And those devices, in particular the LC1, were deployed in substantial quantities, for more than a year, before the problem was
ever discovered.
These original mistakes, combined with the need to provide proper legacy support, have
made configuration management inside our own software products pretty complicated.
There has been some resistance to exposing that sort of complexity to outside developers,
but, clearly, some applications really warrant configuration control. So enter our new
diagram:
8
As the outline on the diagram above shows, this SDK covers, generically, how to
communicate with Innovate devices via either our universal USB driver or our network
protocol. This information can be applied to devices besides the OT-1b and OT-2, such as
the LM-2.
In addition to this generic information, this SDK provides information that is specific to
the OT-1b and OT-2. Namely, how to configure those two particular devices (all the
features exposed by LM Programmer, plus a few more) and, perhaps more interestingly,
access to very low OBD-II services for fairly direct interaction with vehicle ECUs
(Electronic Control Units).
Prerequisites
We tried to create the MTS SDK with the application programmer in mind. But, because
of the subjects involved, this SDK presumes some system level programming experience.
A solid understanding of the C programming language will be very helpful in
understanding the examples and explanations.
In individual subjects additional background knowledge can also be very helpful. For
example, a basic understanding of Windows or BSD ‘sockets’ will make the section on
IMS Net much easier to understand. However, we have tried to add some introduction
links to each subject where possible.
9
MTS Basics (or “Serial 2 revisited”)
Regardless of how you physically connect to an OT-1B/2, its default behavior is to
continuously send a stream of MTS data packets. We often refer to this as “in band”
communication. This is also the only way to get information from any other MTS devices
chained to the OT-1b/2, so some review of the Serial 2 protocol is in order. This protocol
is covered in the verbosely named “Innovate Serial Protocol 2 (ISP2) specification
(preliminary)”. That document, as well as the only slightly more tersely named “Serial2
Protocol Supplement” are possibly worth reading (simply email support@innovate-
tech.com and request them). But they should be taken with a grain of salt. Some features
are not implemented in all devices, and the OT-1b/2, when accessed via USB/Wi-Fi,
‘breaks’ a couple of the documented rules (which were written with serial port
communication in mind).
The following, combined with the source samples will, hopefully, give you most, if not
all, the information typically required.
Basic Scheme
The basic scheme of MTS is not too complicated. With the exception of the host (that’s
generally you!), all devices have two serial ports. The “Serial IN” is for talking to devices
earlier in the chain. The “Serial OUT” is for talking to devices later in the chain (or, if it
is the last device, the host). Even though the terms, “IN” and “OUT” imply a direction, it
is important to understand that each is a full duplex RS-232 port that the devices use to
talk to each other. Even if you are communicating with the device via USB or Wi-Fi you
are, in an MTS sense, ‘talking’ to the “Serial OUT” port of what is, from your point of
view, the last device in the chain. Examine this simple (and reasonably common) setup:
The user has two LC-1 wideband controllers, one for each ‘bank’ in a large engine, an
OT-2 for obtaining some basic information from the vehicle’s ECU (like RPM), and one
of our gauges for monitoring air fuel measurements from the LC-1’s in real time.
10
When our host connects to the OT-2 via Wi-Fi, it is virtually connecting to the physical
serial OUT on the device. That is, it starts seeing the same MTS data that is streaming to
the gauge. But it does not see the gauge, or any other devices chained from the OT-2’s
serial OUT on.
Because of the way the protocol works, everyone (including the host) only has access to
data generated ahead of them in the chain. Anything behind you is invisible to you.
So, from the point of view of our host (presumably an application running on the retro
looking ‘smart phone’ above), the gauge simply does not exist. We can put our finger
over it and see a straight line chain, with us at the left side of it.
At the other end of our chain from our host we have our chain’s “Head” unit. How does
that particular LC-1 know that it is the head unit? Simple, at power-up each device (but
not the host) sends an “H” to its serial IN port. If the device hears an echo, it knows that it
is the one at the end of a chain with the loop back plug.
There has been some confusion about loop back plugs (sometimes called “Arnold”, for
the sake of a pun too painful to repeat here). User’s seem confused about rather the plugs
are necessary or not. The bottom line is that a working MTS chain must always have a
loopback at the end. The reason that it seems like it is sometimes not necessary is that
most new MTS devices (like the OT-1b/2) self terminate when nothing is plugged into
them. Only the earlier MTS devices, like the LC-1, actually require a physical plug.
Once a unit has determined that it is ‘Head’, it begins to start sending data packets, each
containing what information it has (in this case, an AFR measurement) to the device’s
serial OUT connection. Data packets are always generated once every 81.92
milliseconds.
This is important because it means that the MTS stream does not just represent data
values, but also represents a timeline. As to ‘why 81.92 milliseconds?’ the answer is that
automotive science suggests that a sample rate of at least 12 Hz is very good for the types
of measurements we normally do with our equipment. But dividing 1 with 12 gives 83
and 1/3 milliseconds (lots of 3333…) But if you take an 8 MHz clock and divide it by
65536 (a 16 bit counter), you get 81.92 milliseconds. Care to guess at the clock rate of the
original LM-1 or the size of the counter registers used to generate the MTS sample rate in
it?!
So, now we have a ‘timeline’ (or sample clock) where each packet represents a ‘tick’, a
measurement from the first LC-1, and a history lesson, but what happens next? To
understand you need to remember that devices ‘see’ data from all the devices that
proceed them (it arrives on their own serial IN port). So, our second LC-1, just after the
‘head’, ‘sees’ the MTS packets transmitted by the first one.
11
Not only does it see them, the second LC-1 specifically has to pass them on, transmitting
them on its own serial OUT connector, for the data to ever reach our host. But, it does not
have to pass on exactly what it hears!
What the second LC-1 does is to alter the packet header before passing it on. It increases
the ‘length’ field, so that the packet the next unit in the chain (our OT-2) sees is larger –
by the size of the data that the second LC-1 itself has to provide (again, like the first LC1, just one AFR measurement). Then, after altering and relaying the header, the second
LC-1 relays the rest of the original packet it receives unchanged. Finally, it sends its own
data which, because of the altered header, is now properly part of the packet which the
next device in line (the OT-2) receives.
For most of the life of an MTS chain, this is what occurs. The head generates a data
packet, and each device in the chain expands the ‘size’ portion of the header, and then
tags its individual sample data at the end of the packet it is passing on, until the ever
growing packet reaches the host, where it is typically recorded or displayed.
In our illustration above, this is data flowing from right to left, over and over and over.
But there are two other basic cases; ‘Commands’ and ‘Queries’. Both are single
characters sent from devices downstream (the left side of our diagram) to devices
upstream (the right side of our diagram). That is, they start by flowing in the opposite
direction from the data packets described above.
Commands are easy. They are received on each device’s serial OUT port, acted on (if
applicable), and then passed on, unchanged, to the device’s serial IN port. Take the case
of ‘c’, the calibrate command.
Either our host, or our gauge, can transmit it. It is received by the OT-2 on either the
‘real’ or ‘virtual’ serial out port. The OT-2 has no need for calibration, so it does nothing,
but it passes the command on by transmitting it via its serial IN port.
Next, an LC-1 receives the command, and it does have a need to calibrate. So it starts free
air calibration, and then passes the command on to the next device upstream. That LC-1,
in turn, also starts free air calibration. But, because it is the ‘head’ unit, it does not bother
passing the command on to its serial IN port.
Queries are sort of a combination of these two cases. They are one byte, with the high bit
set, that are generated by the host. Unlike commands, they are not immediately acted on
by devices in the chain, but are passed on. The Head unit is the first unit to take action.
Instead of a data packet, it generates a response packet, with its own response to the
query. That packet then flows down the chain just like a data packet, with each device
altering the size of the header and adding its own response information to the end of the
packet, so that the packet is a collection of responses by the time it reaches the host.
So, to recap, we have three basic cases. First, typical sample data flow:
12
Second, ‘Commands’:
Third, and finally, the more complicated ‘Query’:
So, for MTS “In Band” communication (normal), the Host receives two kinds of packets:
• Data
• Response
And transmits two types of one byte instructions:
• Commands
• Queries
Not exactly simple, but not ASN encoded H.324 connection negotiation either. Now that
you have the big picture, let’s review the technical details.
13
Packets in General
As covered above, in ‘in band’ (normal) MTS communication, hosts receive two types of
packets, data, and query responses. The packets are almost identical (they are
distinguished by one bit in the header). The basic structure is:
Note that “Word” means two bytes (16 bits), and they are sent in “Big Endian” order, that
is, 0x1234 would be sent in two consecutive bytes, ‘0x12’, then ‘0x34’. For better or
worse, there is no checksum or other form of error checking.
In the Serial 2 document, the header looks a bit daunting:
Header Word
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 1 R 1 D/S
HF X 1
B7 1 B6
B5
B4
B3
B2
B1
B0
But it really breaks down into just a few simple things. First, there are some fixed values:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 1 R 1 D/S
HF X 1
B7 1 B6
B5
B4
B3
B2
B1
B0
These uniquely identify the header from any other in band data sent. When you start
monitoring the stream of bytes you can begin by AND’ing each byte with 0xA2 and
seeing if the result is 0xA2. If it is, you might have synced to the first byte of a packet. If
you AND the next byte with 0x80 and get 0x80, you can be sure. This test should not
pass at any other point in the data stream except the beginning of a packet.
Next, we have the length (in words) of what is to follow:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 1 R 1 D/S
HF X 1
B7 1 B6
B5
B4
B3
B2
B1
B0
This is one byte, so the maximum payload size is 255 words, or 510 bytes. One oddness
is that, because of the fixed values, the size is split and has to be reassembled. But, if you
count off received data, this reconstructed length will lead you to the next header.
14
The last piece of information that we generally care about is the packet type (remember,
we have two):
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 1 R 1 D/S
HF X 1
B7 1 B6
B5
B4
B3
B2
B1
B0
This is all handled by bit 12. A 1 indicates that it is a DATA packet, a 0 indicates that it is
a RESPONSE packet.
This leaves three other bits:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 1 R 1 D/S
HF X 1
B7 1 B6
B5
B4
B3
B2
B1
B0
Of these, only bit 14 might be of interest. It indicates that someone in the chain is
recording. This is how our gauges know when to blink the ‘recording’ light. Bits 10 and
11 should be ignored.
Now that we can sync to the stream and grab packets, let’s look at what is inside them.
Data Packets
In discussing the basic MTS scheme, we referred a lot to ‘devices’, but when analyzing a
data packet, it is much easier to think in terms of what we commonly refer to as
‘channels’. A channel would be a single sensor reading.
Devices can add more than one channel to the data packet (though the firmware in many
of the devices, and our LogWorks software assumes that the total count of channels in the
packet will not exceed 32). But, while an LC-1 adds 1 channel, an LMA-3 adds 5, an OT1b/2 adds from 1-16, and an LM-2 can add up to a whopping 23, the channels added will
always be one of three types:
• An Aux Channel
• A ‘new’ lambda/AFR channel
• An ‘old’ (LM-1) lambda/AFR channel
Aux Channels
An Aux Channel is the simplest, as we can see from the Serial 2 Specification:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
N 0 0
D12
D11
D10
D9
D8
D7 0 D6
D5
D3
D3
D2
D1
D0
15
It has room for 13 bits of data, but all Innovate Devices only use 10 bits. The reason is
legacy/historical. Notice that there is no indication of data size in the one word (two byte)
payload. The first MTS devices sent 10 bit data, and sent it in bits D0 through D9. If a
device now used the upper bits, the host would have no easy way of knowing which
channels require which scale. So, for an Aux Channel, 0 (0x000) is always the minimum,
1023 (0x3FF) is always the maximum.
Note that, unlike the header word, the MSB in both bytes of this word are 0. This is to
facilitate sync/packet parsing, but it does require that the fixed 0 bit has to be removed
and the 10 bit value properly combined for use.
‘New’ Lambda/AFR Channels
A ‘new’ lambda/AFR Channel is a bit more complicated:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 0 1 0 F2
F1
F0 1 AF7 0
AF6 AF5 AF4 AF3 AF2 AF1 AF
0
1 0 0
L12
L11
L10
L9
L8
L7 0 L6
L5
L4
L3
L2
L1
L0
The first thing to note is bit 14 of the first word. Unlike an Aux Channel, which is always
0, in this channel type, it is always 1. This signals that the channel requires an additional
word. Like the Aux Channel, the high bits are 0 in every byte, to help distinguish it from
the header word.
Again, the idea is to facilitate parsing, high bits, think header, counting off channels, bit
14 set, grab another word for this channel… But, again, this also requires that values
sometimes be recombined. Ultimately, the channel contains three basic pieces of
information. First, a value:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 0 1 0 F2
F1
F0 1 AF7 0
AF6 AF5 AF4 AF3 AF2 AF1 AF
0
1 0 0
L12
L11
L10
L9
L8
L7 0 L6
L5
L4
L3
L2
L1
L0
Although our software often clips this value to 10 bits, the devices themselves do, in fact,
send a full 12 bits of information. However, depending on the circumstances, the value
represents different things (lambda, percentage of O2, and error code, etc.). So the packet
contains information about what type of information is being sent:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 0 1 0 F2
F1
F0 1 AF7 0
AF6 AF5 AF4 AF3 AF2 AF1 AF
0
1 0 0
L12
L11
L10
L9
L8
L7 0 L6
L5
L4
L3
L2
L1
L0
These three bits allow for seven different ‘functions’, or data meanings:
16
000 Lambda valid, lambda value contains lambda reading in .001 lambda increments
Offset by .5 lambda (0x000 = .5 lambda, 0x3FF = 1.523 lambda)
001 Lambda value contains O2 level in 1/10%
010 Free air calibration in progress, Lambda data not valid
011 Need Free air Calibration Request, Lambda data not valid
100 Warming up, Lambda value is temp in 1/10% of operating temp.
101 Heater Calibration, Lambda value contains calibration countdown.
110 Error code in Lambda value
111 reserved
If you don’t want to parse all possible states, you can simply go on 000 means valid data,
not 000 means invalid data. Last we have the information needed to approximate AFR
from the actual lambda reading:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0 0 1 0 F2
F1
F0 1 AF7 0
AF6 AF5 AF4 AF3 AF2 AF1 AF
0
1 0 0
L12
L11
L10
L9
L8
L7 0 L6
L5
L4
L3
L2
L1
L0
This is the ‘Air Fuel Multiplier’, scaled by 10. In other words, 147 really represents 14.7.
You would multiply this number by the lambda measurement to get approximate AFR for
the fuel currently specified.
Although you probably have figured all this out, we get asked how to calculate the proper
values from this packet a lot, so, at the risk of repeating, the basic measurements are:
Assemble “L”
Assemble “AF”
Assemble “F”
if (F == 0) // Valid
{
float lambda = (L * 0.001) + 0.500;
float afr = lambda * AF / 10;
}
‘Old’ (LM-1) Lambda/AFR Channels
The old lambda channel (sent only by the LM-1) is the most complicated, and also the
most troublesome for parsing. Although all the sample applications properly parse this
packet, frankly, if you are writing your own parser you might do well to simply ignore it,
unless you know that you will have to deal with connected LM-1’s.
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
0
LM1 R 0
F2
F1
F0 0 AF7 0
AF6 AF5 AF4 AF3 AF2 AF1 AF
0
1 0 0
L12
L11
L10
L9
L8
L7 0 L6
L5
L4
L3
L2
L1
L0
2 0 0
mb2 mb1 mb0 bv9
bv8
bv7 0 bv6
Bv5
bv4
bv4
bv2
bv1
bv0
17
3 0 0
0 0 0
Ax19 Ax18 Ax17 0
Ax16 Ax15 Ax14 Ax13 Ax12 Ax11 Ax1
0
4
0 0 0
0 0 Ax29 Ax28 Ax27 0
Ax26 Ax25 Ax24 Ax23 Ax22 Ax21 Ax2
0
5
0 0 0 0 0
Ax39 Ax38 Ax37 0
Ax36 Ax35 Ax34 Ax33 Ax32 Ax31 Ax3
0
6
0 0 0 0 0
Ax49 Ax48 Ax47 0
Ax46 Ax45 Ax44 Ax43 Ax42 Ax41 Ax4
0
7
0 0 0 0 0
Ax59 Ax58 Ax57 0
Ax56 Ax55 Ax54 Ax53 Ax52 Ax51 Ax5
0
Although the Serial 2 specification documents this as 7 words, the last five (3-7) are Aux
Channels, and can be treated as such. Word 2 contains battery voltage (albeit in a
complex formula) and can also generally be ignored.
This leaves the first two words. The good news is that they contain the same three values
(L, F, and AF) as the ‘new’ lambda channel. And, better still, the meaning is the same.
The bad news is that bit 15 is set in the first word, and bit 14 may or may not be set,
eliminating our ability to find header bytes or count off channels simply. In any event, the
LM-1 channel would have to identified so the battery information would not be
inadvertently treated as an Aux Channel.
Response Packets
If you value your sanity (and the stability of the devices in the MTS chain), you will only
ever send two queries:1
• 0xCE to obtain device names
• 0xF3 to obtain device types
Yes, there are other documented queries, and they look interesting, but these are the only
two that we use in our software, so they are the only ones consistently and correctly
implemented in all devices.
The response packet generated by each is very similar:
The header we covered above. The “Response Type” word is also pretty simple. It is the
Query (0xCE or 0xF3), placed in a word which follows the same rules as an Aux Channel
in a Data Packet. That is, the high bit of both bytes is 0:
Word
Bit
15
Bit
14
Bit
13
Bit
12
Bit
11
Bit
10
Bit 9 Bit8 Bit7 Bit6 Bit5 Bit4 Bit3 Bit3 Bit1 Bit
0
1
For the one exception to this, see “Special Considerations for Network/Wi-Fi” later in this document.
18
N 0 0 0 0 0 0
0
D7 0 D6
D5
D3
D3
D2
D1
D0
This leaves the 4 Words (sometimes easier to think of as 8 bytes in this case) that each
device provides in the response. The response to the 0xCE query you can probably guess.
The 8 bytes contain the Device’s ASCII name, padded to 8 bytes with zeros. Since users
can alter the names, and the default names are the type of device, we use this name
information to provide somewhat descriptive default channel names in our software.
The response to 0xF3, query device types, is also 8 bytes, and contains the following
information:
Byte
0-1
2-5 6 7
Description
Firmware
Version
Identifier
CPU
Channels/Flags
The first two bytes contain the firmware version, encoded in nibbles (Big Endian). For
example, 1.23a would be 0x12 0x3A. The last nibble should be ignored, since it
represents type of build (beta, manufacturing, update dld file, etc.). However, you will
want to pay attention to the upper three nibbles. This SDK requires version 1.02 (0x102n)
or higher to work. All OT-2 units meet this requirement, but OT-1b units may require
firmware update.
The next four bytes are a unique device identifier. This would be “OT1B” or “OT2 ”
(note the trailing space character) for the two devices covered by this SDK. Again, if you
are connected to an OT-2 via Wi-Fi, this is not really something you have to check. But if
you are connected via USB, then you definitely need to check, because you could be
connected to something completely different, like an LM-2.
The CPU byte is a number that represents the CPU and clock speed of the device. This is
only of interest to LM Programmer for firmware updates, so I have no idea why it is
included here, so do not ask.
The last byte is of real interest, but its meaning is device specific. For devices which have
fixed numbers of channels, like the LC-1 and the TC-4, this byte carries some hardware
related flags. In devices that have variable numbers of channels, like the OT-1b/2 and
LM-2, this byte gives information on how many channels that the device is currently
adding to data packets. For the OT-1, OT-1B, and OT-2, using type byte this is simple.
The byte is a binary count of Aux Channels currently being generated.
So, if you are only interested in OT-1b/2 channels, it is not too complicated. You can get
the device type, check this byte, and know that the last n channels in every MTS data
packet are the channels you are interested in.
If you are specifically interested in channels from other devices, it gets more
complicated. You need to know how many channels the fixed count devices each
produce, and you need to understand how the LM-2 uses this byte, which is a bit more
complicated because it can provide variable numbers of both Aux and Lambda channels.
19
At the time of this writing this would be:
Device
Channels
LC-1
(fixed) 1 Lambda
LM-1
(fixed) 1 Lambda (old) + 5 Aux
LMA-3
(fixed) 5 Aux
DL-32
(fixed) 5 Aux
SSI-4
(fixed) 4 Aux
TC-4
(fixed) 4 Aux
OT-1
(variable) Simple Count, 1-16 in last byte of Type Response
OT-1B
(variable) Simple Count, 1-16 in last byte of Type Response
OT-2
(variable) Simple Count, 1-16 in last byte of Type Response
LM-2
(variable) Count (See Below) in last byte of Type Response
* The LM-2 always provides 1 Lambda channel minimum. In addition, the last Type Response
byte has the following meaning, bit 7 set, +1 Lambda (2nd sensor), bit 6 set, +1 Aux (RPM), bit 5
set, +4 Aux (Analog Inputs), bits 0-4, count of additional Aux (OBD-II, can be 0-16)
Important: Remember, because of the way MTS works, the device closest to the host is
the last response in the packet, the device furthest away the first. So, for either a USB or
network connection, the safe procedure to make sure that the rest of the features in this
SDK are available would be:
1. Sync to the MTS stream (find the header and start parsing packets)
2. Send a Type query (0xF3)
3. Check that the last device in the response packet is either an “OT1B” or “OT2 ”
4. Check that (FirmwareVersion & 0xFFF0) >= 0x1020
Commands
Although the OT-1b and the OT-2 both only respond to one in band MTS commands,
there are some others that you might want to send to the chain:
‘c’ - Calibrate (useful for calibrating LC-1s)
‘R’ - Start Recording (works with LM-1, LM-2, and DL-32)
‘r’ - Stop Recording
‘e’ - ‘Erase’
This literally erases the log memory in an LM-1, but with an LM-2 or DL-32, it only
forces the next ‘R’ command to create a new file on the SD card.
If you are reading this SDK, then there is one command that you will probably want to
use for sure, because the OT-1b/2 will respond to it:
‘S’ - Enter Setup Mode…
20
Get to the Good Stuff!
OK, you’ve waded though more stuff on in band MTS communication than any sane
person would ever want to know. Just think of all those wasted brain cells! So now it is
time to start getting some payoff.
You’ve synced to the MTS data stream, you are parsing packets, and you have even
gotten snazzy and checked device types and names (or, you do not care and are ignoring
everything that the OT-1b/2 is currently spitting at you). Now, you send one byte:
‘S’
Congratulations, you have just boldly gone where third party developers have never gone
before (at least with support and documentation), you have entered “Setup Mode”.
This command is mentioned in the Serial 2 protocol specification, but there are no real
details. So…
Setup Mode
Normally, devices can only enter this mode if they are ‘head’, that is, nothing chained
before them. This caveat is because of problems mentioned previously with large
numbers of units in the field which do not properly handle in-chain configuration related
commands. However, the OT-1b and OT-2 are special in that, when connected to via
USB or Wi-Fi (OT-2 only), they can enter Setup Mode at any time. This is because there
are no devices between them and the host to potentially get confused.
When you enter Setup Mode, three things happen immediately.
1. Any data being received from MTS devices upstream, starts being discarded
21
This means that we are no longer receiving packets from the LC-1s in the example above.
In addition, the gauge is no longer receiving information. So, unless you have a
compelling reason to do so, or you know that no other devices are attached to the OT-2,
you do not want to linger in Setup Mode. This relates to the next thing that happens…
2. The OT-1b/2 starts a ‘Watchdog’ timer
Because the units are designed to be setup and left in a vehicle, and because Setup Mode
potentially stops expected behavior with other devices (see #1 above), the firmware takes
steps to insure that you are in Setup Mode on purpose. Namely, it times out and exits
after 10 seconds of inactivity (or more than 2 seconds of delay between bytes on a multibyte command see below).
Setup mode is also exited automatically if the firmware detects that the connection (USB
or Wi-Fi) has been severed. The point behind this is that even if the host software crashes
(or is rudely and suddenly terminated by the operating system, as sometimes occurs on
handheld platforms like Android and the iPhone), the unit will restore itself to a normal
state after a reasonable delay and without user intervention.
It is mentioned here because it can be a gotcha when debugging. You might be single
step debugging, become briefly distracted by the sheer elegance of your code, and then
suddenly find yourself receiving wholly unexpected responses. You look down, and find
that the MTS light on the device itself has started blinking again…
Seriously, as long as we remain aware of it, we have not found this to be much of a
problem in our own debugging. But some platforms can take more than 10 seconds just to
transition from a break point to single step debugging (especially in some embedded
development). So, if you find yourself stumped, and unable to debug your problem
because of the watch dog timer, please let us know and we will help you work around it.
If you simply must stay in Setup Mode, even though you have gaps in needed commands
of 10 seconds or more, you can periodically send the dummy command 0xFF (no
response) to reset the watchdog timer.
3. The OT-1b/2 sends a ‘welcome to setup mode’ message
This message is 15 bytes long and, frankly, the last 9 bytes are essentially gibberish for.
They contain a lot of conditional information that LM Programmer uses for options
presentation and firmware updates. So, for the purposes of this SDK, let’s call them
reserved for Innovate use. This makes our 15 byte message as follows:
Byte
0-1
2-5
6-14
Description
Firmware
Version
Identifier
Bytes you do not need to know about and
which I do not want to document
22
The Firmware Version and Identifier should be exactly the same as the response that you
got for the in band Query Device Types (0xF3). This can be a handy way to ‘sync’ when
entering Setup Mode.
Since data packets have been streaming, you may have an indeterminate amount of data
buffered up. You can send the ‘S’ command, and then parse the data stream until you find
the expected Firmware Version and Identifier. Discard 9 more bytes and you are ready to
begin using Setup Mode Commands.
Setup Mode Commands
Note: Many of the commands below assume you have a basic knowledge of OBD-II. It is
beyond the scope of this SDK to fully cover this, but a good background article can be
found here:
http://www.dakota-truck.net/OBD2/obd2.html
And, although I am loathe to cite it, Wikipedia has some pretty good general material on
the subject (though, since anyone can edit it, that can easily change):
http://en.wikipedia.org/wiki/OBD-II#OBD-II
That out of the way, back to the subject at hand; unlike in-band mode, Setup Mode is not
packeted, and commands and responses are variable in length. There is no terminator or
delimiter (<cr>, <lf>, etc.), bytes are processed as they are received.
Important: In the following list, commands and/or responses are often documented as
pseudo C structures. In all cases, the structures are byte packed (no padding or alignment
bytes) and values are stored in little endian (yes, ‘in band’ communication is all big
endian, but Setup Mode is device specific and the OT-1b/2 is little endian).
Also note, U8, U16, U32, S8, S16, etc. represent unsigned and signed values of the given
number of bits, again in little endian. No, the world does not need yet another set of
standard data types, but we often share code between firmware and host software, so we
have standardized on these.
Similarly, while the example applications generally use defines for various return values,
the following explanations will typically include absolute numbers. This is simply a
matter of preference. I, personally, like to be able to use this sort of reference to
immediately interpret what I am seeing. Using defines adds an extra level of complexity,
since the matching header files, etc. have to be referenced as well.
23
Command ‘S’ - Get Setup Mode Header
Sent: 1 byte
{
U8 Cmd; // ‘S’
}
Responds: 15 bytes
{
U8 VersionH; // Firmware version MSB
U8 VersionL; // Firmware version LSB
U8 Identifier[4]; // Unique identifier
U8 Reserved[9]; // Don’t ask!
}
Notes: This is exactly the same response you receive automatically
when you entered the mode.
Command ‘s’ – Exit Setup Mode
Sent: 1 byte
{
U8 Cmd; // ‘s’
}
Responds: None
Notes: This command returns you to in-band mode, and disables the
watchdog timer.
Loading...