adc0.h

Go to the documentation of this file.

#ifndef DRIVER_ADC0_H
#define DRIVER_ADC0_H
/**********************************************************************/
/*
 * Copyright (c) 2013-2015, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * \brief Driver for ADC scheduling and integration.
 *
 * \author KLO, Jetro AS
 */ /******************************************************************/

#include <stdint.h>
#include <stdbool.h>
#include <core/clk.h>
#include <hal/nrf_saadc.h>

/**
 * \defgroup ADC nRF52 ADC driver
 * \ingroup nrf52
 * \{
 *
 * This ADC driver can be used for ADC0.
 *
 * All ADC channels must be initialized before the ADC driver may be used.
 * An ADC channel can be configured to have an analog mux (1-64 mux inputs).
 * If an ADC channel has an analog multiplexer, the MUX control lines must be
 * controlled by the same IO port with consecutive port pins.
 * For each configured ADC input, individually voltage reference etc. can be set.
 * Individual buffers must be allocated.
 *
 * It is possible to just start a single AD convertion.
 * It is also possible that each configured ADC input can be started
 * with its own scanning scheduler. Scanning interval is is set with resolution
 * 1/1.024 ms and is based on the mwork scheduler.
 * If multiple configured ADC channels should have the same starting time
 * in the scheduler even though they are started sequentially, they can be
 * started based on a common read time reference.
 * If the Interval parameter is set to zero/0, the application may call the Adc0ManualScheduler()
 * function and do the scheduler timing itself. This manual scheduler will use the same
 * Buffer and IntegratedValue as the automatic mwork scheduler.
 *
 * If the configured ADC input has mux, the allocated buffer will be shared
 * linearly for all the mux inputs.
 * While AD convertion is in progress, or while the scheduler is doing
 * AD convertions, the clock is locked and energy mode EM1 is minimum required.
 */

/***********************************************************************
 * Global defines
***********************************************************************/
/**
 * adc_state_t structure holds pointers to buffers and variables used by the ADC driver.
 * IntegratedValue, VoltageMuxBuffer and Size must be initialized before
 * the PWM driver may be used.
 *
 */
struct adc_state_t
{
  uint32_t *IntegratedValue;  // The scheduler will use this location for storing the integrated value
  uint16_t *Buffer;           // Pointer to buffer area per ADC channel used by the scheduler
  uint32_t TimeRef;           // Used by scheduler for next time to schedule current channel
  uint16_t Size;              // Sizeof Buffer used for data stored by scheduler
  uint16_t Index;             // Used by scheduler to index Buffer.
  uint16_t Count;             // Contains the number of bytes stored within Buffer.
};

/**
 * adc_streamer_state_t structure holds state of the ADC streamer
 */

struct adc_streamer_state_t
{
  uint8_t SampleBufIndex;               /**< Index of the active sampling buffer */
};

struct adc_streamer_t;

/**
 * adc_cb_parameter_t enum holds parameter used by the ADC driver callback function.
 *
 */
enum adc_cb_parameter_t
{
  ADC_MEASURE_NETWORK_OFF,
  ADC_MEASURE_NETWORK_ON
};

/**
 * adc_callback_t Prototype ADC driver callback function.
 *
 */
typedef void (* adc_callback_t)(enum adc_cb_parameter_t AdcCbParameter);

/**
 * adc_streamer_callback_t Prototype ADC driver callback function.
 *
 */
typedef void (* adc_streamer_callback_t)(const struct adc_streamer_t *Adc, uint8_t SampleBufIndex);

/**
 * adc_mux_config_t structure is used for configuration of the ADC multiplexor.
 * The structure must be initialized before the ADC driver may be used.
 *
 */
struct adc_mux_config_t
{
  uint32_t NumberOfChannels : 7;        /**< 0 if no mux, else number of mux inputs (1-64) */
  uint32_t AddressPinCount : 3;         /**< Number of pins used for mux addresses */
  uint32_t FirstChannel : 6;            /**< First mux channel (0 - 63) */
  uint32_t AddressPinLsb : 5;           /**< Pin for LSB mux address lines - must be continuously */
};

/**
 * adc_analog_config_t structure is used for configuration of the analog part of the AD conversion
 * The structure must be initialized before the ADC driver may be used.
 *
 */
