This page contains information about SmartMedia CAS R2 variant scripting.

Refer to the default script (itu.lua) in the Web Portal for a complete working variant script example.

Overview

CAS R2 signaling is done in two parts: line signaling and register signaling. In CAS R2 for E1 trunks, line signaling uses a single timeslot to communicate call states (such as off-hook, answering) for the remaining timeslots. Register signaling is the exchange of MFR2 tones to convey information such as the calling number, called number and calling party category. SmartMedia CAS R2 scripts allow complete customization of the register signaling process, while having some characteristics of the line signaling process customizable. Scripts also contain information relative to the conversion of register signaling data - group B signals and categories - into a format that the application can interpret. The scripting language is Lua.

Mandatory elements

In order for CAS R2 variant scripts to work, some variables, tables and events must be defined from within scripts. All of the following elements are required; if one of these elements is not present, it will not be possible to save the script in the Web Portal or load it on the adapter.

VARIANT_ID

The VARIANT_ID variable must be filled to distinguish variants from another. More precisely, it is used when transporting group B and category information with calls in order to possibly convert information meaning across variants.

Default CAS R2 SmartMedia scripts have variant IDs starting from 1. To avoid future conflicts, user scripts variant IDs should be prefixed with a sufficiently high value. For example, a modified ITU variant could have a ID equal to 0x0001001. Scripts may only share the same variant ID as other scripts if and only if the category and group B meanings are exactly identical.

Group B conversion information

Group B conversion information in scripts is used to convert group B information between CAS R2 variants and between other signaling types. The following elements must be filled so that these conversions can be completed successfully.

GROUPB_DIGIT_TO_MEANING

Each GROUPB_DIGIT_TO_MEANING table element must contain two values: a digit and a meaning. The digit must be a valid digit value (1 to 15) and the meaning must be a valid meaning (see Group B meanings). Each digit must be present in the table.

This table is used to convert group B digits to meaning in the context of an outgoing call. For a given digit, the specified meaning will be propagated to the application.

GROUPB_MEANING_TO_DIGIT

Each GROUPB_MEANING_TO_DIGIT table element must contain two values: a meaning and a digit. Meanings must not appear more than once in the table.

This table is used to convert meanings to digits for an incoming call. This is mostly used for calls where the other leg belongs to another signaling type, although it will be used if the other leg's signaling type is CAS R2 but the variant is different and there was no match in the GROUPB_OTHER_DIGITS table.

If a meaning is not found in this table, the meaning corresponding to GROUPB_DEFAULT_DIGIT will be used.

GROUPB_DEFAULT_DIGIT

This variable must be filled with a valid digit value. It will be used when lookups in the GROUPB_MEANING_TO_DIGIT table fail.

GROUPB_OTHER_DIGITS

Each GROUPB_OTHER_DIGITS table element must contain three values: a variant ID and two valid digit values. This table may be empty but cannot be omitted.

This table is used to convert a variant ID and a digit combination to a digit for the current variant in an outgoing call scenario.

Category conversion information

Category conversion information in scripts is used to convert category information between CAS R2 variants and between other signaling types. The following elements must be filled so that these conversions can be completed successfully.

The pattern used to handle categories is identical to the one used for group B conversions.

CATEGORY_DIGIT_TO_MEANING

Each CATEGORY_DIGIT_TO_MEANING table element must contain two values: a digit and a meaning. The digit must be a valid digit value (1 to 15) and the meaning must be a valid meaning (see Category meanings). Each digit must be present in the table.

This table is used to convert category digits to meaning in the context of an outgoing call. For a given digit, the specified meaning will be propagated to the application.

CATEGORY_MEANING_TO_DIGIT

Each CATEGORY_MEANING_TO_DIGIT table element must contain two values: a meaning and a digit. Meanings must not appear more than once in the table.

This table is used to convert meanings to digits for an incoming call. This is mostly used for calls where the other leg belongs to another signaling type, although it will be used if the other leg's signaling type is CAS R2 but the variant is different and there was no match in the CATEGORY_OTHER_DIGITS table.

If a meaning is not found in this table, the meaning corresponding to CATEGORY_DEFAULT_DIGIT will be used.

CATEGORY_DEFAULT_DIGIT

This variable must be filled with a valid digit value. It will be used when lookups in the CATEGORY_MEANING_TO_DIGIT table fail.

CATEGORY_OTHER_DIGITS

Each CATEGORY_OTHER_DIGITS table element must contain three values: a variant ID and two valid digit values. This table may be empty but cannot be omitted.

This table is used to convert a variant ID and a digit combination to a digit for the current variant in an outgoing call scenario.

