src.dualinventive.com/dinet/libdi-php/libdi/include/di/device.h

/**
 * DI Device Generic Functionality
 */
#ifndef LIBDI_INCLUDE_DEVICE_H_
#define LIBDI_INCLUDE_DEVICE_H_

#include <stdint.h>
#include <stdbool.h>

#include <di/types.h>
#include <di/config.h>
#include <di/device/uid.h>
#include <di/device/error.h>
#include <di/device/cloudlight.h>

#ifdef __cplusplus
extern "C" {
#endif

#define DI_DEVICE_ACTIVATION_DEFAULT_VALUE false
#define DI_DEVICE_TOKEN_DEFAULT_VALUE      0U
#define DI_DEVICE_SERVICE_DEFAULT_VALUE    false

#define DI_DEVICE_CONFIG_DEFAULT_TOKEN      DI_CONFIG_ITEM_DEFAULT_UINT32(DI_DEVICE_TOKEN_DEFAULT_VALUE)
#define DI_DEVICE_CONFIG_DEFAULT_ACTIVATION DI_CONFIG_ITEM_DEFAULT_BOOL(DI_DEVICE_ACTIVATION_DEFAULT_VALUE)
#define DI_DEVICE_CONFIG_DEFAULT_SERVICE    DI_CONFIG_ITEM_DEFAULT_BOOL(DI_DEVICE_SERVICE_DEFAULT_VALUE)
#define DI_DEVICE_CONFIG_DEFAULT_UID        DI_CONFIG_ITEM_DEFAULT_STR(DI_DEVICE_UID_DEFAULT_VALUE)
#define DI_DEVICE_CONFIG_DEFAULT_SERVICE    DI_CONFIG_ITEM_DEFAULT_BOOL(DI_DEVICE_SERVICE_DEFAULT_VALUE)

#define DI_DEVICE_HW_VERSION_LEN            5
#define DI_DEVICE_FW_VERSION_LEN            60

#define DI_DEVICE_UNKNOWN_HW_VERSION	    "0.0"
#define DI_DEVICE_UNKNOWN_FW_VERSION	    "0.0.0"

/** Global device state */
enum di_device_state {
	DI_DEVICE_STATE_SERVICE, /**< Device is in service */
	DI_DEVICE_STATE_IDLE,    /**< Device is idle */
	DI_DEVICE_STATE_ARMED,   /**< Device is armed */
	DI_DEVICE_STATE_ACTIVE,  /**< Device is active */
	DI_DEVICE_STATE_UNKNOWN  /**< Device has unknown state (internal use only, must always come last) */
};

/**
 * enum of possible node roles for device
 * please note these roles are needed for the application (CAN stack has its
 * own administration). CAN adminstration is passed over to application administration
 * since the application cannot respond to events while running in the CAN context
 */
enum di_device_redundant_roles {
	DI_DEVICE_REDUNDANT_ROLE_PASSIVE,
	DI_DEVICE_REDUNDANT_ROLE_FOLLOWER,
	DI_DEVICE_REDUNDANT_ROLE_LEADER
};

/**
 * Device state transition callback
 * @param prev         Previous state
 * @param private_data Application defined private data
 */
typedef void (*di_device_state_cb_t)(enum di_device_state prev, void *private_data);

/**
 * Set device state transition callback
 * @param state    State of interest
 * @param callback Callback for state of interest (May be set to NULL)
 */
void di_device_state_set_callback(enum di_device_state state, di_device_state_cb_t callback);

/**
 * Set next state
 * @retval DNOK         Next state commit successful
 * @retval DNE_OPDENIED State transition denied
 */
di_errno_t di_device_state_set(enum di_device_state next);

/**
 * Get current device state
 */
enum di_device_state di_device_state_get(void);

/**
 * Get current device state string
 */
const char *di_device_state_get_string(void);

/**
 * Get device state string with given state
 */
const char *di_device_state_get_string_enum(enum di_device_state st);

/**
 * Control device service state
 */
di_errno_t di_device_service_set(bool active);

/**
 * Clear device service state -> idle
 */
di_errno_t di_device_service_reset(void);

/**
 * Check if the device is in service
 */
bool di_device_is_in_service(void);

/**
 * Set device token
 * @note This function is write-once, use di_device_token_reset when
 *  device is in ARMED state.
 * @param token Application defined token (DI_DEVICE_TOKEN_UNSET is invalid)
 * @retval DNOK When token is committed
 * @retval DNE_OPDENIED When token may not be set (device in ARMED or ACTIVE state)
 */
di_errno_t di_device_token_set(uint32_t token);

/**
 * Get current token
 * @return Application defined token
 */
uint32_t di_device_token_get(void);

/**
 * Reset token to value DI_DEVICE_TOKEN_UNSET
 * @retval DNOK         Reset successful
 * @retval DNE_OPDENIED Reset operation denied in current device state
 */
di_errno_t di_device_token_reset(void);

/**
 * Activate device
 * @retval DNOK         Activation successful
 * @retval DNE_OPDENIED Activation operation denied in current device state
 */
di_errno_t di_device_activate(void);

/**
 * Deactivate device
 * @retval DNOK         Deactivation successful
 * @retval DNE_OPDENIED Deactivation operation denied in current device state
 */
di_errno_t di_device_deactivate(void);

/**
 * Set device activation state
 * @param  active       Set/clear device active state
 * @retval DNOK         Deactivation successful
 * @retval DNE_OPDENIED Deactivation operation denied in current device state
 */
di_errno_t di_device_activation_set(bool active);

/**
 * Get current device activation state
 */
bool di_device_is_active(void);

/**
 * Init device module
 * * Initializes di_time module
 * * Initializes di_device_lock submodule
 * * Initializes di_device_error submodule
 * @note Must only be called once!
 */
void di_device_init(void);

/**
 * Set current device type
 * @param type		type to set
 */
void di_device_set_type(const char *type);

/**
 * Get current device type
 */
const char *di_device_get_type(void);

/**
 * Set board revision
 * @param rev		current board revision
 */
void di_device_set_board_revision(uint32_t rev);

/**
 * Get board revision
 */
uint32_t di_device_get_board_revision(void);

/**
 * Get board minor version
 */
uint8_t di_device_get_board_minor(void);

/**
 * Set board minor version
 * @param minor Minor version
 */
void di_device_set_board_minor(const uint8_t minor);

/**
 * Get board version string
 * @param[out] version Version destination string
 * @param n Size of the version
 */
void di_device_get_board_version_str(char *version, const size_t n);

/**
 * Set board strapping
 * @param strapped	boolean that indicates if the device is strapped
 */
void di_device_set_board_is_strapped(bool strapped);

/**
 * Get board strapping
 */
bool di_device_get_board_is_strapped(void);

/**
 * Set board role in the redundant setup
 * The application is responsible for setting the role of the board
 * in a redundant setup. The CAN stack will not interfere whith this
 * We need redandant role administration in the application since we
 * cannot repsond to CAN events in the callback directly. We need to
 * transfer these events to an independent thread that does not run
 * in the CAN context while responding to events.
 *
 * @param role		redudant role to set
 */
void di_device_set_board_redundant_role(enum di_device_redundant_roles role);

/**
 * Get board role in the redundant setup
 * only called by the application, never by the CAN stack itself
 */
enum di_device_redundant_roles di_device_get_board_redundant_role(void);

/**
 * Check board role in the redundant setup
 * only called by the application, never by the CAN stack itself
 *
 * @param role		redudant role to check
 */
bool di_device_board_has_redundant_role(enum di_device_redundant_roles role);

#ifdef __cplusplus
}
#endif

#endif /* LIBDI_INCLUDE_DEVICE_H_ */