new_super_rx/save/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) 2003 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 energy[2];
    /*! Frequency error, in Hz */
    float freq_error[2];
} supervisory_stats_t;

typedef struct
{
    /*! Minimum jump in power for tone detection, in dB (10 to 20dB should be OK). */
    float min_power_jump;
    /*! Minimum acceptable level for a tone's power, in dBm0. */
    float min_energy_threshold;
    /*! Maximum permitted ripple for a tone's power, in dB (1 to 3dB should be OK). */
    float max_energy_ripple;
    /*! Maximum permitted normal or reverse twist, in dB. */
    float max_energy_twist;
    /*! How much energies must be above other components, in dB (>20dB starts to be useful). */
    float clean_threshold;
    /*! The maximum permissible frequency offset from the target, in Hz */
    float max_freq_deviation;
    /*! Number of good frames before tone on is declared */
    int min_tone_on_duration;
    /*! Number of low-energy frames before tone off is declared */
    int min_tone_off_duration;
    /*! Number of inconsistent frames before tone abort is declared */
    int abort_timeout;
    /*! The number of frequencies to be monitored */
    int frequencies;
    complexf_t sensor_coeffs[SUPER_TONE_MAX_FREQS][SUPER_TONE_PG_WINDOW/2];
    complexf_t sensor_phase_offsets[SUPER_TONE_MAX_FREQS];
} 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 energy level at each of the frequencies being monitored */
    float energy[SUPER_TONE_MAX_FREQS];
    /*! The periodogram result at each of the frequencies being monitored */
    complexf_t pg_result[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;

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

    /*! 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];
    /*! A list of the last few combined energies in the 2 main responses */
    float summed_energy_db_history[SUPER_TONE_ENERGY_SIZE];
    /*! A smoothed version of the combined energies in the 2 main responses */
    float avg_summed_energy_db;

    /*! The highest energy level amongst the monitored frequencies, in dBm0 */
    float highest_energy_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 energy_db[3];
    /*! The frequency error of the two strongest responses (lower frequency first), in Hz */
    float freq_error[2];

    /*! A bit pattern containing all the signal test results. */
    int test_results;
    /*! The current state of the detector. */
    int state;
    /*! The tones which are considered to be currently present. */
    int tones_present;
    /*! The previous tones which were considered to be present. */
    int last_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 ------------------------------------------------------------*/