new_super_rx/super_tone_rx.h

/*
 * SpanDSP - a series of DSP components for telephony
 *
 * super_tone_rx.h - Flexible telephony supervisory tone detection.
 *
 * Written by Steve Underwood <steveu@coppice.org>
 *
 * Copyright (C) 2005 Steve Underwood
 *
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2, as
 * published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 * $Id$
 */

#if !defined(_SPANDSP_SUPER_TONE_RX_H_x)
#define _SPANDSP_SUPER_TONE_RX_H_x

/*! \page super_tone_rx_page Supervisory tone detection

\section super_tone_rx_page_sec_1 What does it do?

The supervisory tone detector may be configured to detect most of the world's
telephone supervisory tones - things like ringback, busy, number unobtainable,
and so on.

The detector aims to meet the need of the standard call progress tones, to
ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones,
to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special
ringback tone, intercept tone, call waiting tone, busy verification tone,
executive override tone, confirmation tone).

\section super_tone_rx_page_sec_2 How does it work?

The input signal is complex filtered with a bandpass filter that removes DC and
anything above about 800Hz, and the resulting complex signal is decimated by a
factor of 10. This leaves an alias free band of 0 to 800Hz.

A set of periodgrams are calculated, one for each of the frequencies of interest.
A Hamming window is applied to the coefficients used for this, to clean up the
spectral response. The expected phasor rotation between successive periodogram
results is compared with the actual rotation, to evaluate the deviation of the
signal from the expected frequency. 
??????????

*/

/* The maximum number of frequencies to be monitored */
#define SUPER_TONE_MAX_FREQS            8

/* Bandpass filtering */
#define SUPER_TONE_BP_FIR_LEN           60
#define SUPER_TONE_DECIMATION_FACTOR    10
#define SUPER_TONE_FRAME_LEN            (4*SUPER_TONE_DECIMATION_FACTOR)
#define SUPER_TONE_BP_SLEN              (SUPER_TONE_BP_FIR_LEN - SUPER_TONE_DECIMATION_FACTOR)
#define SUPER_TONE_BP_ALEN              (SUPER_TONE_BP_SLEN + SUPER_TONE_FRAME_LEN)

/* Periodogram analysis */
#define SUPER_TONE_PG_WINDOW            56

/* Energy history period */
#define SUPER_TONE_ENERGY_SIZE          9

/*! Tone detection indication callback routine */
//typedef void (*tone_report_func_t)(void *user_data, int code, int level, int delay);

/* Statistics */
typedef struct
{
    /*! Tone power, in dBm0 */
    float power[2];
    /*! Frequency error, in Hz */
    float freq_error[2];
} supervisory_stats_t;

typedef struct
{
    /*! Minimum surge in signal power for a potential tone onset to be declared, in dB. */
    float onset_power_surge;
    /*! Minimum acceptable level for a tone's power, in dBm0. */
    float min_energy_threshold;
    /*! Maximum permitted variation of a tone's power from its mean level, in dB. */
    float max_energy_variation;
    /*! Maximum permitted normal or reverse twist during the onset phase, in dB. */
    float onset_max_twist;
    /*! Maximum permitted normal or reverse twist, in dB. */
    float max_twist;
    /*! How much energies must be above other components during the onset phase, in dB. */
    float onset_energy_margin;
    /*! How much valid energies must be above other components, in dB. */
    float energy_margin;
    /*! The maximum permissible frequency offset from the target, in Hz. */
    float max_freq_error;
    /*! Length of the onset period, in frames. */
    int onset_frame_count;
    /*! Length of the proving period, in frames. */
    int proving_frame_count;
    /*! Number of low-energy frames before tone off is declared. */
    int tone_off_frame_count;
    /*! Number of inconsistent frames before tone abort is declared */
    int abort_frame_count;
    /*! The number of frequencies to be monitored */
    int frequencies;
    /*! Periodogram coefficient sets */
    complexf_t pg_coeffs[SUPER_TONE_MAX_FREQS][SUPER_TONE_PG_WINDOW/2];
    /*! Periodogram frame to frame phase offset */
    complexf_t pg_phase_offset[SUPER_TONE_MAX_FREQS];
    /*! Periodogram phase offset scaling. */
    float pg_scale;
} supervisory_rx_desc_t;

typedef struct
{
    tone_report_func_t tone_callback;
    void *callback_data;
    /*! The descriptor for the tone detector. */
    const supervisory_rx_desc_t *desc;

    /*! The number of samples in the input signal buffer. */
    int input_signal_len;
    /*! Input signal buffer, used to gather enough for a burst of processing. */
    float input_signal[SUPER_TONE_BP_ALEN];
    /*! The decimated signal. */
    complexf_t decimated[SUPER_TONE_PG_WINDOW];

    /*! The energy level out of the bandpass filter, in dBm0 */
    float bandpass_power_db;

    /*! The periodogram result at each of the frequencies being monitored */
    complexf_t pg_result[SUPER_TONE_MAX_FREQS];
    /*! The power level at each of the frequencies being monitored */
    float power[SUPER_TONE_MAX_FREQS];
    /*! The previous periodogram result at each of the frequencies being monitored */
    complexf_t last_pg_result[SUPER_TONE_MAX_FREQS];
    supervisory_stats_t stats;

    /*! A list of the last few total powers for the 2 main responses */
    float total_tone_power_db_history[SUPER_TONE_ENERGY_SIZE];
    /*! A amoothed version of the total power for the 2 main responses */
    float smoothed_total_tone_power_db;

    /*! The indexes into the monitored frequency list of the two strongest
        responses (lower frequency first) and the third strongest response. */
    int index[3];
    /*! The energy levels of the two strongest responses (lower frequency first)
        and the third strongest response, in dBm0. */
    float power_db[3];
    /*! The frequency error of the two strongest responses (lower frequency first), in Hz */
    float freq_error[2];

    /*! The current state of the detector. */
    int state;
    /*! The tones which are considered to be present. */
    int tones_present;
    /*! A counter used for the persistence checking of signal changes. */
    int frame_count;
    /*! Time, in samples, since the last tone report. */
    int since_last_report;
} supervisory_rx_state_t;

#if defined(__cplusplus)
extern "C"
{
#endif

int supervisory_rx(supervisory_rx_state_t *s, const int16_t amp[], int len);

supervisory_rx_desc_t *supervisory_rx_desc(supervisory_rx_desc_t *conf,
                                           const float freq_list[]);

supervisory_stats_t supervisory_rx_get_stats(supervisory_rx_state_t *s);

supervisory_rx_state_t *supervisory_rx_init(supervisory_rx_state_t *s,
                                            const supervisory_rx_desc_t *conf,
                                            tone_report_func_t callback,
                                            void *user_data);

#if defined(__cplusplus)
}
#endif

#endif
/*- End of file ------------------------------------------------------------*/