From 6a263a1959c7affb8db2d82b77835a2ed02b2f95 Mon Sep 17 00:00:00 2001 From: Jeremy Boynes Date: Thu, 2 Nov 2023 13:39:21 +0000 Subject: [PATCH] Add documentation for CAN API --- api/HardwareCAN.h | 46 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/api/HardwareCAN.h b/api/HardwareCAN.h index 6dc87ebc..a5b87604 100644 --- a/api/HardwareCAN.h +++ b/api/HardwareCAN.h @@ -44,12 +44,56 @@ class HardwareCAN virtual ~HardwareCAN() {} + /** + * Initialize the CAN controller. + * + * @param can_bitrate the bus bit rate + * @return true if initialization succeeded and the controller is operational + */ virtual bool begin(CanBitRate const can_bitrate) = 0; - virtual void end() = 0; + /** + * Disable the CAN controller. + * + * Whether any messages that are buffered will be sent is _implementation defined_. + */ + virtual void end() = 0; + /** + * Enqueue a message for transmission to the CAN bus. + * + * This call returns when the message has been enqueued for transmission. + * Due to bus arbitration and error recovery there may be a substantial delay + * before the message is actually sent. + * + * An implementation must ensure that all messages with the same CAN priority + * are sent in the order in which they are enqueued. + * + * It is _implementation defined_ whether multiple messages can be enqueued + * for transmission, and if messages with higher CAN priority can preempt the + * transmission of previously enqueued messages. The default configuration for + * and implementation should not allow multiple messages to be enqueued. + * + * @param msg the message to send + * @return 1 if the message was enqueued, an _implementation defined_ error code < 0 if there was an error + * @todo define specific error codes, especially "message already pending" + */ virtual int write(CanMsg const &msg) = 0; + + /** + * Determine if any messages have been received and buffered. + * + * @return the number of unread messages that have been received + */ virtual size_t available() = 0; + + /** + * Returns the first message received, or an empty message if none are available. + * + * Messages must be returned in the order received. + * + * @return the first message in the receive buffer + */ virtual CanMsg read() = 0; }; pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy