spandsp 3.0.0
power_meter.h
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * power_meter.h
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2003 Steve Underwood
9 *
10 * All rights reserved.
11 *
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Lesser General Public License version 2.1,
14 * as published by the Free Software Foundation.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this program; if not, write to the Free Software
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 */
25
26#if !defined(_SPANDSP_POWER_METER_H_)
27#define _SPANDSP_POWER_METER_H_
28
29/*! \page power_meter_page Power metering
30
31\section power_meter_page_sec_1 What does it do?
32The power metering module implements a simple IIR type running power meter. The damping
33factor of the IIR is selectable when the meter instance is created.
34
35Note that the definition of dBOv is quite vague in most places - is it peak since wave,
36peak square wave, etc.? This code is based on the well defined wording in RFC3389:
37
38"For example, in the case of a u-law system, the reference would be a square wave with
39values +/-8031, and this square wave represents 0dBov. This translates into 6.18dBm0".
40
41\section power_meter_page_sec_2 How does it work?
42*/
43
44/*!
45 Power meter descriptor. This defines the working state for a
46 single instance of a power measurement device.
47*/
48typedef struct power_meter_s power_meter_t;
49
50typedef struct power_surge_detector_state_s power_surge_detector_state_t;
51
52#if defined(__cplusplus)
53extern "C"
54{
55#endif
56
57/*! Initialise a power meter context.
58 \brief Initialise a power meter context.
59 \param s The power meter context.
60 \param shift The shift to be used by the IIR filter.
61 \return The power meter context. */
62SPAN_DECLARE(power_meter_t *) power_meter_init(power_meter_t *s, int shift);
63
64SPAN_DECLARE(int) power_meter_release(power_meter_t *s);
65
66SPAN_DECLARE(int) power_meter_free(power_meter_t *s);
67
68/*! Change the damping factor of a power meter context.
69 \brief Change the damping factor of a power meter context.
70 \param s The power meter context.
71 \param shift The new shift to be used by the IIR filter.
72 \return The power meter context. */
73SPAN_DECLARE(power_meter_t *) power_meter_damping(power_meter_t *s, int shift);
74
75/*! Update a power meter with a signal sample.
76 \brief Update a power meter.
77 \param s The power meter context.
78 \param amp The amplitude of the new audio sample.
79 \return The current power meter reading. */
80SPAN_DECLARE(int32_t) power_meter_update(power_meter_t *s, int16_t amp);
81
82/*! Update a power meter with a block of samples.
83 \brief Update a power meter.
84 \param s The power meter context.
85 \param amp The amplitude of the new audio sample.
86 \param len The number of samples
87 \return The current power meter reading. */
88SPAN_DECLARE(int32_t) power_meter_rx(power_meter_t *s, int16_t amp[], int len);
89
90/*! Get the current power meter reading.
91 \brief Get the current power meter reading.
92 \param s The power meter context.
93 \return The current power meter reading. */
94SPAN_DECLARE(int32_t) power_meter_current(power_meter_t *s);
95
96/*! Get the current power meter reading, in dBm0.
97 \brief Get the current power meter reading, in dBm0.
98 \param s The power meter context.
99 \return The current power meter reading, in dBm0. */
100SPAN_DECLARE(float) power_meter_current_dbm0(power_meter_t *s);
101
102/*! Get the current power meter reading, in dBOv.
103 \brief Get the current power meter reading, in dBOv.
104 \param s The power meter context.
105 \return The current power meter reading, in dBOv. */
106SPAN_DECLARE(float) power_meter_current_dbov(power_meter_t *s);
107
108/*! Get the power meter reading which represents a specified power level in dBm0.
109 \brief Get the current power meter reading, in dBm0.
110 \param level A power level, in dB0m.
111 \return The equivalent power meter reading. */
112SPAN_DECLARE(int32_t) power_meter_level_dbm0(float level);
113
114/*! Get the power meter reading which represents a specified power level in dBOv.
115 \brief Get the current power meter reading, in dBOv.
116 \param level A power level, in dBOv.
117 \return The equivalent power meter reading. */
118SPAN_DECLARE(int32_t) power_meter_level_dbov(float level);
119
120SPAN_DECLARE(int32_t) power_surge_detector(power_surge_detector_state_t *s, int16_t amp);
121
122/*! Get the current surge detector short term meter reading, in dBm0.
123 \brief Get the current surge detector meter reading, in dBm0.
124 \param s The power surge detector context.
125 \return The current power surge detector power reading, in dBm0. */
126SPAN_DECLARE(float) power_surge_detector_current_dbm0(power_surge_detector_state_t *s);
127
128/*! Get the current surge detector short term meter reading, in dBOv.
129 \brief Get the current surge detector meter reading, in dBOv.
130 \param s The power surge detector context.
131 \return The current power surge detector power reading, in dBOv. */
132SPAN_DECLARE(float) power_surge_detector_current_dbov(power_surge_detector_state_t *s);
133
134SPAN_DECLARE(power_surge_detector_state_t *) power_surge_detector_init(power_surge_detector_state_t *s, float min, float surge);
135
136SPAN_DECLARE(int) power_surge_detector_release(power_surge_detector_state_t *s);
137
138SPAN_DECLARE(int) power_surge_detector_free(power_surge_detector_state_t *s);
139
140#if defined(__cplusplus)
141}
142#endif
143
144#endif
145/*- End of file ------------------------------------------------------------*/
int32_t power_meter_current(power_meter_t *s)
Get the current power meter reading.
Definition power_meter.c:108
int32_t power_meter_level_dbm0(float level)
Get the current power meter reading, in dBm0.
Definition power_meter.c:82
int32_t power_meter_level_dbov(float level)
Get the current power meter reading, in dBOv.
Definition power_meter.c:95
int32_t power_meter_update(power_meter_t *s, int16_t amp)
Update a power meter.
Definition power_meter.c:65
float power_surge_detector_current_dbm0(power_surge_detector_state_t *s)
Get the current surge detector meter reading, in dBm0.
Definition power_meter.c:195
float power_surge_detector_current_dbov(power_surge_detector_state_t *s)
Get the current surge detector meter reading, in dBOv.
Definition power_meter.c:201
power_meter_t * power_meter_init(power_meter_t *s, int shift)
Initialise a power meter context.
Definition power_meter.c:132
float power_meter_current_dbm0(power_meter_t *s)
Get the current power meter reading, in dBm0.
Definition power_meter.c:114
float power_meter_current_dbov(power_meter_t *s)
Get the current power meter reading, in dBOv.
Definition power_meter.c:124
int32_t power_meter_rx(power_meter_t *s, int16_t amp[], int len)
Update a power meter.
Definition power_meter.c:72
power_meter_t * power_meter_damping(power_meter_t *s, int shift)
Change the damping factor of a power meter context.
Definition power_meter.c:58
Definition private/power_meter.h:34
Definition private/power_meter.h:43