CASr1 scripting

From TBwiki
(Difference between revisions)
Jump to: navigation, search
(more formatting)
m
 
(81 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{DISPLAYTITLE:E&M}}
+
 
−
E&M is a CASr1 family.
+
This page explains how CASr1 script are implemented. You can read, modify, or create CASR1 scripts to adapt to different variants, or implement new variants.
−
This script is used to configure the following variants:
+
−
* Immediate delay
+
−
* Wink-start
+
−
* Double-ack
+
  
 
== Summary ==
 
== Summary ==
−
This script will be identified as a CASR1 script when the following
+
 
−
variable is set:
+
Toolpack uses the LUA programming language to implement CAS scripts. The CAS scripts are interpreted by the TMG unit in order to handle calls.
 +
 
 +
A portion of the CAS state machine is implemented outside the script, in the CAS stack that runs on the TMG unit, although the script still offers a great level of flexibility to implement various CAS variants.
 +
 
 +
=== CASR1 vs CASR2 scripts ===
 +
CASR1 variants and CASR2 variants both use LUA scripts stored in the same place in the Toolpack configuration Web Portal.
 +
 
 +
However, CASR1 and CASR2 scripts are quite different. They use different constants and function, and will have different "callback" functions called by the CAS stack on the TMG. The general architecture (state machine) of the scripts is also different.
 +
 
 +
In a few words:
 +
 
 +
CASR1 scripts need to:
 +
* Handle incoming CAS bits changes
 +
* Decide when to change sent CAS bits
 +
* Decide when to detect/send ANI/DNIS tones
 +
* Implement a state machine that follows the different call states, and report these states to the CAS stack
 +
 
 +
CASR2 scripts need to:
 +
* Define forward and backward digits to use
 +
* Map digits to various meanings
 +
* Handle received digits and how to handle then
 +
 
 +
The current page explains CASR1 scripts.
 +