struct adc_analog_config_t
{
  int16_t  LowLimit;                    /**< Low limit */
  int16_t  HighLimit;                   /**< High limit */
  uint32_t InputP : 4;                  /**< nrf_saadc_input_t */
  uint32_t ResistorP : 2;               /**< nrf_saadc_resistor_t */
  uint32_t InputN : 4;                  /**< nrf_saadc_input_t */
  uint32_t ResistorN : 2;               /**< nrf_saadc_resistor_t */
  uint32_t Gain : 3;                    /**< nrf_saadc_gain_t */
  uint32_t Reference : 1;               /**< nrf_saadc_reference_t */
  uint32_t AcquistionTime : 3;          /**< nrf_saadc_acqtime_t */
};

/**
 * adc_digital_config_t structure is used for configuration of the digital part of the AD conversion
 * The structure must be initialized before the ADC driver may be used.
 *
 */
struct adc_digital_config_t
{
  uint32_t Resolution : 2;              /**< nrf_saadc_resolution_t */
  uint32_t Oversampling : 4;            /**< nrf_saadc_oversample_t */
};

/**
 * adc_channel_t structure is used for configuration one ADC channel.
 * The channel can be configured to have an analog mux.
 * The structure must be initialized before the ADC driver may be used.
 *
 */
struct adc_channel_t
{
  struct adc_state_t *State;
  struct adc_analog_config_t AnalogConfig; /**< Configuration of the analog part of the ADC */
  struct adc_digital_config_t DigitalConfig; /**< Configuration of the digital part of the ADC */
  struct adc_mux_config_t MuxConfig;    /**< Multiplexor configuration */
  uint32_t Interval;                    /**< 1/1.024 ms resolution */
  adc_callback_t Callback;              /**< Callback function pointer for external power-up of ADC channel */
  uint32_t uDelay;                      /**< Delay in usec to wait after callback for power-on*/
};


/**
 * adc_streamer_t structure is used for configuration of an ADC streamer.
 * The structure must be initialized before the ADC streamer may be used.
 *
 */
struct adc_streamer_t
{
  struct adc_streamer_state_t *State;
  struct adc_analog_config_t AnalogConfig; /**< Configuration of the analog part of the ADC */
  struct adc_digital_config_t DigitalConfig; /**< Configuration of the digital part of the ADC */
  uint32_t SampleRate;                  /**< Sample rate in samples / sec, 0 for external trigger. */
  adc_streamer_callback_t Callback;     /**< The callback is called when a buffer is filled */
  void *SampleBuffer[2];                /**< Sample buffer */
  uint16_t SampleBufferSize;            /**< Size of a single buffer of the double buffer */
  uint8_t InterruptPriority;            /**< NRF_APP_PRIORITIES */
  uint8_t PpiChannel;                   /**< PPI channel, internally used by the streamer */
  bool OversamlingInBurstMode;          /**< true if oversampling is done in bursts */
};

/**
 * adc_schedule_t structure holds parameter used by the ADC scheduler.
 *
 */
struct adc_schedule_t
{
  struct adc_channel_t const **Table;
  uint16_t NumberOfChannels;
};

 /**
  * @name Functions called from application programs
  * @{
  */

/**********************************************************************/
/**
 * @brief Name:       Adc0Init\n
 * Initializes pointers used by ADC scheduler.
 * Called from main program level.
 *
 * @param AdcSchedule Pointer to ADC scheduler table in application layer.
 ***********************************************************************/
extern void Adc0Init(const struct adc_schedule_t *AdcSchedule);

/**********************************************************************/
/**
 * @brief Name:     Adc0ChannelConfig\n
 * Configures an analog channel in scan mode.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @param Index     Scan index. 0 for the main channel, > 0 enables scan and
 *                  correspondes to the particular scan slot.
 * @param Config    Analog channel configuration
 ***********************************************************************/
extern bool Adc0ChannelConfig(const struct adc_channel_t *Adc, int Index, const struct adc_analog_config_t *Config);

/**********************************************************************/
/**
 * @brief Name:     Adc0ChannelStart\n
 * Starts one ADC channel scheduler based on input parameters.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @param TimeRef   Time reference tick got from clock_time() function
 * @return          true if the ADC input was successfully started, otherwise false
 ***********************************************************************/
extern bool Adc0ChannelStart(const struct adc_channel_t *Adc, uint32_t TimeRef);

/**********************************************************************/
/**
 * @brief Name:     Adc0ManualScheduler\n
 * Called by application for manual data scheduling.
 *
 * @param Adc       Configuration structure for ADC input to be used
 ***********************************************************************/
extern void Adc0ManualScheduler(const struct adc_channel_t *Adc);

