Subversion Repositories HomeAutomation

/**

 * @defgroup stdcan StdCan Library

 * @code #include <drivers/can/stdcan.h> @endcode

 *

 * @brief High level functions for bus communication and standard node behaviour.

 *

 * This library provides a higher level interface to the CAN bus than the raw driver/BIOS

 * interface, as well as functions for easy implementation of required node behaviour.

 *

 * It implements receive and transmit FIFOs of configurable lengths, Application Startup

 * message at init, and Heartbeat transmission.

 *

 * @author  Andreas Fritiofson

 * @date    2007-10-24

 */

/**@{*/

#ifndef STDCAN_H_

#define STDCAN_H_

#include <config.h>

#include <drivers/can/canid.h>

#include <inttypes.h>

#ifndef STDCAN_FILTER

#define STDCAN_FILTER 0

#endif

#ifndef STDCAN_RX_QUEUE_SIZE

#define STDCAN_RX_QUEUE_SIZE 8

#endif

#ifndef STDCAN_TX_QUEUE_SIZE

#define STDCAN_TX_QUEUE_SIZE 1

#endif

/**

 * @brief Return values.

 *

 * Most StdCan functions return one of these values.

 */

typedef enum {

    StdCan_Ret_OK, /**< Operation completed successfully. */

    StdCan_Ret_Full, /**< Failed to send because transmit queue was full. */

    StdCan_Ret_Empty, /**< Failed to read because receive queue was empty. */

    StdCan_Ret_Fail, /**< General error. */

    StdCan_Ret_DataErr /**< Malformed data. */

} StdCan_Ret_t;

/**

 * @brief Message structure.

 *

 * Stores a CAN message frame. Flags that are unsupported have been

 * excluded (RTR and standard id).

 */

typedef struct {

#ifdef MODULE_APPLICATION

    union {

        uint32_t Id;    /**< CAN extended ID (29 bits). */

        struct {

            uint8_t Command;

            uint8_t ModuleId;

            uint8_t ModuleType;

            uint8_t ClassAndDirection;

        } Header;

    };

#else

    unsigned long Id; /**< CAN extended ID (29 bits). */

#endif

    char Length; /**< Data length [0,8]. */

    unsigned char Data[8]; /**< Data array. Only the first \c Length elements are valid. */

#if (STDCAN_FILTER)

    unsigned char Match; /**< Filter id that matched this message. */

#endif

} StdCan_Msg_t;

#define StdCan_Ret_class(Header) (uint8_t)((Header.ClassAndDirection >> 1) & 0x0F)

#define StdCan_Set_class(Header, CLASS) Header.ClassAndDirection &= 0x01; Header.ClassAndDirection |= (CLASS << 1);

#define StdCan_Ret_direction(Header) (uint8_t)(Header.ClassAndDirection & 0x01)

#define StdCan_Set_direction(Header, DIR) Header.ClassAndDirection &= 0xfe; Header.ClassAndDirection |= DIR;

#define NODE_HW_ID_BYTE3 (uint8_t)((BIOS_GetHwId()>>24)&0xff)

#define NODE_HW_ID_BYTE2 (uint8_t)((BIOS_GetHwId()>>16)&0xff)

#define NODE_HW_ID_BYTE1 (uint8_t)((BIOS_GetHwId()>>8)&0xff)

#define NODE_HW_ID_BYTE0 (uint8_t)((BIOS_GetHwId())&0xff)

/**

 * @brief Node descriptor.

 *

 * Describes the node and the application running on it.

 * TODO: Discuss the purpose and layout of Node_Desc_t.

 */

typedef struct {

    unsigned short Type; /**< Application type (documented elsewhere). */

    unsigned short Version; /**< Application version number (application defined). */

    unsigned char Id; /**< Node ID. */

} Node_Desc_t;

/**

 * @brief Initialize StdCan.

 *

 * Initializes the StdCan and lower layers and sends an Application Startup

 * Message.

 *

 * @param node_desc

 *      Pointer to node descriptor, containing information about the type and

 *      version of the application that should be announced in startup and

 *      heartbeat messages.

 */

#ifdef MODULE_APPLICATION

StdCan_Ret_t StdCan_Init(void);

#else 

StdCan_Ret_t StdCan_Init(Node_Desc_t* node_desc);

#endif

/**

 * @brief Get a message.

 *

 * Retrieves a message from the receive queue.

 *

 * @param[out] msg

 *      Pointer to message stucture to be filled with the next message from

 *      the queue.

 */

StdCan_Ret_t StdCan_Get(StdCan_Msg_t* msg);

/**

 * @brief Send a message.

 *

 * Puts a message on the transmit queue.

 *

 * @param[in] msg

 *      Pointer to message to send.

 */

StdCan_Ret_t StdCan_Put(StdCan_Msg_t* msg);

/**

 * @brief Send a Heartbeat.

 *

 * Puts a Heartbeat message on the transmit queue. Takes an \c uint8_t and

 * returns \c void in order to be able to use it as a \c Timer callback

 * directly, i.e.

 * @code

 * Timer_SetTimeout(APP_HEARTBEAT_TIMER, STDCAN_HEARTBEAT_PERIOD, TimerTypeFreeRunning, StdCan_SendHeartbeat);

 * @endcode

 * If the transmit queue is full this function will silently fail.

 *

 * @param n

 *      Dummy value.

 */

void StdCan_SendHeartbeat(uint8_t n);

/**

 * @brief Enable a message acceptance filter.

 *

 * Allows incoming messages to be accepted or rejected by matching their id.

 * Message is accepted if @code (message_id ^ id) & mask @endcode is zero for any

 * of the active filters.

 *

 * @param filter

 *      Filter slot to activate (filter < STDCAN_NUM_FILTERS).

 * @param id

 *      Match if id matches the message id in all bit locations that are

 *      not masked.

 * @param mask

 *      Each bit specifies if the corresponding id bit must match (mask[n] = 1)

 *      or is Don't Care (mask[n] = 0).

 */

StdCan_Ret_t StdCan_EnableFilter(unsigned char filter, unsigned long id, unsigned long mask);

/**

 * @brief Disable a message acceptance filter.

 *

 * Disables a filter (marks it at not matching any messages).

 *

 * @param filter

 *      Filter slot to disable (filter < STDCAN_NUM_FILTERS).

 */

StdCan_Ret_t StdCan_DisableFilter(unsigned char filter);

/**@}*/

#endif /*STDCAN_H_*/