Skip to content

Commit c486627

Browse files
authored
Merge pull request #222 from jboynes/can_api
Add documentation for CAN API to fix #221
2 parents 65633ce + 6a263a1 commit c486627

File tree

1 file changed

+45
-1
lines changed

1 file changed

+45
-1
lines changed

api/HardwareCAN.h

+45-1
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,56 @@ class HardwareCAN
4444
virtual ~HardwareCAN() {}
4545

4646

47+
/**
48+
* Initialize the CAN controller.
49+
*
50+
* @param can_bitrate the bus bit rate
51+
* @return true if initialization succeeded and the controller is operational
52+
*/
4753
virtual bool begin(CanBitRate const can_bitrate) = 0;
48-
virtual void end() = 0;
4954

55+
/**
56+
* Disable the CAN controller.
57+
*
58+
* Whether any messages that are buffered will be sent is _implementation defined_.
59+
*/
60+
virtual void end() = 0;
5061

62+
/**
63+
* Enqueue a message for transmission to the CAN bus.
64+
*
65+
* This call returns when the message has been enqueued for transmission.
66+
* Due to bus arbitration and error recovery there may be a substantial delay
67+
* before the message is actually sent.
68+
*
69+
* An implementation must ensure that all messages with the same CAN priority
70+
* are sent in the order in which they are enqueued.
71+
*
72+
* It is _implementation defined_ whether multiple messages can be enqueued
73+
* for transmission, and if messages with higher CAN priority can preempt the
74+
* transmission of previously enqueued messages. The default configuration for
75+
* and implementation should not allow multiple messages to be enqueued.
76+
*
77+
* @param msg the message to send
78+
* @return 1 if the message was enqueued, an _implementation defined_ error code < 0 if there was an error
79+
* @todo define specific error codes, especially "message already pending"
80+
*/
5181
virtual int write(CanMsg const &msg) = 0;
82+
83+
/**
84+
* Determine if any messages have been received and buffered.
85+
*
86+
* @return the number of unread messages that have been received
87+
*/
5288
virtual size_t available() = 0;
89+
90+
/**
91+
* Returns the first message received, or an empty message if none are available.
92+
*
93+
* Messages must be returned in the order received.
94+
*
95+
* @return the first message in the receive buffer
96+
*/
5397
virtual CanMsg read() = 0;
5498
};
5599

0 commit comments

Comments
 (0)