OpenXC Vehicle Interface Firmware¶

Install Git¶

You need to install Git to retrieve the source code repository for the vi-firmware.

$ sudo apt-get install git

$ [sudo] pacman -S git

Clone the vi-firmware Repository¶

On Windows or Mac and you installed the GitHub app, open the vi-firmware repository in you browser and click the “Clone in Desktop” button.

If you are using git from the command line, clone it like so:

$ git clone https://github.com/openxc/vi-firmware

Install Vagrant (Recommended for All Platforms)¶

On all platforms, we recommend using the included Vagrant configuration to get compiling as quickly as possible. Vagrant is a tool that helps developers create and use identical development environments. We include a Vagrantfile in the repository that Vagrant uses to create a small Linux virtual machine with all of the vi-firmware dependencies installed. Once installed, you can open a shell in this VM just by running vagrant ssh. The vi-firmware on the host OS (e.g. your Linux, Windows or OS X machine) is shared to the Vagrant VM at the path /vagrant. You can use whatever text editor or IDE you prefer in your native OS, and simply do the compilation from within the VM.

1. Install VirtualBox.
2. If using Windows 7 (not required in Windows 8), add the VirtualBox tools to your PATH: PATH=%PATH%;c:\Program Files\Oracle\VirtualBox. If you aren’t sure how to edit your PATH, see this guide for all versions of Windows. Log out and back in for the change to take effect.
3. Install Vagrant.
4. Navigate to the vi-firmware repository in the GitHub app, click the gear icon in the top right corner and select “Open in Git Shell”.
5. In the shell, run vagrant up to initialize the Vagrant VM - this may take up to 10 minutes as it downloads and installs a number of dependencies in the VM.
6. If the initialization completes with no errors, run vagrant ssh to open a shell in the VM.
7. The vi-firmware directly is shared with the VM in the default home directory. Move into that directory and compile away:

$ cd vi-firmware
~/vi-firmware $ fab reference build

You can edit the source code from your native OS and re-run fab reference build from the Vagrant shell to compile (to compile for the reference VI, for example). Run vagrant suspend to suspend the VM and vagrant up again to restore it - it will be much faster after the first run.

Native Development¶

Don’t want to use Vagrant? There are varying levels of support for compiling in your native OS - see the native development environment docs.

CAN Message and Signal Details¶

The message contains driver control signals, so we’ll give it the name Driver_Controls so we can keep track of it. The message ID is 0x102.

In the message, there is a signal we’ll call Accelerator_Pedal_Pos that starts at bit 5 and is 7 bits wide - enough to represent pedal positions from 0 to 100.

The value on the bus is exactly how we want it to appear in the translated version over USB or Bluetooth. We want the name to be accelerator_pedal_position and we want to hide the rest of the details. We want the output format, sent via USB and UART (i.e. Bluetooth) from the VI to be the standard translated OpenXC message format (see the message format specification):

{"name": "accelerator_pedal_position", "value": 42}

JSON Configuration¶

The configuration files for the VI firmware are stored as a single JSON object in a file. JSON is a human-readable data format that’s a alternative to XML - we use it because it’s easy to parse, (sorta) easy to write by hand and the syntax is fairly obvious.

{   "name": "accelerator",
    "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    }
}

{   "name": "accelerator",
    "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "name": "Driver_Controls",
            "bus": "hs"
        }
    }
}

{   "name": "accelerator",
    "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "name": "Driver_Controls",
            "bus": "hs",
            "signals": {
                "Accelerator_Pedal_Pos": {
                    "generic_name": "accelerator_pedal_position",
                    "bit_position": 5,
                    "bit_size": 7
                }
            }
        }
    }
}

One Bus, One Numeric Signal¶

We want to read a single, numeric signal from a high speed bus on controller 1. The signal is 7 bits wide, starting from bit 5 in message ID 0x102. We want the name of the signal for OpenXC app developers to be my_openxc_measurement.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7
                }
            }
        }
    }
}

With this configuration, the VI will publish the received CAN signal using the OpenXC simple vehicle message format, e.g. when using the JSON output format:

{"name": "my_openxc_measurement", "value": 42}

Transformed Numeric Signal¶

We want to read the same signal as in the One Bus, One Numeric Signal example, but we want to transform the value with a factor and offset before publishing it. The value on CAN must be multiplied by -1.0 and offset by 1400.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "factor": -1.0,
                    "offset": 1400
                }
            }
        }
    }
}

We added the factor and offset attributes to the signal.

One Bus, One Boolean Signal¶

We want to read a boolean signal from a high speed bus on controller 1. The signal is 1 bits wide, starting from bit 32 in message ID 0x103. We want the name of the signal for OpenXC app developers to be my_boolean_measurement. Because it is a boolean type, the value will appear as true or false in the JSON for app developers.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x103": {
            "bus": "hs",
            "signals": {
                "My_Boolean_Signal": {
                    "generic_name": "my_boolean_measurement",
                    "bit_position": 32,
                    "bit_size": 1,
                    "decoder": "booleanDecoder"
                }
            }
        }
    }
}

We set the decoder for the signal to the booleanDecoder, one of the built-in signal decoders - this will transform the numeric value from the bus (a 0 or 1) into first-class boolean values (true or false).

With this configuration, the VI will publish the received CAN signal using the OpenXC simple vehicle message format, e.g. when using the JSON output format:

{"name": "my_boolean_measurement", "value": true}

One Bus, One State-based Signal¶

We want to read a signal from a high speed bus on controller 1 that has numeric values corresponding to a set of states - what we call a state-based signal

The signal is 3 bits wide, starting from bit 28 in message ID 0x104. We want the name of the signal for OpenXC app developers to be active_state. There are 6 valid states from 0-5, and we want those to appears as the state strings a through f in the JSON for app developers.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x104": {
            "bus": "hs",
            "signals": {
                "My_State_Signal": {
                    "generic_name": "active_state",
                    "bit_position": 28,
                    "bit_size": 3,
                    "states": {
                        "a": [0],
                        "b": [1],
                        "c": [2],
                        "d": [3],
                        "e": [4],
                        "f": [5]
                    }
                }
            }
        }
    }
}

We set the states field for the signal to a JSON object, mapping the string value for each state to the numerical values to which it corresponds. This automatically will set the decoder to the stateDecoder, one of the built-in signal decoder functions.

With this configuration, the VI will publish the received CAN signal using the OpenXC simple vehicle message format, e.g. when using the JSON output format:

{"name": "active_state", "value": "a"}

Combined State-based Signal¶

We want to read the same state-based signal from One Bus, One State-based Signal but we want the values 0-3 on the bus to all correspond with state a and values 4-5 to the string state b.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x104": {
            "bus": "hs",
            "signals": {
                "My_State_Signal": {
                    "generic_name": "active_state",
                    "bit_position": 28,
                    "bit_size": 3,
                    "states": {
                        "a": [0, 1, 2, 3],
                        "b": [4, 5]
                    }
                }
            }
        }
    }
}

Each state string maps to an array - this can seem unnecessary when you only have 1 numeric value for each state, but it allows combined mappings as in this example.

Two Buses, Two Signals¶

We want to read two numeric signals - one from a message on a high speed bus on controller 1, and the other from a message on a medium speed bus on controller 2.

The signal on the high speed bus is 12 bits wide, starting from bit 11 in message ID 0x108. We want the name of the signal for OpenXC app developers to be my_first_measurement.

The signal on the medium speed bus 14 bits wide, starting from bit 0 in message ID 0x90. We want the name of the signal for OpenXC app developers to be my_second_measurement.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        },
        "ms": {
            "controller": 2,
            "speed": 125000
        }
    },
    "messages": {
        "0x108": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_first_measurement",
                    "bit_position": 11,
                    "bit_size": 12
                }
            }
        },
        "0x90": {
            "bus": "ms",
            "signals": {
                "My_Other_Signal": {
                    "generic_name": "my_second_measurement",
                    "bit_position": 0,
                    "bit_size": 14
                }
            }
        }
    }
}

We added the second bus to the buses field and assigned it to controller 2. We added the second message object and made sure to set its bus field to ms.

With this configuration, the VI will publish the received CAN signal using the OpenXC simple vehicle message format, e.g. when using the JSON output format:

{"name": "my_first_measurement", "value": 42}
{"name": "my_second", "value": 942}

Limited Simple Vehicle Message Signal Rate¶

We want to read the same signal as in the One Bus, One Numeric Signal example, but we want it to be sent at a maximum of 5Hz. We want the firmware to pick out messages at a regular period, but we don’t care which data is dropped in order to stay under the maximum.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "max_frequency": 5
                }
            }
        }
    }
}

We set the max_frequency field of the signal to 5 (meaning 5Hz) - the firmware will automatically handle skipping messages to stay below this limit.

Limited Simple Message Rate if Unchanged¶

We want the same signal from Limited Simple Vehicle Message Signal Rate at a limited rate, but we don’t want to lose any information - if the value of the signal changes, we want it to be sent regardless of the max frequency. Repeated, duplicate signal values are fairly common in vehicles, where a signal is sent at a steady frequency even if the value hasn’t changed. For this example, we want to preserve all information - if a signal changes, we want to make sure the data is sent.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "max_frequency": 5,
                    "force_send_changed": true
                }
            }
        }
    }
}

We added the force_send_changed field to the signal, which will make sure the signal is sent immediately when the value changes. This rate limiting is lossless.

Send Signal on Change Only¶

We want to limit the rate of a signal as in Limited Simple Message Rate if Unchanged, but we want to be more strict - the signal should only be published if it actually changes.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "send_same": false
                }
            }
        }
    }
}

