Project DiaStar Server - Administrator's Guide V2.2

From ProjectDiaStar

DiaStar™ Media Engine

The DiaStar™ Media Engine has already been installed as part of the ISO install, but for full operation some further configuration is needed.
You will need to install a DiaStar Media Engine license based on your required functionality (see Project DiaStar Server - Licenses).

License

Once you have obtained your DiaStar™ Media Engine license, copy it into the /usr/dialogic/data directory.
To install the license you need to connect to the DiaStar™ Media Engine Command Line Interpreter:

# telnet localhost 
      (user: root, password: public)

Once in the CLI, first make sure that the ipmedia subsystem is stopped:

CLI> conf system ipmedia stop

This may take a few minutes. When a confirmation message is seen, the license can be applied:

CLI> conf license activate <license_file_name.lic>

Configure

Further configuration depends on the type of system being built. Select the type of system you want to configure:

If the system used for the DiaStar Server will be also be used for Asterisk, make sure that the Asterisk dahdi_dummy driver is not installed. The DiaStar™ Media Engine also uses the system real time clock, but at a different clock speed. Remove it with:

# modprobe -r dahdi_dummy

If this is not done, the DiaStar™ Media Engine services will fail to start

Configuring the DiaStar™ Server

For correct operation of your DiaStar Server you need to create a config file. You will need to re-create this configuration file every time you install a new license. This includes the 4 port trial license.

The service tool is used to create the file /etc/diastar/diastar.conf and starts the service.

# service diastar config --<options>

Supported options:

--isdn (mutually exclusive with --ss7)
--ss7 or --ss7=<type><board-count> (mutually exclusive with --isdn)
--sip
--conf-parties=N

See Command Line Options for further details on these options.

Configuration File Generation Examples

Starting DiaStar with the standard 4 port trial license
This option will allow for four ports of IVVR and video conferencing:

# service diastar config --sip --conf-parties=4

SIP gateway / Multimedia server

# service diastar config --sip

ISDN gateway / SIP gateway & Multimedia server

# service diastar config --isdn --sip

SS7 gateway

# service diastar config --ss7

To generate configuration for SS7 dk devices a value should be added to the --ss7 option. This takes the form: <type><board-count> where type is E for E1 or T for T1 spans and board-count is the number of spans. For example:

# service diastar config --ss7=T3

would generate three boards: dkB1, dkB2, dkB3 each with 24 channels.

Note: The number of SS7 circuit groups found in the /usr/dialogic/SS7/config.txt file must match the number of dti E1 spans in the DiaStar config file. If you are using fewer circuit groups than spans, only channels on those accounted for in config.txt will open. Unwanted dti spans can be deleted or commented out in the DiaStar config file. You also need to adjust the "group" parameter to account for the dti channels that were eliminated. For example, "default=1-120" becomes "default=1-60" if 2 E1 spans are eliminated.

SIP Configuration

Once the --sip option has been used to create a DiaStar configuration file, some further adjustment of SIP parameters may be desired. Here is the default set of values that are generated:

[sip]
; Each subsection begins with a board name parameter.
; The name takes the form "iptBx" where x is 1..n
board = iptB1
 
; maxcalls sets the maximum number of concurrent calls.
maxcalls = 30
 
; bindaddr sets local IPv4 address.
bindaddr = 192.219.17.119
 
; bindaddr sets local port number [5060].
bindport = 5060

A single "virtual board" is set, which uses the eth0 device which is set to the IPv4 address specified. SIP signaling will be expected over UDP port 5060, and a maximum of 30 concurrent calls are possible.

The most common changes here is a change to the SIP port and an adjustment of maximum calls on that device. Note that maxcalls must not exceed the number of licensed SIP ports for the system or DiaStar will fail to start.

If a SIP registrar is used, the following parameters must be uncommented to register DiaStar with it:

; registraraddr is the IPv4 address of the Registrar.
registraraddr = 192.168.20.15
 
; registrarport is the SIP port number on the Registrar [5060].
registrarport = 5060

; registrarttl is registration time-to-live period in seconds.
registrarttl = 1800

; register is used to define an entity to be registered.
; It has four comma seperated values: name,identity,password,realm
; Multiple entities may be registered by using separate lines.
register = 1000,sip:1000@example.com,secret,diastar

All four parameters must be supplied for the register entry. They are defined as follows:

name - SIP user name
identity - full SIP URI for user name
secret - password for SIP digest authentication
realm - authentication realm

