Manual

Introduction

tes•LAX is a CANBus Explorer and visualization tool. While it may be useful for other vehicles, such as the Model S and X, tes•LAX was specifically designed with the Tesla Model 3 in mind.

This manual is intended to help you get the most out of tes•LAX.

Support

tes•LAX is a free-time effort of a single developer. Limited support inquiries can be sent using the issues tracker here: https://github.com/tesLAXApp/tesLAX/issues

Additional Resources

For techncial information the Model 3 CAN Bus, we recommend subscribing to the TechTesla YouTube Channel. TechTesla also has a tes•LAX playlist with specific videos that feature advanced usage of tes•LAX and in-depth discussion of CANBus signals on the Model 3.

Presets

Preset List

A “preset” within tes•LAX is the combination of the list of signals and the gauges configured. Different vehicles may have different signals, and this allows you to quickly switch between configurations.

tes•LAX comes pre-configured with several presets. The “extended release” feature set allows editing of these presets. tes•LAX releases may be bundled with new versions of the signal database. You may be prompted to update their database. To do so, you will need to visit the Preset list.

The bundled Model 3/Y preset is maintained at https://github.com/joshwardell/model3dbc by Josh Wardell with contrabutions from the community. Given that the Tesla changes messages and signals without notice, you may wish to import a more recent DBC. DBC import is part of the “Extra Strength” feature set. Currently, there is no one maintaing a Model S and X database in the same manner. The app provides some signals from various community sources on the web and may be out of date. If you have any suggestions for improving this preset, please submit them using the issue tracker here: https://github.com/tes•LAXApp/tes•LAX/issues

You may see the following icons next to presets in the list:

  • This means this present originally came bundled with tes•LAX but has been since been edited.
  • This means that the current version of tes•LAX contaiins an updated version of this preset. To update, select the preset from the list and tap the button. Then select “Restore Full Preset to Bundled Version” Note that this will erase the exisitng signal database and configured guages and restore the new version as it is bundled with the application. If you previosuly edited this preset, then those changes will be lost.
  • This means that the Preset used to be bundled with tes•LAX but is no longer included or updated. You can chose to keep the preset, or delete it. Since the preset is no longer bundled with tes•LAX, it will be lost and cannot be restored.

When the app contains a bundled preset that is not currently loaded into your active list of presets, it will appear at the bottom of this list under “Available Bundled Presets”. You can opt to add them to your active list or hide them if you do not wish to use it. If you have any hidden presets, you can restore them again using the menu item “Show hiddenpresets”. This will restore any bundled presets that you have hidden in the “Available Bundled Presets” section.

tes•LAX is under active development and while every effort to maintain your custom configurations will be made, some updates may require a database reset.

Tapping an item in the Preset list will activate the preset. A checkmark appears to indicate the active preset. The active preset cannot be deleted.

Tapping the button will bring up the Preset Details screen for the selected preset.

Preset Details

By tappping the button in the preset list, you can see the details of the preset.

You can assign names to numeric bus identifiers in this screen. This is used for multi-bus data sources. See the “Advanced: Muliple Busses” section below for more information.

The Preset Details screen allows the following functions if a preset is bundled with the app:

  • Restore the complete preset (including messages, signals, and configured gauges) from the default bundled version.
  • Restore only the signal database for this preset.
  • Restore only the configured gauges.

The “Extra Strength” feature set provides these additonal features:

  • Edit the preset name, icon, and description by tapping the Edit button in the upper right.
  • Delete a preset
  • Duplicate a preset

The Signal Database

tes•LAX decodes CANBus data by referring to the signal database. The signal database contains messages and signals.

Messages

A message is a group of signals. A message is a single transmission on the CANbus, meaning that all signals within a message are sent/received at the same time.

  • Messages are identified by a 11-bit number called the “Message ID”.
  • The “Message Name” is used to help identify the message. It must be unique and cannot contain spaces.
  • The “Message Size” is the number of bytes of the message. tes•LAX will discard messages that to not have the proper number of bytes.
  • The “Transmitter” is a field used identify which device transmitted a message on the bus. Currently it is not used by tes•LAX.

Signals

