// Copyright (c) Acconeer AB, 2018-2022
// All rights reserved

#ifndef ACC_SERVICE_H_
#define ACC_SERVICE_H_

#include <stdbool.h>

#include "acc_base_configuration.h"
#include "acc_definitions_a111.h"
#include "acc_definitions_common.h"

/**
 * @defgroup Services Services
 *
 * @brief Radar services provided by Acconeer
 *
 * @defgroup Experimental Experimental
 * @brief Features in an early version
 *
 *          In our code you might encounter features tagged “Experimental”.
 *          This means that the feature in question is an early version that has a
 *          limited test scope, and the API and/or functionality might change in
 *          upcoming releases.
 *
 *          The intention is to let users try these features out and we appreciate
 *          feedback.
 *
 * @defgroup Generic Generic Service API
 * @ingroup Services
 *
 * @brief Generic service API description
 *
 * @{
 */


/**
 * @brief Generic service configuration container
 */
struct acc_service_configuration;

typedef struct acc_service_configuration *acc_service_configuration_t;


/**
 * @brief Generic service handle
 */
struct acc_service_handle;

typedef struct acc_service_handle *acc_service_handle_t;


/**
 * @brief Create a service with the provided configuration
 *
 * Only one service may exist for a specific sensor at any given time,
 * unless @ref acc_rss_override_sensor_id_check_at_creation has been invoked.
 * Invalid configurations will not allow for service creation.
 *
 * @param[in] configuration The service configuration to create a service with
 * @return Service handle, NULL if service was not possible to create
 */
acc_service_handle_t acc_service_create(acc_service_configuration_t configuration);


/**
 * @brief Activate the service associated with the provided handle
 *
 * When activated, the application can get data from the service with the
 * associated handle.
 *
 * @param[in] service_handle The service handle for the service to activate
 * @return True if successful, false otherwise
 */
bool acc_service_activate(acc_service_handle_t service_handle);


/**
 * @brief Deactivate the service associated with the provided handle
 *
 * @param[in] service_handle The service handle for the service to deactivate
 * @return True if successful, false otherwise
 */
bool acc_service_deactivate(acc_service_handle_t service_handle);


/**
 * @brief Destroy a service identified with the provided service handle
 *
 * Destroy the context of a service allowing another service to be created using the
 * same resources. The service handle reference is set to NULL after destruction.
 *
 * @param[in] service_handle A reference to the service handle to destroy
 */
void acc_service_destroy(acc_service_handle_t *service_handle);


/**
 * @brief Retrieve a base configuration from a service configuration
 *
 * The base configuration can be used to configure the service for different use cases.
 * See @ref acc_base_configuration.h for configuration parameters.
 *
 * @param[in] service_configuration The service configuration to get a base configuration from
 * @return Base configuration, NULL if the service configuration does not contain a base configuration
 */
acc_base_configuration_t acc_service_get_base_configuration(acc_service_configuration_t service_configuration);


/**
 * @brief Get the sensor ID for the sensor to be configured
 *
 * @param[in] configuration The service configuration to get the sensor id from
 * @return Sensor Id
 */
acc_sensor_id_t acc_service_sensor_get(acc_service_configuration_t configuration);


/**
 * @brief Set the sensor ID for the sensor to be configured
 *
 * @param[in] configuration The service configuration to set the sensor id in
 * @param[in] sensor_id The sensor id to set
 */
void acc_service_sensor_set(acc_service_configuration_t configuration, acc_sensor_id_t sensor_id);


/**
 * @brief Get the requested start of the sweep
 *
 * @param[in] configuration The service configuration to get the requested start from
 * @return Requested start
 */
float acc_service_requested_start_get(acc_service_configuration_t configuration);


/**
 * @brief Set the requested start of the sweep
 *
 * @param[in] configuration The service configuration to set the requested start in
 * @param[in] start_m The requested start in meters
 */
void acc_service_requested_start_set(acc_service_configuration_t configuration, float start_m);


/**
 * @brief Get the requested length of the sweep
 *
 * @param[in] configuration The service configuration to get the requested length from
 * @return Requested length
 */
float acc_service_requested_length_get(acc_service_configuration_t configuration);


/**
 * @brief Set the requested length of the sweep
 *
 * @param[in] configuration The service configuration to set the requested length in
 * @param[in] length_m The requested length in meters
 */
void acc_service_requested_length_set(acc_service_configuration_t configuration, float length_m);


/**
 * @brief Set the service repetition mode to on demand
 *
 * In on demand mode, the sensor produces data when requested by the application.
 * The application is also responsible for the timing between updates.
 *
 * This mode must be used if the configured length requires stitching in the service.
 *
 * @param[in] configuration The service configuration to set on demand mode in
 */
