vcan.h File Reference

#include <stdint.h>
#include <stddef.h>
#include <string.h>
#include <stdlib.h>

Include dependency graph for vcan.h:

Go to the source code of this file.

Data Structures
struct	vcan_msg_t
	Message to transmit or receive. More...
struct	vcan_node
	Virtual node. More...
struct	vcan_bus_t
	Virtual bus. More...

Macros
#define	VCAN_VERSION   "2.0.0"
	VCAN version using semantic versioning.
#define	VCAN_DATA_MAX_LEN   64
	Max payload size of a CAN message in bytes.
#define	VCAN_MAX_CONNECTED_NODES   16
	MAx amount of virtual nodes connected to the virtual bus.

Typedefs
typedef struct vcan_node	vcan_node_t
	Virtual node. More...

Enumerations
enum	vcan_err_t {   VCAN_OK = 0, VCAN_NULL_BUS = 1, VCAN_NULL_MSG = 2, VCAN_NULL_NODE = 3,   VCAN_NULL_CALLBACK = 4, VCAN_TOO_MANY_CONNECTED = 5, VCAN_NODE_NOT_FOUND = 6, VCAN_ALREADY_CONNECTED = 7 }
	VCAN error codes. More...

Functions
vcan_err_t	vcan_init (vcan_bus_t *bus)
	Initialises the bus. More...
vcan_err_t	vcan_connect (vcan_bus_t *bus, vcan_node_t *node)
	Attaches a new node to the bus, enabling it to receive any transmitted message. More...
vcan_err_t	vcan_disconnect (vcan_bus_t *bus, const vcan_node_t *node)
	Detaches a node from the bus, disabling it from receiving any further messages. More...
vcan_err_t	vcan_tx (vcan_bus_t *bus, const vcan_msg_t *msg, const vcan_node_t *src_node)
	Sends a copy of the message to every connected node and calls every nodes's callback to notify them. More...

Detailed Description

VCAN is a tiny Virtual CAN and CAN-FD bus.

Especially useful for debugging and testing without using actual CAN-connected devices, VCAN is a tiny C library that allows the user to connect virtual nodes on a virtual bus and make them react whenever someone transmits a message on the bus.

After the transmission, each node obtains a copy of the message and a callback on each node is called to warn the node of a message being received.

Limitations

VCAN is simple, synchronous and not thread safe. It does not simulate transmission errors, collisions, arbitration, etc. just pure data transfer. Callbacks should be fast.

... but you are free to alter it to your specific needs!

Copyright

Copyright © 2020, Matjaž Guštin dev@m.nosp@m.atja.nosp@m.z.it https://matjaz.it. All rights reserved. License: BSD 3-clause license.

Typedef Documentation

vcan_node_t

typedef struct vcan_node vcan_node_t

Virtual node.

Contains a copy of the last received message and a callback function, which is called whenever a message is received.

Enumeration Type Documentation

vcan_err_t

enum vcan_err_t

VCAN error codes.

Enumerator
VCAN_OK	Successfully completed.
VCAN_NULL_BUS	The bus argument is NULL.
VCAN_NULL_MSG	The message argument is NULL.
VCAN_NULL_NODE	The node argument is NULL.
VCAN_NULL_CALLBACK	The callback within the node is NULL.
VCAN_TOO_MANY_CONNECTED	Max amount of connected nodes reached. Consider increasing VCAN_MAX_CONNECTED_NODES.
VCAN_NODE_NOT_FOUND	This node is not connected to the bus, so it cannot be disconnected.
VCAN_ALREADY_CONNECTED	The node is already connected to the bus.

Function Documentation

vcan_init()

vcan_err_t vcan_init

(

vcan_bus_t *

bus

)

Initialises the bus.

Parameters

bus

not NULL

Returns

• VCAN_NULL_BUS on bus being NULL
• VCAN_OK otherwise

vcan_connect()

vcan_err_t vcan_connect	(	vcan_bus_t *	bus,
		vcan_node_t *	node
	)

Attaches a new node to the bus, enabling it to receive any transmitted message.

When someone transmits a message, the node will get a copy into node->received_msg and its callback will be called, passing the node itself as its only argument.

Parameters

bus	not NULL
node	not NULL, with callback not NULL

Returns

• VCAN_NULL_BUS on bus being NULL
• VCAN_NULL_NODE on node being NULL
• VCAN_NULL_CALLBACK on node->callback_on_rx being NULL
• VCAN_TOO_MANY_CONNECTED when there number of already connected nodes to the bus the maximum. Increase VCAN_MAX_CONNECTED_NODES if required.
• VCAN_ALREADY_CONNECTED when the node is already connected to the bus, there is nothing to be done.
• VCAN_OK otherwise

vcan_disconnect()

vcan_err_t vcan_disconnect	(	vcan_bus_t *	bus,
		const vcan_node_t *	node
	)

Detaches a node from the bus, disabling it from receiving any further messages.

Parameters

bus	not NULL
node	not NULL

Returns

• VCAN_NULL_BUS on bus being NULL
• VCAN_NULL_NODE on node being NULL
• VCAN_NODE_NOT_FOUND the node was not connected to this bus, so there is nothing to do
• VCAN_OK otherwise

vcan_tx()

vcan_err_t vcan_tx	(	vcan_bus_t *	bus,
		const vcan_msg_t *	msg,
		const vcan_node_t *	src_node
	)

Sends a copy of the message to every connected node and calls every nodes's callback to notify them.

If you include a transmitting node, that one is excluded from the reception.

The callbacks must be fast in order to make this function perform quick enough. Before transmitting the next message, the user should take care that each virtual node has finished processing the message (e.g. copying to another location), so the next transmit does not overwrite the unprocessed message in the nodes.

Parameters

bus	not NULL
msg	not NULL
src_node	can be NULL

Returns

• VCAN_NULL_BUS on bus being NULL
• VCAN_NULL_MSG on msg being NULL
• VCAN_OK otherwise