Event handlers

Four register signaling event handlers must be defined in the script.

Call context table

Each event handler will have a table passed as a parameter. This table is the call context table, and contains critical information about the state of the call. Once calls are created (through Bwd_HandleNewCall and Fwd_HandleNewCall), the script must initialize the table with its own state information. Also, for incoming calls, as they go on, the script must fill the table with the collected signaling information. For outgoing calls, the table already contains this signaling information. The signaling information fields contained in the table are as follows:

Return values

Each event handlers must return two values. The first value is the action to take immediately or shortly following the call of the event. It must be set to one of the four following values:

The second return value is the digit that accompanies the action, or NO_DIGIT if no digit must be emitted. Its meaning depends on the first return value.

Backward event handlers

The following event functions must be defined so that the CAS R2 stack can proceed with register signaling for incoming calls.

Bwd_HandleNewCall

The Bwd_HandleNewCall event is called whenever an incoming call is discovered on a timeslot. The purpose of this event is for the script to initialize local variables that will be used throughout the tone exchanges.

The event will have the call context table passed as a parameter. This table must be filled with the call state information required by the script for a new incoming call.

The event must return two values as described in the following table:

Bwd_HandleFwdSignal

The Bwd_HandleFwdSignal is called whenever a tone signal has been received, which is most likely the beginning of a compelled sequence.

The event will receive two parameters: the call context table (which was also passed to Bwd_HandleNewCall) and the received tone signal. The event must use the received tone signal to fill the DestinationNumber, OriginNumber and Category fields of the call context table.

The event must return two values as described in the following table:

Forward event handlers

The following event functions must be defined so that the CAS R2 stack can proceed with register signaling for outgoing calls.

Fwd_HandleNewCall

The Fwd_HandleNewCall event is called whenever an outgoing call is initiated on a timeslot. The purpose of this event is for the script to initialize local variables that will be used throughout the tone exchanges.

The event will have the call context table passed as a parameter. This table must be filled with the call state information required by the script for a new incoming call.

The event must return two values as described in the following table:

Fwd_HandleBwdSignal

The Fwd_HandleBwdSignal event is called whenever a tone signal has been received as a response to the current compelled sequence, which is most likely the beginning of a compelled sequence.

The event will receive two parameters: the call context table (which was also passed to Fwd_HandleNewCall) and the received tone signal. The event must use the available DestinationNumber, OriginNumber and Category fields from the call context table to communicate information to the incoming end.

The event must return two values as described in the following table:

Optional elements

The following elements may or may not be defined into a CAS R2 script.

SCRIPT_FILE_NAME

When affecting a value to this variable, the Web Portal will automatically replace the value to the script name followed by the script revision. If the following piece of code is added appended at the end of the script (this is done for default scripts), it will print a trace when loading a CAS R2 stack which can be recovered using an application.

VARIABLES

The VARIABLES table is used to declare variables which can be altered through the Toolpack Web Portal. Typically, variables declared here contain parameters that affect particular trunks. Each row of this table must contain three elements: the variable name, the variable's default value and the variable's description.

Good practices

• Use the local keyword for declaring variables as much as possible. Non-local variables will stay alive outside the scope of event handlers, which in turn will take more CPU time in the form of garbage collection.

Tone generation module selection

By default the VoIP DSP devices are used to generate the MFCR2 tones. If the unit has only IVR DSP devices, or for other reasons, this can be changed by adding these lines to the scripts:

BWD_VP_GROUP = 0
FWD_VP_GROUP = 0

Script keyword reference

Stack variables

Here is the list of stack variables. These variables are declared before the VARIABLES table is parsed in a script. A single script affectation will modify the value one of these variables. It is also possible to edit these variables in the Toolpack Web Portal.

Group B meanings

Here is the list of all defined group B meanings:

ACCEPT_CHARGE
ACCEPT_NO_CHARGE
REJECT_UNSPECIFIED
REJECT_UNALLOCATED_NUMBER
REJECT_NO_ROUTE_TO_NETWORK
REJECT_NO_ROUTE_TO_DESTINATION
REJECT_USER_BUSY
REJECT_SUBSCRIBER_ABSENT
REJECT_CALL_REJECTED
REJECT_NUMBER_CHANGED
REJECT_EXCHANGE_ROUTING_ERROR
REJECT_DESTINATION_OUT_OF_ORDER
REJECT_ADDRESS_INCOMPLETE
REJECT_NO_CIRCUIT_AVAILABLE
REJECT_NETWORK_OUT_OF_ORDER
REJECT_TEMPORARY_FAILURE
REJECT_SWITCHING_EQUIP_CONGESTION
REJECT_REQUESTED_CIRCUIT_NOT_AVAILABLE
REJECT_RESOURCE_UNAVAILABLE
REJECT_SERVICE_NOT_AVAILABLE
REJECT_CALL_IDENTITY_DOES_NOT_EXIST
REJECT_CALL_IDENTITY_IN_USE
REJECT_PROTOCOL_ERROR
REJECT_INTERWORKING_UNSPECIFIED

