Filter

This page documents the filter configuration

Configuration file fields

This section is autogenerated from the Rule Schema file.

---

Receive filters can.filter

Filter remote request frames can.filter.remote_frames

Controls if remote request frames are forwarded to the message filters. If `Reject` is selected, remote request frames are discarded before they reach the message filters.

Type	Default	Options
integer	0	Reject: 0 Accept: 1

Id can.filter.id

Filters are checked sequentially, execution stops with the first matching filter element. Max 128 11-bit filters and 64 29-bit filters.

Max items
192

Name can.filter.id.name

Optional filter name.

Type	Max length
string	16

State can.filter.id.state

Disabled filters are ignored.

Type	Default	Options
integer	1	Disable: 0 Enable: 1

Type can.filter.id.type

Action on match, accept or reject message.

Type	Default	Options
integer	0	Acceptance: 0 Rejection: 1

ID format can.filter.id.id_format

Filter ID format. Filters apply to messages with matching ID format.

Type	Default	Options
integer	0	Standard (11-bit): 0 Extended (29-bit): 1

Filter method can.filter.id.method

The filter ID matching mechanism.

Type	Default	Options
integer	0	Range: 0 Mask: 1

From (range) / ID (mask) (HEX) can.filter.id.f1

If filter method is Range, this field defines the start of range. If filter method is Mask, this field defines the filter ID.

Type	Default	Max length
string	0	8

To (range) / mask (mask) (HEX) can.filter.id.f2

If filter method is Range, this field defines the end of range. If filter method is Mask, this field defines the filter mask.

Type	Default	Max length
string	7FF	8

---

Configuration explained

This section contains additional information and examples.

The following uses a mix of binary, decimal and hexadecimal number bases. For more information on the notation used, see to Number bases.

Note

In the following, it is convenient to do some calculations using binary numbers (base 2). However, the configuration file generally accepts either decimal or hexadecimal numbers.

Filter processing

The filter elements in the list of filters are processed sequentially starting from the first element. Processing stops on the first filter match.

Example: A message matches filter element 3. Filter element 4 is not evaluated.

Messages matching no filters are rejected as default.

Note

The default Configuration File contains filters accepting all incoming CAN messages

---

Filter state

The state of filter elements can be Enable or Disable. Disabled filter elements are ignored, as if they are not in the list of filters. If there are no enabled filters in the list then all messages are rejected.

By disabling a filter element (instead of deleting the element) it can be easily enabled at a later time.

---

Filter types

Filter elements can be either Acceptance or Rejection:

• If a message matches an Acceptance filter it is accepted

• If a message matches a Rejection filter it is discarded

• If a message does not match a filter, the next filter in the list is processed

The filter list can hold a combination of Acceptance and Rejection filter elements. The first matching filter element determines if a message is accepted or rejected. Acceptance and Rejection filters can be combined to generate a complex message filtering mechanism.

Example: A message matches acceptance filter 3. Rejection filter 4 is not evaluated. The message is accepted.

Example: A message matches rejection filter 2. The following filters are not evaluated. The message is rejected.

Example: A message does not match any filters. The message is rejected.

---

Filter method

Acceptance and Rejection filters can be defined by range or mask. In either case, both the message type (standard / extended) and ID are compared to the filter.

---

Filter range method

With the Range method, the filter defines a range of IDs which are compared to the message ID. Message IDs within the range (both start and end included) match the filter.

Example: Standard ID filter with range from = 1, to = 10:

ID format	ID (DEC)	Match
Standard	0	No
Standard	1	Yes
Standard	10	Yes
Standard	11	No
Extended	1	No

---

Filter mask method

With the Mask method, the filter defines an ID and Mask which are compared to the message ID.

A message matches a mask filter if the following condition is true1:

filter_id & filter_mask == message_id & filter_mask

The below examples demonstrate the use of filters using the Mask method.