void acc_service_repetition_mode_on_demand_set(acc_service_configuration_t configuration);


/**
 * @brief Set the service repetition mode to streaming mode
 *
 * The sensor produces data according to the configured update rate using sensor
 * hardware timing which is very accurate.
 *
 * @param[in] configuration The service configuration to set streaming mode in
 * @param[in] update_rate The output data rate from the service in hertz
 */
void acc_service_repetition_mode_streaming_set(acc_service_configuration_t configuration, float update_rate);


/**
 * @brief Get power save mode
 *
 * The power save modes of the sensor correspond to how much of the sensor hardware is shutdown
 * between data frame aquisition. The supported power save modes are defined in
 * @ref acc_power_save_mode_enum_t.
 *
 * @param[in] configuration The service configuration to get power save mode for
 * @return Power save mode
 */
acc_power_save_mode_t acc_service_power_save_mode_get(acc_service_configuration_t configuration);


/**
 * @brief Set power save mode
 *
 * The power save modes of the sensor correspond to how much of the sensor hardware is shutdown
 * between data frame aquisition. The supported power save modes are defined in
 * @ref acc_power_save_mode_enum_t.
 *
 * @param[in] configuration The service configuration to set power save mode in
 * @param[in] power_save_mode The power save mode to use
 */
void acc_service_power_save_mode_set(acc_service_configuration_t configuration,
                                     acc_power_save_mode_t       power_save_mode);


/**
 * @brief Get receiver gain setting
 *
 * Will be a value between 0.0 and 1.0, where 0.0 is the lowest gain and 1.0 is the highest gain.
 *
 * @param[in] configuration The service configuration to get receiver gain setting for
 * @return Receiver gain setting
 */
float acc_service_receiver_gain_get(acc_service_configuration_t configuration);


/**
 * @brief Set receiver gain setting
 *
 * Must be a value between 0.0 and 1.0, where 0.0 is the lowest gain and 1.0 is the highest gain.
 *
 * @param[in] configuration The service configuration to set receiver gain setting in
 * @param[in] gain Receiver gain setting, must be between 0.0 and 1.0
 */
void acc_service_receiver_gain_set(acc_service_configuration_t configuration, float gain);


/**
 * @brief Get TX disable mode
 *
 * Will be true if TX is disabled, false otherwise.
 *
 * @param[in] configuration The service configuration to get TX disable mode for
 * @return TX disable mode
 */
bool acc_service_tx_disable_get(acc_service_configuration_t configuration);


/**
 * @brief Set TX disable mode
 *
 * If set to true, TX disable mode is enabled. This will disable the radio transmitter.
 * To measure RX noise floor, it is recommended to also switch off internal
 * noise level normalization (see each service if applicable).
 *
 * @param[in] configuration The service configuration to set TX disable mode in
 * @param[in] tx_disable TX disable mode, true or false
 */
void acc_service_tx_disable_set(acc_service_configuration_t configuration, bool tx_disable);


/**
 * @brief Get the hardware accelerated average samples (HWAAS)
 *
 * Each data point can be sampled between 1 and 63 times, inclusive, and the sensor hardware then
 * produces an average value of those samples. The time needed to measure a sweep is roughly proportional
 * to the number of averaged samples. Hence, if there is a need to obtain a higher update rate, HWAAS
 * could be decreased but this leads to lower SNR.
 *
 * @param[in] configuration The service configuration to get hardware accelerated average samples from
 * @return Hardware accelerated average samples
 */
uint8_t acc_service_hw_accelerated_average_samples_get(acc_service_configuration_t configuration);


/**
 * @brief Set the hardware accelerated average samples (HWAAS)
 *
 * Each data point can be sampled between 1 and 63 times, inclusive, and the sensor hardware then
 * produces an average value of those samples. The time needed to measure a sweep is roughly proportional
 * to the number of averaged samples. Hence, if there is a need to obtain a higher update rate, HWAAS
 * could be decreased but this leads to lower SNR.
 *
 * @param[in] configuration The service configuration to set hardware accelerated average samples in
 * @param[in] samples Hardware accelerated average samples
 */
void acc_service_hw_accelerated_average_samples_set(acc_service_configuration_t configuration, uint8_t samples);


/**
 * @brief Get asynchronous measurement mode
 *
 * If set to true, asynchronous measurement is enabled.
 * In synchronous mode the sensor will generate sweep data while the host is waiting.
 * In asynchronous mode the sensor will generate sweep data while the host is working.
 *
 * This means that if in synchronous mode, the sensor will only measure during
 * a get_next call, while in asynchronous mode the sensor can measure outside
 * of the get_next call.
 *
 * Setting asynchronous measurement to false (i.e using synchronous mode) is incompatible
 * with repetition mode streaming where the sensor is in control of the update rate timing.
 *
 * @param[in] configuration The service configuration to get asynchronous_measurement mode from
 * @return asynchronous measurement mode
 */
