Subversion Repositories HomeAutomation

Rev

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