A signal contains the value of interest within the message.

  • The Display Name provides a user-friendly way of describing the signal.

  • The Signal Name is an identifier that does not contain spaces. This identifier is used elsewhere in tes•LAX, for example to associate a signal with a gauge.

  • The Message ID field associates a signal to the message and identifies which which message contains the value.

  • The Message Type is one of two values:

    • Standard values are decoded from the bytes in a message stream.
    • Calculated values are determined by executing a small bit of javascript.
  • The Signed/Unsigned field identifies how the bytes are encoded in the message. Signed values are encoded with two’s-complement.

  • Value Type determines how tes•LAX will display the signal. It is one of three values:

    • Integer - the value is an integer (no decimal)
    • Double is a number with a decimal point.
    • Enumeration is a numeric signal that evaluates to a text value. For example 0=Yes and 1=No. The lookup for the value is defined in the “Enumeration Values” section.
  • The Scale identifies the minimum and maximum of the signal. This can be used to define the range of a gauge.

  • Location identifies where in the message the value is found. It also identifies wither the signal is big-endian or little-endian.

  • Factor/Offset determines how the signal is scaled and interpreted. The raw value is the message is multiplied by the factor and added to the offset.

  • Units Type determines the unit of measure for the signal. It can be multiple types:

    • Constant means the unit is always the same, and is a text value defined in the Unit field.
    • Alternate Signal means that the signal’s unit can change based on the value of another signal in the same message. This other signal is usually an enumeration. For example this alternate signal may be 0 for MPH and 1 for KPH. When selecting this type, the signal that contains the unit need to be selected.
    • There are various other unit types, such as Celsius, Fahrenheit, Miles, Kilometers, etc. By selecting one of these types, tes•LAX will convert the units into the users preferred unit type based on the settings.
    • Some unit types like Watt/Kilowatt will also scale based on the size of the value. When a signal with a watts unit grows past 1000w, it will scale to kilowatts.
  • The Enumeration Values section is for values defined as Enumeration and contains the numeric values and textual description. Some non-enumeration values may have a “Signal Not Available (SNA)” enumeration value but tes•LAX does not refer to this for values that are not enumerations.

  • Multiplexing is for multiplexed signals. If applicable the signal identifies the multiplexer within the same message. The multiplexer index identifies the value of the multiplexer when this signal is currently part of the message.

  • Script is for calculated signals. See the Advanced: Javascript for Calculated Signals section for more information on how this works.

Visualization and Gauges

The current visualization can be configured using the menu in the upper right. The word “Gauge” and “Widget” my be used interchangeably.

  • Edit Gauges and Layout lets you add, remove and configure gauges.
  • Flip View will reverse the screen horizontally for use in situations where you want to reflect the display off of another surface.
  • The Columns picker lets you choose a one, two, three, or four column view.

Gauges and Layout

Selecting Gauges and Layout will bring up a list of all the gauges you have configured.

Note: that you must have purchased Extended Release or Extra Strength to edit or add new gauges and pages.

Pages

Pages will appear at the top of the main tes•LAX screen. Each page has a corresponding icon. When a page is selected, the gauges for that page will be displayed in the active area. Note: gauges that are currently on pages other then the active page will also be evaluated. The total number of gauges across all pages should be considered when building a preset. Too many gauges may result in performance degredation. Furthermore, your data source (such as a bluetooth accessory) may have insufficient bandwidth to provide all of the data, resulting in buffer overruns.

** Note**: tes•LAX comes with presets that contain multiple pages, but only the first page is available to users who have not purchased these extended features.

  • The edit option in the upper right will let you reorder or remove gauges or pages.
  • The add new option will let you add a new item to the visualization.

For all gauges, there is a column span parameter which will allow the item to span multiple columns.

Static Text

A static text item is simply a label added to your visualization in the place of a gauge.

Signal Gauge

A signal gauge allows you to visualize a signal.

  • The subtype parameter lets you choose a radial, linear, or numeric digital version of the gauge.
  • For signals that are decimal, you can limit the number of decimal places
  • Range lets you determine the maximum and minimum of the gauge
    • Static will keep the maximum and minimum values as defined in the signal database.
    • Lifetime Max/Min will use the maximum and minimum values as observed over the lifetime of the app.
    • This Drive Max/Min will use the maximum and minimum values as observed during the session as defined by the last time an accessory or log file playback was started.
  • Symmetric Range will center the origin of and make the maximum and minimum values the same (one positive and one negative)

Binary Message

The Binary Message visualization is part of the extra strength feature set. It will show the bits of the message a 8x8 matrix. You must select a message from the signal database.

Binary Signal

The Binary Signal visualization is part of the extra strength feature set. It is the same as the Binary Message visualization, but will highlight the bits of the selected signal in the context of the other bits of the message. You must select a signal from the database.

Signal Metrics

The signal metrics widget will show the maximum and minimum values for the selected signal (both lifetime and for the current drive session). It also lets you reset the the observed maximum and minimum values.

