CAN filter configuration to use along libcanard V1

noxuz · December 11, 2020, 2:56pm

Hello, I’m trying to configure the CAN reception filters for receiving 7609.Heartbeat.V1 messages in a mask + id filtering scheme.

For the simplest case of uniquely allowing this subject throughout the hardware filters, my first thought is to use (0x1FFF << 8) for the mask and (0x1D55 << 8) for the corresponding ID.

This comes from the CAN bit layout of V1 spec.

Is this approach accurate or which is the mask intented to use when using messages? The intrigue started when reviewing the below section of libuavcan v0, and found that the default mask as 0xFFFF80, which covers more than the 13 subject-ID bits on both sides; but couldn’t find the v0 pdf to compare the bit layout with v1.

github.com

OpenCyphal-Garage/libuavcan/blob/legacy-v0/libuavcan/include/uavcan/transport/can_acceptance_filter_configurator.hpp#L66

      
        
             * DefaultFilterMsgMask = 00000 11111111 11111111 10000000
             * DefaultFilterMsgID   = 00000 iiiiiiii iiiiiiii 00000000, no need to explicitly define, since MsgID initialized
             * as 0.
             * DefaultFilterServiceMask = 00000 00000000 01111111 10000000
             * DefaultFilterServiceID   = 00000 00000000 0ddddddd 10000000, all Service Response Frames are accepted by
             * HW filters.
             * DefaultAnonMsgMask = 00000 00000000 00000000 11111111
             * DefaultAnonMsgID   = 00000 00000000 00000000 00000000, by default the config is added to accept all anonymous
             * frames. In case there are no anonymous messages, invoke computeConfiguration(IgnoreAnonymousMessages).
             */
            static const unsigned DefaultFilterMsgMask = 0xFFFF80;
            static const unsigned DefaultFilterServiceMask = 0x7F80;
            static const unsigned DefaultFilterServiceID = 0x80;
            static const unsigned DefaultAnonMsgMask = 0xFF;
            static const unsigned DefaultAnonMsgID = 0x0;
            
            
typedef uavcan::Multiset<CanFilterConfig> MultisetConfigContainer;
            
            
static CanFilterConfig mergeFilters(CanFilterConfig& a_, CanFilterConfig& b_);
            static uint8_t countBits(uint32_t n_);
            uint16_t getNumFilters() const;

Thanks beforehand.

pavel.kirienko · December 11, 2020, 5:23pm

Hey Abraham,

Yep, sounds right, should work.

The old bit layout is documented here: https://legacy.uavcan.org/Specification/4._CAN_bus_transport_layer/#can-frame-format. It is no longer valid so I don’t recommend looking at it.

Instead, you can refer to PyUAVCAN; in the internals under pyuavcan.transport.can you will find a function that computes the set of acceptance filter configurations for a given list of subject-identifiers:

github.com

UAVCAN/pyuavcan/blob/f43afb54e944e766a052957ac6f03310ecc97c82/pyuavcan/transport/can/_identifier.py#L163-L197


def generate_filter_configurations(subject_id_list: typing.Iterable[int],
                                   local_node_id:   typing.Optional[int]) \
        -> typing.Sequence[pyuavcan.transport.can.media.FilterConfiguration]:
    from .media import FrameFormat, FilterConfiguration

    def ext(idn: int, msk: int) -> FilterConfiguration:
        assert idn <= _CANID_EXT_MASK and msk <= _CANID_EXT_MASK
        return FilterConfiguration(identifier=idn, mask=msk, format=FrameFormat.EXTENDED)

    full: typing.List[FilterConfiguration] = []

    if local_node_id is not None:
        assert local_node_id <= CANID.NODE_ID_MASK
        # If the local node-ID is set, we may receive service requests, so we need to allocate one filter for those.
        full.append(ext(idn=_BIT_SRV_NOT_MSG | (int(local_node_id) << 7),
                        msk=_BIT_SRV_NOT_MSG | _BIT_R23 | (CANID.NODE_ID_MASK << 7)))
        # Also, we may need loopback frames for timestamping, so we add a filter for frames where the source node-ID
        # equals ours. Both messages and services!
        full.append(ext(idn=int(local_node_id),
                        msk=_BIT_R23 | CANID.NODE_ID_MASK))