More information on DiaStar authentication can be found in section 4.23 here. The authorization parameters are sent only when challenged by the registrar and should be set to dummy values if authorization is not needed.

A SIP outbound proxy is often used in conjunction with a SIP registrar. Uncommenting and adjusting these lines will forward outbound SIP call requests to an outbound proxy server:

; proxyaddr is the IPv4 address of the proxy server.
proxyaddr = 192.168.20.15

; proxyport is the SIP port number on the proxy server [5060].
proxyport = 5060

SS7 Configuration

Most SS7 and SIGTRAN configuration is not directly done in the DiaStar config file. Instead, it is done as part of setting up the DiaStar Media Engine. See Project DiaStar_Server - SS7 Configuration

Video Conferencing Configuration

The --conf-parties=N option is used to generate configuration for a single N party conference. This shows all options and can be used as a base for customisation.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; The following section is used for conferences.
; This section is sub-divided with each subsection defining one virtual board.

[conference]
; Each subsection begins with a board name parameter.
; The name takes the form "mcxBx" where x is 1..n
board = mcxB1

; The id parameter is a globally unique number used by the client to identify a
; conference. Multiple conferences may be defined under each board sub-section.
; Its value comprises of one or more integers that identify individual
; conferences to which subsequent parameters are applied.
; e.g. id = 1,2,3  or id = 1-4
id = 1

; mode defines the how the conference is managed: adhoc | controlled.
mode = adhoc

; max_parties defines the maximum number of parties in the conference.
max_parties = 6

; layout defines the number of tiles to display: 1,4,6 or 9.
layout = 6

; caption determines if the caller's id is overlaid on their image.
caption = yes

; duration sets the time in milliseconds that the caption is displayed. Use
; 'infinite' without the quotes to display the caption for the entire call.
duration = 20000

; beep determines is a tone is played when a party joins/leaves a conf.
beep = yes

; clamp_dtmf determines if dtmf digits are suppressed.
clamp_dtmf = yes

; agc determines if automatic gain control should be used.
agc = yes

; ec determines if echo cancellation should be used.
ec = yes

Two conference modes are available - 'adhoc' and 'controlled'. The mode is set using the 'mode' parameter within a conference definition within the diastar.conf file. (see below)

An adhoc conference may be entered and exited at any time, by any participant. All conferees are equal participants.

A controlled conference has different roles for each conferee. The conference follows certain rules:

Only one controller per conference is allowed
A controlled conference must have a controller call active before other callers will be admitted
A non-controller participant take one of two other roles: presenter or attendee
Presenters (default) are full participants whose media are included in the conference output
Attendees are like 'listen-only' audio conference participants. They receive the conference output but do not have their media included in it.
A controller party must be established in order for presenters and attendees to be admitted to the conference
The controller's video is shown only when no presenters are present. This allows the controller to play a image/video to the attendees while they wait for the presenter(s) to arrive. The controller's audio is always included in the mix and should be muted locally as necessary.
When the controller call ends the conference itself ends and all other parties are automatically hung up

Remember that the DiaStar service must be restarted for changes to go into effect:

> service diastar restart

Custom Tone Detection

DiaStar can detect single tones and dual tones, with optional cadences, these detected both during a call and as part of the Call Progress Analysis feature The tones are defined using templates that are read in from files stored in a dedicated directory, the default location being /etc/diastar/tones.d. DiaStar reads in all files with a .conf extension. Each file may define multiple templates defined by familiar ini file style syntax.

The section name uniquely identifies the a template and is used to identify the tone in CPA results.

Template parameters (vary depending on mode):

  freq1    frequency 1 in Hz 
  fq1dev   frequency 1 deviation in Hz 
  freq2    frequency 2 in Hz 
  fq2dev   frequency 2 deviation in Hz 
  ontime   tone-on time in milliseconds
  ontdev   tone-on time deviation in milliseconds
  offtime  tone-off time in milliseconds
  offtdev  tone-off time deviation in milliseconds
  repcnt   number of repetitions of the cadence

Frequencies must be in the range 300Hz to 3k5Hz.
Dual tones with frequency components closer than approximately 63Hz cannot be detected, for these cases a single tone definition should be used.
The minimum ontime and offtime for cadence detection is 40ms on and 40ms off.