CAN Bus Cam

The CAN Bus Cam feature allows you to record video while overlaying the top four gauges from your current preset.

tes•LAX will request access to your camera, microphone, and photo library for this feature. If granted, tes•LAX only uses these permissions to record audio and video at the user’s request, and save the resulting video to the user’s camera roll.

  • This feature is CPU intensive and may lag or drop frames and audio if your device can’t keep up.
  • Upon pressing the “record” button, the camera will lock to the current orientation (portrait or landscape)
  • Upon completing your recording, the video will save to your camera roll.
  • When recording is complete, press the icon to return to the main screen. This icon will not appear during recording.

Connecting to Accessories

tes•LAX supports connectivity to the OBDLink MX+ accessory. This is currently the only supported bluetooth accessory.

You must first pair and connect to the accessory in the iOS standard Settings app first. Then come into tes•LAX and select “Accessories” from the upper left menu. Any connected accessories will be shown. Tap the accessory to begin a connection.

You can also select connect to first available if you wish tes•LAX to connect to any accessory when it is (or becomes) available for connection.

WiFi Accessories

tes•LAX supports connectivity to WiFi based accessories that use the AT- or ST- command sets. It is recommended that you use an accessory that supports the ST- command set, as it supports filtering. ELM327-based AT- command set accessories do not support filtering and also do not have sufficient performance. Use of such accessories may work with significant buffer overruns and lost packets.

Given the number of accessories in the marketplace, we can not guarantee compatibility with every accessory. Please test your accessory using the free feature set before deciding to purchase additional features.

Also, note that some WiFi accessories use and open network which is not password protected or encrypted. This can pose a security risk, as some accessories allow writing to the CAN bus as well. We do not recommend using accessories with open networks. Please consult your accessory manual or manufacturer to learn if your accessory can be secured before using it with tes•LAX.

Panda OBD-2 Interface