We accomplish this by setting the send_same field to false. This is most appropriate for boolean and state-based signals where the transition is most important. Considering that a host device may connect to the VI after the message has been sent, using this field has the potential of making it difficult to tell the current state of the vehicle on startup - you have to wait for a state change before knowing any values. For that reason, we’ve moved away from using this for most firmware (using a combination of a max_frequency of 1Hz and force_send_changed == true) but the option is still available.

Separate Files for Message Sets¶

Starting from the Two Buses, Two Signals example, we want to split up the configuration into mutiple files because it’s getting too big and hard to follow. This will especially be true as we add more message and signals.

Starting from this complete configuration:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        },
        "ms": {
            "controller": 2,
            "speed": 125000
        }
    },
    "messages": {
        "0x108": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_first_measurement",
                    "bit_position": 11,
                    "bit_size": 12
                }
            }
        },
        "0x90": {
            "bus": "ms",
            "signals": {
                "My_Other_Signal": {
                    "generic_name": "my_second_measurement",
                    "bit_position": 0,
                    "bit_size": 14
                }
            }
        }
    }
}

we move the messages that we want to read from the hs bus to the file hs.json:

{
    "messages": {
        "0x108": {
            "signals": {
                "My_Signal": {
                    "generic_name": "my_first_measurement",
                    "bit_position": 11,
                    "bit_size": 12
                }
            }
        }
    }
}

and we move the messages that we want to read from the ms bus to the file ms.json:

{
    "messages": {
        "0x90": {
            "signals": {
                "My_Other_Signal": {
                    "generic_name": "my_second_measurement",
                    "bit_position": 0,
                    "bit_size": 14
                }
            }
        }
    }
}

Notice in both of these files, the messages no longer have the bus attribute - we’re instead going to specify that in the top level configuration:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        },
        "ms": {
            "controller": 2,
            "speed": 125000
        }
    },
    "mappings": [
        {"mapping": "hs.json", "bus": "hs"},
        {"mapping": "ms.json", "bus": "ms"}
    ]
}

The primary advantage of using separate files is readability, but it also makes the message definitions more re-usable between vehicle platforms and buses. For example, we could quickly parse all of the messages from the ms.json mapping file from the hs bus instead of ms by flipping the bus attribute in the top-level config file.

Mapped from a DBC File¶

If you use Vector DBC files to store your “gold standard” CAN signal definitions, you can save some effort by exporting the DBC to an XML file and merging it with your VI configuration file. You won’t need to manually copy the bit_position, bit_size, factor and offset attributes.

If we are to implement One Bus, One Numeric Signal manually, we would use this configuration file:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "factor": -1.0,
                    "offset": 1400
                }
            }
        }
    }
}

If the message and signal is defined in a DBC file, we can save some effort. Using a program like Vector CANdb++, export the DBC file to XML. Place the XML file in the same directory as your JSON configuration file. We need to first split up the configuration into a mapped messages file and a top-level config, as in Separate Files for Message Sets example.

In our config.json:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "mappings": [
         {"mapping": "hs.json", "bus": "hs"}
    ]
}

and in hs.json:

{
    "messages": {
        "0x102": {
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "factor": -1.0,
                    "offset": 1400
                }
            }
        }
    }
}

Now that we have the DBC exported to an XML file (we’ll assume it’s named exported-hs.xml), we can remove the bit_position, bit_size, factor and offset fields and let them be imported from the XML - the only thing required is a generic_name:

In our config.json:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "mappings": [
         {"mapping": "hs.json",
            "bus": "hs",
            "database": "exported-hs.xml"}
    ]
}

and in hs.json:

{
    "messages": {
        "0x102": {
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement"
                }
            }
        }
    }
}

It’s not huge savings for 1 signal, but once you get a dozen it can save a lot of effort and opportunities for bugs.

Same Message ID, Two Buses¶

One shortcoming of a single configuration file is that you can’t define a CAN message with the same ID to exist on two different, buses. For example, this isn’t value JSON because the 0x100 key is repeated:

{
    "messages": {
        "0x100": {
            "bus": "hs"
         },
         "0x100": {
            "bus": "ms"
         }
    }
}

Instead, you can use mappings files as in Separate Files for Message Sets and put the messages for each bus in separate files. Here’s the main configuration file:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        },
        "ms": {
            "controller": 2,
            "speed": 125000
        }
    },
    "mappings": [
        {"mapping": "hs.json", "bus": "hs"},
        {"mapping": "ms.json", "bus": "ms"}
    ]
}

and here’s hs.json:

{
    "messages": {
        "0x100": {
             "My_Signal": {
                 "generic_name": "my_first_measurement",
                 "bit_position": 3,
                 "bit_size": 7
             }
        }
    }
}

and finally, ms.json:

{
    "messages": {
        "0x100": {
            "signals": {
                "My_Other_Signal": {
                    "generic_name": "my_second_measurement",
                    "bit_position": 0,
                    "bit_size": 14
                }
            }
        }
    }
}

The two different CAN messages with the same ID can co-exist in these separate files, linked as mappings through the main config.

Unfiltered Raw CAN¶

We want to read all raw CAN messages from a bus at full speed. Be aware that the VI hasn’t been optimized for this level of throughput, and it’s not guaranteed at this time that messages will not be dropped. We recommend using rate limiting, which can dramatically decrease the bandwidth required without losing any information.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000,
            "raw_can_mode": "unfiltered"
        }
    }
}

With this configuration, the VI will publish all CAN messages it receives using the OpenXC raw CAN message format, e.g. when using the JSON output format:

{"bus": 1, "id": 1234, "value": "0x12345678"}

Filtered Raw CAN¶

We want to read only the message with ID 0x21 from a high speed bus on controller 1.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000,
            "raw_can_mode": "filtered"
        }
    },
    "messages": {
      "0x21": {
        "bus": "hs"
      }
    }
}

We added the 0x21 message and assigned it to bus hs, but didn’t define any signals (it’s not necessary when using the raw CAN mode).

This configuration will cause the VI to publish using the OpenXC raw CAN message format, but you will only received message 0x21.

Unfiltered Raw CAN with Limited, Variable Data Rate¶

We want to read all raw CAN messages from a bus, but we don’t want the output interface to be overwhelmed by repeated duplicate messages. This is fairly common in vehicles, where a message is sent at a steady frequency even if the value hasn’t changed. For this example, we want to preserve all information - if a message changes, we want to make sure the data is sent.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000,
            "raw_can_mode": "unfiltered",
            "max_message_frequency": 1,
            "force_send_changed": true
        }
    }
}

We combine two attributes to both limit the data rate from raw CAN messages, and also make sure the transfer is lossless. The max_message_frequency field sets the maximum send frequency for CAN messages that have not changed to 1Hz. We also set the force_send_changed field to true, which will cause a CAN message with a new value to be sent to the output interface immediately, even if it would go above the 1Hz frequency. The default is true, so we could also leave this parameter out for the same effect. The result is that each CAN message is sent at a minimum of 1Hz and a maximum of the true rate of change for the message.

Unfiltered Raw CAN with Strict, Limited Data Rate¶

We want to read all raw CAN messages as in Unfiltered Raw CAN with Limited, Variable Data Rate but we want to set a strict limit on the read frequency of each CAN message. We don’t care if we skip some CAN messages, even if they have new data - the maximum frequency is the most important thing.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000,
            "raw_can_mode": "unfiltered",
            "max_message_frequency": 1,
            "force_send_changed": false.
        }
    }
}

We set the force_send_changed field to false so the firmware will strictly enforce the max message frequency.

Simple Messages and CAN Messages Together¶

We want to read the same signal as in the One Bus, One Numeric Signal example, but we also want to receive all unfiltered CAN messages simultaneously.

{   "buses": {
        "hs": {
            "controller": 1,
            "raw_can_mode": "unfiltered",
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7
                }
            }
        }
    }
}

We added set the raw_can_mode for the bus to unfiltered, as in Unfiltered Raw CAN. No other changes are required - the CAN and simple vehicle messages co-exist peacefully. If we set raw_can_mode to filtered, it would only send the raw message for 0x102, where we’re getting the numeric signal.

With this configuration, the VI will publish a mixed stream of OpenXC messages, both the CAN message format, and the simple vehicle message format, e.g. when using the JSON output format:

{"bus": 1, "id": 258, "value": "0x12345678"}
{"name": "my_openxc_measurement", "value": 42}

Custom Transformed Numeric Signal¶

Similar to the Transformed Numeric Signal example, we want to modify a numeric value read from a CAN signal before sending it to the app developer, but the the desired transformation isn’t as simple as an offset. We want to read the same signal as before, but if it’s below 100 it should be rounded down to 0. We want our custom transformation to happen after using the existing factor and offset.

To accomplish this, we need to know a little C - we will write a custom signal decoder to make the transformation. Here’s the JSON configuration:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "factor": -1.0,
                    "offset": 1400,
                    "decoder": "ourRoundingDecoder"
                }
            }
        }
    },
    "extra_sources": [
      "my_handlers.cpp"
    ]
}

We set the decoder for the signal to ourRoundingDecoder, and we’ll define that in a separate file named my_handlers.cpp. We also added the extra_sources field, which is a list of the names of C++ source files on our path to be included with the generated firmware code.

In my_handlers.cpp:

/* Round the value down to 0 if it's less than 100. */
float ourRoundingDecoder(CanSignal* signal, CanSignal* signals,
      int signalCount, float value, bool* send) {
   if(value < 100) {
      value = 0;
   }
   return value;
}

After being transformed with the factor and offset for the signal from the configuration file, the value is passed to our decoder. We make whatever custom transformation required and return the new value.

