.. _candb_support:

CANdb Support
==============================

Using CAN database (CANdb or .dbc) files with OpenECU
-------------------------------------------------------------------

.. contents:: Table of Contents

Overview
--------------------------------------

CAN database files provide a great way to organize and manage your CAN
network. In general, OpenECU is compatible with CANdb files. However, there
are a few restrictions as described below.

To use a CANdb file in your model, go to the Simulink library browser and
select Pi OpenECU -> Communication Drivers -> CAN Drivers to get to the CAN
block library. From there, you can drag and drop one of our CANdb blocks into
your model.

- Use **pcx_CANdb_ReceiveMessage** to receive a message using your CANdb file.
- Use **pcx_CANdb_TransmitMessage** to transmit a message using your CANdb file.

OpenECU follows the Simulink standard format for all *sink* blocks. This means
that the sample time will be inherited from the signals that are driving the
block. This also means that the ``GenMsgCycleTime`` parameter from the CANdb
file is ignored.

To set the transmission rate to a rate that is different from the base rate of
your model, a *Rate Transition* block must be added to all signals going into
the **pcx_CANdb_TransmitMessage** block.

- The *Rate Transition* block can be found in the *Signal Attributes* Simulink
  library.
- To set the signal rate, double click the *Rate Transition* block and set the
  ``Output port sample time:`` box to the desired rate (in seconds).

Unsupported Features
------------------------------------

OpenECU currently does **not** support the following features of CANdb files:

- Multiplexed messages
- Anything in the *Attributes* part of the CANdb file.
- ``GenSigStartValue`` to set initial value until first message is received.

  - OpenECU uses 0 as the initial value of each signal.
  - Alternate behavior can be handled by your application software.
- ``GenMsgCycleTime`` to set transmission rate.

Common Questions and Problems
-----------------------------------

We have gathered up a list of the most common support questions and problems
and answered them below.

Another ECU on My Network Stopped Transmitting a Message
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is up to you to decide what is best for your application.

- ``rx_trig_flag`` will become 1 during the model iteration that a message was received.
  - ``rx_trig_flag`` will become 0 on the following iteration.

What Happens if More Than One Message of the Same ID Are Received in a Single Model Iteration?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this case, the following will occur:

- The output ports for each signal will contain the most recently received
  message.
- Signal data from earlier messages will be lost.
- The ``overrun_flag`` output port will become 1 for one model iteration when
  this occurs.

Error Messages Are Popping Up, and I Don't Know What They Mean
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This usually happens when OpenECU cannot find your CANdb file.

- Your CANdb file **must** be on your Matlab path.

The Signal Looks Good on the CAN Bus, but I'm Seeing Strange Numbers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Check your signal data type.
- Next, check the signal data type against what is defined in the data dictionary.
- If the types do not match, change one or the other to match.

The Signal Looks Good on the CAN Bus, but OpenECU Is Always Showing 0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The usual cause for these two issues is due to the "Clip Signals To
Engineering Limits" feature.

To determine if this is an issue:

1. Double-click the pcx_CANdb_ReceiveMessage block that is having the problem.
2. Check if "Clip Signals To Engineering Limits?" is ticked.

I Recently Changed the Signal Order (or Added/Removed Signals) in My CANdb File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this situation, the block works properly, but it may not work how you are
used to Simulink working.

- If you have a Subsystem block and you re-order the ports, Simulink
  automatically re-routes the wires outside of the Subsystem block to keep
  the port connections correct.
- Simulink will not automatically re-route the wires to OpenECU blocks.

If you ever add, remove, or re-order signals in a message, you **must**
re-check the signal wiring into your block.