varch/doc/cant.en.md

Introduction

cant is a simple CAN (Controller Area Network) device testing module for the C language. It conducts tests on the CAN bus from the application layer perspective, enabling the monitoring of data error frames and frame losses. Additionally, it can simulate the CAN bus load to ensure stability under high - voltage bus conditions.

Interfaces

Type Definitions

cant_transfer_t Function Pointer Type

typedef int (*cant_transfer_t)(uint32_t canid, uint8_t *data, uint16_t length);

Type Description: This is a function pointer type related to CAN transmission, which can be used for CAN data sending or receiving functions. Parameter Introduction:

• canid: The identifier of the CAN message.
• data: A pointer to the data to be sent or received.
• length: The length of the data. Return Value: The function returns an int value, and its specific meaning is determined by the actual function used.

Structure Definitions

CANT Structure

typedef struct 
{
    struct 
    {
        uint8_t channel;
        uint8_t baundrate;
        uint16_t period;                        // `cant_task()` call period
        cant_transfer_t transmit;               // can transmit the drive function
        cant_transfer_t receive;                // can receive hook functions
    } config;
    
    uint16_t busload;
    uint32_t periodbits;
    uint32_t timestamp;

    struct 
    {
        uint32_t canid;
        float compression;
        float rate;
        uint16_t tarload;
        uint32_t gapbase;
        uint32_t gapcount;
        uint32_t curcount;
        uint8_t data[64];
    } dummy;

    struct 
    {
        uint32_t canid;
        uint32_t errcount;
        uint32_t curcount;
        uint32_t vercount;
        uint32_t lstcount;
    } verify;
} CANT;

Structure Description: This structure is used to represent a CAN device, including the configuration information, bus load, timestamp, dummy data, and verification data of the CAN device. Sub - structure and Member Introduction:

• config Sub - structure: Contains the configuration information of the CAN device.
  • channel: The channel number of the CAN bus.
  • baundrate: The baud rate of the CAN bus.
  • period: The call period of the cant_task() function.
  • transmit: A pointer to the CAN data sending function.
  • receive: A pointer to the CAN data receiving function.
• busload: The load value of the CAN bus.
• periodbits: Bit information related to the period.
• timestamp: The timestamp.
• dummy Sub - structure: Contains the dummy data of the CAN device.
  • canid: The identifier of the CAN message.
  • compression: The compression factor, of type float.
  • rate: The rate, of type float.
  • tarload: The target load.
  • gapbase: The gap base value.
  • gapcount: The gap count.
  • curcount: The current count.
  • data: The data array, with a size of 64 bytes.
• verify Sub - structure: Contains the verification data of the CAN device.
  • canid: The identifier of the CAN message.
  • errcount: The error count.
  • curcount: The current count.
  • vercount: The verification count.
  • lstcount: The last count.

Functions

cant_set_dummy_canid Function

int cant_set_dummy_canid(CANT *cant, uint32_t canid);

Function Description: Sets the CAN identifier of the dummy data of the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to be operated on.
• canid: The CAN identifier to be set. Return Value:
• CANT_E_OK: The setting is successful.
• CANT_E_INVALID: The passed cant pointer is NULL.
• CANT_E_ECANID: The passed canid is 0.

cant_set_verify_canid Function

int cant_set_verify_canid(CANT *cant, uint32_t canid);

Function Description: Sets the CAN identifier of the verification data of the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to be operated on.
• canid: The CAN identifier to be set. Return Value:
• CANT_E_OK: The setting is successful.
• CANT_E_INVALID: The passed cant pointer is NULL.
• CANT_E_ECANID: The passed canid is 0.

cant_set_busload Function

int cant_set_busload(CANT *cant, uint16_t load);

Function Description: Sets the bus load of the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to be operated on.
• load: The bus load value to be set. Return Value:
• CANT_E_OK: The setting is successful.
• CANT_E_INVALID: The passed cant pointer is NULL.

cant_get_busload Function

int cant_get_busload(CANT *cant, uint16_t *load);

Function Description: Obtains the bus load of the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to be operated on.
• load: A pointer to the variable used to store the bus load value. Return Value:
• CANT_E_OK: The acquisition is successful.
• CANT_E_INVALID: The passed cant pointer is NULL.
• CANT_E_LOAD: The passed load pointer is NULL.

cant_transmit Function

int cant_transmit(CANT *cant, uint32_t canid, uint8_t *data, uint16_t length);

Function Description: Sends data through the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to be operated on.
• canid: The CAN identifier of the data to be sent.
• data: A pointer to the data to be sent.
• length: The length of the data to be sent. Return Value:
• CANT_E_OK: The sending is successful.
• CANT_E_INVALID: The passed cant pointer is NULL.
• CANT_E_DATA: The passed data pointer is NULL.
• CANT_E_TRANSMIT: The transmit function pointer in the cant structure is NULL.
• CANT_E_TRANSFAIL: The actual sending function returns a non - zero value, indicating a sending failure.

cant_receive Function

int cant_receive(CANT *cant, uint32_t canid, uint8_t *data, uint16_t length);

Function Description: Receives data through the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to be operated on.
• canid: The CAN identifier of the data to be received.
• data: A pointer to the buffer used to store the received data.
• length: The length of the data to be received. Return Value:
• CANT_E_OK: The reception is successful.
• CANT_E_INVALID: The passed cant pointer is NULL.

cant_init Function

int cant_init(CANT *cant);

Function Description: Initializes the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to be initialized. Return Value:
• CANT_E_OK: The initialization is successful.
• CANT_E_INVALID: The passed cant pointer is NULL.

cant_task Function

int cant_task(CANT *cant);

Function Description: The main task function of the CAN device, used to handle the periodic tasks of the CAN device. Parameter Introduction:

• cant: A pointer to the CANT structure, representing the CAN device to execute the task. Return Value:
• CANT_E_OK: The task is executed successfully.
• CANT_E_INVALID: The passed cant pointer is NULL.