/**********************************************************************/
/**
 * @brief Name:     Adc0ChannelDisable\n
 * Disables one ADC channel scheduler based on input parameters.
 * When all channels are disabled, the scheduler is stopped.
 *
 * @param Adc       Configuration structure for ADC input to be used
 ***********************************************************************/
extern void Adc0ChannelDisable(const struct adc_channel_t *Adc);

/**********************************************************************/
/**
 * @brief Name:     Adc0ChannelDisableAll\n
 * Disables all ADC channel schedulers and stops the scheduler.
 ***********************************************************************/
extern void Adc0ChannelDisableAll(void);

/**********************************************************************/
/**
 * @brief Name:     Adc0GetMuxValue\n
 * Starts ADC for selected ADC channel and mux input.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @param MuxChannel
 * @return          Converted ADC value for selected channel and mux input
 ***********************************************************************/
extern uint16_t Adc0GetMuxValue(const struct adc_channel_t *Adc, uint8_t MuxChannel);

/**********************************************************************/
/**
 * @brief Name:     Adc0GetValue\n
 * Starts ADC for selected ADC channel.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @return          Converted ADC value for selected channel
 ***********************************************************************/
static inline uint16_t Adc0GetValue(const struct adc_channel_t *Adc)
{
  return Adc0GetMuxValue(Adc, 0);
}

/**********************************************************************/
/**
 * @brief Name:     Adc0GetLastMuxValue
 * Returns last converted ADC value for selected ADC channel and mux input.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @param MuxChannel
 * @return          Last converted ADC value for selected ADC channel and mux input
 ***********************************************************************/
extern uint16_t Adc0GetLastMuxValue(const struct adc_channel_t *Adc, uint8_t MuxChannel);

/**********************************************************************/
/**
 * @brief Name:     Adc0GetLastValue
 * Returns last converted ADC value for selected ADC channel.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @return          Last converted ADC value for selected ADC channel
 ***********************************************************************/
static inline uint16_t Adc0GetLastValue(const struct adc_channel_t *Adc)
{
  return Adc0GetLastMuxValue(Adc, 0);
}

/**********************************************************************/
/**
 * @brief Name:     Adc0GetIntegratedMuxValue
 * Returns integrated ADC value for selected ADC channel and mux input.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @param MuxChannel
 * @param Count     Number of samples in the integrated value is returned in Count
 * @return          Integrated ADC value for selected channel and mux input
 ***********************************************************************/
extern uint32_t Adc0GetIntegratedMuxValue(const struct adc_channel_t *Adc, uint8_t MuxChannel, uint16_t *Count);

/**********************************************************************/
/**
 * @brief Name:     Adc0GetIntegratedValue
 * Returns integrated ADC value for selected ADC channel.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @param Count     Number of samples in the integrated value is returned in Count
 * @return          Integrated ADC value for selected channel
 ***********************************************************************/
static inline uint32_t Adc0GetIntegratedValue(const struct adc_channel_t *Adc, uint16_t *Count)
{
  return Adc0GetIntegratedMuxValue(Adc, 0, Count);
}

/**********************************************************************/
/**
 * @brief Name:     Adc0GetMeanMuxValue
 * Returns mean ADC value for selected ADC channel and mux input.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @param MuxChannel
 * @return          Mean ADC value for selected channel and mux input
 ***********************************************************************/
extern uint16_t Adc0GetMeanMuxValue(const struct adc_channel_t *Adc, uint8_t MuxChannel);

/**********************************************************************/
/**
 * @brief Name:     Adc0GetMeanValue
 * Returns mean ADC value for selected ADC channel.
 *
 * @param Adc       Configuration structure for ADC input to be used
 * @return          Mean ADC value for selected channel
 ***********************************************************************/
static inline uint16_t Adc0GetMeanValue(const struct adc_channel_t *Adc)
{
  return Adc0GetMeanMuxValue(Adc, 0);
}

/**********************************************************************/
/**
 * @brief Name:     Adc0StreamerStart\n
 * Starts continous sampling and streaming of data.
 *
 * @param Adc       Configuration structure for the streamer
 * @return          true if the streamer was started, false otherwise
 ***********************************************************************/
extern bool Adc0StreamerStart(const struct adc_streamer_t *Adc);

/**********************************************************************/
/**
 * @brief Name:     Adc0StreamerDisable\n
 * Stops continous sampling and streaming of data.
 *
 * @param Adc       Configuration structure for the streamer
 ***********************************************************************/
extern void Adc0StreamerDisable(const struct adc_streamer_t *Adc);

/** @} */

/** \} ADC */

#endif //DRIVER_ADC0_H