Distinctive Ringing

Some traditional analog phone lines (POTS lines) can be set up so that calls to 2 or more telephone numbers will be sent to them, with the recipient being able to tell which number was dialed by the different ring tone played when calls to different numbers arrive. These different ring types are called "Distinctive Ringing"

VoiceGuide can be setup to detect the different type of Ringing and make this information available to the script.

For VoiceGuide to detect the different rings, the cadences of the rings need to be specified in a ConfigLine.xml file. Here is the relevant section of that file with one ring tone defined.

<DistinctiveRings>
  <DistinctiveRing>
    <Name>TestPBXDoubleRing</Name>
    <ID>TestPbxStandard</ID>
    <Description></Description>
    <Notes></Notes>
    <Cadence>
      <On>55</On>
      <OnDev>10</OnDev>
      <Off>55</Off>
      <OffDev>10</OffDev>
    </Cadence>
    <Cadence>
      <On>55</On>
      <OnDev>10</OnDev>
      <Off>285</Off>
      <OffDev>10</OffDev>
    </Cadence>
  </DistinctiveRing>
</DistinctiveRings>

The time intervals are all specified in 10ms units. The above example shows the definition of a ring that is on for 550ms, the off for 550ms, then on again for 550ms and off for 2850ms, with the pattern repeating afterwards. This definition is loaded by VoiceGuide at startup, and incoming Ring signals (on analog lines) are compared to see if they match any of the definitions.

If a ring matches on of the definitions then the $RV[DISTINCT_RING] variable is set to hold the Name value of the ring definition entry. eg. if the ring matches the example definition above then VoiceGuide will set $RV[DISTINCT_RING] to hold a value of: TestPBXDoubleRing also $RV[DISTINCT_RING_TestPBXDoubleRing] will be set to hold a value of True

Note that VoiceGuide must be set to answer at the beginning of 3rd ring or later in order to be able to hear enough rings to match up their cadence with the example sequence. The 'answer after X rings' setting must always be at least 1 more then the number of Cadence entries in the DistinctiveRing definition.

Confirming the Distinct Ring cadence is loaded properly

Here is the relevant extract from the VoiceGuide log file showing the details of the cadence loaded by Voiceguide at startup.

074958.48 0 init load Distinct Ring definitions start [C:\Projects\vg32\data\ConfigLine.xml]
074958.49 0 init distinct ring definitions found:1
074958.49 0 init ring 1 [TestPBXDoubleRing] total cadences:2
074958.49 0 init distinct ring 1 [TestPBXDoubleRing] cadence 1 [55:10,55:10][110:20]
074958.49 0 init distinct ring 1 [TestPBXDoubleRing] cadence 2 [55:10,285:10][340:20]
074958.49 0 init load Distinct Ring definitions end

Relevant log section showing matching incoming ring

Here is the relevant extract from the VoiceGuide log file showing the details of the incoming call, the ring timings and VoiceGuide matching them against loaded cadence templates. At the end of the trace we can see VoiceGuide matched the cadence against the definition of ring tone, and has added $RV[DISTINCT_RING] to that line's RV set.

Note that with Dialogic cards the cadences are matched using ring rising edge timings. In the example below the rising edge of the second ring arrived 1200ms seconds after the rising edge of first ring, and the 3rd ring arrived 3430ms seconds after the rising edge of the second ring. This fell within the allowed 1st cadence of 900ms-1300ms and the allowed second cadence of 3200ms to 3600ms.

112418.28 1 ring 1
112418.28 1 ring time since last ring event (sec): 0.00
112418.28 1 rings=1, min rings before answer=4 (iCallerIdHasArrived=0)
112418.28 1 tw DialogicEvent 134,TDX_CST,0,0,0,DE_RINGS,ET_RON,
112418.28 1 event ScriptEventCode TDX_CST, code=134, state=0
112419.48 1 ring 2
112419.48 1 ring time since last ring event (sec): 1.20
112419.48 1 ring match against pattern 1, cadences=1
112419.48 1 ring template 1, cadence 1 = [110|20] edge time=1203.3
112419.48 1 ring match distinct ring pattern 1 cycle 1 ok
112419.48 1 rings=2, min rings before answer=4 (iCallerIdHasArrived=0)
112419.48 1 tw DialogicEvent 134,TDX_CST,0,0,0,DE_RINGS,ET_RON,
112419.48 1 event ScriptEventCode TDX_CST, code=134, state=0
112422.92 1 ring 3
112422.92 1 ring time since last ring event (sec): 3.43
112422.92 1 ring match against pattern 1, cadences=2
112422.92 1 ring template 1, cadence 1 = [110|20] edge time=120.3
112422.92 1 ring match distinct ring pattern 1 cycle 1 ok
112422.92 1 ring template 1, cadence 2 = [340|20] edge time=343.4
112422.92 1 ring match distinct ring pattern 1 cycle 2 ok
112422.92 1 ring full match ring pattern 1 (2 cadences)
112422.92 1 rv add [DISTINCT_RING]{TestPBXDoubleRing}

The ring timing marks : "ring time since last ring event" allow you to examine any new ring types' cadences and set the Distinctive Ring definitions accordingly.

Note that with Dialogic cards the cadences are matched using ring rising edge timings, so it is not really essential to correctly set the ON and OFF values, as long as the sum of the ON and OFF values within the cadence matches the time to the next ring rising edge. The <OnDev> and <OffDev> values are also summed to give the overall allowed time deviation.