Category meanings

Here is the list of all defined category meanings:

CATEGORY_UNKNOWN
CATEGORY_OPERATOR_FRENCH
CATEGORY_OPERATOR_ENGLISH
CATEGORY_OPERATOR_GERMAN
CATEGORY_OPERATOR_RUSSIAN
CATEGORY_OPERATOR_SPANISH
CATEGORY_SUBSCRIBER
CATEGORY_SUBSCRIBER_WITH_PRIORITY
CATEGORY_DATA
CATEGORY_TEST
CATEGORY_PAYPHONE

References

• Lua Programming Language official website
• Line signaling Wikipedia article
• Register signaling Wikipedia article

Note: To activate a configuration, you must be the Root user or have a user access level of 0.

To activate a system configuration:

1. Select Systems from the navigation panel.

2. Click Edit next to the system you wish to activate,in order to access the System Configuration screen.

3. Activate the configuration:

• Enter a name for the system
• Under Activate Configuration:
  • Select a Configuration on which to run the system
  • Click Activate

Note: Make certain that Lock Active Configuration box (located at the top of the page) is 'unchecked. Failure to do so will prevent the configuration from being saved.

Verify that an activation confirmation message is displayed. The system will remind you to back up your database when you are done configuring (at top of screen, in yellow):

• T1/E1/J1 interfaces
• DS3 interfaces
• SONET/SDH interfaces

To create a new line interface:

1- Select Tdm Interfaces-->Line Interfaces from the navigation panel

2- Click Create New Line Interface to create a single interface ,or Create Multiple Line Interfaces to create many interfaces at once

3- Create the new line interface:

• Enter a name for the interface
• Set a type for the interface
• Set a local index for the line
• Select a length and an encoding scheme
• Click Create

4- Verify that the "Line interface was successfully created" message is displayed

The E1/J1/T1 line services are also known as trunks or spans.

To create a new line service:

1- Select Tdm Interfaces-->Line Interfaces from the navigation panel

2- Click Edit next to the line service for which you wish to create a line service

3- In the following window, click Create New Child Line Service (also, a number can be created at once by selecting Create Multiple Child Line Service)

4- Create the new Child Line Service:

• Enter a name for the new line
• Select an available local index, from the drop-down box
• Select appropriate framing and loopback modes
• Click Create

5- Navigate back to the line interface page, by following link displayed in the upper-left corner of the screen. The new line service should be displayed in the Line Services list

Step 1: Create different MTP3 Point Code for signaling and for voice Traffic

Click Point Codes in the navigation panel

Click Create New Point Code

Configure the new point code:

   Enter a name for the point code

   Select a point code type (select type-specific parameters)

   Select a point code length (14, 16, 24 bits)

   Enter a point code

   Click Create Repeat above steps for creating a voice traffic PC

Step 2: Create different MTP3 Routes for signaling and voice traffic

Click Create New Mtp3 Route in the MTP3 network configuration window:

Configure the new MTP3 route:

   Enter a name for the route

   Select a point code for the route

   Select a point type

   Check the Route to Adjacent box, if this route is directed to an adjacent network

   Click Create

Repeat above steps for voice traffic MTP3 Route.

Associate the newly created routes with your MTP3 linkset:

   Select a linkset from the list provided at the bottom of the route configuration window

   Click the "<<" button to associate the linkset with the newly created route

Route Retry feature is applied when more than one matching route is returned by the active routing script. Algorithm works in the following way:

• outgoing call will be made based on the first matching route
• if call fails while there are other matching routes left, new outgoing call attempt is made using next matching route 

Call attempt is considered failed in the following conditions:

• Call is terminated by remote side before reaching "Answered" state. Termination cause will determine if route retry is needed or not (enabled or disabled in 'Profiles -> Edit -> Reason Cause Mapping')
• Timeout occurs before call reaches specified call state (this timeout is ignored when last matching route is attempted)

Route retry timeout can be customized using two parameters:

