Subversion Repositories HomeAutomation

Rev

Rev 693 | Rev 1909 | 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 <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.     unsigned long Id; /**< CAN extended ID (29 bits). */
  61.     char Length; /**< Data length [0,8]. */
  62.     unsigned char Data[8]; /**< Data array. Only the first \c Length elements are valid. */
  63. #if (STDCAN_FILTER)
  64.     unsigned char Match; /**< Filter id that matched this message. */
  65. #endif
  66. } StdCan_Msg_t;
  67.  
  68. /**
  69.  * @brief Node descriptor.
  70.  *
  71.  * Describes the node and the application running on it.
  72.  * TODO: Discuss the purpose and layout of Node_Desc_t.
  73.  */
  74. typedef struct {
  75.     unsigned short Type; /**< Application type (documented elsewhere). */
  76.     unsigned short Version; /**< Application version number (application defined). */
  77.     unsigned char Id; /**< Node ID. */
  78. } Node_Desc_t;
  79.  
  80. //(why have constats passed as parameters? they are defined at compiletime /arune)
  81.  
  82.  
  83. /**
  84.  * @brief Initialize StdCan.
  85.  *
  86.  * Initializes the StdCan and lower layers and sends an Application Startup
  87.  * Message.
  88.  *
  89.  * @param node_desc
  90.  *      Pointer to node descriptor, containing information about the type and
  91.  *      version of the application that should be announced in startup and
  92.  *      heartbeat messages.
  93.  */
  94. StdCan_Ret_t StdCan_Init(Node_Desc_t* node_desc);
  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.