For more information about CASR2 scripts, please refer to the following page: [[Web_Portal_Tutorial_Guide_v2.6#CASR2]]
 +
 
 +
=== Set the script type to CASR1 ===
 +
A CAS script be identified as a CASR1 script when the following variable is set:
 
<pre>
 
<pre>
 
SCRIPT_TYPE="CASR1"
 
SCRIPT_TYPE="CASR1"
 
</pre>
 
</pre>
−
The CASR1 script allows implementation of all variants of CASR1 stacks
 
−
by controlling what actions must take place following received events.
 
  
 +
If this variable is missing, the script will be interpreted as "CASR2".
 +
 +
=== Provided scripts ===
 +
Toolpack already supports multiple CAS variants through scripts that are installed in any new Toolpack installation:
 +
<ul>
 +
  <li>
 +
    CASR1 variants:
 +
    <ul>
 +
      [[CAS#Supported_CAS_R1_variants|Supported CASR1 variants]]
 +
    </ul>
 +
  </li>
 +
  <li>
 +
    CASR2 variants:
 +
    <ul>
 +
      [[CAS#Supported_CAS_R2_variants|Supported CASR2 variants]]
 +
    </ul>
 +
  </li>
 +
</ul>
  
 
== Overview ==
 
== Overview ==
−
The script will received an indication for each timeslot it has to
+
=== Per-timeslot context ===
−
"control" through function HandleNewTimeslot.
+
The CASR1 scripts works on a "per timeslot" basis. It's informed of each timeslot that is under it's control through callback function ''HandleNewTimeslot''.
−
The script will then be notified of any event on that timeslot
+
 
 +
A context is provided with each timeslot, so the script can store "per-timeslot" variables in order to implement the state machine.
 +
 
 +
=== Per-timeslot events ===
 +
Once a timeslot has been created in the script, the CAS stack will inform the script of any event on that timeslot
 
(CAS bits changes and others).
 
(CAS bits changes and others).
 
To each received event, the script will take one ore more action.
 
To each received event, the script will take one ore more action.
  
 +
=== Per-timeslot actions ===
 +
The CAS script can perform various actions on a timeslot, while it handles timeslot events.
 +
 +
For example, it can
 +
* change CAS bits (or send "wink")
 +
* report call state to the CAS stack (seizure, call alerting, call answered, call terminating, timeslot remotely blocked, etc.).
 +
* ask for ANI/DNIS detection
 +
* ask for transmission of ANI/DNIS
 +
* Start a timer
 +
* And more...
 +
 +
=== Per-timeslot state machine ===
 
It's up to the script implementation to define it's own states
 
It's up to the script implementation to define it's own states
 
for handling the calls. The script is thus very flexible in the way
 
for handling the calls. The script is thus very flexible in the way
Line 31: Line 85:
 
how calling/called numbers are exchanged, what is the call flow etc.)
 
how calling/called numbers are exchanged, what is the call flow etc.)
 
The reader shall find that information in the specifications for
 
The reader shall find that information in the specifications for
−
CASR1 variants. This script should provide all tools required to
+
CASR1 variants.
−
actually implement CASR1 variants.
+
  
 +
The current document provides general information on available timeslot events and actions that allow to actually implement CASR1 variants.
 +
 +
 +
 +
 +
== Script entry points ==
 +
There are 2 functions that the script must provide, and that will be called by the stack when appropriate:
 +
* [[#handle_new_timeslot|HandleNewTimeslot( in_TimeslotCtx, in_InitialCasBits )]]
 +
* [[#handle_event|HandleEvent( in_TimeslotCtx, in_EventType, ... )]]
 +
(see documentation blow for detailed information)
  
 
== Configurable global script constants==
 
== Configurable global script constants==
 
The script can define some constants required by the stack (though
 
The script can define some constants required by the stack (though
 
default values are provided if the script does not define these
 
default values are provided if the script does not define these
−
constants.
+
constants).
 +
=== SCRIPT_TYPE ===
 +
Defines the type of this sript. This constant is mandatory for CASR1 scripts.
 
<pre>
 
<pre>
 
SCRIPT_TYPE = "CASR1"
 
SCRIPT_TYPE = "CASR1"
 
</pre>
 
</pre>
−
Defines the type of this sript. Must be CASR1 in current case.
 
  
−
<pre>
+
=== ABCD_PATTERN_MATCH_MASK ===
−
ABCD_PATTERN_MATCH_MASK = 0x1111
+
Mask to apply to CAS bits detected from remote equipment (for bits 0xABCD).
−
</pre>
+
−
Mask to apply to CAS bits detected from remote equipment.
+
 
A bit which mask is set to 0 will be ignored and always reported as
 
A bit which mask is set to 0 will be ignored and always reported as
 
zero (0) to this script.
 
zero (0) to this script.
Line 53: Line 115:
 
(and even sometimes toggeling!) values.
 
(and even sometimes toggeling!) values.
  
−
- TONE_USE_DTMF = 1
+
Default: 0x1111
−
Indicates the type of tones must be used to send/receive AND/DNIS.
+
 
−
Value of 1 stands for DTMF. Value of 0 defaults to MFR1.
+
 
<pre>
 
<pre>
−
DTMF mapping:
+
ABCD_PATTERN_MATCH_MASK = 0x1111
 +
</pre>
 +
 +
=== TONE_USE_DTMF ===
 +
Indicates the type of tones must be used to send/receive AND/DNIS.
 +
Value of 1 stands for DTMF. Value of 0 defaults to MFR1.
 +
 
 +
Default: 1 (use DTMF)
 +
 
 +
<pre>
 +
TONE_USE_DTMF = 1
 +
</pre>
 +
 
 +
=== TONE_ON_TIME ===
 +
Defines the "on time" (in ms) of tones used when sending ANI/DNIS.
 +
 
 +
Default: 60ms
 +
 
 +
<pre>
 +
TONE_ON_TIME = 60
 +
</pre>
 +
 
 +
=== TONE_OFF_TIME ===
 +
Defines the "off time" (inter-digit delay)(in ms) of tones used when sending ANI/DNIS.
 +
 
 +
Default: 40ms
 +
 
 +
<pre>
 +
TONE_OFF_TIME = 50
 +
</pre>
 +
 
 +
=== TONE_LEVEL ===
 +
Defines the audio power level (in DB) of tones used when sending ANI/DNIS, or dial tone.
 +
 
 +
Default: -10db
 +
 
 +
<pre>
 +
TONE_LEVEL = -10
 +
</pre>
 +
 +
=== TONE_VP_GROUP ===
 +
Defines the type of tone detector/generator that will be used for CASR1 calls:
 +
* Group 0: Use DSP resources (for TMG that have DSP resources)
 +
* Group 1: Use VOIP resources (for TMG that have VOIP resources)
 +
 
 +
It may be required to change this value if using CASR1 scripts on TMG units that don't have either DSP or VOIP resources.
 +
 
 +
Default: 1 (VOIP resources)
 +
 
 +
<pre>
 +
TONE_VP_GROUP = 1
 +
</pre>
 +
 
 +
 
 +
=== TX_DIAL_TONE ===
 +
Defines if (and which) dial tone must be played on a backward (incoming) call.
 +
Empty string (or missing variable) results in no dial tone being played.
 +
 
 +
Default: No dial tone
 +
 
 +
<pre>
 +
TX_DIAL_TONE = "(350,440)" -- This is default US dial tone
 +
</pre>
 +
 
 +
=== USE_FORCED_RELEASE ===
 +
Defines if "forced release" option must be used to terminate non-answered backward (incoming) calls.
 +
 
 +
In most CASR1 variants, the CAS bits for a backward (incoming) calls remain "on-hook" until the call is answered (except for short "wink" periods).
 +
Because of that, it's not possible to indicate remote equipment that we want to terminate this incoming call, since bits are already "on hook".
 +
 
 +
The solution to that is to quickly set the CAS bits to "off-hook" then "on-hook", to indicate to remote side that we want to terminate the call.
 +
 
 +
This option should be used with care, because it may cause remote equipment to think the call has been answered for about 200ms. This could cause billing or statistics (ASR) calculation problems on the remote equipment if it does not expect that.
 +
 
 +
Default: 0 (Don't use forced release)
 +
 
 +
<pre>
 +
TX_DIAL_TONE = "(350,440)" -- This is default US dial tone
 +
</pre>
 +
 
 +
== Tones mapping to ASCII characters ==
 +
<div id="tones_format">
 +
=== DTMF mapping ===
 +
DTMF tones are represented, in the script, as ASCII characters.
 +
(these are used to define ANI/DNIS prefix/suffix, or to explicitly provide the ANI/DNIS for a call).
 +
 
 +
Please refer to the following table to know which ASCII character is used to represent each existing DTMF tone:
 +
<pre>
 +
 
'0' -> DTMF Digit 0: 941Hz + 1336Hz
 
'0' -> DTMF Digit 0: 941Hz + 1336Hz
 
'1' -> DTMF Digit 1: 697Hz + 1209Hz
 
'1' -> DTMF Digit 1: 697Hz + 1209Hz
Line 68: Line 217:
 
'8' -> DTMF Digit 8: 852Hz + 1336Hz
 
'8' -> DTMF Digit 8: 852Hz + 1336Hz
 
'9' -> DTMF Digit 9: 852Hz + 1477Hz
 
'9' -> DTMF Digit 9: 852Hz + 1477Hz
−
'*' -> DTMF Digit Star (*): 941Hz + 1209Hz
+
'*' -> DTMF Digit Star (*): 941Hz + 1209Hz
−
'#' -> DTMF Digit Pound (#): 941Hz + 1477Hz
+
'#' -> DTMF Digit Pound (#): 941Hz + 1477Hz
 
'A' -> DTMF Digit A: 697Hz + 1633Hz
 
'A' -> DTMF Digit A: 697Hz + 1633Hz
 
'B' -> DTMF Digit B: 770Hz + 1633Hz
 
'B' -> DTMF Digit B: 770Hz + 1633Hz
Line 75: Line 224:
 
'D' -> DTMF Digit D: 941Hz + 1633Hz
 
'D' -> DTMF Digit D: 941Hz + 1633Hz
 
Alternative values for * and #:
 
Alternative values for * and #:
−
'E' -> DTMF Digit Star (*): 941Hz + 1209Hz
+
'E' -> DTMF Digit Star (*): 941Hz + 1209Hz
−
'F' -> DTMF Digit Pound (#): 941Hz + 1477Hz
+
'F' -> DTMF Digit Pound (#): 941Hz + 1477Hz
 
</pre>
 
</pre>
−
MFR1 mapping:
+
 
 +
=== MFR1 mapping ===
 +
MFR1 tones are represented, in the script, as ASCII characters.
 +
(these are used to define ANI/DNIS prefix/suffix, or to explicitly provide the ANI/DNIS for a call).
 +
 
 +
Please refer to the following table to know which ASCII character is used to represent each existing MFR1 tone:
 
<pre>
 
<pre>
 
'0' -> MFR1 Digit 0: 1300Hz + 1500Hz
 
'0' -> MFR1 Digit 0: 1300Hz + 1500Hz
Line 90: Line 244:
 
'8' -> MFR1 Digit 8: 900Hz  + 1500Hz
 
'8' -> MFR1 Digit 8: 900Hz  + 1500Hz
 
'9' -> MFR1 Digit 9: 1100Hz + 1500Hz
 
'9' -> MFR1 Digit 9: 1100Hz + 1500Hz
−
'*' -> MFR1 KP (Start of pulsing): 1100Hz + 1700Hz
+
'*' -> MFR1 KP (Start of pulsing): 1100Hz + 1700Hz
−
'#' -> MFR1 ST (End of pulsing): 1500Hz + 1700Hz
+
'#' -> MFR1 ST (End of pulsing): 1500Hz + 1700Hz
−
'A' -> MFR1 STI: 900Hz  + 1700Hz
+
'A' -> MFR1 STI: 900Hz  + 1700Hz
−
'B' -> MFR1 STII: 1300Hz + 1700Hz
+
'B' -> MFR1 STII: 1300Hz + 1700Hz
 
'C' -> MFR1 STIII: 700Hz  + 1700Hz
 
'C' -> MFR1 STIII: 700Hz  + 1700Hz
 
'D' -> Not supported in MFR1
 
'D' -> Not supported in MFR1
−
</pre>
+
 
 
Alternative characters:
 
Alternative characters:
−
<pre>
+
'E' -> MFR1 KP (Start of pulsing): 1100Hz + 1700Hz
−
'E' -> MFR1 KP (Start of pulsing): 1100Hz + 1700Hz
+
'F' -> MFR1 ST (End of pulsing): 1500Hz + 1700Hz
−
'F' -> MFR1 ST (End of pulsing): 1500Hz + 1700Hz
+
 
</pre>
 
</pre>
  
−
<pre>
+
== Static constants pushed by the stack, for usage in this script==
−
TONE_ON_TIME = 60
+
=== Actions ===
−
</pre>
+
Available actions for [[#stack_action|StackAction]] function:
−
Determines the "on time" (in ms) of tones used when sending ANI/DNIS.
+
  
 +
Commonly used actions:
 
<pre>
 
<pre>
−
TONE_OFF_TIME = 50
+
ACTION_END_SIGNALING
 +
ACTION_SET_CAS_BITS
 +
ACTION_SEND_WINK
 +
ACTION_WAIT_WINK
 +
ACTION_SEND_ANI
 +
ACTION_SEND_DNIS
 +
ACTION_WAIT_ANI
 +
ACTION_WAIT_DNIS
 +
ACTION_REPORT_SEIZURE
 +
ACTION_REPORT_VALIDATE_CALL
 +
ACTION_REPORT_ACCEPTED
 +
ACTION_REPORT_ALERTED
 +
ACTION_REPORT_ANSWERED
 +
ACTION_REPORT_BLOCKED
 +
ACTION_REPORT_UNBLOCKED
 +
ACTION_START_TIMER
 +
ACTION_CANCEL_TIMER
 
</pre>
 
</pre>
−
Determines the "off time" (inter-digit delay)(in ms) of tones used
 
−
when sending ANI/DNIS.
 
  
 +
Additional actions to implement special variants
 
<pre>
 
<pre>
−
TONE_LEVEL = -10
+
ACTION_SEND_TONE
 +
ACTION_SET_ANI
 +
ACTION_SET_DNIS
 
</pre>
 
</pre>
−
Determines the level (in DB) of tones used when sending ANI/DNIS.
 
  
 +
=== Events ===
 +
Events received by this script on [[#handle_event|HandleEvent]] function:
  
−
 
+
Commonly used events:
−
== Static constants pushed by the stack, for usage in this script==
+
−
Available actions for "StackAction" function:
+
−
Commonly used actions:
+
−
<pre>
+
−
ACTION_END_SIGNALING
+
−
ACTION_SET_CAS_BITS
+
−
ACTION_SEND_WINK
+
−
ACTION_WAIT_WINK
+
−
ACTION_SEND_ANI
+
−
ACTION_SEND_DNIS
+
−
ACTION_WAIT_ANI
+
−
ACTION_WAIT_DNIS
+
−
ACTION_REPORT_SEIZURE
+
−
ACTION_REPORT_VALIDATE_CALL
+
−
ACTION_REPORT_ACCEPTED
+
−
ACTION_REPORT_ALERTED
+
−
ACTION_REPORT_ANSWERED
+
−
ACTION_REPORT_BLOCKED
+
−
ACTION_REPORT_UNBLOCKED
+
−
ACTION_START_TIMER
+
−
ACTION_CANCEL_TIMER
+
−
</pre>
+
−
Additional actions to implement special variants
+
 
<pre>
 
<pre>
−
ACTION_SEND_TONE
+
EVENT_CAS_BITS_CHANGED
−
ACTION_SET_ANI
+
EVENT_WINK_DETECTED
−
ACTION_SET_DNIS
+
EVENT_WINK_COMPLETED
 +
EVENT_ANI_RECEIVED
 +
EVENT_DNIS_RECEIVED
 +
EVENT_ANI_SENT
 +
EVENT_DNIS_SENT
 +
EVENT_APP_FWD_MAKE_CALL
 +
EVENT_APP_BWD_MUST_ALERT
 +
EVENT_APP_BWD_MUST_ANSWER
 +
EVENT_APP_END_SIGNALING
 +
EVENT_APP_BLOCK_TIMESLOT
 +
EVENT_APP_UNBLOCK_TIMESLOT
 +
EVENT_TIMEOUT
 
</pre>
 
</pre>
  
−
Events received by this script on "HandleEvents" function:
+
Additional events to implement special variants
−
Commonly used events:
+
 
<pre>
 
<pre>
−
EVENT_CAS_BITS_CHANGED
+
EVENT_TONE_RECEIVED
−
EVENT_WINK_DETECTED
+
EVENT_TONE_SENT
−
EVENT_WINK_COMPLETED
+
−
EVENT_ANI_RECEIVED
+
−
EVENT_DNIS_RECEIVED
+
−
EVENT_ANI_SENT
+
−
EVENT_DNIS_SENT
+
−
EVENT_APP_FWD_MAKE_CALL
+
−
EVENT_APP_BWD_MUST_ALERT
+
−
EVENT_APP_BWD_MUST_ANSWER
+
−
EVENT_APP_END_SIGNALING
+
−
EVENT_APP_BLOCK_TIMESLOT
+
−
EVENT_APP_UNBLOCK_TIMESLOT
+
−
EVENT_TIMEOUT
+
 
</pre>
 
</pre>
−
Additional events to implement special variants
 
−
EVENT_TONE_RECEIVED
 
−
EVENT_TONE_SENT
 
 
 
−
Result code that HandleNewTimeslot or HandleEvent funtions must return:
+
=== Result codes ===
 +
Result codes that [[#handle_new_timeslot|HandleNewTimeslot]] or [[#handle_event|HandleEvent]] functions must return:
 
<pre>
 
<pre>
−
RESULT_OK
+
RESULT_OK
−
RESULT_FAIL
+
RESULT_FAIL
−
RESULT_MISMATCH
+
RESULT_MISMATCH
−
RESULT_OUT_OF_RESOURCE
+
RESULT_OUT_OF_RESOURCE
−
RESULT_INVALID_PARAM
+
RESULT_INVALID_PARAM
−
RESULT_INVALID_STATE
+
RESULT_INVALID_STATE
−
RESULT_NOT_SUPPORTED
+
RESULT_NOT_SUPPORTED
−
RESULT_TRUNK_RES_NOT_IDLE
+
RESULT_TRUNK_RES_NOT_IDLE
−
RESULT_BLOCKED_LOCALLY
+
RESULT_BLOCKED_LOCALLY
−
RESULT_BLOCKED_REMOTELY
+
RESULT_BLOCKED_REMOTELY
 
</pre>
 
</pre>
 
 
−
Call release causes to use with ACTION_END_SIGNALING
+
=== Call release causes ===
 +
Call release causes to use with [[#ACTION_END_SIGNALING|ACTION_END_SIGNALING]]
 
<pre>
 
<pre>
−
CAUSE_FWD_SEIZURE_COLLISION
+
CAUSE_FWD_SEIZURE_COLLISION
−
CAUSE_FWD_SEIZURE_ACK_TIMEOUT
+
CAUSE_FWD_SEIZURE_ACK_TIMEOUT
−
CAUSE_FWD_TONE_TIMEOUT
+
CAUSE_FWD_TONE_TIMEOUT
−
CAUSE_FWD_ANSWER_TIMEOUT
+
CAUSE_FWD_ANSWER_TIMEOUT
−
CAUSE_FWD_CALL_REFUSED
+
CAUSE_FWD_CALL_REFUSED
−
CAUSE_FWD_REJECT_CALL
+
CAUSE_FWD_REJECT_CALL
−
CAUSE_FWD_HANG_UP
+
CAUSE_FWD_HANG_UP
−
CAUSE_BWD_TONE_TIMEOUT
+
CAUSE_BWD_TONE_TIMEOUT
−
CAUSE_BWD_REJECT_CALL
+
CAUSE_BWD_REJECT_CALL
−
CAUSE_BWD_CALL_REFUSED
+
CAUSE_BWD_CALL_REFUSED
−
CAUSE_BWD_ALERT_TIMEOUT
+
CAUSE_BWD_ALERT_TIMEOUT
−
CAUSE_BWD_ANSWER_TIMEOUT
+
CAUSE_BWD_ANSWER_TIMEOUT
−
CAUSE_BWD_HANG_UP
+
CAUSE_BWD_HANG_UP
 
</pre>
 
</pre>
 
 
−
Trace levels (used with function StackLogTrace).
+
=== Trace levels ===
−
Least verbose is TRACE_LEVEL_0 (almost never printed).
+
Trace levels (used with function [[#stack_log_trace|StackLogTrace]]).
−
Most verbose is TRACE_LEVEL_4 (generally printed)
+
 
 +
* Least verbose is TRACE_LEVEL_0 (almost never printed).
 +
* Most verbose is TRACE_LEVEL_4 (generally printed).
 +
 
 
<pre>
 
<pre>
−
TRACE_LEVEL_0
+
TRACE_LEVEL_0
−
TRACE_LEVEL_1
+
TRACE_LEVEL_1
−
TRACE_LEVEL_2
+
TRACE_LEVEL_2
−
TRACE_LEVEL_3
+
TRACE_LEVEL_3
−
TRACE_LEVEL_4
+
TRACE_LEVEL_4
−
TRACE_LEVEL_ALWAYS
+
TRACE_LEVEL_ALWAYS
−
TRACE_LEVEL_ERROR
+
TRACE_LEVEL_ERROR
−
</pre>
+
</pre>
  
 
== Mandatory functions to implement in this script ==
 
== Mandatory functions to implement in this script ==
Line 221: Line 369:
 
be called by the CAS stack at appropriate moments.
 
be called by the CAS stack at appropriate moments.
  
 +
<div id="handle_new_timeslot">
 
=== HandleNewTimeslot( in_TimeslotCtx, in_InitialCasBits )===
 
=== HandleNewTimeslot( in_TimeslotCtx, in_InitialCasBits )===
 
This function is called to prepare a new timeslot so it's ready to
 
This function is called to prepare a new timeslot so it's ready to
 
be used to receive events and eventually handle a CASR1 call.
 
be used to receive events and eventually handle a CASR1 call.
−
When this function is called, the timeslot must be set to "off-hook"
+
−
state. The stack will later send EVENT_APP_UNBLOCK_TIMESLOT when
+
When this function is called, the timeslot must be initially be considered "locally blocked (and CAS bits must be set to "off-hook" state). The stack will later send EVENT_APP_UNBLOCK_TIMESLOT when
 
it's time to go "on-hook" and be ready to make calls.
 
it's time to go "on-hook" and be ready to make calls.
−
Parameters:
+
 
−
in_TimeslotCtx :
+
===='''in_TimeslotCtx'''====
−
Context containing variables for this timeslot.
+
Context containing variables for this timeslot. This context is a LUA table. This table already contains two values:
−
This context is a LUA table.
+
* ["TrunkNumber"]
−
This table already contains two values:
+
* ["TimeslotNumber"]
−
["TrunkNumber"] and ["TimeslotNumber"]
+
The script can store it's own LUA variables here (like the "call state"), which will be accessible for any event on this timeslot.
−
The script can create it's own variables here (like the
+
 
−
"call state"), which will be accessible for any event on
+
===='''in_InitialCasBits'''====
−
this timeslot.
+
The initial states of CAS bits received from remote equipment (integer like 0x1111)
−
in_InitialCasBits :
+
 
−
The initial states of CAS bits received from remote equipment
+
<div id="handle_event">
−
(integer like 0x1111)
+
 
−
+
 
=== HandleEvent( in_TimeslotCtx, in_EventType, ... ) ===
 
=== HandleEvent( in_TimeslotCtx, in_EventType, ... ) ===
−
This function reports that an event occurred on a timeslot
+
This function reports that an event occurred on a timeslot.
−
Parameters :
+
 
−
in_TimeslotCtx :
+
==== in_TimeslotCtx ====
−
Timeslot context used by the script to store any timeslot-
+
Timeslot context used by the script to store any timeslot-related information, like the "call state".
−
related information, like the "call state".
+
 
−
This is the table that was passed to HandleNewTimeslot.
+
This is the table that was passed to HandleNewTimeslot.
−
in_EventType :
+
 
−
The type of the event that was just received
+
==== in_EventType ====
−
(see constants EVENT_* documented below)
+
The type of the event that was just received
−
... :
+
 
−
Variable number of parameters, that depend on event type.
+
See below for list of events that can be received: [[#CASR1_script_events|CASR1 script events]]
−
Available event types and their parameters:
+
 
−
EVENT_CAS_BITS_CHANGED:
+
==== ... ====
−
Parameter:
+
Variable number of parameters, that depend on event type.
−
- Received CAS bits (integer like 0x1111)
+
 
−
Indicates that CAS bits values received by
+
To access these parameters, the LUA syntax is as follows:
−
remote equipment have changed.
+
<pre>
−
EVENT_WINK_DETECTED:
+
-- Create an array with the variable number of arguments:
−
No specific parameter.
+
local args = {...}
−
Indicates that a "Wink" has been detected.
+
-- Accessing the first argument
−
This event can only follow ACTION_WAIT_WINK.
+
local first_argument_value = args[1]
−
EVENT_WINK_COMPLETED:
+
</pre>
−
No specific parameter.
+
 
−
Indicates that a "Wink" has been sent successfully.
+
==== Return value ====
−
This event can only follow ACTION_SEND_WINK.
+
This function must return RESULT_OK, or one of the return codes defined above.
−
EVENT_TONE_RECEIVED
+
 
−
Parameter:
+
This result code tells to the stack if the event was properly handled by the script. Upon non-OK code, the stack may decide to terminate the call, assuming the script is incomplete and did not expect the event.
−
- String that represents the received tone (digit)
+
 
−
(see "Digit format" below)
+
Please note that RESULT_OK is normally returned even in case of events that make the call fail or be dropped. The purpose of this result code is not to indicate if the event cause a call to be dropped, but rather to indicate that the script really does not know what to do with the received event.
−
Indicates that a tone was detected.
+
 
−
Not normally used in CASR1 standard variants.
+
== CASR1 script events ==
−
Note: This does not include tones that are
+
The CASR1 script will receive (and must handle) the following events (received in function [[#handle_event|HandleEvent]]
−
collected as part of ACTION_WAIT_ANI or
+
 
−
ACTION_WAIT_DNIS, which are coalesced and
+
=== EVENT_CAS_BITS_CHANGED ===
−
reported as separate events.
+
Indicates that new CAS bits have been received from remote equipment.
−
EVENT_ANI_RECEIVED
+
 
−
No specific parameter.
+
Parameters:
−
Indicates that ANI (calling number) has been
+
<ol>
−
sent received (prefix/suffix detected).
+
  <li>
−
This event can only follow ACTION_WAIT_ANI.
+
    Received CAS bits (integer like 0x1111)<br />
−
Note: The received ANI/DNIS digits are not passed
+
    Indicates that CAS bits values received by remote equipment have changed.
−
to the script. The script does not have
+
  </li>
−
to know them. But the stack keeps them
+
</ol>
−
and they will be reported to the
+
 
−
application upon ACTION_REPORT_VALIDATE_CALL
+
=== EVENT_WINK_DETECTED ===
−
EVENT_DNIS_RECEIVED
+
Indicates that a "Wink" has been detected. This event can only follow [[#ACTION_WAIT_WINK|ACTION_WAIT_WINK]].
−
Same as EVENT_ANI_RECEIVED, but for DNIS
+
 
−
(called number)
+
No specific parameter.
−
EVENT_TONE_SENT
+
 
−
No specific parameter.
+
=== EVENT_WINK_COMPLETED ===
−
Indicates that a tone (digit) as been sent
+
Indicates that a "Wink" has been sent successfully. This event can only follow [[#ACTION_SEND_WINK|ACTION_SEND_WINK]].
−
successfully following ACTION_SEND_TONE.
+
 
−
Not normally used in CASR1 standard variants.
+
No specific parameter.
−
EVENT_ANI_SENT
+
 
−
No specific parameter.
+
=== EVENT_TONE_RECEIVED ===
−
Indicates that ANI (calling number) has been
+
Indicates that a tone was detected.
−
sent successfully (all tones played).
+
 
−
This event can only follow ACTION_SEND_ANI.
+
Not normally used in CASR1 standard variants, because most variants can rely on [[#ACTION_WAIT_ANI|ACTION_WAIT_ANI]] or [[#ACTION_WAIT_DNIS|ACTION_WAIT_DNIS]] to collect calling/called numbers in one single action.
−
EVENT_DNIS_SENT
+
 
−
Same as EVENT_ANI_SENT, but for DNIS
+
And thus this event will not report tones that are collected by the CAS stack as part of [[#ACTION_WAIT_ANI|ACTION_WAIT_ANI]] or [[#ACTION_WAIT_DNIS|ACTION_WAIT_DNIS]].
−
(called number)
+
 
−
EVENT_APP_FWD_MAKE_CALL
+
Parameters:
−
No specific parameter.
+
<ol>
−
Indicate that a new "forward" call must be made.
+
  <li>
−
The script shall take appropraite actions to
+
    A one-character string that represents the received tone (digit).<br />
−
initiate a new call (most likely change the
+
    See [[#tones_format|Tones mapping to ASCII characters]] for details about which ASCII character represents which tone.
−
CAS bits to the "off hook" state).
+
  </li>
−
EVENT_APP_BWD_MUST_ALERT
+
</ol>
−
No specific parameter.
+
 
−
Indicates that this "backward" call must now
+
=== EVENT_ANI_RECEIVED ===
−
be set to "alerted" state (meaning we have accepted
+
Indicates that ANI (calling number) has been sent received (prefix/suffix detected). This event can only follow [[#ACTION_WAIT_ANI|ACTION_WAIT_ANI]].
−
the call, and received required information to
+
 
−
proceed). The decision of when to alert the call
+
Note: The received ANI/DNIS digits are not passed to the script as [[#EVENT_TONE_RECEIVED|EVENT_TONE_RECEIVED]]. Instead, the stack stores them as the 'calling number' which will be reported to the application upon [[#ACTION_REPORT_VALIDATE_CALL|ACTION_REPORT_VALIDATE_CALL]]
−
is made by the application, and at that moment
+
 
−
the script receives this event so it can take
+
No specific parameter.
−
appropriate actions to alert a "backward" call.
+
 
−
(in most variants, there is nothing to do, on
+
=== EVENT_DNIS_RECEIVED ===
−
some variants, a "Wink" may be sent).
+
Same as [[#EVENT_ANI_RECEIVED|EVENT_ANI_RECEIVED]], but for DNIS (called number)
−
EVENT_APP_BWD_MUST_ANSWER
+
 
−
No specific parameter.
+
=== EVENT_TONE_SENT ===
−
Indicates that this "backward" call must now
+
Indicates that a tone (digit) as been sent successfully following [[#ACTION_SEND_TONE|ACTION_SEND_TONE]]. Not normally used in CASR1 standard variants.
−
be set to "answered" state. The decision of when  
+
 
−
set the call "answered" is made by the application,
+
No specific parameter.
−
and at that moment the script receives this event
+
 
−
so it can take appropriate actions to answer.
+
=== EVENT_ANI_SENT ===
−
(in most variants, CAS bits must be set to
+
Indicates that ANI (calling number) has been sent successfully (all tones played).  
−
an "answered" pattern).
+
This event can only follow [[#ACTION_SEND_ANI|ACTION_SEND_ANI]].
−
EVENT_APP_END_SIGNALING
+
No specific parameter.
−
No specific parameter.
+
 
−
Indicates either that:
+
=== EVENT_DNIS_SENT ===
−
  - Application requests to terminate the call.
+
Same as [[#EVENT_ANI_SENT|EVENT_ANI_SENT]], but for DNIS (called number)
−
    The script then take appropriate action, like
+
 
−
sedding CAS bits to "idle" state, wait for
+
=== EVENT_APP_FWD_MAKE_CALL ===
−
remote equipment to acknowledge, then at the
+
Indicate that a new "forward" call must be made.
−
end use ACTION_END_SIGNALING to confirm that
+
 
−
termination is completed.
+
The script shall take appropriate actions to initiate a new call (most likely change the CAS bits to the "off hook" state).
−
  - Script previously called ACTION_END_SIGNALING,
+
 
−
    (after remote equipment set CAS bits to "idle"
+
No specific parameter.
−
or after an error in the script), in which
+
 
−
case this event confirms that the application
+
=== EVENT_APP_BWD_MUST_ALERT ===
−
is also ready to terminate the call.
+
Indicates that this "backward" call must now be set to "alerted" state (meaning we have accepted the call, and received required information to proceed).
−
EVENT_APP_BLOCK_TIMESLOT
+
 
−
No specific parameter.
+
The decision of when to alert the call is made by the application, and at that moment the script receives this event so it can take appropriate actions to alert a "backward" call. (in most variants, there is nothing to do, on some variants, a "Wink" may be sent).
−
Indicates that the timeslot must be locally
+
 
−
blocked, the next time it becomes "idle".
+
No specific parameter.
−
It's blocked by going "off-hook" and remaining
+
 
−
in that state no matter remote state.
+
=== EVENT_APP_BWD_MUST_ANSWER ===
−
This is also the default state for a newly
+
Indicates that this "backward" call must now be set to "answered" state.
−
created timeslot.
+
 
−
This state can only be canceled by
+
The decision of when set the call "answered" is made by the application, and at that moment the script receives this event so it can take appropriate actions to answer. (in most variants, CAS bits must be set to "off hook" pattern).
−
EVENT_APP_UNBLOCK_TIMESLOT
+
 
−
EVENT_APP_UNBLOCK_TIMESLOT
+
No specific parameter.
−
No specific parameter.
+
 
−
Cancels a previous EVENT_APP_BLOCK_TIMESLOT.
+
=== EVENT_APP_END_SIGNALING ===
−
This causes our CAS bits to be set to "on hook".
+
Indicates either that:
−
EVENT_TIMEOUT
+
<ul>
−
No specific parameter.
+
<li>
−
Indicates that the timer previously started with
+
Application requests to terminate the call.<br/>
−
ACTION_START_TIMER has expired.
+
The script then take appropriate action, like sending CAS bits to "idle" state, wait for remote equipment to acknowledge, then at the end use [[#ACTION_END_SIGNALING|ACTION_END_SIGNALING]] to confirm that termination is completed.
−
Returns :
+
</li>
−
RESULT_OK, or one of the return codes defined above.
+
<li>
−
This result code tells to the stack if the event was properly
+
Script had already previously called [[#ACTION_END_SIGNALING|ACTION_END_SIGNALING]], (after remote equipment set CAS bits to "idle" or after an error in the script), in which case this event confirms that the application is also ready to terminate the call.<br/>
−
handled by the script. Upon non-OK code, the stack may decide
+
The script generally returns to "idle" state after that event.
−
to terminate the call.
+
</li>
 +
</ul>
 +
 
 +
No specific parameter.
 +
 
 +
=== EVENT_APP_BLOCK_TIMESLOT ===
 +
Indicates that the timeslot must be locally blocked, the next time it becomes "idle".
 +
 
 +
On most variants where this is supported, a timeslot is "blocked" by going "off-hook", but not sending ANI/DNIS and remaining in that state no matter remote state.
 +
 
 +
This is also the default state for a newly created timeslot.
 +
 
 +
When this event is received on a non-idle timeslot (in a call, or establishing a call), it does not drop the call. Timeslot will be blocked only once the timeslot is back to "idle".
 +
 
 +
This state can only be canceled by [[#EVENT_APP_UNBLOCK_TIMESLOT|EVENT_APP_UNBLOCK_TIMESLOT]]
 +
 
 +
No specific parameter.
 +
 
 +
=== EVENT_APP_UNBLOCK_TIMESLOT ===
 +
Cancels a previous [[#EVENT_APP_BLOCK_TIMESLOT|EVENT_APP_BLOCK_TIMESLOT]], which (in most variants) requires to set our CAS bits to "on hook" (unless still in a call).
 +
 
 +
No specific parameter.
 +
 
 +
=== EVENT_TIMEOUT ===
 +
Indicates that the timer previously started with [[#ACTION_START_TIMER|ACTION_START_TIMER]] has expired. It's up to the script to determine the meaning of the timeout and take appropriate action.
 +
 
 +
No specific parameter.
  
 
== Stack functions that can be called by this script ==
 
== Stack functions that can be called by this script ==
 +
 +
The CAS stack provides a few functions that the script can call.
  
 
=== StackActionToString( in_Action ) ===
 
=== StackActionToString( in_Action ) ===
−
Returns string value of an action type.
+
<div id="stack_action_to_string">
−
Example:
+
Returns string value of an action type, generally used for printing debug traces.
−
local action = ACTION_END_SIGNALING
+
 
−
StackActionToString( action )
+
In the following example the StackAction function is remapped so that the script will print the action name in a trace every time that "StackAction" is called.
−
will return the string "ACTION_END_SIGNALING".
+
<pre>
−
+
-----------------------------------------------------------------------
 +
-- Wraps StackAction function calls with debug comments
 +
-----------------------------------------------------------------------
 +
CasR1.StackAction = StackAction
 +
function StackAction(name, ...)
 +
StackLogTrace(TRACE_LEVEL_2, "Calling StackAction '%s'", StackActionToString(name) )
 +
CasR1.StackAction(name, ...)
 +
end
 +
</pre>
  
 
=== StackEventToString( in_Event ) ===
 
=== StackEventToString( in_Event ) ===
−
Returns string value of an event type.
+
<div id="stack_event_to_string">
−
Example:
+
Returns string value of an event type, generally used for printing debug traces.
−
StackEventToString( in_Event )
+
−
will return the string "EVENT_TIMEOUT".
+
  
 +
Example:
 +
<pre>
 +
function HandleEvent( in_TimeslotCtx, in_EventType, ... )
 +
StackLogTrace
 +
(
 +
TRACE_LEVEL_3,
 +
"Event %s received",
 +
StackEventToString( in_EventType )
 +
)
 +
</pre>
  
−
=== 5.3 StackCauseToString( in_Cause ) ===
+
=== StackCauseToString( in_Cause ) ===
−
Returns string value of a release cause.
+
<div id="stack_cause_to_string">
−
Example:
+
Returns string value of a call release cause, generally used for printing debug traces.
−
my_release_cause = CAUSE_FWD_SEIZURE_COLLISION
+
−
StackCauseToString( my_release_cause )
+
−
will return the string "CAUSE_FWD_SEIZURE_COLLISION".
+
  
−
=== 5.4 StackLogTrace( in_TraceLevel, in_Format, ... ) ===
+
=== StackLogTrace( in_TraceLevel, in_Format, ... ) ===
−
Asks the stack to print a trace (generally debug traces).
+
<div id="stack_log_trace">
−
Traces will be sent to the "tblogtrace" application.
+
Will print a trace (generally debug traces).
−
Parameters:
+
 
−
in_TraceLevel:
+
Date/time, trunk number and timeslot number are automatically printed with this trace.
−
Level of the trace (see TRACE_LEVEL_* above)
+
 
−
in_Format:
+
These traces will be seen in the Toolpack [[Toolpack_Application:tblogtrace|tblogtrace]] application (and it's corresponding log file on the server's hard drive).
−
String that contains the trace to print, plus refernences
+
 
−
to other arguments ("printf" style format)
+
Parameters:
−
...:
+
<ul>
−
Values for printf-style refernces of in_Format.
+
<li>
−
Example:
+
in_TraceLevel:<br />
−
local cas_bits = 0x1100
+
Level of the trace (see [[#Trace_levels|TRACE_LEVEL]] )
−
StackLogTrace( TRACE_LEVEL_2, "Send CAS bits %08X", cas_bits )
+
</li>
−
will print "Send CAS bits 1100" to tblogtrace log.
+
<li>
−
+
in_Format:<br />
 +
String that contains the trace to print, plus references to other arguments ("printf" style format)
 +
</li>
 +
<li>
 +
...:<br />
 +
Values for printf-style refernces of in_Format.
 +
</li>
 +
</ul>
 +
 
 +
Example:
 +
<pre>
 +
local cas_bits = 0x1100
 +
StackLogTrace( TRACE_LEVEL_2, "Send CAS bits %08X", cas_bits )
 +
</pre>
  
 
=== StackAction( in_Action, ... ) ===
 
=== StackAction( in_Action, ... ) ===
−
This function executes the specified action (in some cases with
+
<div id="stack_action">
−
the specified action-specific arguments).
+
This function executes the specified action (in some cases with the specified action-specific arguments).
−
The action is done asynchronously, meaning that control will  
+
 
−
immediately return to the script. Events will be received later
+
The action is done asynchronously, meaning that control will immediately return to the script. Events will be received later according to the actions taken.
−
according to the actions taken.
+
 
−
Upon an event, the script may perform multiple actions (like
+
Upon an event, the script may perform multiple actions (like starting a timer, declaring the call "alerted" and sending CAS bits for example)
−
starting a timer, declarign the call "alerted" and sending
+
 
−
CAS bits for example)
+
Parameters :  
−
Parameters :  
+
<ul>
−
in_Action :
+
<li>
−
The action to perform.
+
in_Action:<br />
−
(see constants ACTION_* documented below)
+
The action to perform.<br />
−
... :
+
(see [[#Stack_actions|Stack Actions]] for list of available actions)
−
Variable number of action-specific arguments.
+
</li>
−
ACTION_END_SIGNALING:
+
<li>
−
Parameter:
+
...:<br />
−
- The call release cause to report.
+
Variable number of action-specific arguments..<br />
−
  See values "CAUSE_".
+
(see [[#Stack_actions|Stack Actions]] for description of each arguments specific to each action)
−
Indicates either that:
+
</li>
−
  - Application previously requested to terminate
+
</ul>
−
    the call (with EVENT_APP_END_SIGNALING), in
+
 
−
which case this action is used by the script
+
== Stack actions ==
−
to indicate that signaling is fully idle (local
+
=== ACTION_END_SIGNALING ===
−
CAS bits set to "idle", remote equipment  
+
Indicates either that:
−
has acknowledged too with "idle" CAS bits).
+
<ul>
−
  - Script wants to terminate the call
+
<li>
−
    (after remote equipment set CAS bits to "idle"
+
Application previously requested to terminate the call (with EVENT_APP_END_SIGNALING), in which case this action is used by the script to indicate that signaling is fully idle (local CAS bits set to "idle", remote equipment has acknowledged too with "idle" CAS bits).
−
or after an error in the script). After
+
</li>
−
sending ACTION_END_SIGNALING, the script must
+
<li>
−
wait until EVENT_APP_END_SIGNALING is
+
Script wants to terminate the call (after remote equipment set CAS bits to "idle" or after an error in the script). After sending ACTION_END_SIGNALING, the script must wait until EVENT_APP_END_SIGNALING is received, which confirms that application is ready to terminate the call. Only at that moment the script shall set it's CAS bits to "idle" value.
−
received, which confirms that application is
+
</li>
−
ready to terminate the cally. Only at that
+
</ul>
−
moment the script shall set it's CAS bits
+
 
−
to "idle" value.
+
Parameter:
−
ACTION_SET_CAS_BITS
+
<ol>
−
Parameter:
+
  <li>
−
- CAS bits to set (integer like 0x1111)
+
    The call release cause to report. (See [[#Call_release_causes|Call release causes])
−
Used to change the CAS bits that we are
+
  </li>
−
sending on current timeslot towawrd remote
+
</ol>
−
equipment.
+
 
−
ACTION_SEND_WINK
+
=== ACTION_SET_CAS_BITS ===
−
Parameters:
+
Changes the CAS bits that we're sending to the remote equipment.
−
- CAS bits to set during the "Wink"
+
 
−
(integer like 0x1111)
+
Parameter:
−
- Duration of the "Wink" (in milliseconds)
+
<ol>
−
Used to send a "Wink", which is temporary change of
+
  <li>
−
the CAS bits for few milliseconds, then back to
+
    CAS bits to set (integer like 0x1111)
−
initial CAS bits value.
+
  </li>
−
EVENT_WINK_COMPLETED will be received by
+
</ol>
−
the script once Wink has completed (CAS bits are
+
 
−
back to their initial value)
+
=== ACTION_SEND_WINK ===
−
ACTION_WAIT_WINK
+
Used to send a "Wink", which is temporary change of the CAS bits for few milliseconds, then back to initial CAS bits value.
−
Parameters:
+
 
−
- Expected CAS bits during the "Wink"
+
[[#EVENT_WINK_COMPLETED|EVENT_WINK_COMPLETED]] will be received by the script once Wink has completed (CAS bits are back to their initial value).
−
(integer like 0x1111)
+
Parameters:
−
- Minimum duration of the "Wink" (in ms)
+
<ol>
−
- Maximum duration of the "Wink" (in ms)
+
  <li>
−
Used to request a "Wink" detection.
+
    CAS bits to set during the "Wink" (integer like 0x1111)
−
Upon next CAS bits change from remote equipment,
+
  </li>
−
the stack will see if the bits match the Wink
+
  <li>
−
expected bits.
+
    Duration of the "Wink" (in milliseconds)
−
EVENT_WINK_DETECTED will be reported
+
  </li>
−
if CAS bits received from remote equipment change
+
</ol>
−
to the expected pattern for a duration within
+
 
−
specified range, then go back to original value.
+
=== ACTION_WAIT_WINK ===
−
Any other CAS bits change not deteced as a "Wink"
+
 
−
will be reported to the script by
+
Used to request a "Wink" detection.
−
EVENT_CAS_BITS_CHANGED (which will probably want
+
 
−
to drop the call because a Wink was expected)
+
Upon next CAS bits change from remote equipment, the stack will see if the bits match the Wink expected bits.
−
ACTION_SEND_TONE
+
 
−
Parameters:
+
[[#EVENT_WINK_DETECTED|EVENT_WINK_DETECTED]] will be reported if CAS bits received from remote equipment change to the expected pattern for a duration within specified range, then go back to original value.
−
- Digit (tone) to send.
+
 
−
(see "Digit format" below)
+
While waiting for a wink, any other CAS bits change not detected as a "Wink" will be reported to the script by [[#EVENT_CAS_BITS_CHANGED|EVENT_CAS_BITS_CHANGED]]
−
Used to send one digit (tone) toward remote
+
 
−
equipment. EVENT_TONE_SENT will be received
+
Parameters:
−
once the tone has been successfully sent.
+
<ol>
−
Not normally used in CASR1 standard variants.
+
  <li>
−
Note: This action is not used to send ANI/DNIS
+
    Expected CAS bits during the "Wink" (integer like 0x1111)
−
(calling/called numbers), it's used to
+
  </li>
−
send other tones that may be used within
+
  <li>
−
the current CASR1 variant call flow.
+
    Minimum duration of the "Wink" (in ms)
−
ACTION_SEND_ANI
+
  </li>
−
Parameters:
+
  <li>
−
- Prefix to send before ANI. Can be empty.
+
    Maximum duration of the "Wink" (in ms)
−
- Suffix to send after ANI. Can be empty.
+
  </li>
−
(see "Digit format" below)
+
</ol>
−
Used to send ANI (calling number) toward
+
 
−
remote equipment, using tones.
+
=== ACTION_SEND_TONE ===
−
A prefix may be inserted before ANI.
+
Used to send one digit (tone) toward remote equipment. [[#EVENT_TONE_SENT|EVENT_TONE_SENT]] will be received once the tone has been successfully sent.
−
A suffix is mandatory. It's transmitted after ANI.
+
Not normally used in CASR1 standard variants.
−
Remote equipment expects that suffix to determine
+
 
−
that the ANI has been entirely sent.
+
Note: This action is not used to send ANI/DNIS (calling/called numbers), it's used to send other tones that may be used within the current CASR1 variant call flow.
−
EVENT_ANI_SENT will be received once  
+
 
−
transmission of prefix + ANI + suffix completed
+
Parameter:
−
ACTION_SEND_DNIS
+
<ol>
−
Same as ACTION_SEND_ANI, but for sending DNIS
+
  <li>
−
(called number)
+
    Digit (tone) to send. See [[#tones_format|Tones mapping to ASCII characters]] for details about which ASCII character represents which tone.
−
ACTION_WAIT_ANI
+
  </li>
−
Parameters:
+
</ol>
−
- Prefix to expect before ANI. Can be empty.
+
 
−
- Suffix to expect after ANI. Can be empty only
+
=== ACTION_SEND_ANI ===
−
if next argument (nb expected digits) is set.
+
Used to send ANI (calling number) toward remote equipment.
−
(see "Digit format" below)
+
 
−
- Number of expected digits.
+
A prefix may be inserted before ANI, and a suffix maybe appended after the ANI.
−
Optional. Only required if suffix is empty.
+
 
−
Used to wait for ANI (calling number) from
+
[[#EVENT_ANI_SENT|EVENT_ANI_SENT]] will be received once transmission of prefix + ANI + suffix is completed.
−
remote equipment, by detecting tones.
+
 
−
A prefix may be expected before ANI.
+
Parameters:
−
A suffix is mandatory. It's received after ANI to
+
<ol>
−
indicate that the ANI has been entirely transmitted.
+
  <li>
−
EVENT_ANI_RECEIVED will be received if a
+
    Prefix to send before ANI. Can be empty.<br />
−
matching prefix + suffix are detected.
+
    See [[#tones_format|Tones mapping to ASCII characters]] for details about which ASCII character represents which tone.
−
ACTION_WAIT_DNIS
+
  </li>
−
Same as ACTION_WAIT_ANI, but for receiving DNIS
+
  <li>
−
(called number)
+
    Suffix to send after ANI. Can be empty.<br />
−
ACTION_SET_ANI
+
    See [[#tones_format|Tones mapping to ASCII characters]] for details about which ASCII character represents which tone.
−
Parameters:
+
  </li>
−
- ANI to set
+
</ol>
−
Used to replace the ANI detected by the stack with
+
 
−
this ANI provided by the script.
+
=== ACTION_SEND_DNIS ===
−
This action must be calld before action
+
Same as [[#ACTION_SEND_ANI|ACTION_SEND_ANI]], but for sending DNIS (called number)
−
TBX_CASR2VMLIB_CASR1_ACTION_REPORT_VALIDATE_CALL
+
 
−
(otherwise it's too late to set ANI)
+
=== ACTION_WAIT_ANI ===
−
Not normally used in CASR1 standard variants.
+
Used to wait for ANI (calling number) from remote equipment, by detecting tones.
−
ACTION_SET_DNIS
+
 
−
Same as ACTION_SET_ANI, but for DNIS (called number)
+
Detection methods for ANI:
−
ACTION_REPORT_SEIZURE
+
<ol>
−
No parameter.
+
  <li>
−
Tell the application that seizure (off-hook) has
+
    '''Prefix/suffix''' separators indicate the start and/or end of the transmission of ANI.<br />
−
been deteced on a timeslot.
+
    If prefix is detected, it's removed from the ANI. If not detected, it does not matter.<br />
−
ACTION_REPORT_VALIDATE_CALL
+
    If suffix is detected, it's removed from the ANI, and ANI is immediately reported as complete.<br />
−
No parameter.
+
    If suffix is not detected, then another ANI detection method may still trigger end of ANI (inter-digit timeout, or fixed number of digits)
−
Tell the application that ANI and/or DNIS have
+
  </li>
−
been successfully received, and we now have the
+
  <li>
−
information required to process this incoming call.
+
    '''Fixed expected number of digits'''<br />
−
ACTION_REPORT_ACCEPTED
+
    With that method, ANI or DNIS is considered complete when the specified number of digits have been received.
−
No parameter.
+
  </li>
−
Tell the application that a "forward" call has
+
  <li>
−
been accepted by remote equipment, often by
+
    '''Inter-digit timeout'''<br />
−
detecting a "Wink".
+
    With that method, as soon as there is more than this delay after receiving a digit, the ANI or DNIS is considered complete.
−
ACTION_REPORT_ALERTED
+
  </li>
−
No parameter.
+
</ol>
−
Tell the application that a "forward" call has
+
 
−
been alerted by remote equipment.
+
More than one of the methods above can be used.
−
On most variants, there is no specific indication
+
If none of these options are used, the script will consider that ANI is not used (won't be received, must not be sent).
−
from remote side, and this action must be taken
+
 
−
upon EVENT_DNIS_SENT.
+
Once ANI has been considered complete by one of the 3 methods above, then [[#EVENT_ANI_RECEIVED|EVENT_ANI_RECEIVED]] is reported to the script.
−
On other variants, a "Wink" may be awaited before
+
 
−
calling this action.
+
Parameters:
−
ACTION_REPORT_ANSWERED
+
<ol>
−
No parameter.
+
  <li>
−
Tell the application that a "forward" call has
+
    Prefix to expect before ANI. Can be empty. See explanation above.
−
been answered by remote equipment, generally
+
  </li>
−
because "off-hook" CAS bits have been received.
+
  <li>
−
ACTION_REPORT_BLOCKED
+
    Suffix to expect after ANI. Can be empty. See explanation above.
−
No parameter.
+
  </li>
−
Tells the application that the script considers
+
  <li>
−
the timeslot as "remotely blocked". This is the
+
    Number of expected digits. Set to 0 to ignore. See explanation above.
−
case when remote side goes "off hook" and remains
+
  </li>
−
in that state for some duration after we've
+
  <li>
−
returned to "on hook" on our side.
+
    Inter-digit timeout. Set to 0 to ignore. See explanation above.
−
ACTION_REPORT_UNBLOCKED
+
  </li>
−
NO parameter.
+
</ol>
−
Tells the application that the timeslot is no
+
 
−
more "remotely blocked", because remote
+
=== ACTION_WAIT_DNIS ===
−
equipment went "on hook" after we reported
+
Same as [[#ACTION_WAIT_ANI|ACTION_WAIT_ANI]], but for receiving DNIS (called number).
−
ACTION_REPORT_BLOCKED.
+
 
−
ACTION_START_TIMER
+
=== ACTION_SET_ANI ===
−
Parameter:
+
Used by a script that wants to provide the ANI (rather than using [[#ACTION_WAIT_ANI|ACTION_WAIT_ANI]] to receive it).
−
- Timer duration in milliseconds.
+
 
−
Starts a timer. EVENT_TIMEOUT will be
+
This function is not normally used. But it can be useful in some cases:
−
posted if the timer expires before
+
<ul>
−
ACTION_CANCEL_TIMER is called.
+
  <li>
−
ACTION_CANCEL_TIMER
+
    For incoming (backward) calls:
−
No parameter.
+
    <ul>
−
Cancels a timer previously started with
+
      <li>Script wants to provide a ANI on a network where no ANI is sent by the remote equipment.</li>
−
ACTION_START_TIMER.
+
      <li>Script wants to override the ANI detected ([[#ACTION_WAIT_ANI|ACTION_WAIT_ANI]]) by another one chosen by the script.</li>
−
+
      <li>Script wants to collect tones one by one ([[#EVENT_TONE_RECEIVED|EVENT_TONE_RECEIVED]], and built the ANI from these tones.</li>
−
Digit format:
+
    </ul>
−
The digit format (for sending tone or ANI/DNIS prefix/suffix)
+
  </li>
−
is represented by a string that contains up to 3 of the
+
  <li>
−
following characters: 0123456789ABCD*#
+
    For outgoing (forward) calls:
 +
    <ul>
 +
      <li>Script wants to override the ANI (calling number) provided by Toolpack when this outgoing call was initialized.</li>
 +
    </ul>
 +
  </li>
 +
</ul>
 +
 
 +
This function must be called before the ANI is used in the signalling process, which means:
 +
* For incoming (backward) calls: before [[#ACTION_REPORT_VALIDATE_CALL|ACTION_REPORT_VALIDATE_CALL]].
 +
* For outgoing (forward) calls: before [[#ACTION_SEND_ANI|ACTION_SEND_ANI]].
 +
 
 +
 
 +
Parameter:
 +
<ol>
 +
  <li>
 +
    ANI to set
 +
  </li>
 +
</ol>
 +
 
 +
=== ACTION_SET_DNIS ===
 +
Same as [[#ACTION_SET_ANI|ACTION_SET_ANI]], but for DNIS (called number).
 +
 
 +
=== ACTION_REPORT_SEIZURE ===
 +
Tell the application that seizure (off-hook) has been detected on a timeslot.
 +
 
 +
No parameter.
 +
 
 +
=== ACTION_REPORT_VALIDATE_CALL ===
 +
Tell the application that ANI and/or DNIS have been successfully received, and we now have the information required to process this incoming call.
 +
 
 +
No parameter.
 +
 
 +
=== ACTION_REPORT_ACCEPTED ===
 +
Tell the application that a "forward" call has been accepted by remote equipment, often by detecting a "Wink".
 +
 
 +
No parameter.
 +
 
 +
=== ACTION_REPORT_ALERTED ===
 +
Tell the application that a "forward" call has been alerted by remote equipment.
 +
 
 +
On most variants, there is no specific indication from remote side, and this action must be taken upon [[#EVENT_DNIS_SENT|EVENT_DNIS_SENT]].
 +
 
 +
On other variants, a "Wink" may be awaited before calling this action (variants where there is a second "Wink" after digits are successfully received by remote equipment).
 +
 
 +
No parameter.
 +
=== ACTION_REPORT_ANSWERED ===
 +
Tell the application that a "forward" call has been answered by remote equipment, generally because "off-hook" CAS bits have been received.
 +
 
 +
No parameter.
 +
 
 +
=== ACTION_REPORT_BLOCKED ===
 +
Tells the application that the script considers the timeslot as "remotely blocked".
 +
 
 +
This is generally the case when remote side goes "off hook" and does not send digits for a long time, without going back "on hook".
 +
 
 +
Reporting a timeslot as "remotely blocked" will inform Toolpack that this timeslot cannot be used to make outgoing calls. Toolpack can thus route outgoing calls accordingly.
 +
 
 +
No parameter.
 +
 
 +
=== ACTION_REPORT_UNBLOCKED ===
 +
Tells the application that the timeslot is no more "remotely blocked", because remote equipment went "on hook" after it was reported "remotely blocked.
 +
(in other words, this cancels [[#ACTION_REPORT_BLOCKED|ACTION_REPORT_BLOCKED]])
 +
 
 +
No parameter.
 +
 
 +
=== ACTION_START_TIMER ===
 +
Starts a timer.
 +
 
 +
[[#EVENT_TIMEOUT|EVENT_TIMEOUT]] will be posted if the timer expires before [[#ACTION_CANCEL_TIMER|ACTION_CANCEL_TIMER]] is called.
 +
 
 +
Starting a timer when another timer was already started will cancel previous timer and replace it with new timer.
 +
 
 +
Parameter:
 +
<ol>
 +
  <li>
 +
    Timer duration in milliseconds.
 +
  </li>
 +
</ol>
 +
 
 +
=== ACTION_CANCEL_TIMER ===
 +
Cancels a timer previously started with [[#ACTION_START_TIMER|ACTION_START_TIMER]].
 +
 
 +
No parameter.
 +
 
 +
== Debugging the script ==
 +
=== Validating LUA language syntax ===
 +
The LUA language syntax is automatically validated when saving the script from the Web Portal.
 +
 
 +
The Web Portal will refuse to save a script that has a LUA language syntax error.
 +
 
 +
=== Using log traces ===
 +
The CAS stack provides the [[#stack_log_trace|StackLogTrace]] function that allows the script to print traces through execution.
 +
 
 +
Traces can be of different levels (more or less verbose). It is recommended to leave traces at various levels through the script so it can be easily debugged "in the field" by simply changing the trace level of the CAS stack while testing a call.
 +
 
 +
It's also a good practice that the script prints "error" traces to report any error in the log. But be careful not to write error traces in the log for "normal" situations, like calls that fail due to answer timeout for example, as we don't want the logs to be filled out with error traces that correspond to a situation that's actually "normal" on a network.
 +
 
 +
==== Viewing traces ====
 +
All traces printed by the CAS script will be received by the Toolpack [[Toolpack_Application:tblogtrace|tblogtrace]] application, and written to disk on the host server in the corresponding log file.

Latest revision as of 11:54, 20 December 2017

This page explains how CASr1 script are implemented. You can read, modify, or create CASR1 scripts to adapt to different variants, or implement new variants.

Contents

Summary

Toolpack uses the LUA programming language to implement CAS scripts. The CAS scripts are interpreted by the TMG unit in order to handle calls.

A portion of the CAS state machine is implemented outside the script, in the CAS stack that runs on the TMG unit, although the script still offers a great level of flexibility to implement various CAS variants.

CASR1 vs CASR2 scripts

CASR1 variants and CASR2 variants both use LUA scripts stored in the same place in the Toolpack configuration Web Portal.

However, CASR1 and CASR2 scripts are quite different. They use different constants and function, and will have different "callback" functions called by the CAS stack on the TMG. The general architecture (state machine) of the scripts is also different.

In a few words:

CASR1 scripts need to:

  • Handle incoming CAS bits changes
  • Decide when to change sent CAS bits
  • Decide when to detect/send ANI/DNIS tones
  • Implement a state machine that follows the different call states, and report these states to the CAS stack

CASR2 scripts need to:

  • Define forward and backward digits to use
  • Map digits to various meanings
  • Handle received digits and how to handle then

The current page explains CASR1 scripts. For more information about CASR2 scripts, please refer to the following page: Web_Portal_Tutorial_Guide_v2.6#CASR2

Set the script type to CASR1

A CAS script be identified as a CASR1 script when the following variable is set: 

SCRIPT_TYPE="CASR1"

If this variable is missing, the script will be interpreted as "CASR2".

Provided scripts

Toolpack already supports multiple CAS variants through scripts that are installed in any new Toolpack installation:

Overview

Per-timeslot context

The CASR1 scripts works on a "per timeslot" basis. It's informed of each timeslot that is under it's control through callback function HandleNewTimeslot.

A context is provided with each timeslot, so the script can store "per-timeslot" variables in order to implement the state machine.

Per-timeslot events

Once a timeslot has been created in the script, the CAS stack will inform the script of any event on that timeslot (CAS bits changes and others). To each received event, the script will take one ore more action.

Per-timeslot actions

The CAS script can perform various actions on a timeslot, while it handles timeslot events.

For example, it can

  • change CAS bits (or send "wink")
  • report call state to the CAS stack (seizure, call alerting, call answered, call terminating, timeslot remotely blocked, etc.).
  • ask for ANI/DNIS detection
  • ask for transmission of ANI/DNIS
  • Start a timer
  • And more...

Per-timeslot state machine

It's up to the script implementation to define it's own states for handling the calls. The script is thus very flexible in the way it implements the CASR1 variant call flow.

The current document does not describe how CASR1 call flows are implemented (what are CAS bits, when and why to they "change", how calling/called numbers are exchanged, what is the call flow etc.) The reader shall find that information in the specifications for CASR1 variants.

The current document provides general information on available timeslot events and actions that allow to actually implement CASR1 variants.



Script entry points

There are 2 functions that the script must provide, and that will be called by the stack when appropriate:

(see documentation blow for detailed information)

Configurable global script constants

The script can define some constants required by the stack (though default values are provided if the script does not define these constants).

SCRIPT_TYPE

Defines the type of this sript. This constant is mandatory for CASR1 scripts. 

SCRIPT_TYPE 				= "CASR1"

ABCD_PATTERN_MATCH_MASK

Mask to apply to CAS bits detected from remote equipment (for bits 0xABCD). A bit which mask is set to 0 will be ignored and always reported as zero (0) to this script. This is useful in some cases when unused bits have undefined (and even sometimes toggeling!) values.

Default: 0x1111 

ABCD_PATTERN_MATCH_MASK 	= 0x1111

TONE_USE_DTMF

Indicates the type of tones must be used to send/receive AND/DNIS. Value of 1 stands for DTMF. Value of 0 defaults to MFR1.

Default: 1 (use DTMF) 

TONE_USE_DTMF			 	= 1

TONE_ON_TIME

Defines the "on time" (in ms) of tones used when sending ANI/DNIS.

Default: 60ms 

TONE_ON_TIME				= 60

TONE_OFF_TIME

Defines the "off time" (inter-digit delay)(in ms) of tones used when sending ANI/DNIS.

Default: 40ms 

TONE_OFF_TIME				= 50

TONE_LEVEL

Defines the audio power level (in DB) of tones used when sending ANI/DNIS, or dial tone.

Default: -10db 

TONE_LEVEL				= -10

TONE_VP_GROUP

Defines the type of tone detector/generator that will be used for CASR1 calls:

  • Group 0: Use DSP resources (for TMG that have DSP resources)
  • Group 1: Use VOIP resources (for TMG that have VOIP resources)

It may be required to change this value if using CASR1 scripts on TMG units that don't have either DSP or VOIP resources.

Default: 1 (VOIP resources) 

TONE_VP_GROUP				= 1


TX_DIAL_TONE

Defines if (and which) dial tone must be played on a backward (incoming) call. Empty string (or missing variable) results in no dial tone being played.

Default: No dial tone 

TX_DIAL_TONE			= "(350,440)"	-- This is default US dial tone

USE_FORCED_RELEASE

Defines if "forced release" option must be used to terminate non-answered backward (incoming) calls.

In most CASR1 variants, the CAS bits for a backward (incoming) calls remain "on-hook" until the call is answered (except for short "wink" periods). Because of that, it's not possible to indicate remote equipment that we want to terminate this incoming call, since bits are already "on hook".

The solution to that is to quickly set the CAS bits to "off-hook" then "on-hook", to indicate to remote side that we want to terminate the call.

This option should be used with care, because it may cause remote equipment to think the call has been answered for about 200ms. This could cause billing or statistics (ASR) calculation problems on the remote equipment if it does not expect that.

Default: 0 (Don't use forced release) 

TX_DIAL_TONE			= "(350,440)"	-- This is default US dial tone

Tones mapping to ASCII characters

DTMF mapping

DTMF tones are represented, in the script, as ASCII characters. (these are used to define ANI/DNIS prefix/suffix, or to explicitly provide the ANI/DNIS for a call).

Please refer to the following table to know which ASCII character is used to represent each existing DTMF tone: 

	
		'0'	->	DTMF Digit 0: 				941Hz + 1336Hz
		'1'	->	DTMF Digit 1: 				697Hz + 1209Hz
		'2'	->	DTMF Digit 2: 				697Hz + 1336Hz
		'3'	->	DTMF Digit 3: 				697Hz + 1477Hz
		'4'	->	DTMF Digit 4: 				770Hz + 1209Hz
		'5'	->	DTMF Digit 5: 				770Hz + 1336Hz
		'6'	->	DTMF Digit 6: 				770Hz + 1477Hz
		'7'	->	DTMF Digit 7: 				852Hz + 1209Hz
		'8'	->	DTMF Digit 8: 				852Hz + 1336Hz
		'9'	->	DTMF Digit 9: 				852Hz + 1477Hz
		'*'	->	DTMF Digit Star (*): 			941Hz + 1209Hz
		'#'	->	DTMF Digit Pound (#): 			941Hz + 1477Hz
		'A'	->	DTMF Digit A: 				697Hz + 1633Hz
		'B'	->	DTMF Digit B: 				770Hz + 1633Hz
		'C'	->	DTMF Digit C: 				852Hz + 1633Hz
		'D'	->	DTMF Digit D: 				941Hz + 1633Hz
		Alternative values for * and #:
		'E'	->	DTMF Digit Star (*): 			941Hz + 1209Hz
		'F'	->	DTMF Digit Pound (#): 			941Hz + 1477Hz

MFR1 mapping

MFR1 tones are represented, in the script, as ASCII characters. (these are used to define ANI/DNIS prefix/suffix, or to explicitly provide the ANI/DNIS for a call).

Please refer to the following table to know which ASCII character is used to represent each existing MFR1 tone: 

		'0'	->	MFR1 Digit 0: 				1300Hz + 1500Hz
		'1'	->	MFR1 Digit 1: 				700Hz  + 900Hz
		'2'	->	MFR1 Digit 2: 				700Hz  + 1100Hz
		'3'	->	MFR1 Digit 3: 				900Hz  + 1100Hz
		'4'	->	MFR1 Digit 4: 				700Hz  + 1300Hz
		'5'	->	MFR1 Digit 5: 				900Hz  + 1300Hz
		'6'	->	MFR1 Digit 6: 				1100Hz + 1300Hz
		'7'	->	MFR1 Digit 7: 				700Hz  + 1500Hz
		'8'	->	MFR1 Digit 8: 				900Hz  + 1500Hz
		'9'	->	MFR1 Digit 9: 				1100Hz + 1500Hz
		'*'	->	MFR1 KP (Start of pulsing):		1100Hz + 1700Hz
		'#'	->	MFR1 ST (End of pulsing):		1500Hz + 1700Hz
		'A'	->	MFR1 STI: 				900Hz  + 1700Hz
		'B'	->	MFR1 STII: 				1300Hz + 1700Hz
		'C'	->	MFR1 STIII: 				700Hz  + 1700Hz
		'D'	->	Not supported in MFR1

		Alternative characters:
		'E'	->	MFR1 KP (Start of pulsing):		1100Hz + 1700Hz
		'F'	->	MFR1 ST (End of pulsing):		1500Hz + 1700Hz

Static constants pushed by the stack, for usage in this script

Actions

Available actions for StackAction function:

Commonly used actions: 

ACTION_END_SIGNALING
ACTION_SET_CAS_BITS
ACTION_SEND_WINK
ACTION_WAIT_WINK
ACTION_SEND_ANI
ACTION_SEND_DNIS
ACTION_WAIT_ANI
ACTION_WAIT_DNIS
ACTION_REPORT_SEIZURE
ACTION_REPORT_VALIDATE_CALL
ACTION_REPORT_ACCEPTED
ACTION_REPORT_ALERTED
ACTION_REPORT_ANSWERED
ACTION_REPORT_BLOCKED
ACTION_REPORT_UNBLOCKED
ACTION_START_TIMER
ACTION_CANCEL_TIMER

Additional actions to implement special variants 

ACTION_SEND_TONE
ACTION_SET_ANI
ACTION_SET_DNIS

Events

Events received by this script on HandleEvent function:

Commonly used events: 

EVENT_CAS_BITS_CHANGED
EVENT_WINK_DETECTED
EVENT_WINK_COMPLETED
EVENT_ANI_RECEIVED
EVENT_DNIS_RECEIVED
EVENT_ANI_SENT
EVENT_DNIS_SENT
EVENT_APP_FWD_MAKE_CALL
EVENT_APP_BWD_MUST_ALERT
EVENT_APP_BWD_MUST_ANSWER
EVENT_APP_END_SIGNALING
EVENT_APP_BLOCK_TIMESLOT
EVENT_APP_UNBLOCK_TIMESLOT
EVENT_TIMEOUT

Additional events to implement special variants 

EVENT_TONE_RECEIVED
EVENT_TONE_SENT

Result codes

Result codes that HandleNewTimeslot or HandleEvent functions must return: 

RESULT_OK
RESULT_FAIL
RESULT_MISMATCH
RESULT_OUT_OF_RESOURCE
RESULT_INVALID_PARAM
RESULT_INVALID_STATE
RESULT_NOT_SUPPORTED
RESULT_TRUNK_RES_NOT_IDLE
RESULT_BLOCKED_LOCALLY
RESULT_BLOCKED_REMOTELY

Call release causes

Call release causes to use with ACTION_END_SIGNALING 

CAUSE_FWD_SEIZURE_COLLISION
CAUSE_FWD_SEIZURE_ACK_TIMEOUT
CAUSE_FWD_TONE_TIMEOUT
CAUSE_FWD_ANSWER_TIMEOUT
CAUSE_FWD_CALL_REFUSED
CAUSE_FWD_REJECT_CALL
CAUSE_FWD_HANG_UP
CAUSE_BWD_TONE_TIMEOUT
CAUSE_BWD_REJECT_CALL
CAUSE_BWD_CALL_REFUSED
CAUSE_BWD_ALERT_TIMEOUT
CAUSE_BWD_ANSWER_TIMEOUT
CAUSE_BWD_HANG_UP

Trace levels

Trace levels (used with function StackLogTrace).

  • Least verbose is TRACE_LEVEL_0 (almost never printed).
  • Most verbose is TRACE_LEVEL_4 (generally printed). 
TRACE_LEVEL_0
TRACE_LEVEL_1
TRACE_LEVEL_2
TRACE_LEVEL_3
TRACE_LEVEL_4
TRACE_LEVEL_ALWAYS
TRACE_LEVEL_ERROR

Mandatory functions to implement in this script

The script must provide the following mandatory functions, that will be called by the CAS stack at appropriate moments.

HandleNewTimeslot( in_TimeslotCtx, in_InitialCasBits )

This function is called to prepare a new timeslot so it's ready to be used to receive events and eventually handle a CASR1 call.

When this function is called, the timeslot must be initially be considered "locally blocked (and CAS bits must be set to "off-hook" state). The stack will later send EVENT_APP_UNBLOCK_TIMESLOT when it's time to go "on-hook" and be ready to make calls.

in_TimeslotCtx

Context containing variables for this timeslot. This context is a LUA table. This table already contains two values:

  • ["TrunkNumber"]
  • ["TimeslotNumber"]

The script can store it's own LUA variables here (like the "call state"), which will be accessible for any event on this timeslot.

in_InitialCasBits

The initial states of CAS bits received from remote equipment (integer like 0x1111)

HandleEvent( in_TimeslotCtx, in_EventType, ... )

This function reports that an event occurred on a timeslot.

in_TimeslotCtx

Timeslot context used by the script to store any timeslot-related information, like the "call state".

This is the table that was passed to HandleNewTimeslot.

in_EventType

The type of the event that was just received

See below for list of events that can be received: CASR1 script events

...

Variable number of parameters, that depend on event type.

To access these parameters, the LUA syntax is as follows: 

	-- Create an array with the variable number of arguments:
	local args = {...}
	-- Accessing the first argument
	local first_argument_value = args[1]

Return value

This function must return RESULT_OK, or one of the return codes defined above.

This result code tells to the stack if the event was properly handled by the script. Upon non-OK code, the stack may decide to terminate the call, assuming the script is incomplete and did not expect the event.

Please note that RESULT_OK is normally returned even in case of events that make the call fail or be dropped. The purpose of this result code is not to indicate if the event cause a call to be dropped, but rather to indicate that the script really does not know what to do with the received event.

CASR1 script events

The CASR1 script will receive (and must handle) the following events (received in function HandleEvent

EVENT_CAS_BITS_CHANGED

Indicates that new CAS bits have been received from remote equipment.

Parameters:

  1. Received CAS bits (integer like 0x1111)
    Indicates that CAS bits values received by remote equipment have changed.

EVENT_WINK_DETECTED

Indicates that a "Wink" has been detected. This event can only follow ACTION_WAIT_WINK.

No specific parameter.

EVENT_WINK_COMPLETED

Indicates that a "Wink" has been sent successfully. This event can only follow ACTION_SEND_WINK.

No specific parameter.

EVENT_TONE_RECEIVED

Indicates that a tone was detected.

Not normally used in CASR1 standard variants, because most variants can rely on ACTION_WAIT_ANI or ACTION_WAIT_DNIS to collect calling/called numbers in one single action.

And thus this event will not report tones that are collected by the CAS stack as part of ACTION_WAIT_ANI or ACTION_WAIT_DNIS.

Parameters:

  1. A one-character string that represents the received tone (digit).
    See Tones mapping to ASCII characters for details about which ASCII character represents which tone.

EVENT_ANI_RECEIVED

Indicates that ANI (calling number) has been sent received (prefix/suffix detected). This event can only follow ACTION_WAIT_ANI.

Note: The received ANI/DNIS digits are not passed to the script as EVENT_TONE_RECEIVED. Instead, the stack stores them as the 'calling number' which will be reported to the application upon ACTION_REPORT_VALIDATE_CALL

No specific parameter.

EVENT_DNIS_RECEIVED

Same as EVENT_ANI_RECEIVED, but for DNIS (called number)

EVENT_TONE_SENT

Indicates that a tone (digit) as been sent successfully following ACTION_SEND_TONE. Not normally used in CASR1 standard variants.

No specific parameter.

EVENT_ANI_SENT

Indicates that ANI (calling number) has been sent successfully (all tones played). This event can only follow ACTION_SEND_ANI. No specific parameter.

EVENT_DNIS_SENT

Same as EVENT_ANI_SENT, but for DNIS (called number)

EVENT_APP_FWD_MAKE_CALL

Indicate that a new "forward" call must be made.

The script shall take appropriate actions to initiate a new call (most likely change the CAS bits to the "off hook" state).

No specific parameter.

EVENT_APP_BWD_MUST_ALERT

Indicates that this "backward" call must now be set to "alerted" state (meaning we have accepted the call, and received required information to proceed).

The decision of when to alert the call is made by the application, and at that moment the script receives this event so it can take appropriate actions to alert a "backward" call. (in most variants, there is nothing to do, on some variants, a "Wink" may be sent).

No specific parameter.

EVENT_APP_BWD_MUST_ANSWER

Indicates that this "backward" call must now be set to "answered" state.

The decision of when set the call "answered" is made by the application, and at that moment the script receives this event so it can take appropriate actions to answer. (in most variants, CAS bits must be set to "off hook" pattern).

No specific parameter.

EVENT_APP_END_SIGNALING

Indicates either that:

  • Application requests to terminate the call.
    The script then take appropriate action, like sending CAS bits to "idle" state, wait for remote equipment to acknowledge, then at the end use ACTION_END_SIGNALING to confirm that termination is completed.
  • Script had already previously called ACTION_END_SIGNALING, (after remote equipment set CAS bits to "idle" or after an error in the script), in which case this event confirms that the application is also ready to terminate the call.
    The script generally returns to "idle" state after that event.

No specific parameter.

EVENT_APP_BLOCK_TIMESLOT

Indicates that the timeslot must be locally blocked, the next time it becomes "idle".

On most variants where this is supported, a timeslot is "blocked" by going "off-hook", but not sending ANI/DNIS and remaining in that state no matter remote state.

This is also the default state for a newly created timeslot.

When this event is received on a non-idle timeslot (in a call, or establishing a call), it does not drop the call. Timeslot will be blocked only once the timeslot is back to "idle".

This state can only be canceled by EVENT_APP_UNBLOCK_TIMESLOT

No specific parameter.

EVENT_APP_UNBLOCK_TIMESLOT

Cancels a previous EVENT_APP_BLOCK_TIMESLOT, which (in most variants) requires to set our CAS bits to "on hook" (unless still in a call).

No specific parameter.

EVENT_TIMEOUT

Indicates that the timer previously started with ACTION_START_TIMER has expired. It's up to the script to determine the meaning of the timeout and take appropriate action.

No specific parameter.

Stack functions that can be called by this script

The CAS stack provides a few functions that the script can call.

StackActionToString( in_Action )

Returns string value of an action type, generally used for printing debug traces.

In the following example the StackAction function is remapped so that the script will print the action name in a trace every time that "StackAction" is called. 

-----------------------------------------------------------------------
--	Wraps StackAction function calls with debug comments
-----------------------------------------------------------------------
CasR1.StackAction = StackAction
function StackAction(name, ...)	
	StackLogTrace(TRACE_LEVEL_2, "Calling StackAction '%s'", StackActionToString(name) )
	CasR1.StackAction(name, ...)
end

StackEventToString( in_Event )

Returns string value of an event type, generally used for printing debug traces.

Example: 

function HandleEvent( in_TimeslotCtx, in_EventType, ... )
	StackLogTrace
	(
		TRACE_LEVEL_3, 
		"Event %s received",
		StackEventToString( in_EventType )
	)

StackCauseToString( in_Cause )

Returns string value of a call release cause, generally used for printing debug traces.

StackLogTrace( in_TraceLevel, in_Format, ... )

Will print a trace (generally debug traces).

Date/time, trunk number and timeslot number are automatically printed with this trace.

These traces will be seen in the Toolpack tblogtrace application (and it's corresponding log file on the server's hard drive).

Parameters:

  • in_TraceLevel:
    Level of the trace (see TRACE_LEVEL )
  • in_Format:
    String that contains the trace to print, plus references to other arguments ("printf" style format)
  • ...:
    Values for printf-style refernces of in_Format.

Example: 

	local cas_bits = 0x1100
	StackLogTrace( TRACE_LEVEL_2, "Send CAS bits %08X", cas_bits )

StackAction( in_Action, ... )

This function executes the specified action (in some cases with the specified action-specific arguments).

The action is done asynchronously, meaning that control will immediately return to the script. Events will be received later according to the actions taken.

Upon an event, the script may perform multiple actions (like starting a timer, declaring the call "alerted" and sending CAS bits for example)

Parameters :

  • in_Action:
    The action to perform.
    (see Stack Actions for list of available actions)
  • ...:
    Variable number of action-specific arguments..
    (see Stack Actions for description of each arguments specific to each action)

Stack actions

ACTION_END_SIGNALING

Indicates either that:

  • Application previously requested to terminate the call (with EVENT_APP_END_SIGNALING), in which case this action is used by the script to indicate that signaling is fully idle (local CAS bits set to "idle", remote equipment has acknowledged too with "idle" CAS bits).
  • Script wants to terminate the call (after remote equipment set CAS bits to "idle" or after an error in the script). After sending ACTION_END_SIGNALING, the script must wait until EVENT_APP_END_SIGNALING is received, which confirms that application is ready to terminate the call. Only at that moment the script shall set it's CAS bits to "idle" value.

Parameter:

  1. The call release cause to report. (See [[#Call_release_causes|Call release causes])

ACTION_SET_CAS_BITS

Changes the CAS bits that we're sending to the remote equipment.

Parameter:

  1. CAS bits to set (integer like 0x1111)

ACTION_SEND_WINK

Used to send a "Wink", which is temporary change of the CAS bits for few milliseconds, then back to initial CAS bits value.

EVENT_WINK_COMPLETED will be received by the script once Wink has completed (CAS bits are back to their initial value). Parameters:

  1. CAS bits to set during the "Wink" (integer like 0x1111)
  2. Duration of the "Wink" (in milliseconds)

ACTION_WAIT_WINK

Used to request a "Wink" detection.

Upon next CAS bits change from remote equipment, the stack will see if the bits match the Wink expected bits.

EVENT_WINK_DETECTED will be reported if CAS bits received from remote equipment change to the expected pattern for a duration within specified range, then go back to original value.

While waiting for a wink, any other CAS bits change not detected as a "Wink" will be reported to the script by EVENT_CAS_BITS_CHANGED

Parameters:

  1. Expected CAS bits during the "Wink" (integer like 0x1111)
  2. Minimum duration of the "Wink" (in ms)
  3. Maximum duration of the "Wink" (in ms)

ACTION_SEND_TONE

Used to send one digit (tone) toward remote equipment. EVENT_TONE_SENT will be received once the tone has been successfully sent. Not normally used in CASR1 standard variants.

Note: This action is not used to send ANI/DNIS (calling/called numbers), it's used to send other tones that may be used within the current CASR1 variant call flow.

Parameter:

  1. Digit (tone) to send. See Tones mapping to ASCII characters for details about which ASCII character represents which tone.

ACTION_SEND_ANI

Used to send ANI (calling number) toward remote equipment.

A prefix may be inserted before ANI, and a suffix maybe appended after the ANI.

EVENT_ANI_SENT will be received once transmission of prefix + ANI + suffix is completed.

Parameters:

  1. Prefix to send before ANI. Can be empty.
    See Tones mapping to ASCII characters for details about which ASCII character represents which tone.
  2. Suffix to send after ANI. Can be empty.
    See Tones mapping to ASCII characters for details about which ASCII character represents which tone.

ACTION_SEND_DNIS

Same as ACTION_SEND_ANI, but for sending DNIS (called number)

ACTION_WAIT_ANI

Used to wait for ANI (calling number) from remote equipment, by detecting tones.

Detection methods for ANI:

  1. Prefix/suffix separators indicate the start and/or end of the transmission of ANI.
    If prefix is detected, it's removed from the ANI. If not detected, it does not matter.
    If suffix is detected, it's removed from the ANI, and ANI is immediately reported as complete.
    If suffix is not detected, then another ANI detection method may still trigger end of ANI (inter-digit timeout, or fixed number of digits)
  2. Fixed expected number of digits
    With that method, ANI or DNIS is considered complete when the specified number of digits have been received.
  3. Inter-digit timeout
    With that method, as soon as there is more than this delay after receiving a digit, the ANI or DNIS is considered complete.

More than one of the methods above can be used. If none of these options are used, the script will consider that ANI is not used (won't be received, must not be sent).

Once ANI has been considered complete by one of the 3 methods above, then EVENT_ANI_RECEIVED is reported to the script.

Parameters:

  1. Prefix to expect before ANI. Can be empty. See explanation above.
  2. Suffix to expect after ANI. Can be empty. See explanation above.
  3. Number of expected digits. Set to 0 to ignore. See explanation above.
  4. Inter-digit timeout. Set to 0 to ignore. See explanation above.

ACTION_WAIT_DNIS

Same as ACTION_WAIT_ANI, but for receiving DNIS (called number).

ACTION_SET_ANI

Used by a script that wants to provide the ANI (rather than using ACTION_WAIT_ANI to receive it).

This function is not normally used. But it can be useful in some cases:

  • For incoming (backward) calls:
    • Script wants to provide a ANI on a network where no ANI is sent by the remote equipment.
    • Script wants to override the ANI detected (ACTION_WAIT_ANI) by another one chosen by the script.
    • Script wants to collect tones one by one (EVENT_TONE_RECEIVED, and built the ANI from these tones.
  • For outgoing (forward) calls:
    • Script wants to override the ANI (calling number) provided by Toolpack when this outgoing call was initialized.

This function must be called before the ANI is used in the signalling process, which means:


Parameter:

  1. ANI to set

ACTION_SET_DNIS

Same as ACTION_SET_ANI, but for DNIS (called number).

ACTION_REPORT_SEIZURE

Tell the application that seizure (off-hook) has been detected on a timeslot.

No parameter.

ACTION_REPORT_VALIDATE_CALL

Tell the application that ANI and/or DNIS have been successfully received, and we now have the information required to process this incoming call.

No parameter.

ACTION_REPORT_ACCEPTED

Tell the application that a "forward" call has been accepted by remote equipment, often by detecting a "Wink".

No parameter.

ACTION_REPORT_ALERTED

Tell the application that a "forward" call has been alerted by remote equipment.

On most variants, there is no specific indication from remote side, and this action must be taken upon EVENT_DNIS_SENT.

On other variants, a "Wink" may be awaited before calling this action (variants where there is a second "Wink" after digits are successfully received by remote equipment).

No parameter.

ACTION_REPORT_ANSWERED

Tell the application that a "forward" call has been answered by remote equipment, generally because "off-hook" CAS bits have been received.

No parameter.

ACTION_REPORT_BLOCKED

Tells the application that the script considers the timeslot as "remotely blocked".

This is generally the case when remote side goes "off hook" and does not send digits for a long time, without going back "on hook".

Reporting a timeslot as "remotely blocked" will inform Toolpack that this timeslot cannot be used to make outgoing calls. Toolpack can thus route outgoing calls accordingly.

No parameter.

ACTION_REPORT_UNBLOCKED

Tells the application that the timeslot is no more "remotely blocked", because remote equipment went "on hook" after it was reported "remotely blocked. (in other words, this cancels ACTION_REPORT_BLOCKED)

No parameter.

ACTION_START_TIMER

Starts a timer.

EVENT_TIMEOUT will be posted if the timer expires before ACTION_CANCEL_TIMER is called.

Starting a timer when another timer was already started will cancel previous timer and replace it with new timer.

Parameter:

  1. Timer duration in milliseconds.

ACTION_CANCEL_TIMER

Cancels a timer previously started with ACTION_START_TIMER.

No parameter.

Debugging the script

Validating LUA language syntax

The LUA language syntax is automatically validated when saving the script from the Web Portal.

The Web Portal will refuse to save a script that has a LUA language syntax error.

Using log traces

The CAS stack provides the StackLogTrace function that allows the script to print traces through execution.

Traces can be of different levels (more or less verbose). It is recommended to leave traces at various levels through the script so it can be easily debugged "in the field" by simply changing the trace level of the CAS stack while testing a call.

It's also a good practice that the script prints "error" traces to report any error in the log. But be careful not to write error traces in the log for "normal" situations, like calls that fail due to answer timeout for example, as we don't want the logs to be filled out with error traces that correspond to a situation that's actually "normal" on a network.

Viewing traces

All traces printed by the CAS script will be received by the Toolpack tblogtrace application, and written to disk on the host server in the corresponding log file.
Retrieved from "https://docs.telcobridges.com/mediawiki/index.php?title=CASr1_scripting&oldid=24378"
Personal tools