This file has been truncated. show original

Further, you may need to handle the case where the set of subject-IDs you are supposed to receive is larger than the set of the available acceptance filters. In this case, the coalescing algorithm that is described in the Spec in “Automatic hardware acceptance filter configuration” and implemented in pyuavcan.transport.can.media may be of help:

github.com

UAVCAN/pyuavcan/blob/f43afb54e944e766a052957ac6f03310ecc97c82/pyuavcan/transport/can/media/_filter.py#L85-L115


def optimize_filter_configurations(configurations: typing.Iterable[FilterConfiguration],
                                   target_number_of_configurations: int) -> typing.Sequence[FilterConfiguration]:
    """
    Implements the CAN acceptance filter configuration optimization algorithm described in the Specification.
    The algorithm was originally proposed by P. Kirienko and I. Sheremet.

    Given a
    set of ``K``  filter configurations that accept CAN frames whose identifiers belong to the set ``C``,
    and ``N`` acceptance filters implemented in hardware, where ``1 <= N < K``, find a new
    set of ``K'`` filter configurations that accept CAN frames whose identifiers belong to the set ``C'``,
    such that ``K' <= N``, ``C'`` is a superset of ``C``, and ``|C'|`` is minimized.

    The algorithm is not defined for ``N >= K`` because this configuration is considered optimal.
    The function returns the input set unchanged in this case.
    If the target number of configurations is not positive, a ValueError is raised.

    The time complexity of this implementation is ``O(K!)``; it should be optimized.
    """
    if target_number_of_configurations < 1:
        raise ValueError(f'The number of configurations must be positive; found {target_number_of_configurations}')

This file has been truncated. show original

noxuz · December 11, 2020, 8:27pm

Perfect!

The default filter config I was looking for will end up with the ID field as (0x1FFF << 8), and in the case of the mask, same as line #195 from the PyUAVCAN function you shared, adding 3 bits to the mask aside from the (0x1D55 << 8).

github.com

OpenCyphal/pycyphal/blob/f43afb54e944e766a052957ac6f03310ecc97c82/pyuavcan/transport/can/_identifier.py#L194

      
        
                    # If the local node-ID is not set, we may need to receive loopback frames for sent anonymous transfers.
                    # This essentially means that we need to allow ALL anonymous transfers. Those may be only messages, as there
                    # is no such thing as anonymous service transfer.
                    full.append(ext(idn=_BIT_MSG_ANON,
                                    msk=_BIT_SRV_NOT_MSG | _BIT_MSG_ANON | _BIT_R23 | _BIT_MSG_R7))
            
            
    # One filter per unique subject-ID. Sorted for testability.
                for sid in sorted(set(subject_id_list)):
                    s_mask = pyuavcan.transport.MessageDataSpecifier.SUBJECT_ID_MASK
                    assert sid <= s_mask
                    full.append(ext(idn=int(sid) << 8,
                                    msk=_BIT_SRV_NOT_MSG | _BIT_R23 | (s_mask << 8) | _BIT_MSG_R7))
            
            
    return full
            
            

            
def _unittest_can_filter_configuration() -> None:
                from .media import FilterConfiguration, optimize_filter_configurations, FrameFormat
            
            
    def ext(idn: int, msk: int) -> FilterConfiguration:
                    assert idn <= _CANID_EXT_MASK and msk <= _CANID_EXT_MASK

I also found the migration guide below that clarifies why the bits 22 and 21 are being ignored in the mask. This completes the explanation of all the bits particular when dealing solely with messages, as in the simplest case mentioned earlier.

I think this step of configuring the filter is the only one that is skipped from the libcanard example provided in the repo’s readme; and adding this step to the section that demonstrates how to setup reception could be of support for the documentation.

Quick idea is a single line just below the previous section:

configureHWfilter(7509, 2**13 - 1); // ID-Mask pair for receiving Hearbeat messages

Thank you Pavel for the explanation.

pavel.kirienko · December 12, 2020, 1:03pm

I think it would be more valuable to add a short paragaph of text about acceptance filters. It is better than code because libcanard itself does not provide any facilities for acceptance filter configuration. A pull request with that change to the README would be accepted.