• 'Menu -> Gateway -> Configuration -> Advanced Parameters -> Route retry timeout' - timeout delay in seconds to reach 'minimum call state' (value of 0 makes timeout never occur)
• 'Menu -> Gateway -> Configuration -> Advanced Parameters -> Route retry mode' - minimum call state to reach before the specified timeout occurs:
  • Call accepted
  • Call progress received
  • Call alerted
  • Call answered

If the timeout delay is expired before call reaches the specified state, call is considered failed and retry occurs. If the call reaches the minimal state, timeout isn't taken under consideration anymore, but explicit termination from remote side with error cause may still trigger retry with next route.

The 4 states above correspond to the following protocol-specific events:

SIP:
 Accepted: 100 Trying
 Progress: 183 with SDP (*)
 Alerted:  180 Ringing
 Answered: 200 OK
ISDN:
 Accepted: CALL PROCEEDING
 Progress: PROG
 Alerted:  ALERTING
 Answered: CONNECT
SS7:
 Accepted: <none>
 Progress: CPG
 Alerted:  ACM
 Answered: CONN/ANM
CAS R2:
 Accepted: SeizureAckCasBit
 Progress: <none>
 Alerted:  GroupB SuccessDigit
 Answered: AnswerCasBit

(*) 183 with SDP is usually interpreted as a "ALERT" (not a PROGRESS) unless explicitly configured on NAP level ("NAP -> Edit -> Advanced Parameters ->183 triggers call progress")

Route Retry termination cause configuration

To control if the route retry algorithm should stop or continue to the next route, each termination cause can be configured in the profile and set to either Continue or Stop.

Configuration is delivered via WebPortal in Profile setup 'Menu -> Profiles -> Edit -> Reason Cause Mapping -> Edit Reason Cause Mapping' and applied per NAP or Route basis.

Route Retry global configuration

Route Retry mode and timeout parameters can be configured globally, per NAP, or per Route. Configuration precedence takes following order:

1. Route configuration
2. NAP configuration
3. Global clonfiguration

The global Route Retry mode and timeout parameters can be found in the SmartMedia WebPortal Gateway application configuration menu:

• Go to the 'Menu -> Gateway -> Configuration' menu.
• Expand the 'Advanced Parameters' section
• Modify accordingly the values of 'Route retry mode' and 'Route retry timeout'
• Press Save

Route Retry per-NAP configuration

Per-NAP Route Retry mode and timeout parameters are configured by adding a custom 'NAP column':

• Go to the 'Menu -> Gateway -> Routes -> NAP Columns' menu.
• Click on Create New Nap Column in the 'Editing Naps' section
  • In the Name text box, enter 'route_retry_mode'
  • In the Type attributes text box, enter '|accept|call_progress|alert|answer'
  • Leave the Default text box blank
• Click Save
• Click again on Create New Nap Column in the 'Editing Naps' section
  • In the Name text box, enter 'route_retry_timeout'
  • In the Type attributes text box, enter 'integer'
  • Leave the Default text box blank
• Click Save

After creating above columns, each time you create or edit a NAP in NAP Columns menu, Route Retry mode and timeout paramters will be available. In case those are left blank for a particular NAP, global configuration will take precedence. Assigning a value in either of these parameters will override the global value for that parameter.

Route Retry per-route configuration

Per-route Route Retry mode and timeout parameters are configured by adding a custom 'Route column':

• Go to the 'Menu -> Gateway -> Routes' menu.
• Click on Create New Route Column in the 'Editing Routes' section
  
  • In the Name text box, enter 'route_retry_mode'
  • In the Type attributes text box, enter '|accept|call_progress|alert|answer'
  • Leave the Default text box blank
• Click Save
• Click again on Create New Route Column in the Editing Routes section
  • In the Name text box, enter 'route_retry_timeout'
  • In the Type attributes text box, enter 'integer'
  • Leave the Default text box blank
• Click Save

After creating above columns, each time you create or edit a Route, Route Retry mode and timeout parameters will be shown under Custom Params. In case those are left blank for a particular Route, global configuration will take precedence. Assigning a value in either of these parameters will override the global value for that parameter.

Customize Route retry parameters from routing script

Any part of the routing script that has access to the route object can read or modify below parameters:

• route[:route_retry_mode]
• route[:route_retry_timeout]

Those fields initially contain values of 'Custom Route Columns' (as explained above), but can be overwritten by the routing script.

STEP 1>>enable recording

STEP 2>>>retrieve recorded files

Select Call Trace under Maintenance.

STEP 3>>>

Select which recording you would like to analyze or download.

Step 4>>>>

Alternatively, you can ssh to the unit and run the following command:

# yum clean all
# yum update
# yum group update

Reboot the unit

# reboot