Subversion Repositories HomeAutomation

Rev

Rev 687 | Rev 693 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | SVN | RSS feed

  1. /**
  2.  * @defgroup stdcan StdCan Library
  3.  * @code #include <drivers/can/stdcan.h> @endcode
  4.  *
  5.  * @brief High level functions for bus communication and standard node behaviour.
  6.  *
  7.  * This library provides a higher level interface to the CAN bus than the raw driver/BIOS
  8.  * interface, as well as functions for easy implementation of required node behaviour.
  9.  *
  10.  * It implements receive and transmit FIFOs of configurable lengths, Application Startup
  11.  * message at init, and Heartbeat transmission.
  12.  *
  13.  * @author  Andreas Fritiofson
  14.  * @date    2007-10-24
  15.  */
  16.  
  17. /**@{*/
  18.  
  19. #error StdCan: For discussion only! Do not use in application code.
  20.  
  21. #ifndef STDCAN_H_
  22. #define STDCAN_H_
  23.  
  24. #include <config.h>
  25.  
  26. #ifndef STDCAN_FILTER
  27. #define STDCAN_FILTER 1
  28. #endif
  29. #ifndef STDCAN_RX_QUEUE_SIZE
  30. #define STDCAN_RX_QUEUE_SIZE 8
  31. #endif
  32. #ifndef STDCAN_TX_QUEUE_SIZE
  33. #define STDCAN_TX_QUEUE_SIZE 1
  34. #endif
  35.  
  36. /**
  37.  * @brief Return values.
  38.  *
  39.  * Most StdCan functions return one of these values.
  40.  */
  41. typedef enum {
  42.     StdCan_Ret_OK, /**< Operation completed successfully. */
  43.     StdCan_Ret_Full, /**< Failed to send because transmit queue was full. */
  44.     StdCan_Ret_Empty, /**< Failed to read because receive queue was empty. */
  45.     StdCan_Ret_Fail, /**< General error. */
  46.     StdCan_Ret_DataErr /**< Malformed data. */
  47. } StdCan_Ret_t;
  48.  
  49. /**
  50.  * @brief Message structure.
  51.  *
  52.  * Stores a CAN message frame. Flags that are unsupported have been
  53.  * excluded (RTR and standard id).
  54.  */
  55. typedef struct {
  56.     unsigned long Id; /**< CAN extended ID (29 bits). */
  57.     char Length; /**< Data length [0,8]. */
  58.     unsigned char Data[8]; /**< Data array. Only the first \c Length elements are valid. */
  59. #if (STDCAN_FILTER)
  60.     unsigned char Match; /**< Filter id that matched this message. */
  61. #endif
  62. } StdCan_Msg_t;
  63.  
  64. /**
  65.  * @brief Node descriptor.
  66.  *
  67.  * Describes the node and the application running on it.
  68.  * TODO: Discuss the purpose and layout of Node_Desc_t.
  69.  */
  70. typedef struct {
  71.     unsigned short Type; /**< Application type (documented elsewhere). */
  72.     unsigned short Version; /**< Application version number (application defined). */
  73.     unsigned char Id; /**< Node ID. */
  74. } Node_Desc_t;
  75.  
  76. /**
  77.  * @brief Initialize StdCan.
  78.  *
  79.  * Initializes the StdCan and lower layers and sends an Application Startup
  80.  * Message.
  81.  *
  82.  * @param node_desc
  83.  *      Pointer to node descriptor, containing information about the type and
  84.  *      version of the application that should be announced in startup and
  85.  *      heartbeat messages.
  86.  */
  87. StdCan_Ret_t StdCan_Init(Node_Desc_t* node_desc);
  88.  
  89. /**
  90.  * @brief Get a message.
  91.  *
  92.  * Retrieves a message from the receive queue.
  93.  *
  94.  * @param[out] msg
  95.  *      Pointer to message stucture to be filled with the next message from
  96.  *      the queue.
  97.  */
  98. StdCan_Ret_t StdCan_Get(StdCan_Msg_t* msg);
  99.  
  100. /**
  101.  * @brief Queue size.
  102.  *
  103.  * Returns the number of messages pending in the receive queue.
  104.  *
  105.  * @retval
  106.  *      Number of messages in the receive queue.
  107.  */
  108. unsigned char StdCan_Get_Pending();
  109.  
  110. /**
  111.  * @brief Send a message.
  112.  *
  113.  * Puts a message on the transmit queue.
  114.  *
  115.  * @param[in] msg
  116.  *      Pointer to message to send.
  117.  */
  118. StdCan_Ret_t StdCan_Put(StdCan_Msg_t* msg);
  119.  
  120. /**
  121.  * @brief Send a Heartbeat.
  122.  *
  123.  * Puts a Heartbeat message on the transmit queue. Takes an \c uint8_t and
  124.  * returns \c void in order to be able to use it as a \c Timer callback
  125.  * directly, i.e.
  126.  * @code
  127.  * Timer_SetTimeout(APP_HEARTBEAT_TIMER, STDCAN_HEARTBEAT_PERIOD, TimerTypeFreeRunning, StdCan_SendHeartbeat);
  128.  * @endcode
  129.  * If the transmit queue is full this function will silently fail.
  130.  *
  131.  * @param n
  132.  *      Dummy value.
  133.  */
  134. void StdCan_SendHeartbeat(uint8_t n);
  135.  
  136. /**
  137.  * @brief Enable a message acceptance filter.
  138.  *
  139.  * Allows incoming messages to be accepted or rejected by matching their id.
  140.  * Message is accepted if @code (message_id ^ id) & mask @endcode is zero for any
  141.  * of the active filters.
  142.  *
  143.  * @param filter
  144.  *      Filter slot to activate (filter < STDCAN_NUM_FILTERS).
  145.  * @param id
  146.  *      Match if id matches the message id in all bit locations that are
  147.  *      not masked.
  148.  * @param mask
  149.  *      Each bit specifies if the corresponding id bit must match (mask[n] = 1)
  150.  *      or is Don't Care (mask[n] = 0).
  151.  */
  152. StdCan_Ret_t StdCan_EnableFilter(unsigned char filter, unsigned long id, unsigned long mask);
  153.  
  154. /**
  155.  * @brief Disable a message acceptance filter.
  156.  *
  157.  * Disables a filter (marks it at not matching any messages).
  158.  *
  159.  * @param filter
  160.  *      Filter slot to disable (filter < STDCAN_NUM_FILTERS).
  161.  */
  162. StdCan_Ret_t StdCan_DisableFilter(unsigned char filter);
  163.  
  164. /**@}*/
  165.  
  166. #endif /*STDCAN_H_*/
  167.