Communications library overview

Table of Contents

• Introduction
• Key Features
• Architecture
• Main Components
  • Network Manager
    • Interface Properties
    • Interface Types and Status
    • Best Practices
  • Serial Ports
    • Interface Properties
    • Best Practices
  • CAN
    • CAN Adapter Interface Properties
    • CAN Socket Interface Properties
    • Best Practice

Introduction

The D7 SDK Communications (comms) Library provides interfaces for the following functionality:

• Network interfaces. Discovering and getting information about network interfaces on the Veethree D7 platform. It allows applications to enumerate available interfaces and retrieve their properties such as IP address, hardware address, status, and type.
• Serial ports. Supports RS232 and RS422 (full-duplex) or RS485 (half-duplex).
• CAN interfaces. It allows bringing CAN interfaces up and down, configuring them (bitrate, sample point, clock, controller mode, etc.) and getting their current configuration. It also allows listing all the available CAN interfaces.

Key Features

Networking:

• Network interface discovery
• Interface information retrieval (IP address, MAC address)
• Interface status monitoring
• Interface type identification

Serial Ports:

• Opening and closing ports
• Flushing or draining ports
• Interfaces for reading and writing single bytes
• Interfaces for reading and writing multiple bytes (buffers)
• Set a receiver callback function when opening a port

CAN Interfaces:

• Starting and stopping interfaces
• Setting and getting configurations for each available interface
• Sending and receiving raw CAN frames using familiar socket programming idioms
• Access to raw sockets if more control is needed
• Waiting to read from one of many sockets simultaneously (select)
• Setting per-socket callbacks on CAN frame reception at any point in the program

Architecture

The comms library addresses many areas, which can be split as:

• Networking is built around the network_manager class which provides static methods for working with network interfaces. The library uses standard Linux networking APIs to gather interface information.
• Serial ports for working with RS232, RS422 and RS485 protocols.
• The CAN module is built around the can_adapter and can_socket classes. In order to send and receive frames, a can_socket must be bound to a can_adapter. A socket can only be bound to one adapter; multiple sockets can be bound to a single adapter. The module effectively wraps SocketCAN.

Main Components

Network Manager

The Network Manager provides static methods for discovering and retrieving information about network interfaces.

Key methods:

• vsdk::comms::network_manager::get_interfaces() - Get all available network interfaces
• vsdk::comms::network_manager::get_interface(std::string_view iface) - Get a specific network interface by name

#include <comms/network_manager.h>
#include <utils/fmt_wrapper.h>
 
void example() {
    using namespace vsdk::comms;
    // Get all available network interfaces
    auto interfaces = network_manager::get_interfaces();
    // Display information about each interface
    for (const auto& iface : interfaces) {
        utils::print("Interface: {}\n", iface.name);
        utils::print(" IP Address: {}\n", iface.ip);
    }
}

Interface Properties

The Networking Library uses the interface struct to represent network interfaces:

• name - The name of the interface (e.g., "eth0", "can0", "lo")
• ip - The IP address assigned to the interface (if available)
• hwaddr - The hardware/MAC address of the interface
• status - The current status of the interface (up or down)
• type - The type of the interface (normal/Ethernet, CAN, or loopback)

Interface Types and Status

The Networking Library uses enum classes to represent interface types and status:

• vsdk::comms::interface_status - Enum representing the status of an interface
  • up - Interface is up and running
  • down - Interface is down
• vsdk::comms::interface_type - Enum representing the type of an interface
  • normal - Standard Ethernet interface (e.g., eth0)
  • can - CAN interface (e.g., can0)
  • loopback - Loopback interface (e.g., lo)

Best Practices

• Check interface status before attempting to use its IP address
• Handle exceptions when working with network interfaces
• Use the appropriate interface type check when working with specific interfaces
• For CAN interfaces, additional configuration may be required via system tools

See the Networking Examples page for complete code examples.

Serial Ports