There are a few other valid type signatures for these custom value decoders - for converting numeric values to boolean or state-based signals.

Transformed with Signal Reference¶

We need to combine the values of two signals from a CAN message to create a single value - one signal is the absolute value, the other is the sign.

Both signals are on the high speed bus in the message with ID 0x110. The absolute value signal is 5 bits wide, starting from bit 2. The sign signal is 1 bit wide, starting from bit 12 - when the value of the sign signal is 0, the final value should be negative. We want to the final value to be sent to app developers with the name my_signed_measurement.

We will use a custom decoder for the signal to reference the sign signal’s last value when transforming the absolute value signal.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x110": {
            "bus": "hs",
            "signals": {
                "My_Value_Signal": {
                    "generic_name": "my_signed_measurement",
                    "bit_position": 2,
                    "bit_size": 5,
                    "decoder": "ourSigningDecoder"
                },
                "My_Sign_Signal": {
                    "generic_name": "sign_of_signal",
                    "bit_position": 12,
                    "bit_size": 1,
                    "decoder": "ignoreDecoder"
                }
            }
        }
    },
    "extra_sources": [
      "my_handlers.cpp"
    ]
}

We don’t want to the sign signal to be sent separately on the output interfaces, but we need the firmware to read and store its value so we can refer to it from our custom decoder. We set the sign signal’s decoder to ignoreDecoder which will still process and store the value, but withold it from the output data stream.

For the absolute value signal, we set the decoder to a custom function where we look up the sign signal and use its value to transform the absolute value. In my_handlers.cpp:

/* Load the last value for the sign signal and multiply the absolute value
by it. */
float ourRoundingDecoder(CanSignal* signal, CanSignal* signals,
      int signalCount, float value, bool* send) {
    CanSignal* signSignal = lookupSignal("sign_of_signal",
            signals, signalCount);

    if(signSignal == NULL) {
        debug("Unable to find sign signal");
        *send = false;
    } else {
        if(signSignal->lastValue == 0) {
            // left turn
            value *= -1;
        }
    }
    return value;
}