The Panda OBD-2 Inteface for Comma.ai is supported for advanced users. The Panda is not recommended for novice users. Some notes about the Panda:

  • IMPORTANT: Sometime around August 2020, Comma.ai decided to discontinue WiFi support from the Panda White. This makes it unsuitable for use with iOS devices and tes•LAX. Advanced users may wish to re-flash their Panda with an older firmware that maintains WiFi support for use with tes•LAX. Version v1.5.2-DEV has been confirmed to work (see https://github.com/commaai/panda-artifacts) as later versions may have WiFi disabled.
  • There are other accessories that use the same protocol, such as Josh Wardell’s CANServer poduct. If your specific accessory uses a different IP address, you may need to change the accessory settings to before tapping connect. CANServer also supports an extended protocol with filtering. tes•LAX also supports this protocol when used with accessories that support the additional commands.
  • You must join the Panda’s WiFi network in secure mode prior to connecting in tes•LAX. This means that you will require the WiFi password for your Panda. The only way to retreive the password from the Panda is over USB using the Python API. This requires a special USB device called a “Panda Paw” or a non-standard USB-A to USB-A cable without the 5v pin connected.
  • The Panda supports up to 3 busses. You can select which bus you would like delivered to tes•LAX. If you select ‘all’ then every message from any canbus will be delivered to tes•LAX. Typcal OBD-2 harnesses usually use the Panda’s 1st CAN Bus channel (physical bus index = 0).
  • Enabling the “Passive Mode” toggle before initiating a panda connection will put the app into a “listen only” mode. This is for advanced users that want to stream raw UDP data in Panda format to tes•LAX. tes•LAX will not send the keep-alive packets or provision filters in this mode.

File Operations

The “Open File” option in the upper left menu will allow you to select a log file from your iCloud drive or local device. tes•LAX supports the following file types:

  • TXT file - this is a standard log file format of HEX CANBus data. Each line is a a hexadecimal message. The first 3 hexadecimal characters are the message ID, and the remaining hexadecimal characters are the content of the message. It is not timestamped, so tes•LAX will replay a TXT log file at a constant rate.
  • ASC file - this is a typical CANBus file format. It contains additional information, but tes•LAX only refers to the timestamp, message ID, and message bytes. tes•LAX will refer to the timestamp when determining when to deliver the next message to the visualziation.
  • DBC file - import a DBC file into your signal database. See the DBC File Import section for more information

You can playback a file to see the data rendered live on your configured gauges. Alternately, you can convert the log file to CSV.

Convert to CSV

  • ASC files contain timing information and will export timestamps. ASC files will show an option to standardize the time base by selecting a timebase with the slider. This will assemble multiple readings into a single row, with the keeping the latest value for any given signal within the time period. Text files will not have this option.
  • TXT files do not contain timing information and will not contain timestamps.
  • You can opt to carry over the values from the previous row.
  • The CSV exporter supports a maximum of 2000 columns. If your log file contains signals and messages in excess of 2000 columns, the export file will be truncated to 2000 columns.

Log file recording

Log recording is part of the extra strength feature set. When connected to a datasource, it will appear in the upper left menu.

Select the preferred log format (BLF/ASC/TXT) in the setting screen. There is also an option to begin recording immediately upon the connection of an accessory.

Note, that during log file playback you can initiate a log file playback. This isn’t terribly useful other than for offline debugging and testing purposes.

The file formats are as follows:

  • TXT - a text file format that is made up of a 3-digit hexidecimal address followed by the message data in hexidecimal. This is similar to logging the raw data coming from an AT- or ST-command set accessory, but does not include any of the commands being sent to the device or their response.
  • ASC - a more advanced format that supports timestamps and multiple busses
  • BLF - a compressed binary format that supports timestamps and multiple busses.

Note that on slower devices, heavy traffic being rendered to the dispay and logged to file may result in lagging or other issues.

DBC File Import

DBC Import is part of the extra strength feature set. It will allow you to read a DBC file containing a signal database. You have the option to merge the signals into the currently selected preset, or replace all the signals in the currently selected preset.

There are two options in the settings screen that modify the behavior of the DBC import:

  • Import comments as display name if your DBC file uses the comments tag for the signal to hold “user friendly” display name, this option will allow you to import it directly into the display name field. By convention, tes•LAX will import up to the first comma (,) as the display name, and interpret any additional data past the comma as a comment.

  • Keep units as constant values by default, tes•LAX will try to identify unit strings in the DBC file for use with the “preferred units” feature. Selecting this option will disable this fature and import all units as constant strings.

Settings

The settings screen contains the following options:

  • Prevent device from sleeping keeps the display active while running tes•LAX. Note: preventing the device from sleeping can leave static content displayed for a long time. This could could cause image retention for display technologies such as OLED.

  • Show driving reminder When connecting to an accessory, tes•LAX displays a reminder to not use tes•LAX while driving. It is recommended that you leave this option enabled.

  • Reset Counters will clear the observed maximum and minimum values for signals.

  • Log file format see Log File Playback section for more information on supported log file formats.

  • Auto-start logging on connecting of an accessory.

  • Disable filtering while logging normally, tes•LAX will instruct the connected accessory to filter out messages that are not currently displayed in the visualization. This option will disable this filtering during logging. This will allow you to capture all messages on the CANbus. However, this will also overwhelm the MX+ and bluetooth connecting, resulting in buffer overruns and packet loss.

  • DBC Import Options see DBC import section for more information.

  • About this app provides version information for debugging and support purposes.

Other Settings

The default Settings.app contains two options:

  • Reset database will erase the exsiting database and load a fresh copy of the defualt database.

  • Console Logging for debugging only. It is recommended that you don’t enable this option unless requested. The log file will be called “console.log” in the iCloud or local tes•LAX documents directory and will grow unbounded if left enabled.

Advanced: Muliple Busses

Some data sources may provide data coming from multiple CAN buses. This can be from a Panda-compatible accessory, or the playback of an ASC file that contains multiple bus.

  • The data source will often index each message received with a number, starting at zero (zero-indexed) In the tes•LAX user interface, these indexes will appear starting at one.
  • tes•LAX will use the information in the active Preset’s page to convert the numeric tag to an actual bus name
  • tes•LAX has the concept of an “Any Bus” messages sent to Any Bus will be delivered to all signals. Signals set to “Any Bus” will respond to any message regardless of how it is tagged.
  • In the signal list, each message may be assigned to a specific bus name. Only messages from this bus, or “any bus” will be delivered to the message’s associated signals.

Logical Diagram of Multi-Bus Message Flow

Advanced: Filtering and Javascript

Filtering

By default, tes•LAX will configure a connected OBDLink MX+ with filters to reduce the number of packets.

  1. Upon connection, the messages needed by currently configured list of gauges in the visuality will be sent to the accessory for filtering.

  2. When new gauges are added, the CANbus monitoring will be temporary stopped to add add a new filter as needed.

  3. When gauges are removed, the filtering will not be immediately removed. Instead, the app waits for buffer overrun. Before resuming monitoring, the filters will be cleared and reapplied with only the messages needed.

  4. During logging, you can opt to disable filters. This is good for finding new messages in the logs, but you will experience repeated buffer overruns as the MX+ and bluetooth connection may not be able to keep up.

Buffer Overrun

By some estimates, Tesla uses 55-60% of the full 500Mbps of the CANBus. The OBDLink MX+ then converts these messages to a more verbose, human readable hexidecimal format before sending the data over bluetooth to your iOS device. This means that there is a lot of data going over the bluetooth link and often the connection can’t keep up. The app asks MX+ to apply filters such that only the signals you are actively watching are being sent to the iOS device. With the default out-of-the-box view, you may have buffer overruns occasionally, but not repeatedly. You could reduce the number of signals on the display; but as you add more signals, you increase the bandwidth required and may exceed the capacity of the link.

When logging, you have the option to disable filters. As mentioned previously, you will receive repeated buffer overruns when operating in this mode.

When a buffer overrun occurs, the MX+ will temporarily stop monitoring the CANBus. tes•LAX will reprovision the filters if necessary, and then begin monitoring again. This will result in a loss of some packets in the buffer and on the CANBus until monitoring is resotored. In practice, this may result in the some packet loss and a reduction of the refresh rate as you will not be able to receive every message that was transmitted on the CANBus.

You can reduce buffer overruns by applying the following techniques:

  • Reduce the number of gauges on your view. Specifically, you want to be montoring fewer messages. Data transmission rates are not impacted by multiple gauges that monitor signals within the same message.
  • Idenfity and avoid higher transmission rate signals in your visualizations. For example, on the Model 3, some temperature signals are sent at a rate of once-per-second (1hz). Other vehicle controller messages are sent at a rate of 10hz. Craft your gauge selections to show you the data you’re interested and avoid unnecssary signals and messages.
  • Make sure you have a strong, interference-free bluetooth connection to between your iOS device and your MX+ dongle.

JavaScript

For calculated signals, you can configure a bit of JavaScript. Here are a few notes:

Preset scripts

“Preset Scripts” are available in by editing the preset and selecting “Preset Javascript”

  • The ‘Initialization Script’ will execute when a Preset is made active. This is useful for initializing global state or loading libraries.
  • The ‘Periodic Script’ will execute per the configured interval whenever a data source is streaming data.

Calculated Signals

Calculated signals execute and perform calculations on incoming CAN bus data.

  • Calculated signals are still associated with a message. They must be triggered by an incoming message to execute.

    • All signals in the message are decoded and set as variables within the message. This can be used to create calculate signals from signals in the same message.
    • All the bytes of the message are assigned as an array called message[] in the JavaScript context. This can be used to implement custom decoding.
  • Signals being used in the visualization are set as variables in the JavaScript context. If you wish to use a signal from another message, then you need to make sure it is part of your visualization somewhere else.

Examples

Battery Power

At the time of writing, the Model 3, does not have a BattPower signal. Instead, Message 0x132 has BattVoltage132 and SmoothBattCurrent132.

tes•LAX comes pre-configured with signal called “BattPower” which is a calcualted signal with the following JavaScript:

BattVoltage132 * SmoothBattCurrent132 / 1000.0

Note also that this uses the “Kilowatt” unit type, so this signal will scale appropriately for both small and large values.

Average Cell Voltage

Unlike the Model 3, the S & X have a message that shows individual cell voltages.

These are all part of one signal, and they come in multiplexed. This means each time the message is received it will have the voltages for a different set of cells.

In order to calculate an average across all cells, we need to average the CellVoltageXX_6F2 signals.

Since they come in over time, we need to check to see if they exist first (they may not yet have been seen)

This calculated signal is assigned to message 0x6F2 which contains the cell voltages. Every time a 0x6F2 comes in, the values are assigned to the javascript context. Over time all 96 will eventually be available.

function pad(num, size) {
    var s = num+"";
    while (s.length < size) s = "0" + s;
    return s;
}

var total = 0.0
var count = 0.0
for (cell = 1; cell <= 96; cell++) {
  var variable = "CellVoltage"+pad(cell,2)+"_6F2"
    var thisCell = null
    try {
        thisCell = eval(variable)
    } catch(err) {}

    if (thisCell != null) {
        count += 1.0
        total += thisCell
    }
}
total/count

In practice, you will see this signal fluctuate as cell voltages come in over time, until all 96 values are available.

This example also shows that you can have sub functions. (In this case, a quick-and-dirty function to zero-pad a number when determining the signal name)