Subversion Repositories HomeAutomation

Rev

Rev 687 | Rev 693 | Go to most recent revision | Show entire file | Regard whitespace | Details | Blame | Last modification | View Log | SVN | RSS feed

Rev 687 Rev 690
Line 1... Line 1...
1 
/**
 1 
/**
- 
 
 2 
 * @defgroup stdcan StdCan Library
2 
 * High level functions for bus communication and standard node behaviour.
 3 
 * @code #include <drivers/can/stdcan.h> @endcode
3 
 *
 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
4 
 * @author  Andreas Fritiofson
 11 
 * message at init, and Heartbeat transmission.
5 
 *
 12 
 *
- 
 
 13 
 * @author  Andreas Fritiofson
6 
 * @date    2007-10-24
 14 
 * @date    2007-10-24
7 
 */
 15 
 */
8 
 
 16 
 
- 
 
 17 
/**@{*/
- 
 
 18 
 
9 
#error StdCan: For discussion only! Do not use in application code.
 19 
#error StdCan: For discussion only! Do not use in application code.
10 
 
 20 
 
11 
#ifndef STDCAN_H_
 21 
#ifndef STDCAN_H_
12 
#define STDCAN_H_
 22 
#define STDCAN_H_
13 
 
 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 
 
14 
/**
 36 
/**
15 
 * Return values.
 37 
 * @brief Return values.
- 
 
 38 
 *
16 
 * Most StdCan functions return one of these values.
 39 
 * Most StdCan functions return one of these values.
17 
 */
 40 
 */
18 
typedef enum {
 41 
typedef enum {
19 
    StdCan_Ret_OK, /**< Operation completed successfully. */
 42 
    StdCan_Ret_OK, /**< Operation completed successfully. */
20 
    StdCan_Ret_Full, /**< Failed to send because transmit queue was full. */
 43 
    StdCan_Ret_Full, /**< Failed to send because transmit queue was full. */
Line 22... Line 45...
22 
    StdCan_Ret_Fail, /**< General error. */
 45 
    StdCan_Ret_Fail, /**< General error. */
23 
    StdCan_Ret_DataErr /**< Malformed data. */
 46 
    StdCan_Ret_DataErr /**< Malformed data. */
24 
} StdCan_Ret_t;
 47 
} StdCan_Ret_t;
25 
 
 48 
 
26 
/**
 49 
/**
27 
 * Message structure.
 50 
 * @brief Message structure.
- 
 
 51 
 *
28 
 * Stores a CAN message frame. Flags that are unused at this level have been
 52 
 * Stores a CAN message frame. Flags that are unsupported have been
29 
 * excluded (RTR and standard id).
 53 
 * excluded (RTR and standard id).
30 
 */
 54 
 */
31 
typedef struct {
 55 
typedef struct {
32 
    unsigned long Id; /**< CAN extended ID (29 bits). */
 56 
    unsigned long Id; /**< CAN extended ID (29 bits). */
33 
    char Length; /**< Data length [0,8]. */
 57 
    char Length; /**< Data length [0,8]. */
34 
    unsigned char Data[8]; /**< Data array. Only the first \c Length elements are valid. */
 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
35 
} StdCan_Msg_t;
 62 
} StdCan_Msg_t;
36 
 
 63 
 
37 
/**
 64 
/**
38 
 * Node descriptor structure.
 65 
 * @brief Node descriptor.
- 
 
 66 
 *
39 
 * Describes the node and the application running on it.
 67 
 * Describes the node and the application running on it.
40 
 * TODO: Discuss the purpose and layout of Node_Desc_t.
 68 
 * TODO: Discuss the purpose and layout of Node_Desc_t.
41 
 */
 69 
 */
42 
typedef struct {
 70 
typedef struct {
43 
    unsigned short Type; /**< Application type (documented elsewhere). */
 71 
    unsigned short Type; /**< Application type (documented elsewhere). */
44 
    unsigned short Version; /**< Application version number (application defined). */
 72 
    unsigned short Version; /**< Application version number (application defined). */
45 
    unsigned char Id; /**< Node ID. */
 73 
    unsigned char Id; /**< Node ID. */
46 
} Node_Desc_t;
 74 
} Node_Desc_t;
47 
 
 75 
 