We use the lookupSignal` function to load a struct representing the sign_of_signal CAN signal we defined in the configuration, and check the lastValue attribute of the struct. If for some reason we aren’t able to find the configured sign signal, lookupSignal will return NULL and we can stop hold the output of the final value by flipping *send to false. The firmware will check the value of *send after each call to a decoder to confirm if the translation pipeline should continue.

One slight problem with this approach: there is currently no guaranteed ordering for the signals. It’s possible the lastValue for the sign signal isn’t from the same message as the absolute value signal you are current handling in the function. With a continuous value, there’s only a small window where this could happen, but if you must be sure the values came from the same message, you may need to write a Composite Signal.

Composite Signal¶

We want complete control over the output of a measurement from the car. We have a CAN message that includes 3 different signals that represent a GPS latitude value, and want to combine them into a single value in degrees.

The three signals are in the message 0x87 on a high speed bus connected to controller 1. The three signals:

• The whole latitude degrees signal starts at bit 10 and is 8 bits wide. The value on CAN requires an offset of -89.0.
• The latitude minutes signal starts at bit 18 and is 6 bits wide.
• The latitude minute fraction signal starts at bit 24 and is 14 bits wide. The value on CAN requires a factor of .0001.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x87": {
            "bus": "hs",
            "handlers": ["latitudeMessageHandler"],
            "signals": {
                "Latitude_Degrees": {
                    "generic_name": "latitude_degrees",
                    "bit_position": 10,
                    "bit_size": 8,
                    "offset": -89,
                    "ignore": true
                },
                "Latitude_Minutes": {
                    "generic_name": "latitude_minutes",
                    "bit_position": 18,
                    "bit_size": 6,
                    "ignore": true
                },
                "Latitude_Minute_Fraction": {
                    "generic_name": "latitude_minute_fraction",
                    "bit_position": 24,
                    "bit_size": 14,
                    "factor": 0.0001,
                    "ignore": true
                },
            }
        }
    },
    "extra_sources": [
      "my_handlers.cpp"
    ]
}

We made two changes to the configuration from a simple translation config:

• We set the ignore field to true for each of the component signals in the message. The signal definitions (i.e. the position, offset, etc) will be included in the firmware build so we can access it from a custom message handler, but the signals will not be processed by the normal translation stack.
• We set the handlers for the 0x87 message to an array containing our custom message handler, latitudeMessageHandler. This field should be an array as you can provide multiple message handlers. You could just call multiple handlers from a single handler function, but having them all defined in the configuration file makes the behavior more clear at a glance.

In my_handlers.cpp:

/* Combine latitude signals split into their components (degrees,
 * minutes and fractional minutes) into 1 output message: latitude in
 * degrees with with decimal precision.
 *
 * The following signals must be defined in the signal array, and they must
 * all be contained in the same CAN message:
 *
 *      * latitude_degrees
 *      * latitude_minutes
 *      * latitude_minutes_fraction
 *
 * This is a message handler, and takes care of sending the output message.
 *
 * messageId - The ID of the received GPS latitude CAN message.
 * data - The CAN message data containing all GPS latitude information.
 * signals - The list of all signals.
 * signalCount - The length of the signals array.
 * send - (output) Flip this to false if the message should not be sent.
 * pipeline - The pipeline that wraps the output devices.
 *
 * This type signature is required for all custom message handlers.
 */
void latitudeMessageHandler(CanMessage* message, CanSignal* signals,
        int signalCount, Pipeline* pipeline) {
    // Retrieve the CanSignal struct representations of the 3 latitude
    // component signals. These are still included in the firmware build
    // when the 'ignore' flag was true for the signals.
    CanSignal* latitudeDegreesSignal =
        lookupSignal("latitude_degrees", signals, signalCount);
    CanSignal* latitudeMinutesSignal =
        lookupSignal("latitude_minutes", signals, signalCount);
    CanSignal* latitudeMinuteFractionSignal =
        lookupSignal("latitude_minute_fraction", signals, signalCount);

    // Confirm that we have all required signal components
    if(latitudeDegreesSignal == NULL ||
            latitudeMinutesSignal == NULL ||
            latitudeMinuteFractionSignal == NULL) {
        debug("One or more GPS latitude signals are missing");
        return;
    }

    // begin by assuming we will send the message, no errors yet
    bool send = true;

    // Decode and transform (using any factor and offset defined in the
    // CanSignal struct) each of the component signals from the message data
    // preTranslate is intended to be used in conjunction with postTranslate
    // - together they keep metadata about the receive signals in memory.
    float latitudeDegrees = preTranslate(latitudeDegreesSignal, data, &send);
    float latitudeMinutes = preTranslate(latitudeMinutesSignal, data, &send);
    float latitudeMinuteFraction = preTranslate(
            latitudeMinuteFractionSignal, data, &send);

    // if we were able to decode all 3 component signals (i.e. none of the
    // calls to preTranslate flipped 'send' to false
    if(send) {
        float latitude = (latitudeMinutes + latitudeMinuteFraction) / 60.0;
        if(latitudeDegrees < 0) {
            latitude *= -1;
        }
        latitude += latitudeDegrees;

        // Send the final latitude value to the output interfaces (via the
        // pipeline)
        sendNumericalMessage("latitude", latitude, pipeline);
    }

    // Conclude by updating the metadata for each of the component signals
    // with postTranslate
    postTranslate(latitudeDegreesSignal, latitudeDegrees);
    postTranslate(latitudeMinutesSignal, latitudeMinutes);
    postTranslate(latitudeMinuteFractionSignal, latitudeMinuteFraction);
}

A more complete, functional example of a message handler is included in the VI firmware repository - one that handles both latitude and longitude in a CAN message. There is also additional documentation on the message handler type signature.

Initializer Function¶

We want to initialize a counter when the VI powers up that we will use from some custom signal decoder.

{   "buses": {
        "hs": {
            "controller": 1,
            "raw_can_mode": "unfiltered",
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7
                }
            }
        }
    },
    "initializers": [
       "initializeMyCounter"
    ],
    "extra_sources": [
      "my_initializers.cpp"
    ]
}

We added an initializers field, which is an array containing the names of C functions matching the initializer type signature.

In my_initializers.cpp:

int MY_COUNTER;
void initializeMyCounter() {
   MY_COUNTER = 42;
}

This isn’t a very useful initializer, but there much more you could do - you’ll want to look into the lowest level APIs in the firmware source. Look through the .h files, where most functions are documented.

Looper Function¶

We want to increment a counter every time through the main loop of the firmware, regardless of whatever CAN messages we may have received.

{   "buses": {
        "hs": {
            "controller": 1,
            "raw_can_mode": "unfiltered",
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7
                }
            }
        }
    },
    "loopers": [
       "incrementMyCounter"
    ],
    "extra_sources": [
      "my_loopers.cpp"
    ]
}

We added a loopers field, which is an array containing the names of C functions matching the looper type signature.

In my_loopers.cpp:

void incrementMyCounter() {
   static int myCounter = 0;
   ++myCounter;
}

As with the initializer, this isn’t a very functional example, but there much more you could do - you’ll want to look into the lowest level APIs in the firmware source. Look through the .h files, where most functions are documented.

Ignore Depending on Value¶

We want to ignore a signal (and not translate it and send over USB/Bluetooth) if the value matches certain critera. We’ll use a custom decoder as in Custom Transformed Numeric Signal but instead of modifying the value of the signal, we’ll use the send flag to tell the VI if it should process the value or not.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "factor": -1.0,
                    "offset": 1400,
                    "decoder": "ourFilteringDecoder"
                }
            }
        }
    },
    "extra_sources": [
      "my_handlers.cpp"
    ]
}

In my_handlers.cpp:

/* Ignore the signal if the value is less than 100 */
float ourFilteringDecoder(CanSignal* signal, CanSignal* signals,
      int signalCount, float value, bool* send) {
   if(value < 100) {
      *send = false;
   }
   return value;
}

Named Numeric Signal Write Request¶

We want to send a single numeric value to the VI, and have it translated back into a CAN signal in a message on a high speed bus attached to controller 1. The signal is 7 bits wide, starting from bit 5 in message ID 0x102. We want the name of the signal that will be sent to the VI to be my_openxc_measurement.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "writable": true
                }
            }
        }
    }
}

This configuration is the same as the read-only example One Bus, One Numeric Signal with the addition of the writable flag to the signal. When this flag is true, an OpenXC message sent back to the VI from an app with the name my_openxc_measurement will be translated to a CAN signal in a new message and written to the bus.

If the VI is configured to use the JSON output format, sending this OpenXC single-valued message to the VI via USB or UART (Bluetooth) would trigger a CAN write:

{"name": "my_openxc_measurement", "value": 42}

With the tools from the OpenXC Python library you can send that from a terminal with the command:

openxc-control write --name my_openxc_measurement --value 42

and if you compiled the firmware with DEBUG=1, you can view the view the logs to make sure the write went through with this command:

openxc-control write --name my_openxc_measurement --value 42 --log-mode stderr

Named Boolean Signal Write Request¶

We want to send a single boolean value to the VI, and have it translated back into a CAN signal in a message on a high speed bus attached to controller 1. The signal is 1 bits wide, starting from bit 3 in message ID 0x201. We want the name of the signal that will be sent to the VI to be my_boolean_request.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_boolean_request",
                    "bit_position": 3,
                    "bit_size": 1,
                    "writable": true,
                    "encoder": "booleanWriter"
                }
            }
        }
    }
}

In addition to setting writable to true, We set the encoder for the signal to the built-in booleanWriter. This will handle converting a true or false value from the user back to a 1 or 0 in the outgoing CAN message.

If the VI is configured to use the JSON output format, sending this OpenXC single-valued message to the VI via USB or UART (Bluetooth) would trigger a CAN write:

{"name": "my_boolean_request", "value": true}

With the tools from the OpenXC Python library you can send that from a terminal with the command:

openxc-control write --name my_boolean_request --value true

Named State-based Signal Write Request¶

We want to send a state as a string to the VI, and have it translated back into a numeric CAN signal in a message on a high speed bus attached to controller 1. As in One Bus, One State-based Signal, the signal is 3 bits wide, starting from bit 28 in message ID 0x104. We want the name of the signal for OpenXC app developers to be active_state. There are 6 valid states from 0-5 in the CAN signal, but we want the app developer to send the strings a through f to the VI.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_state_request",
                    "bit_position": 28,
                    "bit_size": 3,
                    "states": {
                        "a": [0],
                        "b": [1],
                        "c": [2],
                        "d": [3],
                        "e": [4],
                        "f": [5]
                    },
                    "writable": true
                }
            }
        }
    }
}

The writable field is all that is required - the signal will be automatically configured to use the built-in stateWriter as its encoder because the signal has a states array. If a user sends the VI the value c in a write request with the name my_state_request, it will be encoded as 2 in the CAN signal in the outgoing message.

If the VI is configured to use the JSON output format, sending this OpenXC single-valued message to the VI via USB or UART (Bluetooth) would trigger a CAN write:

{"name": "my_state_request", "value": "a"}

With the tools from the OpenXC Python library you can send that from a terminal with the command:

openxc-control write --name my_state_request --value "\"a\""

Becuase of the way string escaping works from the command prompt, you have to add escaped \" characters so the tool knows you want to send a string.

Named, Transformed Written Signal¶

We want to write the same signal as Named Numeric Signal Write Request but round any values below 100 down to 0 before sending (similar to the read-only example Custom Transformed Numeric Signal).

To accomplish this, we need to know a little C - we will write a custom signal encoder to make the transformation. Here’s the JSON configuration:

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000
        }
    },
    "messages": {
        "0x102": {
            "bus": "hs",
            "signals": {
                "My_Signal": {
                    "generic_name": "my_openxc_measurement",
                    "bit_position": 5,
                    "bit_size": 7,
                    "factor": -1.0,
                    "offset": 1400,
                    "encoder": "ourRoundingWriteEncoder"
                }
            }
        }
    },
    "extra_sources": [
      "my_handlers.cpp"
    ]
}

We set the encoder for the signal to ourRoundingWriteEncoder, and we’ll define that in a separate file named my_handlers.cpp. The extra_sources field is also set, meaning that our custom C/C++ code will be included with the firmware build.

In my_handlers.cpp:

/* Round the value down to 0 if it's less than 100 before writing to CAN. */
uint64_t ourRoundingWriteEncoder(CanSignal* signal, CanSignal* signals,
     int signalCount, double value, bool* send) {
   if(value < 100) {
      value = 0;
   }
   // encodeSignal pulls the CAN signal definition from the CanSignal struct
   // and encodes the value into the right bits of a 64-bit return value.
   return encodeSignal(signal, value);
}

Signal encoders are responsible for transforming a float, string or boolean value into a 64-bit integer, to be used in the outgoing message.

Composite Write Request¶

When the app developer sends a numeric measurement to the VI, we want to send:

• 1 arbitrary CAN message with the ID 0x34 on a high speed bus connected to controller 1, with the value 0x1234.
• The value sent by the developer encoded into the message ID 0x35 in a signal starting at bit 0, 4 bits wide on the same high speed bus. We don’t want this value to be writable by the app developer unless a part of these 3 writes combined.
• A boolean signal in the message 0x101 on a medium speed bus connected to controller 2, starting at bit 12 and 1 bit wide. If the numeric value from the user is greater than 100, the boolean value should be true.

{   "name": "passthrough",
    "buses": {
        "hs": {
            "controller": 1,
            "raw_writable": true,
            "speed": 500000
         },
         "ms": {
            "controller": 2,
            "speed": 125000
         }
    },
    "messages": {
        "0x35": {
            "bus": "hs",
            "signals": {
                "My_Numeric_Signal": {
                    "generic_name": "my_number_signal",
                    "bit_position": 0,
                    "bit_size": 4
                }
            }
        }
        "0x101": {
            "bus": "ms",
            "signals": {
                "My_Other_Signal": {
                    "generic_name": "my_value_is_over_100_signal",
                    "bit_position": 12,
                    "bit_size": 1
                }
            }
        }
    },
    "commands": [
       {"name": "my_command",
          "handler": "handleMyCommand"}
    ],
    "extra_sources": [
      "my_handlers.cpp"
    ]
}

We added a commands field, which contains an array of JSON objects with name and handler fields. The name of the command, my_command is what app developers will send to the VI. The handler is the name of a C++ function will define in one of the files listed in extra_sources.

In the configuration, also note that:

• The raw CAN message that we want to send isn’t included. Since raw_writable is true for the hs bus, there’s no need to define it in the configuration.
• The my_number_signal signal doesn’t have the writable flag set to true (it’s omitted, and the default is false). This means an app developer will not be able to send write requests for my_number_signal directly.

In my_handlers.cpp:

void handleMyCommand(const char* name, openxc_DynamicField* value,
      openxc_DynamicField* event, CanSignal* signals, int signalCount) {

   // Look up the numeric and boolean signals we need to send and abort if
   // either is missing
   CanSignal* numericSignal = lookupSignal("my_number_signal", signals,
         signalCount);
   CanSignal* booleanSignal = lookupSignal("my_value_is_over_100_signal",
         signals, signalCount);
   if(numericSignal == NULL || booleanSignal == NULL) {
      debug("Unable to find signals, can't send trio");
      return;
   }

   // Build and enqueue the arbitrary CAN message to be sent - note that none
   // of the CAN messages we enqueue in the handler will be sent until after
   // it returns - interaction with the car via CAN must be asynchronous.
   CanMessage message = {0x34, 0x12345};
   CanBus* bus = lookupBus(0, getCanBuses(), getCanBusCount());
   if(bus != NULL) {
     can::write::enqueueMessage(bus, &message);
   }

   // Send the numeric signal
   can::write::encodeAndSendSignal(numericSignal, value,
          // the last parameter is true, meaning we want to force sending
          // this signal even though it's not marked writable in the
          // config
          true);

   // For the boolean signal, send 'true' if the value sent by the user is
   // greater than 100
   can::write::encodeAndSendBooleanSignal(booleanSignal, value > 100, true);
}

Write a CAN messages¶

There’s not much to configure for raw CAN writes, since your application is decided what message to build instead of the VI. The only requirement is that the bus you wish to write on is configured as writable with the raw_writable flag, otherwise the VI will reject the request to send.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000,
             "raw_writable": true
        }
    }
}

With this configuration, you can send a CAN message write request to the VI using the OpenXC raw CAN message format (via any of the I/O interfaces) and it will send it out to the bus. For example, when using the JSON output format, sending this to the VI:

{"bus": 1, "id": 1234, "value": "0x12345678"}

would cause it to write a CAN message with the arbitration ID 1234 and the payload 0x12345678 to the bus attached to the first CAN controller.

With the tools from the OpenXC Python library you can send that from a terminal with the command:

openxc-control write --bus 1 --id 1234 ---data 0x12345678

and if you compiled the firmware with DEBUG=1, you can view the view the logs to make sure the write went through with this command:

openxc-control write --bus 1 --id 1234 ---data 0x12345678 --log-mode stderr

Writing with Filtered CAN¶

It’s also possible to write arbitrary CAN messages with you are using filtered raw CAN reads. Your write requests aren’t restricted to the filtered set, simply add the raw_writable flag and you can send any message.

{   "buses": {
        "hs": {
            "controller": 1,
            "speed": 500000,
            "raw_can_mode": "filtered",
             "raw_writable": true
        }
    },
    "messages": {
      "0x21": {
        "bus": "hs"
      }
    }
}

The rest is the same as in the unfiltered write example.

Recurring Simple Diagnostic PID Request¶

We want to send a request for a mode 0x22 PID once per second and publish the full details of the response out as an OpenXC message.

{   "buses": {
        "hs": {
            "controller": 1,
            "raw_writable": true,
            "speed": 500000
        }
    },
    "diagnostic_messages": [
        {
            "bus": "hs",
            "id": 2015,
            "mode": 34,
            "pid": 42,
            "frequency": 1
        }
    ]
}

We added a diagnostic_messages array and one diagnostic request object in that array. The id, mode, and frequency are the only required fields, and we added a pid to this as well.

It’s also important that the CAN controller is configured as writable with the raw_writable flag, otherwise the VI will not be able to send the diagnostic request.

With this configuration, the VI will publish the diagnostic response received from the bus using the OpenXC diagnostic response message format, e.g. when using the JSON output format:

{"bus": 1,
  "id": 2016,
  "mode": 34,
  "pid": 42,
  "success": true,
  "payload": "0x1234"}

Note that the id of the response is different from the request, because we sent the request to the functional broadcast address 0x7df. If you use a physical address with your request, the ID of the response will match. The bus is also different from that specified in the mapping - it’s the controller ID, not the name of the bus.

Recurring Parsed OBD-II PID Request¶

We want to send a request for the OBD-II PID for engine RPM once per second, and publish the full details of the response out as an OpenXC message. We want to use a decoder to parse the response’s payload to get the actual engine RPM value.

{   "buses": {
        "hs": {
            "controller": 1,
            "raw_writable": true,
            "speed": 500000
        }
    },
    "diagnostic_messages": [
        {
            "bus": "hs",
            "id": 2015,
            "mode": 1,
            "pid": 12,
            "frequency": 1,
            "decoder": "handleObd2Pid"
        }
    ]
}

Besides changing the mode and pid, we added a decoder. The handleObd2Pid decoder is included by default in the vi-firmware repository, and knows how to decode a number of the most interesting and widely implemented OBD-II PIDs.

With this configuration, the VI will publish the diagnostic response received from the bus using the OpenXC diagnostic response message format, e.g. when using the JSON output format:

{"bus": 1,
  "id": 2016,
  "mode": 34,
  "pid": 42,
  "success": true,
  "payload": "0x1234"}

Unlike the configuration example without a decoder, this response has a value instead of the raw payload. The value is whatever your decoder function returns.

Recurring Named Diagnostic PID Request¶

Just like before, we want to request the OBD-II PID for engine RPM once per second, but this time we don’t care about returning the full details in the response message. We just want a named message like an OpenXC simple vehicle message.

{   "buses": {
        "hs": {
            "controller": 1,
            "raw_writable": true,
            "speed": 500000
        }
    },
    "diagnostic_messages": [
        {
            "bus": "hs",
            "id": 2015,
            "mode": 1,
            "pid": 12,
            "frequency": 1,
            "decoder": "handleObd2Pid",
            "name": "engine_speed"
        }
    ]
}

We simply added a name field to the diagnostic message configuration. This will change the output format to the OpenXC simple vehicle message format, e.g. when using the JSON output format:

{"name": "engine_speed", "value": 45}

where value is the return value from the decoder.

On-Demand Request from Command Handler¶

You can generate a new recurring or one-off diagnostic request from any custom command handler signal decoder, or CAN message handler. Take a look at the diagnostics.h module for functions that may be useful.

For this example, we want to generate a mode 3 diagnostic request to get trouble codes when a “collect_trouble_codes” command is sent. We will register a callback function to handle the payload of the response to parse out the trouble code we are looking for. Here’s our VI config:

{   "buses": {
        "hs": {
            "controller": 1,
            "raw_writable": true,
            "speed": 500000
        }
    },
    "commands": [
        {"name": "collect_trouble_codes",
         "handler": "collectTroubleCodes"}
    ],
    "extra_sources": [
      "my_handlers.cpp"
    ]
}

Just as in the Composite Write Request, we added a commands field with one custom command, mapping collect_trouble_codes to the command handler function collectTroubleCodes (to be defined in my_handlers.cpp).

In my_handlers.cpp:

void handleTroubleCodeResponse(
         DiagnosticsManager* manager,
         const ActiveDiagnosticRequest* request,
         const DiagnosticResponse* response,
         float parsed_payload) {
    // Received a response to our mode 3 request

    // response->payload is an array (with length response->payload_length)
    // that contains the trouble code data - do whatever you need to do to parse
    // out your trouble codes.

    // If you need to send anything out on the I/O interfaces (e.g. to let
    // a client know about a particular trouble code), you can use the
    // openxc::pipeline::publish(...) function.
}

void handleMyCommand(const char* name, openxc_DynamicField* value,
      openxc_DynamicField* event, CanSignal* signals, int signalCount) {

   // Build and broadcast a non-recurring mode 3 diagnostic request
   DiagnosticRequest request = {
       arbitration_id: 0x7df,
       mode: 3
   };

   addRequest(&getConfiguration()->diagnosticsManager,
      // use the CAN bus on controller 0 (this is a little bit dangerous,
      // you'll want to do some error checking to amke sure this bus exists.
      getCanBuses()[0],
      &request,
      NULL, // no human readable name
      false, // don't wait for multiple responses
      NULL, // no response decoder
      handleTroubleCodeResponse); // when a response is received, call our handler
}

This combination of a command handler and diagnostic response callback requests trouble codes from the vehicle whenever the command is received, and can take any action on the response (in the callback.

Message Set¶

Each JSON mapping file defines a “message set,” and it should have a name. Typically this identifies a particular model year vehicle, or possibly a broader vehicle platform. The name field is required.

bit_numbering_inverted (optional)

This flag controls the default bit numbering for all messages included in this message set. You can override the bit numbering for any particular message or mapping, too.

false by default, true by default for database-backed mappings.

max_message_frequency

Set a default value for all buses for this attribute - see the Can Buses section for a description.

raw_can_mode

Set a default value for all buses for this attribute - see the Can Buses section for a description.

Parent Message Sets¶

Message sets are composable - you can extend a set by adding a path to the parent(s) to the parents key.

Initializers¶

The key initializers should have as its value an array of strings. Each string should be the name of a function with the type signature:

void function();

These functions will be called once at the beginning of execution, before reading any CAN messages.

Loopers¶

The key loopers should have as its value an array of strings. Each string should be the name of a function with the type signature:

void function();

These functions will be called once each time through the main loop function, after reading and processing any CAN messages.

CAN Buses¶

The key buses must be an object, where each field is a CAN bus uses by this message set, and which CAN controllers are attached on the microcontroller. The

controller

The integer ID of the CAN controller to which this bus is attached. The platforms we are using now only have 2 CAN controllers, identified here by 1 and 2 - these are the only acceptable bus addresses. If this field is not defined, the bus and any messages associated with it will be ignored (but it won’t cause an error, so you can swap between buses very quickly).

speed

The CAN bus speed in Kbps, most often 125000 or 500000.

raw_can_mode

Controls sending raw CAN messages (encoded as JSON objects) from the bus over the output channel. Valid modes are off (the default if you don’t specify this attribute), filtered (if messages are defined for the bus, will enable CAN filters and only transmit those messages), or unfiltered (disable acceptance filters and send all received CAN messages). If this attribute is set on a CAN bus object, it will override any default set at the message set level (e.g. you can have all buses configured to send filtered raw CAN messages, but override one to send unfiltered).

raw_writable

Controls whether or not raw CAN messages from the user can be written back to this bus, without any sort of translation. This is false by default. Even when this is false, messages may still be written to the bus if a signal is configured as writable, but they will translated from the user’s input first.

max_message_frequency

The default maximum frequency for all CAN messages when using the raw passthrough mode. To put no limit on the frequency, set this to 0 or leave it out. If this attribute is set on a CAN bus object, it will override any default set at the message set level. This value cascades to all CAN message objects for their max_frequency attribute, which can also be overridden at the message level.

force_send_changed (optional)

Meant to be used in conjunction with max_message_frequency, if this is true a raw CAN message will be sent regardless of the given frequency if the value has changed (when using raw CAN passthrough). Setting the value here, on the CAN bus object, will cascade down to all CAN messages unless overridden. Defaults to true.

CAN Messages¶

The messages key is a object with fields mapping from CAN message IDs to signal definitions. The fields must be hex IDs of CAN messages as strings (e.g. 0x90).

void handleSteeringWheelMessage(int messageId, uint64_t data,
        CanSignal* signals, int signalCount, Pipeline* pipeline);
    float steeringWheelAngle = decodeCanSignal(&signals[1], data);
    float steeringWheelSign = decodeCanSignal(&signals[2], data);

    float finalValue = steeringWheelAngle;
    if(steeringWheelSign == 0) {
        // left turn
        finalValue *= -1;
    }

    char* message = generateJson(signals[1], finalValue);
    sendMessage(usbDevice, (uint64_t*) message, strlen(message));
}

openxc_DynamicField decodeSteeringWheelAngle(CanSignal* signal,
        CanSignal* signals, int signalCount,
        openxc::pipeline::Pipeline* pipeline,
        float value, bool* send) {
    if(signal->lastValue == 0) {
        // left turn
        value *= -1;
    }
    return openxc::payload::wrapNumber(value);
}

openxc_DynamicField customDecoder(CanSignal* signal, CanSignal* signals,
    int signalCount, openxc::pipeline::Pipeline* pipeline,
        float value, bool* send);

Diagnostic Messages¶

The diagnostic_messages key is an array of objects describing a recurring diagnostic message request.

Mappings¶

The mappings field is an optional field allows you to move the definitions from the messages list to separate files for improved composability and readability.

For an detailed explanation of mapped message sets, see the example of a message set using mappings, see the Separate Files for Message Sets configuration example.

The mappings field must be a list of JSON objects with:

mapping -

A path to a JSON file containing a single object with the key messages, containing objects formatted as the CAN Messages section describes. In short, you can pull out the messages key from the main file and throw it into a separate file and link it in here. You can also do the same with a diagnostic_messages field containing Diagnostic Messages.

bus (optional)

The name of one of the defined CAN buses where these messages can be found - this value will be set for all of the messages contained the mapping file, but can be overridden by setting bus again in an individual message.

database (optional)

A path to a CAN message database associated with these mappings. Right now, XML exported from Vector CANdb++ is supported. If this is defined, you can leave the bit position, bit size, factor, offset, max and min values out of the mapping file - they will be picked up automatically from the database.

bit_numbering_inverted (optional)

This flag controls the default bit numbering for the messages contained in this mapping. Messages in the mapping can override the bit numbering by explicitly specifying their own value for this flag. Defaults to the value of the message set, or true if this mapping is database-backed.

enabled (optional)

Enable or disable all processing of the CAN messages in a mapping. By default, a mapping is enabled; if this flag is false, all CAN message and signals from the mapping will be excluded from the generated source code. Defaults to true.

Extra Sources¶

The extra_sources key is an optional list of C++ source files that should be injected into the generated signals.cpp file. These may include signal decoders, message handlers, initializers or custom loopers.

Commands¶

The commands field is a mapping of arbitrary command names to functions that should be called to run arbitrary code in the VI on-demand (e.g. sending multiple CAN signals at once). The value of this attribute is a list of objects with these attributes:

name

The name of the command to be recognized on the OpenXC translated interface.

enabled (optional)

Enable or disable all processing of a command. By default, a command is enabled. If this flag is false, the command will be excluded from the generated source code. Defaults to true.

handler

The name of a custom command handler function (that matches the CommandHandler function prototype from canutil.h) that should be called when the named command arrives over the translated VI interface (e.g. USB or Bluetooth).

void (*CommandHandler)(const char* name, openxc_DynamicField* value,
        openxc_DynamicField* event, CanSignal* signals, int signalCount);

Any message received from the USB host with that given command name will be passed to your handler. This is useful for situations where there isn’t a 1 to 1 mapping between OpenXC command and CAN signal, e.g. if the left and right turn signal are split into two signals instead of the 1 state-based signal used by OpenXC. You can use the sendCanSignal function in canwrite.h to do the actual data sending on the CAN bus.

Default Build¶

You must always specify your target platform with the PLATFORM environment variable. For this example, we’ll set PLATFORM=FORDBOARD.

By default, if you just run make with no other environment variables set, the firmware is built with these options. This is a good build to use if you want to send diagnostic requests through a VI:

$ make
<...snip lots of output...>
Compiled with options:
-      FORDBOARD = PLATFORM
-      1         = BOOTLOADER
-      0         = DEBUG
-      0         = DEFAULT_METRICS_STATUS
-      1         = DEFAULT_ALLOW_RAW_WRITE_USB
-      0         = DEFAULT_ALLOW_RAW_WRITE_UART
-      0         = DEFAULT_ALLOW_RAW_WRITE_NETWORK
-      USB       = DEFAULT_LOGGING_OUTPUT
-      JSON      = DEFAULT_OUTPUT_FORMAT
-      0         = DEFAULT_EMULATED_DATA_STATUS
-      SILENT_CAN= DEFAULT_POWER_MANAGEMENT
-      0x1       = DEFAULT_USB_PRODUCT_ID
-      0         = DEFAULT_CAN_ACK_STATUS
-      1         = DEFAULT_OBD2_BUS
-      0         = DEFAULT_RECURRING_OBD2_REQUESTS_STATUS

The Makefile will always print the configuration used so you can double check.

• This default configuration will run on a Ford reference VI <http://vi.openxcplatform.com/> (PLATFORM is FORDBOARD) running the pre-loaded bootloader (BOOTLOADER is 1).
• Debug mode is off (DEBUG is 0) so no log messages will be output via USB for maximum performance.
• If the VI configuration allows raw CAN writes, they will only be permitted if set via USB (DEFAULT_ALLOW_RAW_WRITE_USB is 1 but the *_UART and *_NETWORK versions are 0.
• The data sent from the VI will be serialized to JSON in the format defined by the OpenXC message format <https://github.com/openxc/openxc-message-format>.
• The VI will go into sleep mode only when no CAN bus activity is detected for a few seconds (the DEFAULT_POWER_MANAGEMENT mode is SILENT_CAN).
• The CAN controllers will be initialized as listen only unless the VI configuration explicitly states they are writable (DEFAULT_CAN_ACK_STATUS is 1). This means that the VI may not work in a bench testing setup where nothing else on the bus is ACKing.

fab reference build

fab c5 build

fab chipkit build

Automatic Recurring OBD-II Requests Build¶

Another common build is one that automatically queries the vehicle to check if it supports a pre-defined set (see the file obd2.cpp) of interesting OBD-II parameters, and if so, sets up recurring requests for them. Compile with these options:

$ export DEFAULT_RECURRING_OBD2_REQUESTS_STATUS=1
$ export DEFAULT_POWER_MANAGEMENT=OBD2_IGNITION_CHECK
$ make
<...snip lots of output...>

Compiled with options:
-      FORDBOARD = PLATFORM
-      1         = BOOTLOADER
-      0         = DEBUG
-      0         = DEFAULT_METRICS_STATUS
-      1         = DEFAULT_ALLOW_RAW_WRITE_USB
-      0         = DEFAULT_ALLOW_RAW_WRITE_UART
-      0         = DEFAULT_ALLOW_RAW_WRITE_NETWORK
-      USB       = DEFAULT_LOGGING_OUTPUT
-      JSON      = DEFAULT_OUTPUT_FORMAT
-      0         = DEFAULT_EMULATED_DATA_STATUS
-      OBD2_IGNIT= DEFAULT_POWER_MANAGEMENT
-      0x1       = DEFAULT_USB_PRODUCT_ID
-      0         = DEFAULT_CAN_ACK_STATUS
-      1         = DEFAULT_OBD2_BUS
-      1         = DEFAULT_RECURRING_OBD2_REQUESTS_STATUS

Notice we changed:

• DEFAULT_RECURRING_OBD2_REQUESTS_STATUS to 1. This enables the automatic OBD-II queries.
• DEFAULT_POWER_MANAGEMENT to OBD2_IGNITION_CHECK (the Makefile summary display truncates this value). This changes the power management mode to actively probe the vehicle for the engine and vehicle speed. Some vehicles will keep modules alive if anyone is making diagnostic requests (e.g. the VI), and we want to avoid that because it could drain the car’s battery. This mode actively infers if the ignition is on and stops sending diagnostic queries if we think the car is off. The combination of an engine and vehicle speed check should be compatible with hybrid vehicles.

fab reference translated_obd2 build

Emulated Data Build¶

If you want to test connectivity to a VI from your client device without going to a vehicle, but you don’t care about the actual vehicle data being generated, you can compile a build that generates random vehicle data and sends it via the normal I/O interfaces.

If you are building an app, you’ll want to use a trace file <http://openxcplatform.com/resources/traces.html> or the vehicle simulator <https://github.com/openxc/openxc-vehicle-simulator>.

The config a VI to emulate a vehicle:

$ export DEFAULT_EMULATED_DATA_STATUS=1
$ export DEFAULT_POWER_MANAGEMENT=ALWAYS_ON
$ make
<...snip lots of output...>

Compiled with options:
-      FORDBOARD = PLATFORM
-      1         = BOOTLOADER
-      0         = DEBUG
-      0         = DEFAULT_METRICS_STATUS
-      1         = DEFAULT_ALLOW_RAW_WRITE_USB
-      0         = DEFAULT_ALLOW_RAW_WRITE_UART
-      0         = DEFAULT_ALLOW_RAW_WRITE_NETWORK
-      USB       = DEFAULT_LOGGING_OUTPUT
-      JSON      = DEFAULT_OUTPUT_FORMAT
-      0         = DEFAULT_EMULATED_DATA_STATUS
-      OBD2_IGNIT= DEFAULT_POWER_MANAGEMENT
-      0x1       = DEFAULT_USB_PRODUCT_ID
-      0         = DEFAULT_CAN_ACK_STATUS
-      1         = DEFAULT_OBD2_BUS
-      1         = DEFAULT_RECURRING_OBD2_REQUESTS_STATUS

There are 2 changes from the default build:

• DEFAULT_EMULATED_DATA_STATUS is 1, which will cause fake data to be generated and published from the VI.
• DEFAULT_POWER_MANAGEMENT is ALWAYS_ON, so the VI will not go to sleep while plugged in. Make sure to clear this configuration option before making a build to run in a vehicle, or you could drain the battery!

fab reference emulator build

Fabric Shortcuts¶

The repository includes a fabfile.py script, which works with the Fabric commmand line utility to simplify some of these build configurations. The fab commands are composable, following this simple formula:

• Start your command with fab
• Specify the target platform with chipkit, c5, or reference.
• Optionally include emulator or translated_obd2 to enable one of the example builds described above.
• End with build to start the compilation.

For example, this builds the firmware for a chipKIT and includes emulated data:

fab chipkit emulator build

while this builds the default firmware, ready for OBD2 requests for the chipKIT:

fab chipkit build

The fab commands can be run from any folder in the vi-firmware repository.

Source Code¶

Clone the repository from GitHub:

$ git clone https://github.com/openxc/vi-firmware

Some of the library dependencies are included in this repository as git submodules, so before you go further run:

$ git submodule update --init

If this doesn’t print out anything or gives you an error, make sure you cloned this repository from GitHub with git and that you didn’t download a zip file. The zip file is missing all of the git metadata, so submodules will not work.

PIC32 Dependencies¶

If you are planning to build for the PIC32 platforms (e.g. the chipKIT Max32 or C5), you need these dependencies.

MPIDE¶

Building the source for the VI for the chipKIT microcontroller requires MPIDE (the development environment and compiler toolchain for chipKIT provided by Digilent). Installing MPIDE can be a bit quirky on some platforms, so if you’re having trouble take a look at the installation guide for MPIDE.

Although we just installed MPIDE, building via the GUI is not supported. We use GNU Make to compile and upload code to the device. You still need to download and install MPIDE, as it contains the PIC32 compiler.

You need to set an environment variable (e.g. in $HOME/.bashrc) to let the project know where you installed MPIDE (make sure to change these defaults if your system is different!):

# Path to the extracted MPIDE folder (this is correct for OS X)
export MPIDE_DIR=/Applications/Mpide.app/Contents/Resources/Java

Remember that if you use export, the environment variables are only set in the terminal that you run the commands. If you want them active in all terminals (and you probably do), you need to add these export ... lines to the file ~/.bashrc (in Linux) or ~/.bash_profile (in OS X) and start a new terminal.

Digilent / Microchip Libraries¶

It also requires some libraries from Microchip that we are unfortunately unable to include or link to as a submodule from the source because of licensing issues:

• Microchip USB device library (download DSD-0000318 from the bottom of the Network Shield page)
• Microchip CAN library (included in the same DSD-0000318 package as the USB device library)

You can read and accept Microchip’s license and download both libraries on the Digilent download page.

Once you’ve downloaded the .zip file, extract it into the libs directory in this project. It should look like this:

- /Users/me/projects/vi-firmware/
---- libs/
-------- chipKITUSBDevice/
         chipKitCAN/
        ... other libraries

FTDI Driver¶

If you’re using Mac OS X or Windows, make sure to install the FTDI driver that comes with the MPIDE download. The chipKIT uses a different FTDI chip than the Arduino, so even if you’ve used the Arduino before, you still need to install this driver.

LPC176x Dependencies¶

If you are planning to build for the LPC176x platforms (e.g. the Ford Reference VI), you need these dependencies.

GCC for ARM Toolchain¶

Download the binary version of the toolchain for your platform (Linux, OS X or Windows) from this Launchpad site.

OpenOCD¶

If you plan to flash an LPC17xx based board with JTAG and not use the USB bootloader included with the Ford Reference VI, you need OpenOCD.

$ pacman -S openocd

$ brew install libftdi libusb
$ brew install --enable-ft2232_libftdi openocd

$ sudo sed -i "" -e "/Olimex OpenOCD JTAG A/{N;N;N;N;N;N;N;N;N;N;N;N;N;N;N;N;d;}" /System/Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist
$ sudo kextunload /System/Library/Extensions/FTDIUSBSerialDriver.kext/
$ sudo kextload /System/Library/Extensions/FTDIUSBSerialDriver.kext/

Pre-requisites¶

Follow the steps in Development Environment Setup to install Git and clone the vi-firmware repository.

Cygwin Pre-Setup¶

Compiling natively in Windows (e.g. at a Windows Command Prompt) is not supported. Cygwin (32-bit) is unofficially supported, but is no longer recommended. You’ll be much happier using Vagrant, promise!

If you still wish to use Cygwin, download 32-bit version of Cygwin (even if you’re on 64-bit Windows) and run the installer - during the installation process, select these packages:

make, gcc-core, patchutils, unzip, python, check, curl, libsasl2, python-setuptools

After it’s installed, open a new Cygwin terminal and configure it to ignore Windows-style line endings in scripts by running this command:

$ set -o igncr && export SHELLOPTS

Bootstrap¶

Run the bootstrap.sh script:

$ cd vi-firmware
vi-firmware/ $ script/bootstrap.sh

If there were no errors, you are ready to compile. If there are errors, try to follow the recommendations in the error messages. You may need to manually install the dependencies if your environment is not in a predictable state. If you’re stuck, you might seriously consider using Vagrant!

Flashing a Pre-compiled Firmware¶

Pre-compiled binaries (built with the BOOTLOADER flag enabled, see all compiler flags) are compatible with the OpenLPC USB bootloader - follow the instructions for Flashing User Code to update the vehicle interface.

Compiling¶

$ fab reference build

$ export PLATFORM=FORDBOARD
$ export BOOTLOADER=0
$ make clean
$ make -j4
$ make flash

UART¶

The software configuration is identical to the Blueboard. The reference VI includes an RN-41 on the PCB attached to the RX, TX, CTS and RTS pins, in addition to the UART status pin.

When a Bluetooth host pairs with the RN-42 and opens an RFCOMM connection, pin 0.18 will be pulled high and the VI will being streaming vehicle data over UART.

Debug Logging¶

In most cases the logging provided via USB is sufficient, but if you are doing low-level development and need the simpler UART interface, you can enable it with the DEFAULT_LOGGING_OUTPUT="UART" build option.

Logging will be on UART0, which is exposed on the bottom of the board at J3, a 5-pin ISP connector.

LED Lights¶

The reference VI has 2 RGB LEDs. If the LEDs are a dim green and red, then the firmware was not flashed properly and the board is not running.

LED A

• CAN activity detected - Blue
• No CAN activity on either bus - Orange

LED B

• USB connected, Bluetooth not connected - Green
• Bluetooth connected, USB in either state - Blue
• Neither USB or Bluetooth connected - Off

Bootloader¶

The OpenLPC USB bootloader is tested and working, and enables the LPC17xx to appear as a USB drive. See the documentation in that repository for instructions on how to flash the bootloader (a JTAG programmer is required). The reference VI from Ford is pre-programmed with this bootloader.

UART¶

On the LPC17xx, UART1 is used for OpenXC output at the 230000 baud rate. Like on the chipKIT, hardware flow control (RTS/CTS) is enabled, so CTS must be pulled low by the receiving device before data will be sent.

• Pin 2.0 - UART1 TX, connect this to the RX line of the receiver.
• Pin 2.1 - UART1 RX, connect this to the TX line of the receiver.
• Pin 2.2 - UART1 CTS, connect this to the RTS line of the receiver.
• Pin 2.7 - UART1 RTS, connect this to the CTS line of the receiver.

UART data is sent only if pin 0.18 is pulled high. If you are using a Bluetooth module like the BlueSMiRF from SparkFun, you need to hard-wire 5v into pin 0.18 to actually enabling UART. Other hardware implementations (like the Ford Reference VI) may be able to hook the Bluetooth connection status to this pin instead, to make the status of UART more dynamic.

UART Debug Logging¶

In most cases the logging provided via USB is sufficient, but if you are doing low-level development and need the simpler UART interface, you can enable it with the DEFAULT_LOGGING_OUTPUT="UART" build option.

On the Blueboard LPC1768H, logging will be on UART0 at 115200 baud:

• Pin 0.2 - UART0 TX, connect this to the RX line of the receiver
• Pin 0.3 - UART0 RX, connect this to the TX line of the receiver

LED Lights¶

LEDs are not currently supported on the Blueboard.

USB¶

The micro-USB port on the Digilent Network Shield is used to send and receive OpenXC messages. The mini-USB cable on the Max32 itself is only used for re-programming.

UART¶

On the chipKIT, UART1A is used for OpenXC output at the 230000 baud rate. Hardware flow control (RTS/CTS) is enabled, so CTS must be pulled low by the receiving device before data will be sent. There are a few tricky things to watch out for with UART (i.e. Bluetooth) output on the chipKIT, so make sure to read this entire section.

UART1A is also used by the USB-Serial connection, so in order to flash the PIC32, the Tx/Rx lines must be disconnected. Ideally we could leave that UART interface for debugging, but there are conflicts with all other exposed UART interfaces when using flow control.

• Pin 0 - U1ARX, connect this to the TX line of the receiver.
• Pin 1 - U1ATX, connect this to the RX line of the receiver.
• Pin 18 - U1ARTS, connect this to the CTS line of the receiver.
• Pin 19 - U1ACTS, connect this to the RTS line of the receiver.

UART data is sent only if pin A1 is pulled low (to ground). If you are using a Bluetooth module like the BlueSMiRF from SparkFun, you need to hard-wire GND into this pin to actually enabling UART. To disable UART, pull A1 high (hard-wire to 5v) or leave it floating.

No data received over UART (i.e. Bluetooth)?

If you are powering the device via USB but not also reading data via USB, it may be blocked waiting to send data. Try unplugging the USB connection and powering the device via the OBD connector.

Debug Logging¶

In most cases the logging provided via USB is sufficient, but if you are doing low-level development and need the simpler UART interface, you can enable it with the DEFAULT_LOGGING_OUTPUT="UART" build option, but be aware that UART logging will dramatically decrease the performance of the VI.

On the chipKIT Max32, UART logging will be on UART2 (Pin 16 - Tx, Pin 17 - Rx) at 115200 baud.

LED Lights¶

The chipKIT has 1 user controllable LED. When CAN activity is detected, the LED will be enabled (it’s green).

Compiling and Flashing¶

Attach the chipKIT to your computer with a mini-USB cable, cd into the src subdirectory, build and upload to the device.

vi-firmware/src/ $ fab chipkit build
vi-firmware/src/ $ make flash

If the flash command can’t find your chipKIT, you may need to set the SERIAL_PORT variable if the serial emulator doesn’t show up as /dev/ttyUSB* in Linux, /dev/tty.usbserial* in Mac OS X or com3 in Windows. For example, if the chipKIT shows up as /dev/ttyUSB4:

$ SERIAL_PORT=/dev/ttyUSB4 make flash

and if in Windows it appeared as COM4:

$ SERIAL_PORT=com4 make flash

IDE Support¶

It is possible to use an IDE like Eclipse to edit and compile the project.

• Follow the directions in the above “Installation” section.
• Install Eclipse with the CDT project
• In Eclipse, go to File -> Import -> C/C++ -> Existing Code as Makefile Project and then select the vi-firmware/src folder.
• In the project’s properties, under C/C++ General -> Paths and Symbols, add these to the include paths for C and C++:
  • ${MPIDE_DIR}/hardware/pic32/compiler/pic32-tools/pic32mx/include
  • ${MPIDE_DIR}/hardware/pic32/cores/pic32
  • /src/libs/CDL/LPC17xxLib/inc (add as a “workspace path”)
  • /src/libs/chipKITCAN (add as a “workspace path”)
  • /src/libs/chipKITUSBDevice (add as a “workspace path”)
  • /src/libs/chipKITUSBDevice/utility (add as a “workspace path”)
  • /src/libs/chipKITEthernet (add as a “workspace path”)
  • /usr/include (only if you want to use the test suite, which requires the check C library)
• In the same section under Symbols, if you are building for the chipKIT define a symbol with the name __PIC32__
• In the project folder listing, select Resource Configurations -> Exclude from   Build for these folders:
  • src/libs
  • build

If you didn’t set up the environment variables from the Installation section (e.g. MPIDE_HOME), you can also do that from within Eclipse in C/C++ project settings.

There will still be some errors in the Eclipse problem detection, e.g. it doesn’t seem to pick up on the GCC __builtin_* functions, and some of the chipKIT libraries are finicky. This won’t have an effect on the actual build process, just the error reporting.

Bootloader¶

All stock chipKITs are programmed with a compatible bootloader at the factory. The PIC32 avrdude bootloader is also tested and working and allows flashing over USB with avrdude.

Flashing a Pre-compiled Firmware¶

Assuming your C5 has the bootloader already flashed, once you have the USB cable attached to your computer and to the C5, follow the same steps to upload as for the chipKIT Max32.

The C5 units offered directly from the CrossChasm website are pre-programmed with the bootloader.

Bootloader¶

The C5 can be flashed with the same PIC32 avrdude bootloader, as the chipKIT.

The OpenXC fork of the bootloader (the previous link) defines a CROSSCHASM_C5 configuration that exposes a CDC/ACM serial port function over USB. Once the bootloader is flashed, there is a 5 second window when the unit powers on when it will accept bootloader commands.

In Linux and OS X it will show up as something like /dev/ACM0, and you can treat this just as if it were a serial device.

In Windows, you will need to install the stk500v2.inf <https://raw.github.com/openxc/PIC32-avrdude-bootloader/master/Stk500v2.inf> driver before the CDC/ACM modem will show up - download that file, right click and choose Install. The C5 should now show up as a COM port for for 5 seconds on bootup.

The C5 units offered directly from the CrossChasm website are pre-programmed with the bootloader.

If you need to reflash the bootloader yourself, a ready-to-go .hex file is available in the GitHub repository and you can flash it with MPLAB IDE/IPE and an ICSP programmer like the Microchip PICkit 3. You can also build it from source in MPLAB by using the CrossChasm C5 configuration.

Compiling¶

The instructions for compiling from source are identical to the chipKIT Max32 except that PLATFORM=CROSSCHASM_C5 instead of CHIPKIT.

If you will not be using the avrdude bootloader and will be flashing directly via ICSP, make sure to also compile with BOOTLOADER=0 to enable the program to run on bare metal.

USB¶

The micro-USB port on the board is used to send and receive OpenXC messages.

UART¶

On the C5, UART1A is used for OpenXC output at the 230000 baud rate. Hardware flow control (RTS/CTS) is enabled, so CTS must be pulled low by the receiving device before data will be sent.

TODO add pinout of expansion header, probably a picture

UART data is sent only if pin 0.58 (or PORTB BIT 4, RB4) is pulled high (to 5vv). If you are using a Bluetooth module like the BlueSMiRF from SparkFun, you need to hard-wire 5v into this pin to actually enabling UART. To disable UART, pull this pin low or leave it floating.

Debug Logging¶

In most cases the logging provided via USB is sufficient, but if you are doing low-level development and need the simpler UART interface, you can enable it with the DEFAULT_LOGGING_OUTPUT="UART" build option.

On the C5, logging is on UART3A at 115200 baud (if the firmware was compiled with DEBUG=1).

LED Lights¶

The C5 has 2 user controllable LEDs. When CAN activity is detected, the green LED will be enabled. When USB or Bluetooth is connected, the blue LED will be enabled.

Writing to CAN¶

By default, the CAN controllers on the VI are configured to be in a read-only mode - they won’t even send ACK frames. If you configure one of the buses to be raw_writable in the firmware configuration, the controller will be write-enabled for raw CAN messages, e.g.:

{   "name": "passthrough",
    "buses": {
        "hs": {
            "controller": 1,
            "raw_can_mode": "unfiltered",
            "raw_writable": true,
            "speed": 500000
        }
    }
}

With a writable bus, you can send CAN messages (in the OpenXC “raw” message JSON format) to the VI’s input interfaces (e.g. USB, Bluetooth) and they’ll be written out to the bus verbatim.

Obviously this is an advanced feature with many security and safety implications. The CAN controllers are configured as read-only by default for good reason - make sure you understand the risks before enabling raw CAN writes.

For additional security, by default the firmware will not accept raw CAN write requests from remote interfaces even if raw_writable is true. Write requests from Bluetooth and network connections will be ignored - only USB is allowed by default. If you wish to write raw CAN messages wirelessly (and understand that those words make security engineers queasy), compile with the NETWORK_ALLOW_RAW_WRITE or BLUETOOTH_ALLOW_RAW_WRITE flags (see all compile-time flags).

The raw CAN write support is intended soley for protoyping and advanced development work - for any sort of consumer-level app, it’s much better to use writable simple vehicle messages.

Compiling with Binary Output¶

To use the binary output format, compile with the DEFAULT_OUTPUT_FORMAT=PROTOBUF environment variable set (see all compile-time flags).

Motivation¶

The default output format encodes data from the vehicle as JSON, using the OpenXC message format. There are JSON formats for both translated and raw messages. The format is human-readable and very simple to parse, but it’s not very compact.

For one, it representes everything in human-readable text, so for example, the number 999 (which could be stored in only 10 bits) takes 3 bytes - more than twice the space.

This isn’t an issue for most users, as the output interfaces have plenty of bandwidth (USB is around 125-160 KB/s and the popular RN-42 Bluetooth tops out at 23KB/s), and the actual amount of data sent from the pre-compiled binary firmware (from Ford, for example) is only about 3-6KB/s using JSON.

However, some applications need to pull a lot more data out of the car, perhaps by reading raw CAN messages or reading many signals at high frequencies. These can quickly overwhelm the output pipe using JSON.

Simulating a CAN Network¶

Speaking of CAN bus bench testing, it’s possible to create a 2-node CAN network on your desk with 2 VIs to test your firmware. This is especially handy for prototyping new translated signals, since you can record a raw CAN bus trace from a vehicle and do all of your work inside where it’s warm and comfortable.

Preparing the Transmitter¶

1. Decide which of the VIs is the transmitter and which is the receiver. The receiver is most like your VI under test.
2. Follow the normal firmware build process (the CAN signals defined don’t matter, just the bus speeds) but set the TRANSMITTER environment variable: TRANSMITTER=1 make. This changes the USB product ID from 1 to 2, so you can address the transmitter VI independently from the receiver. TODO create a transmitter config file with raw writable bus and no power management.

Preparing the Receiver¶

Compile the VI firmware for the receiver as usual, but instead of just make, run DEFAULT_CAN_ACK_STATUS=1 make This configures the CAN controllers as write-enabled, so that your VI under test can ACK the CAN messages. If nobody on the bus ACKs, you will receive nothing. In a car there are usually many other things ACKing, so we can be “listen only”.

Sending Data on the Bus¶

You need a pre-recorded raw CAN trace file from a vehicle. To create one, compile the firmware in the passthrough mode (see the low-level CAN docs) and flash a VI, then use openxc-dump to receive the raw messages - point that at a file on disk to create a trace.

With a raw CAN trace file named raw-can-trace.json:

$ openxc-control writeraw --usb-product 2 -f raw-can-trace.json

That will send all of the message in the file, correctly spaced according to the timestamps. If you want to send continuously, you can loop the file like this:

$ watch -n 0 openxc-control writeraw --usb-product 2 -f raw-can-trace.json

Receiving Data¶

Receive data as usual from the VI under test, as if it was in real car.