Example

 ; This file defines tone detector templates for use with DiaStar.
 ;
 ; Single tone
 
 [1kHz]
 freq1 = 1000
 fq1dev = 20
 
 ; Dual tone
 
 [C5A5]
 freq1 = 523
 fq1dev = 20
 freq2 = 794
 fq2dev = 20
 
 ; Single tone, cadenced.
 
 [1kHz-cadenced-500-500]
 freq1 = 1000
 fq1dev = 20
 ontime = 500
 ontdev = 50
 offtime = 500
 offtdev = 50
 
 ; Dual tone, cadenced
 
 [C5A5-cadenced-500-500]
 freq1 = 523
 fq1dev = 20
 freq2 = 794
 fq2dev = 20
 ontime = 500
 ontdev = 50
 offtime = 500
 offtdev = 50

Media Files

DiaStar uses a special directory layout to manage media files. The base of the directory structure is /var/lib/diastar/media, which may be changed using the path parameter within the media section of the diastar.conf file:

[media]
; path defines the name of the base directory for media files.
path = /var/lib/diastar/media

Each codec has its own directory and in the case of video codecs, directories for different formats/sizes. (Currently QCIF and CIF).

/var/lib/diastar/media/
`-- en_US
    |-- h263
    |   |-- CIF
    |   |-- QCIF
    |   `-- SUB-QCIF
    |-- mpv4-es
    |   |-- CIF
    |   |-- QCIF
    |   `-- SUB-QCIF
    |-- h264
    |   |-- CIF
    |   |-- QCIF
    |   `-- SUB-QCIF
    |-- jpeg
    |   |-- CIF
    |   |-- QCIF
    |   `-- SUB-QCIF
    |-- pcma
    |-- pcmu
    |-- g722
    |-- g729    
    `-- vox