The Serial Port Class for the D7 platform offers an abstraction layer, enabling communication with RS232, RS422, and RS485 serial interfaces.

#include <cstdint>
#include <comms/serial_port_common.h>
#include <comms/serial_port.h>
 
void example()
{
    // this example writes to a loopback port using RS232
    using namespace vsdk::comms;
    port_attributes rs232_attr;
    rs232_attr.port = port_alias::port1;
    rs232_attr.uart_mode = port_mode::rs232;
    rs232_attr.baud_rate = port_baud_rate::uart115200;
    rs232_attr.data_bits = port_data_bits::bits8;
    rs232_attr.stop_bits = port_stop_bits::bits1;
    rs232_attr.parity = port_parity::none;
    serial_port port(rs232_attr);
    port.drain();
    port.flush(port_flus_mode::both);
    // write 50 bytes
    constexpr uint8_t bytes{ 50 };
    for (uint8_t byte{}; byte < bytes; ++byte) {
        port.write(byte);
    }
    // read 50 bytes
    for (uint8_t byte{}; byte < bytes; ++byte) {
        uint8_t value{};
        ssize_t result{};
        while (result <= 0) {
            result = port.read(value);
        }
    }
}

Interface Properties

• vsdk::comms::port_baud_rate: defines standard baud rates for serial communication.
• vsdk::comms::port_parity: specifies parity settings for serial communication.
• vsdk::comms::port_stop_bits: indicates the number of stop bits in serial communication.
• vsdk::comms::port_data_bits: represents the number of data bits in serial communication.
• vsdk::comms::port_flush_mode: defines modes for flushing serial port buffers.
• vsdk::comms::port_alias: enumerates supported serial port aliases.
• vsdk::comms::port_mode: a bitmask representing operational modes of a serial port.
• vsdk::comms::port_attributes: holds configuration settings for a serial port, including alias, baud rate, parity, stop bits, data bits, mode, and device name.

Best Practices

See the Serial Examples page for the code examples.

CAN

The can_adapter class offers a simple interface for setting up a CAN adapter. It uses the Linux kernel's built-in CAN driver to ensure the correctness of the requested configuration. In effect, it offers the same checks as running ip link set <interface name> <configurations>, but with a simpler programmatic interface.

The can_socket class is an RAII-style wrapper for a CAN socket. It uses a shared_ptr internally to maintain the state, so the underlying socket stays open until the last reference to it goes out of scope. This means that copying and moving an instance of can_socket increases the reference count of the underlying socket, and one instance going out of scope decreases the reference count.

CAN Adapter Interface Properties

• vsdk::comms::can_parameters: its members represent all the available CAN adapter settings. When setting a configuration, any members left as std::nullopt will be ignored.
• vsdk::comms::ctrl_mode: the CAN controller modes. When setting the controlle mode, std::nullopt members are ignore, members set to false are turned off, members set to true are turned on.
• vsdk::comms::transmitter_delay_compensation: the transmitter delay compensation setting. The read-only fields are only set by can_adapter::get_config; they are ignored in can_adapter::set_config.
• vsdk::comms::can_bus_err_counter: the bus error counters
• vsdk::comms::can_bit_timing: holds the settings for the adapter's bit timings
• vsdk::comms::can_status: the different states in which the CAN Bus may be
• vsdk::comms::can_msg_frame: a raw CAN frame structure

CAN Socket Interface Properties

• vsdk::comms::can_socket_recv_callback: a function that can be set to run when a can_socket successfully receives a CAN frame. If set using can_socket::set_receive_callback, then can_socket::receive will return the callback's return value.
• vsdk::comms::select_result_can: the return type of can_socket::select_receive_timeout. The error code is guaranteed to be set. The other fields may be std::nullopt in case of error. If any of the sockets received a CAN frame before the timeout expired, the structure will contain the adapter that the frame was read on and the frame that was read.

Best Practice

Always check the return codes of can_socket methods. The only method for which is safe to ignore the return value is can_socket::close.