bool acc_service_asynchronous_measurement_get(acc_service_configuration_t configuration);


/**
 * @brief Set asynchronous measurement mode
 *
 * If set to true, asynchronous measurement is enabled.
 * In synchronous mode the sensor will generate sweep data while the host is waiting.
 * In asynchronous mode the sensor will generate sweep data while the host is working.
 *
 * This means that if in synchronous mode, the sensor will only measure during
 * a get_next call, while in asynchronous mode the sensor can measure outside
 * of the get_next call.
 *
 * Setting asynchronous measurement to false (i.e using synchronous mode) is incompatible
 * with repetition mode streaming where the sensor is in control of the update rate timing.
 *
 * @param[in] configuration The service configuration to set asynchronous_measurement mode in
 * @param[in] asynchronous_measurement asynchronous measurement mode, true or false
 */
void acc_service_asynchronous_measurement_set(acc_service_configuration_t configuration, bool asynchronous_measurement);


/**
 * @brief Get the currently used service profile
 *
 * See @ref acc_service_profile_t for details
 *
 * @param[in] service_configuration The configuration to get a profile for
 * @return The current profile, 0 if configuration is invalid
 */
acc_service_profile_t acc_service_profile_get(acc_service_configuration_t service_configuration);


/**
 * @brief Set a service profile
 *
 * See @ref acc_service_profile_t for details
 *
 * @param[in] service_configuration The configuration to set a profile for
 * @param[in] profile                The profile to set
 */
void acc_service_profile_set(acc_service_configuration_t service_configuration,
                             acc_service_profile_t       profile);


/**
 * @brief Get Maximize signal attenuation mode
 *
 * Will be true if Maximize signal attenuation mode is enabled, false otherwise
 *
 * @param[in] service_configuration The configuration to get Maximize signal attenuation mode for
 * @return Maximize signal attenuation mode
 */
bool acc_service_maximize_signal_attenuation_get(acc_service_configuration_t service_configuration);


/**
 * @brief Set Maximize signal attenuation mode
 *
 * Enable or disable Maximize signal attenuation mode to measure the direct leakage
 *
 * @param[in] service_configuration        The configuration to set Maximize signal attenuation mode in
 * @param[in] maximize_signal_attenuation  Maximize signal attenuation mode, true or false
 */
void acc_service_maximize_signal_attenuation_set(acc_service_configuration_t service_configuration,
                                                 bool                        maximize_signal_attenuation);


/**
 * @brief Set the maximum unambiguous range
 *
 * Sets the maximum unambiguous range (MUR), which in turn sets the maximum measurable
 * distance (MMD).
 *
 * The MMD is the maximum value for the range end, i.e., the range start + length. The MMD
 * is smaller than the MUR due to hardware limitations.
 *
 * The MUR is the maximum distance at which an object can be located to guarantee that its
 * reflection corresponds to the most recent transmitted pulse. Objects farther away than
 * the MUR may fold into the measured range. For example, with a MUR of 10 m, an object at
 * 12 m could become visible at 2 m.
 *
 * A higher setting gives a larger MUR/MMD, but comes at a cost of increasing the
 * measurement time for a sweep. The measurement time is approximately proportional to the
 * MUR.
 *
 * This setting changes the pulse repetition frequency (PRF) of the radar system. The
 * relation between PRF and MUR is
 * MUR = c / (2 * PRF)
 * where c is the speed of light.
 *
 * | Setting           |    MUR |    MMD |      PRF |
 * |------------------:|-------:|-------:|---------:|
 * | ACC_SERVICE_MUR_6 | 11.5 m |  7.0 m | 13.0 MHz |
 * | ACC_SERVICE_MUR_9 | 17.3 m | 12.7 m |  8.7 MHz |
 *
 * It is not possible to change MUR for the IQ service.
 *
 * @param[in] service_configuration The configuration
 * @param[in] max_unambiguous_range The desired maximum unambiguous range
 */
void acc_service_mur_set(acc_service_configuration_t service_configuration,
                         acc_service_mur_t           max_unambiguous_range);


/**
 * @brief Get the maximum unambiguous range
 *
 * This gets the maximum unambiguous range. For more information see acc_service_mur_set().
 *
 * @param[in] service_configuration The configuration
 * @return Maximum unambiguous range
 */
acc_service_mur_t acc_service_mur_get(acc_service_configuration_t service_configuration);


/**
 * @}
 */

#endif