Example: Filter configuration which accepts one specific message ID: \(2000_{10} = 11111010000_2\). The filter ID is set to the value of the message ID to accept. The filter mask is set to all ones, such that all bits of the filter are considered, as given in (1).

\[\begin{split}\begin{array}{cc} \begin{array}{cc} \begin{array}{l} \text{Filter ID}\\ \text{Filter mask}\\ \text{Masked filter} \end{array} & \begin{array}{r} 11111010000_2\\ \&\color{green}{11111111111_2} \\\hline 11111010000_2 \end{array} \end{array} (1) & \begin{array}{cc} \begin{array}{l} \text{Message ID}\\ \text{Filter mask}\\ \text{Masked ID} \end{array} & \begin{array}{r} 11111010000_2\\ \&\color{green}{11111111111_2} \\\hline 11111010000_2 \end{array} \end{array} (2) \end{array}\end{split}\]

To test if the message passes the filter, we apply the filter mask to the message ID as given in (2). The masked filter and the masked ID are equal - the message matches the filter.

Example: Filter configuration which accepts two message IDs:

• \(2000_{10} = 11111010000_2\)

• \(2001_{10} = 11111010001_2\)

Note that the two binary numbers are identical except for the rightmost bit. To design a filter which accepts both IDs, we can use the mask field to mask out the rightmost bit - such that it is not considered when the filter is applied. In (1) the mask is set such that the rightmost bit is not considered (indicated by red color).

\[\begin{split}\begin{array}{cc} \begin{array}{cc} \begin{array}{l} \text{Filter ID}\\ \text{Filter mask}\\ \text{Masked filter} \end{array} & \begin{array}{r} 11111010000_2\\ \&\color{green}{1111111111}\color{red}{0_2} \\\hline 11111010000_2 \end{array} \end{array} (1) & \begin{array}{cc} \begin{array}{l} \text{Message ID}\\ \text{Filter mask}\\ \text{Masked ID} \end{array} & \begin{array}{r} 11111010001_2\\ \&\color{green}{1111111111}\color{red}{0_2} \\\hline 11111010000_2 \end{array} \end{array} (2) \end{array}\end{split}\]

To test if the messages pass the filter, we apply the mask to the message ID \(11111010001_2\) as given in (2). The masked filter and the masked ID are equal - the message matches the filter. Note that both \(11111010000_2\) and \(11111010001_2\) match the filter, as the rightmost bit is not considered by the filter (the rightmost bit is masked out).

Example: J1939 - filter configuration which accepts PGN 61444 (EEC1) messages.

J1939 message frames use 29-bit CAN-IDs. The Parameter Group Number (PGN) is defined by 18 of the 29 bits. The remaining 11 bits define the priority and source address of the message. It is often useful to configure a filter to accept a specific PGN regardless of the source address and the priority - this can be done using the filter mask (to ignore the source and priority).

Below, the left red bits represent the 3-bit priority, the green bits the 18-bit PGN and the right red bits the 8-bit source address of the 29-bit CAN-ID.

\[\color{red}{000}\color{green}{111111111111111111}\color{red}{00000000}_{2} = \text{3FFFF00}_{16}\]

Message ID bits in positions with zero bits in the filter mask are ignored. By using \(\text{3FFFF00}_{16}\) as filter mask, the source and priority are ignored.

To specifically accept PGN 61444 (\(\text{F004}_{16}\)) messages, the message ID is set to \(\text{F00400}_{16}\) - note the the final 8-bit \(\text{00}_{16}\) represents the source address which is ignored by the filter mask (these bits can be any value).

Filter mask \(\text{3FFFF00}_{16}\) can be used for all J1939 PGN messages. To accept specific PGNs, the message ID is adjusted. To accept one specific PGN (as in the example above), the message ID is set to the specific PGN with \(\text{00}_{16}\) appended to represent the ignored source address field.

---

Filter list examples

Below examples demonstrate how filters can be combined into a list of filters.

Example: The filter list is set up to accept standard messages with even IDs in range \(500_{10}-1000_{10}\) (500, 502, … 998, 1000):

