lifegrd.h

This library is Copyright (c) Raphael Zulliger <[e-mail]>. It is licensed under the GNU L

/***************************************************************************
                          lifegrd.h  -  description
                             -------------------
    begin                : Fri May 17 2002
    copyright            : (C) 2002 by Raphael Zulliger
    email                : [e-mail]
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This library is Copyright (c) Raphael Zulliger <[e-mail]>.       *
 *   It is licensed under the GNU Library General Public License (LGPL).   *
 *                                                                         *
 ***************************************************************************/


/** \file
 *  \brief Heartbeat and nodeguarding
 *
 *  Lifeguarding & Nodeguard related stuff, such as heartbeat and lifeguard messages
 *  \warning Only Heartbeat is implemented yet.
 */

#ifndef __lifegrd_h__
#define __lifegrd_h__

#include <def.h>
#include <objdict.h>
#include <canop.h>


/** This variable indicates wheter the device is in the Notfall-state (this means
 *  that one of its heartbeatproducers hasn't send a heartbeat message. 
 */
extern BOOL bErrorOccured;

/** Struct for creating a table where all cob_ids of our consumers are stored. inclusive the time
 *  since the last heartbeat...
 */
typedef struct td_s_heartbeat_entry
{
    /** ID of the node which we have to guard
     */
	WORD id;
    /** this is the maximum time between two heartbeat messages... if this value is set
     *  to 0, then this heartbeat is disabled.
     */
	WORD should_time;
	/** time since the last heartbeat-message. scale is not yet clear. maybe 1 = 1ms...
	 * everytime a new heartbeat-message has been received, this var must be set to 0
     */
    WORD time;
} s_heartbeat_entry;

/** This variable holds all heartbeat related values for our hearbeat consumers.
 */
extern s_heartbeat_entry heartBeatTable[];


/** Struct for creating a table where the needed heartbeat values for this CANopen node
 *  are stored. Thanks to this table, the heartbeat related functions don't have to
 *  access the object dictionary every time.
 */
typedef struct td_s_ourHeartBeatValues
{
	/** the configured time within we have to send our heartbeat message
     */
	WORD ourShouldTime;
	/** the time which has passed since the last sending of a heartbeat message
     */
	WORD ourTime;
	/** the time when the heartbeat-function (Process_LifeGuard) has been called.
     *  This is neccessary to know, so we can decide when to send our heartbeat.
     */
	WORD ourLastTime;
} s_ourHeartBeatValues;

/** This variable holds the values about the heartbeat settings of this node
 */
extern s_ourHeartBeatValues ourHeartBeatValues;


//*************************************************************************/
//Functions
//*************************************************************************/

/** initialisates all neccessary values for lifeguarding. Therefore this function
 *  reads index 1016 and 1017 of the object dictionary and fills in the data
 *  into the variable heartBeatTable and ourHeartBeatValues. Everytime the indicies
 *  1016 or 1017 have changed, this function must be called
 */
void lifeguardInit(void);

/** Checks wheter all heartbeat messages (where this node is a heartbeat consumer)
 *  have arrived within the configured time (configuration in the object dictionary).
 *  if not all messages have arrived, lifeguardCallback is called, so the user can
 *  perform any error-handling.
 *  This function also sends the heartbeat messages of this node, if neccessary.
 */
void processLifeGuard(void);

/** This function is called by processLifeGuard( ) if one or more heartbeat message
 *  haven't arrived within the configured time. The argument is one of the following:
 *  CONNECTION_OK, CONNECTION_FAILED, GUARDING_MESSAGE_LOST, HEARTBEAT_MESSAGE_LOST,
 *  HEARTBEAT_CONSUMER_LOST defined in file def.h
 *  \param bReason can be one of the Error-states defined in def.h, such as
 *          - CONNECTION_OK
 *          - CONNECTION_FAILED
 *          - GUARDING_MESSAGE_LOST
 *          - HEARTBEAT_MESSAGE_LOST
 *          - HEARTBEAT_CONSUMER_LOST
 */
void lifeguardCallback( BYTE bReason );

/** This function is called by proccessRxCanMessages( ). it is responsible to
 *  process a canopen-message which seams to be an NMT Error Control
 *  Messages. At them moment we assume that every NMT error control message
 *  is a heartbeat message.
 *  \param canopenMessage The CAN-message which has to be analysed.
 */
void processReceivedNMTErrorControl( s_rx_buffer_message* canopenMessage );

#endif //__lifegrd_h__