/**
 * @file liboasis-usb-att.h
 *
 * @brief OASIS USB Attenuator driver library interface
 *
 * This file describes the external interface to the OASIS USB Attenuator
 * driver and provides the definitios for proper communication
 * with the device
 *
 * Copyright (c) 2018 CERN
 * @author Tomasz Włostowski <tomasz.wlostowski@cern.ch>
 *
 * @section license_sec License
 * Released under the GPL v2. (and only v2, not any later version)
 */


#ifndef __LIBOASIS_USB_ATT_H
#define __LIBOASIS_USB_ATT_H

#ifdef __cplusplus
extern "C" {
#endif

/** 
 * @enum oau_att_value_enum
 * @brief Valid relay values
 *
 */
enum oau_att_value_enum {
	ATT_ERR	=	-1,	/**< Error */
	ATT_NONE = 	0x0,	/**< No attenuation */
	ATT_1 = 	0x01,	/**< Attenuator 1: 20dB */
	ATT_2 = 	0x03,	/**< Attenuator 1+2: 40dB */
};

/**
 * @brief Open a msatt device
 *
 * A board is selected by lun, and a handle is returned for further
 * reference to it.
 *
 * @param serial - serial number of USB attenuator
 *
 * @return >0 - on success, device file descriptor number
 */
int oau_att_open(char *serial);

/**
 * @brief close a channel handle
 *
 * @param fd  Handle to close
 */
int oau_att_close(int fd);

/**
 * @brief Get attenuation value for a given channel
 * 
 * Each channel can be on one of these states: 
 * 		- No attenuation active (Relay value = 0x0)
 *		- 20dB attenuation 	(Relay value = 0x1)
 * 		- 40dB attenuation	(Relay value = 0x3)
 *
 * @param fd 		Device handle identifying board
 * @param channel 	Channel [1,2,3,4] on the board to read from
 * 
 * @return ATT_ERR on failure, another oau_att_value_enum value on success
 */
enum oau_att_value_enum oau_att_get_relay(int fd, int channel);

/**
 * @brief Set attenuation value for a given channel
 * 
 * @param fd		Device handle identifying board
 * @param channel 	Channel on the board [1,2,3,4] 
 * @param val 		Valid oau_att_value_enum relay value
 * 
 * @return Upon successful completion, returns a value other than -1. On failure it returns -1
 */
int oau_att_set_relay(int fd, int channel, enum oau_att_value_enum val);

/**
 * @brief Gets the number of channels (2 or 4)
 * 
 * @param fd		Device handle identifying board
 * 
 * @return -1 on fail, 2 for MSATTN2 and 4 for MSATTN4
 */
int oau_att_get_nchannels(int fd);

/* libmsatt version string */
extern const char * const liboau_att_version_s;
#ifdef __cplusplus
}
#endif


#endif /* __LIBOASIS_USB_ATT_H */