48 
/**
 76 
/**
49 
 * Initialize StdCan.
 77 
 * @brief Initialize StdCan.
- 
 
 78 
 *
50 
 * Initializes the StdCan and lower layers and sends an Application Startup
 79 
 * Initializes the StdCan and lower layers and sends an Application Startup
51 
 * Message.
 80 
 * Message.
52 
 *
 81 
 *
53 
 * @param node_desc
 82 
 * @param node_desc
54 
 *      Pointer to node descriptor, containing information about the type and
 83 
 *      Pointer to node descriptor, containing information about the type and
Line 56... Line 85...
56 
 *      heartbeat messages.
 85 
 *      heartbeat messages.
57 
 */
 86 
 */
58 
StdCan_Ret_t StdCan_Init(Node_Desc_t* node_desc);
 87 
StdCan_Ret_t StdCan_Init(Node_Desc_t* node_desc);
59 
 
 88 
 
60 
/**
 89 
/**
61 
 * Get a message.
 90 
 * @brief Get a message.
- 
 
 91 
 *
62 
 * Retrieves a message from the receive queue.
 92 
 * Retrieves a message from the receive queue.
63 
 *
 93 
 *
64 
 * @param[out] msg
 94 
 * @param[out] msg
65 
 *      Pointer to message stucture to be filled with the next message from
 95 
 *      Pointer to message stucture to be filled with the next message from
66 
 *      the queue.
 96 
 *      the queue.
67 
 */
 97 
 */
68 
StdCan_Ret_t StdCan_Get(StdCan_Msg_t* msg);
 98 
StdCan_Ret_t StdCan_Get(StdCan_Msg_t* msg);
69 
 
 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 
 
70 
/**
 110 
/**
71 
 * Send a message.
 111 
 * @brief Send a message.
- 
 
 112 
 *
72 
 * Puts a message on the transmit queue.
 113 
 * Puts a message on the transmit queue.
73 
 *
 114 
 *
74 
 * @param[in] msg
 115 
 * @param[in] msg
75 
 *      Pointer to message to send.
 116 
 *      Pointer to message to send.
76 
 */
 117 
 */
77 
StdCan_Ret_t StdCan_Put(StdCan_Msg_t* msg);
 118 
StdCan_Ret_t StdCan_Put(StdCan_Msg_t* msg);
78 
 
 119 
 
79 
/**
 120 
/**
80 
 * Send a Heartbeat.
 121 
 * @brief Send a Heartbeat.
- 
 
 122 
 *
81 
 * Puts a Heartbeat message on the transmit queue. Takes an \c uint8_t and
 123 
 * Puts a Heartbeat message on the transmit queue. Takes an \c uint8_t and
82 
 * returns \c void in order to be able to use it as a \c Timer callback
 124 
 * returns \c void in order to be able to use it as a \c Timer callback
83 
 * directly, i.e.
 125 
 * directly, i.e.
84 
 * \code
 126 
 * @code
85 
 *      Timer_SetTimeout(APP_HEARTBEAT_TIMER, STDCAN_HEARTBEAT_PERIOD, TimerTypeFreeRunning, StdCan_SendHeartbeat);
 127 
 * Timer_SetTimeout(APP_HEARTBEAT_TIMER, STDCAN_HEARTBEAT_PERIOD, TimerTypeFreeRunning, StdCan_SendHeartbeat);
86 
 * \endcode
 128 
 * @endcode
87 
 * If the transmit queue is full this function will silently fail.
 129 
 * If the transmit queue is full this function will silently fail.
88 
 *
 130 
 *
89 
 * @param n
 131 
 * @param n
90 
 *      Dummy value.
 132 
 *      Dummy value.
91 
 */
 133 
 */
92 
void StdCan_SendHeartbeat(uint8_t n);
 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 
/**@}*/
93 
 
 165 
 
94 
#endif /*STDCAN_H_*/
 166 
#endif /*STDCAN_H_*/