The following two filters are used to construct the wanted filter mechanism:

• Rejection filter which rejects all odd message IDs

• Acceptance filter which accepts all message IDs in range \(500_{10}-1000_{10}\)

The rejection filter is setup to reject all odd messages by using Mask filtering. The filter is set up with:

• Filter ID: \(1_{10} = 00000000001_{2}\)

• Filter Mask: \(1_{10} = 00000000001_{2}\)

Above rejection filter rejects all messages with the rightmost bit set (all odd IDs).

The acceptance filter is set up to accept all messages in range \(500_{10}-1000_{10}\) by using Range filtering. The filter is set up with:

• Filter from: \(500_{10}\)

• Filter to: \(1000_{10}\)

The filter list is constructed with the rejection filter first, followed by the acceptance filter.

Note that messages are first processed by the rejection filter (rejects all odd messages), then proccessed by the acceptance filter (accepts all message in range). If none of the filters match, the default behavior is to reject the message. It is in this case important that the rejection filter is placed before the acceptance filter in the list (processing stops on first match).

Filter list test table:

Message ID	Filter elm 1	Filter elm 2	Result
\(498_{10}\)	Ignore	Ignore	Reject
\(499_{10}\)	Reject		Reject
\(500_{10}\)	Ignore	Accept	Accept
\(501_{10}\)	Reject		Reject
\(999_{10}\)	Reject		Reject
\(1000_{10}\)	Ignore	Accept	Accept
\(1001_{10}\)	Reject		Reject
\(1002_{10}\)	Ignore	Ignore	Reject

---

Message Prescaling

Message prescaling can be used to decrease the number of logged messages for a given message ID. Prescaling is applied to the messages accepted by the associated filter. The list of filters can be assigned a mixture of prescaler types.

Applying filters can dramatically reduce log file size, resulting in prolonged offline logging and reduced data transfer time and size.

The prescaling type can be set to:

• None: Disables prescaling

• Count: Prescales based on message occurrences

• Time: Prescales based on message period time

• Data: Prescales based on changes in the message data payload

The first message with a given ID is always accepted regardless of prescaling type.

Note

A maximum of 100 unique message IDs can be prescaled for each CAN-bus channel (the first 100 IDs received by the device). Additional unique IDs are not prescaled

Count

Count prescaling reduces the number of messages with a specific ID by a constant factor (prescaling value). A prescaling value of 2 accepts every 2nd message (with a specific ID), a value of 3 every 3rd and so on up to 2562.

Count prescaling applied to ID \(600_{10}\) with a scaling value of 3

ID (DEC)	ID occurrences	Result
\(600_{10}\)	1	Accept
\(600_{10}\)	2	Reject
\(600_{10}\)	3	Reject
\(600_{10}\)	4	Accept
\(600_{10}\)	5	Reject

Time

Time prescaling sets a lower limit on time interval (period time) of a specific message ID. This is done by rejecting messages until at least the prescaler time has elapsed3. The prescaler timer is reset each time a message is accepted. The prescaling value is set in milliseconds4 with a valid range 1-4194304 (0x400000).

This prescaler type is e.g. useful if a slowly changing signal (low frequency signal content) is broadcasted on the CAN-bus at a high frequency5.

Example: A slowly changing temperature measurement broadcasted every 10 ms (100Hz). Prescaled to a minimum time interval of 100ms (prescaler value set to 100).

Example: Time prescaling applied to ID \(700_{10}\) with a time interval of 1000ms selected.

ID (DEC)	Message timestamp [ms]	Prescaler timer [ms]	Result
\(700_{10}\)	200	0	Accept
\(700_{10}\)	700	500	Reject
\(700_{10}\)	1000	800	Reject
\(700_{10}\)	1200	1000 -> 0 (reset)	Accept
\(700_{10}\)	1300	100	Reject
\(700_{10}\)	3200	2000 -> 0 (reset)	Accept
\(700_{10}\)	4200	1000 -> 0 (reset)	Accept
\(700_{10}\)	5200	1000 -> 0 (reset)	Accept

