@@ -44,12 +44,56 @@ class HardwareCAN
4444virtual ~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+ */
4753virtual bool begin (CanBitRateconst 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+ */
5181virtual int write (CanMsgconst &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+ */
5288virtual 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+ */
5397virtual CanMsgread () = 0;
5498};
5599