Subversion Repositories HomeAutomation

Rev

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