Data

Data prescaling can be used to only accept messages when the data payload changes. A mask can be set to only consider changes in one or more specific data bytes. The mask works on a byte level. The mask is entered in hex up to 8 bytes long (16 hex characters). Each byte contains 8 bits, allowing for the mask to be applied to any of the maximum 64 data bytes (CAN FD).

This prescaler type is useful if only changes in data or parts of the data are to be logged.

Examples of data masks:

• "": A empty mask triggers on any data change (equivalent to mask value FFFFFFFFFFFFFFFF)

• 1: Triggers on changes to the first data byte (binary 1)

• 2: Triggers on changes to the second data byte (binary 10)

• 3: Triggers on changes to the first or second data byte (binary 11)

• 9: Triggers on changes to the first or fourth data byte (binary 1001)

• FF: Triggers on changes to any of the first 8 data bytes (binary 11111111)

• 100: Triggers on changes to the 9th data byte (binary 100000000)

If the data payload contains more data bytes than entered in the mask, then changes to the additional bytes are ignored by the prescaler.

Warning

Data prescaling assumes that a message with a specific ID always carries the same number of data bytes

Example: A discretely changing signal is broadcasted every 100 ms (10Hz). A data prescaler is used such that only changes in the signal are logged.

Example: Data prescaling applied to ID \(800_{10}\) with empty mask (all changes considered). D0-D3 is a 4-byte payload (with D0 the first data byte).

ID (DEC)	D0	D1	D2	D3	Result
\(800_{10}\)	00	11	22	33	Accept
\(800_{10}\)	00	11	22	33	Reject
\(800_{10}\)	00	BB	22	33	Accept
\(800_{10}\)	AA	BB	22	33	Accept
\(800_{10}\)	AA	BB	22	DD	Accept
\(800_{10}\)	AA	BB	22	DD	Reject

Example: Data prescaling applied to ID \(800_{10}\) with mask 1 (considering only changes to the 1st data byte). D0-D3 is a 4-byte payload (with D0 the first data byte).

ID (DEC)	D0	D1	D2	D3	Result
\(800_{10}\)	00	11	22	33	Accept
\(800_{10}\)	00	11	22	33	Reject
\(800_{10}\)	00	BB	22	33	Reject
\(800_{10}\)	AA	BB	22	33	Accept
\(800_{10}\)	AA	BB	22	DD	Reject
\(800_{10}\)	AA	BB	22	DD	Reject

Example: Data prescaling applied to ID \(800_{10}\) with mask 8 (considering only changes to the 4th data byte). D0-D3 is a 4-byte payload (with D0 the first data byte).

ID (DEC)	D0	D1	D2	D3	Result
\(800_{10}\)	00	11	22	33	Accept
\(800_{10}\)	00	11	22	33	Reject
\(800_{10}\)	00	BB	22	33	Reject
\(800_{10}\)	AA	BB	22	33	Reject
\(800_{10}\)	AA	BB	22	DD	Accept
\(800_{10}\)	AA	BB	22	DD	Reject

Example: Data prescaling applied to ID \(800_{10}\) with mask 9 (considering only changes to the 1st or 4th data byte). D0-D3 is a 4-byte payload (with D0 the first data byte).

ID (DEC)	D0	D1	D2	D3	Result
\(800_{10}\)	00	11	22	33	Accept
\(800_{10}\)	00	11	22	33	Reject
\(800_{10}\)	00	BB	22	33	Reject
\(800_{10}\)	AA	BB	22	33	Accept
\(800_{10}\)	AA	BB	22	DD	Accept
\(800_{10}\)	AA	BB	22	DD	Reject

---

1

& is used as the bitwise AND operation

2

A scaling factor of 1 effectively disables prescaling

3

Note that messages are not resampled to a specific fixed period time

4

It is not possible to do sub-millisecond time prescaling

5

Higher frequency than needed to get a good representation of the signal content