VOX files must be encoded as: 8kHz, 16bit signed-linear pcm (equivalent to Asterisk's .sln format).

Here is an example of a directory structure for an application in US English called "pitching_demo" which contains video clips for H.263 and MPEG4 video and PCM audio:

/var/lib/diastar/media/en_US/h263/CIF/pitching_demo/main_menu_000.vid
/var/lib/diastar/media/en_US/h263/QCIF/pitching_demo/main_menu_000.vid
/var/lib/diastar/media/en_US/mpv4-es/CIF/pitching_demo/main_menu_000.vid
/var/lib/diastar/media/en_US/mpv4-es/QCIF/pitching_demo/main_menu_000.vid
/var/lib/diastar/media/en_US/vox/pitching_demo/main_menu_000.pcm

When playing a media file DiaStar will choose the file that most closely matches the codecs requested by the external SIP call.

Language support

The directory structure includes a language component. The default language is defined as en_US, which may be changed using the language parameter within the media section of the diastar.conf file:

;language defines the default language that is used when none has been specified by the client. Forms part of the file path.
language = en_US

The default language is used when the Woomera client does not specify a language in a play/record request, in the case of Asterisk the channel driver will always pass the channel's language variable.

Media File Management

When running DiaStar as an appliance it may useful to provide users with remote access to the media files. It is recommended that such access is limited to authenticated users with file system access restricted to the media directories only. One possible solution to this to use WebDAV. Web-based Distributed Authoring and Versioning is a set of extensions to the Hypertext Transfer Protocol (HTTP) that allows computer-users to edit and manage files collaboratively on remote World Wide Web servers. Here are instructions for setting up WebDAV on an Apache Web Server.

Tools and Utilities

The following open source packages can be useful for working with audio and video media files - converting and editing raw media preparing it for use with DiaStar.

Audio tools

Video tools

FFmpeg

The Tech Briefs section of the DiaStar Wiki contains further information on using various tools for multimedia production.

Video Overlays

DiaStar uses ImageMagick libraries to enable static images and and captions to be created dynamically by the client. This simplifies the task of building menus as it relieves the application developer from having to create every image in advance and having to maintain these as the application evolves. This feature may also be used to create simple presentations and games etc.

Images are built from three data sources:

a predefined document template, stored on the DiaStar server.
a predefined style definition, stored on the DiaStar server.
dynamic content data provided by the client at run-time.

DiaStar combines these to create a single jpeg image.

Document templates

Templates define the structural elements that make up the image.

Template files are stored in the directory: /etc/diastar/imagemaker.d and have names ending with the extension '.conf'. DiaStar will load all such named files in this directory at start up. These files use the familiar ini file format and may contain multiple template definitions. Each section defines a single template with the name of the section serving as globally unique name.

Example template document:

;-------------------------------------------------------------------------------
; Example ImageMaker document templates. 
; This file should be placed into the imagemaker.d directory. 
;-------------------------------------------------------------------------------
;
; Each section defines one document template.
;
; -----------------------------------------------------------------------------
; | Parameter | Value     | Description                                       |
; |-----------+-----------+---------------------------------------------------|
; |  style    | filename  | File containing the style information for the doc.|
; |-----------+-----------+---------------------------------------------------|
; |  text     | Unique id | A text element                                    |
; |-----------+-----------+---------------------------------------------------|
; |  list     | Unique id | A list element (text)                             |
; |-----------+-----------+---------------------------------------------------|
; |  image    | Unique id | An image element                                  |
; -----------------------------------------------------------------------------
;
; The following values are used internally and *must not* be used for 
; element ids: id document
;-------------------------------------------------------------------------------

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; A basic menu. Three elements: A title, list of options and a footer.
;
[menu]
;
style = /var/lib/diastar/imagemaker/style/menu.style
;
text = header
list = items
text = footer

; End of template

Template Styling

The appearance of the document template's elements is defined using a separate style document, which is located in the directory: /var/lib/diastar/imagemaker/style A single style document may be shared by multiple templates with style definitions for unknown elements simply being ignored. This behaviour allows several templates to use a single style document to provide a common theme.

The image generator supports many image formats including 'png'. Using the png format allows layering effects can be achieved through the use of transparency in background images. All image files used to compose the output image are stored in the directory: /var/lib/diastar/imagemaker/images

Example style document

;
; Style information for a full-screen menu.
;
; This file consists of a section named 'document' that defines the main style 
; for the doc. This followed by sections that specify style information for the
; corresponding element in the document that this style is applied to.
; Colors may be defined as: a css hex value, a css color name or transparent.
; See http://www.w3.org/TR/SVG/types.html#ColorKeywords for color names.
;
; height            height of document or element in pixels (CIF is 288).
; width             width of document or element in pixels (CIF is 352).
; top               offset of the top of an element relative to the document.
; left              offset of the left of an element relative to the document.
; padding           offset of the content relative to top and left.
; background-image  filename of an optional background image for the document.
; background-color  color used to fill the document or element background.
; color             color used for text.
; border-radius     corner radius in pixels.
; border-color      color used for element border.
; border-width      element border width in pixels.
; text-align        justification of the text (left, center, right).
; font-size         size of the text font  (small, medium, large).
;-------------------------------------------------------------------------------

[document]
height = 288
width = 352
background-image = /var/lib/diastar/imagemaker/images/diastar-background.png
background-color = #162660
color = #fff

[header]
height = 36
width = 328
top = 12
left = 12
padding = 4
background-color = aliceblue
color = #003
border-radius = 6
text-align = center
font-size = large

[items]
height = 184
width = 328
top = 60
left = 12
padding = 12
background-color = transparent
color = #fff
text-align = left
font-size = medium

[footer]
height = 20
width = 328
top = 260
left = 12
padding = 2
background-color = transparent
color = #9999a8
text-align = center
font-size = small

; End of style

Dynamic Content

Asterisk: Content is defined as the optional third parameter to the WoomeraBackground application. This borrows from the format used by url query strings to specify a number of ampersand separated parameters. Each parameter is defined as a name followed by an equals-sign followed by a value. The first parameter uses the reserved name 'id' which specifies the name of the template being used. The remaining parameters specify template element names and their respective contents. With the exception of the list element type, all elements take only a single value. The list element may be defined multiple times in order to define each item. If a parameter value needs to contain ampersand or equals characters, these must be passed as percent escaped hex values e.g. for an ampersand use %26.

Dial plan example using the 'menu' template shown previously:

exten => 637,1,Answer
exten => 637,n,Set(OVERLAY=id=menu&header=Menu du Jour&items=1 Pie&items=2 Chips&items=3 Burger&items=4 Pizza&items =5 Jacket&items=6 Panini&items=7 Pasta&footer=Tuesday)
exten => 637,n,WoomeraBackground(music,black,${OVERLAY})
exten => 637,n,Wait(60)
exten => 637,n,Hangup

Running the DiaStar™ Server

The preferred method of running DiaStar is to use the service tool.

Using the service tool

# service diastar start
# service diastar stop
# service diastar restart
# service diastar status

Alternatively, DiaStar can also be run from the command-line as either a console application or as a daemon. Console mode can be especially useful when debugging.

As a console application

 # diastar --console --conf=diastar.conf

Additional examples:

 # diastar --console -v --conf=diastar.conf
 # diastar --console -v --logdir=/var/log/diastar --conf=diastar.conf
 # diastar --console --probe --sip --conf=sip.conf

As a daemon

 # diastar --conf=diastar.conf