power_meter.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * power_meter.h
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 #if !defined(_POWER_METER_H_)
00027 #define _POWER_METER_H_
00028 
00029 /*! \page power_meter_page Power metering
00030 
00031 \section power_meter_page_sec_1 What does it do?
00032 The power metering module implements a simple IIR type running power meter. The damping
00033 factor of the IIR is selectable when the meter instance is created.
00034 
00035 Note that the definition of dBOv is quite vague in most places - is it peak since wave,
00036 peak square wave, etc.? This code is based on the well defined wording in RFC3389:
00037 
00038 "For example, in the case of a u-law system, the reference would be a square wave with
00039 values +/-8031, and this square wave represents 0dBov.  This translates into 6.18dBm0".
00040 
00041 \section power_meter_page_sec_2 How does it work?
00042 */
00043 
00044 /*!
00045     Power meter descriptor. This defines the working state for a
00046     single instance of a power measurement device.
00047 */
00048 typedef struct
00049 {
00050     /*! The shift factor, which controls the damping of the power meter. */
00051     int shift;
00052 
00053     /*! The current power reading. */
00054     int32_t reading;
00055 } power_meter_t;
00056 
00057 typedef struct
00058 {
00059     power_meter_t short_term;
00060     power_meter_t medium_term;
00061     int signal_present;
00062     int32_t surge;
00063     int32_t sag;
00064     int32_t min;
00065 } power_surge_detector_state_t;
00066 
00067 #if defined(__cplusplus)
00068 extern "C"
00069 {
00070 #endif
00071 
00072 /*! Initialise a power meter context.
00073     \brief Initialise a power meter context.
00074     \param s The power meter context.
00075     \param shift The shift to be used by the IIR filter.
00076     \return The power meter context. */
00077 SPAN_DECLARE(power_meter_t *) power_meter_init(power_meter_t *s, int shift);
00078 
00079 SPAN_DECLARE(int) power_meter_release(power_meter_t *s);
00080 
00081 SPAN_DECLARE(int) power_meter_free(power_meter_t *s);
00082 
00083 /*! Change the damping factor of a power meter context.
00084     \brief Change the damping factor of a power meter context.
00085     \param s The power meter context.
00086     \param shift The new shift to be used by the IIR filter.
00087     \return The power meter context. */
00088 SPAN_DECLARE(power_meter_t *) power_meter_damping(power_meter_t *s, int shift);
00089 
00090 /*! Update a power meter.
00091     \brief Update a power meter.
00092     \param s The power meter context.
00093     \param amp The amplitude of the new audio sample.
00094     \return The current power meter reading. */
00095 SPAN_DECLARE(int32_t) power_meter_update(power_meter_t *s, int16_t amp);
00096 
00097 /*! Get the current power meter reading.
00098     \brief Get the current power meter reading.
00099     \param s The power meter context.
00100     \return The current power meter reading. */
00101 SPAN_DECLARE(int32_t) power_meter_current(power_meter_t *s);
00102 
00103 /*! Get the current power meter reading, in dBm0.
00104     \brief Get the current power meter reading, in dBm0.
00105     \param s The power meter context.
00106     \return The current power meter reading, in dBm0. */
00107 SPAN_DECLARE(float) power_meter_current_dbm0(power_meter_t *s);
00108 
00109 /*! Get the current power meter reading, in dBOv.
00110     \brief Get the current power meter reading, in dBOv.
00111     \param s The power meter context.
00112     \return The current power meter reading, in dBOv. */
00113 SPAN_DECLARE(float) power_meter_current_dbov(power_meter_t *s);
00114 
00115 /*! Get the power meter reading which represents a specified power level in dBm0.
00116     \brief Get the current power meter reading, in dBm0.
00117     \param level A power level, in dB0m.
00118     \return The equivalent power meter reading. */
00119 SPAN_DECLARE(int32_t) power_meter_level_dbm0(float level);
00120 
00121 /*! Get the power meter reading which represents a specified power level in dBOv.
00122     \brief Get the current power meter reading, in dBOv.
00123     \param level A power level, in dBOv.
00124     \return The equivalent power meter reading. */
00125 SPAN_DECLARE(int32_t) power_meter_level_dbov(float level);
00126 
00127 SPAN_DECLARE(int32_t) power_surge_detector(power_surge_detector_state_t *s, int16_t amp);
00128 
00129 /*! Get the current surge detector short term meter reading, in dBm0.
00130     \brief Get the current surge detector meter reading, in dBm0.
00131     \param s The power surge detector context.
00132     \return The current power surge detector power reading, in dBm0. */
00133 SPAN_DECLARE(float) power_surge_detector_current_dbm0(power_surge_detector_state_t *s);
00134 
00135 /*! Get the current surge detector short term meter reading, in dBOv.
00136     \brief Get the current surge detector meter reading, in dBOv.
00137     \param s The power surge detector context.
00138     \return The current power surge detector power reading, in dBOv. */
00139 SPAN_DECLARE(float) power_surge_detector_current_dbov(power_surge_detector_state_t *s);
00140 
00141 SPAN_DECLARE(power_surge_detector_state_t *) power_surge_detector_init(power_surge_detector_state_t *s, float min, float surge);
00142 
00143 SPAN_DECLARE(int) power_surge_detector_release(power_surge_detector_state_t *s);
00144 
00145 SPAN_DECLARE(int) power_surge_detector_free(power_surge_detector_state_t *s);
00146 
00147 #if defined(__cplusplus)
00148 }
00149 #endif
00150 
00151 #endif
00152 /*- End of file ------------------------------------------------------------*/

Generated on Thu Oct 18 15:28:01 2012 for spandsp by  doxygen 1.4.7