![Table of Contents
[ ii ]
Step 5: Install sound and music files 32
Compiling FreeSWITCH for Windows 33
Building the solution with MSVC/MSVCEE 33
Starting FreeSWITCH 37
Running FreeSWITCH in the background 38
Summary 40
Chapter 3: Test Driving the Default Configuration 41
Important concepts to understand 41
Putting FreeSWITCH to work 46
Controlling FreeSWITCH with the CLI 46
Configuring a SIP phone to work with FreeSWITCH 49
SIP settings 50
Testing the default Dialplan 57
Test calls for a single phone 57
Test calls for two or more phones 60
Summary 62
Chapter 4: SIP and the User Directory 63
Understanding the FreeSWITCH user directory 63
Working with the FreeSWITCH user directory 65
User features 66
Adding a user 67
Testing voicemail 70
Groups of users 72
Connecting to the world with gateways 74
Setting up a new gateway 74
Making calls 77
Receiving calls 78
Making calls without a gateway 78
SIP profiles and user agents 79
Summary 80
Chapter 5: Understanding the XML Dialplan 81
FreeSWITCH XML Dialplan elements 82
Call legs and channel variables 82
Accessing channel variables 84
Regular expressions 85
Contexts 86
Default 87
Public 87
Features 87
Extensions 88
Conditions 88
Actions and anti-actions 90](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-12-320.jpg)
![Table of Contents
[ iii ]
How Dialplan processing works 91
Creating a new extension 95
Important Dialplan applications 97
bridge 98
playback 98
say 98
play_and_get_digits 99
ivr 100
sleep 101
answer 101
hangup 101
set 101
Dialstring formats 102
Summary 104
Chapter 6: Using the Built-in XML IVR Engine 105
IVR engine overview 106
IVR XML configuration file 106
IVR menu definitions 107
greet-long 108
greet-short 108
invalid-sound 108
exit-sound 109
timeout 109
inter-digit-timeout 109
max-failures 110
max-timeouts 110
digit-len 110
tts-voice 110
tts-engine 110
confirm-key 111
IVR menu destinations 111
menu-exec-app 112
menu-exec-api 112
menu-play-sound 113
menu-back 113
menu-top 113
Routing calls to your IVR 114
Nesting IVRs 114
Using phrases with IVRs 115
Calling Phrase Macros 115](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-13-320.jpg)
![Table of Contents
[ iv ]
Phrase Macro examples: voicemail 116
Advanced routing 120
Summary 122
Chapter 7: Building IVR Applications with Lua 123
Getting started with Lua 124
Running Lua scripts from the Dialplan 124
Basic Lua syntax 125
Building voice applications 126
Simple IVR—interacting with the caller 129
Conditions and looping 131
Advanced IVR concepts 140
Connecting to a database with LuaSQL 141
Making a web call with curl 146
Lua patterns versus regular expressions 151
Scripting tips 152
Summary 153
Chapter 8: Advanced Dialplan Concepts 155
Dialplan overview 156
General Dialplan concepts 159
Contexts 160
Conditions 161
Actions 162
Putting it all together 163
XML Dialplan module review 164
Extensions 165
Conditions 166
Special condition variables 169
Inline execution 170
Actions and anti-actions 172
Pitfalls to avoid 172
XML Dialplan commands 174
Hunting versus executing 179
Utilizing variables 184
Testing variables with regular expressions 184
Caller profile fields 184
Channel variables 185
Channel variables and call setup 185
Global variables 187
Dialplan functions 187
Real-time condition evaluation 188
String conditioning 189](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-14-320.jpg)
![Table of Contents
[ ]
Database queries 189
SIP contact parameters 190
Set, export, and legs 191
Set versus export 191
Passing variables via call headers 192
XML Dialplan cookbook 192
Match by IP address and call a number 192
Match IP address and Caller ID 194
Match number and strip digits 194
Match number, strip digits, and add prefix 195
Call registered device 195
Try party A, then party B 196
Check for authenticated user 196
Route DIDs to extensions 197
Try a local extension, failback to voicemail 197
Alternate outbound gateways 198
Alternatives to XML 198
YAML 199
Asterisk Dialplan 199
Summary 200
Chapter 9: Controlling FreeSWITCH Externally 201
General overview 202
Event system architecture 203
Event-based modules 203
mod_event_socket 204
Configuring event socket settings 204
Reading events 205
Sending events 208
Events from the Dialplan 209
mod_event_multicast 210
Port/address 210
Bindings 211
TTL 211
mod_erlang_event 211
FreeSWITCH event system commands 211
auth password 211
api 212
bgapi 212
event 213
divert_events 214
filter 214
filter delete 215](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-15-320.jpg)
![Table of Contents
[ vi ]
sendevent 215
sendmsg uuid 216
execute 217
hangup 217
nomedia 218
log level 218
nolog 218
noevents 218
Event-based applications 218
FreeSWITCH Console application 219
PHP Socket connections 219
Perl Socket connections 219
Event Socket Library 220
Supported libraries 220
ESLObject 220
eslSetLogLevel($loglevel) 221
ESLevent object 221
serialize([$format]) 221
setPriority([$number]) 221
getHeader($header_name) 221
getBody() 221
getType() 221
addBody($value) 222
addHeader($header_name, $value) 222
delHeader($header_name) 222
firstHeader() 222
nextHeader() 222
ESLconnection object 222
new($host, $port, $password) 222
new($fd) 223
socketDescriptor() 223
connected() 223
getInfo() 223
send($command) 223
sendRecv($command) 223
api($command[, $arguments]) 224
bgapi($command[, $arguments]) 224
sendEvent($send_me) 224
recvEvent() 224
recvEventTimed($milliseconds) 224
filter($header, $value) 224
events($event_type,$value) 225
execute($app[, $arg][, $uuid]) 225
executeAsync($app[, $arg][, $uuid]) 225
setAsyncExecute($value) 225
setEventLock($value) 225
disconnect() 226](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-16-320.jpg)
![Table of Contents
[ vii ]
Events in practice 226
Event Socket Library example: running a command 226
Examples of sending events to FreeSWITCH 227
Setting phone lights 227
Rebooting a phone 228
Requesting phone reconfiguration 228
Custom notify messages 228
Summary 229
Chapter 10: Advanced Features and Further Reading 231
Multi-user conferencing 232
Configuration 232
Conference profiles 232
Caller controls 237
Advertise 237
Sending and receiving XMPP events 238
Connecting callers to the conference 238
Controlling active conferences 239
Nibblebill 239
Use cases 240
Billing (pre-pay) 240
Billing (post-pay) 240
Pay-per-call service billing 240
Maximum credit and/or fraud prevention 240
Design goals 241
Installation and configuration 241
Database tables 242
Creating the database table for PostgreSQL 242
Creating the database table for MySQL 243
Billing a call 243
Nibble method (default) 243
Alternative to nibble billings 244
Examples 244
Different rates per user 244
Single rate for all users 245
Different rates per area code 246
Different rates per service delivery 247
Hang up the call when the balance is depleted 248
Application/CLI/API commands 249
Check 249
Flush 249
Pause 250
Resume 250
Reset 250
Adding and deducting funds 250
Enabling session heartbeat 251
Bill based on B leg only 251](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-17-320.jpg)
![Table of Contents
[ viii ]
XML/Curl 251
Installation 252
Configuration 253
Bindings 254
HTTP requests 255
HTTP response 255
Optimization 256
Order of requests 256
Request/response examples 256
Dialplan bindings 261
Request 261
Reply 262
Other bindings 262
General Not found reply 262
Debugging 263
Failing back 263
Alternative endpoints 264
Skype and GSM endpoints 264
Skype with mod_skypopen 265
GSM with mod_gsmopen 266
TDM with OpenZAP and FreeTDM 267
Configuration tools and related projects 267
Web GUIs 267
WikiPBX 268
FreePBX v3 268
FusionPBX 269
2600hz 270
Supporting libraries 270
Liverpie (Ruby) 271
FreeSWITCHeR (Ruby) 271
Librevox (Ruby) 271
EventSocket (Python/Twisted) 271
FSSocket (Perl) 272
Summary 272
Appendix A: The FreeSWITCH Online Community 273
The FreeSWITCH mailing lists 273
Talking in real-time via IRC 275
The FreeSWITCH main website and wiki 277
The main FreeSWITCH page—www.freeswitch.org 277
The FreeSWITCH Wiki page—wiki.freeswitch.org 277
The annual ClueCon open source developer conference 278
Appendix B: The History of FreeSWITCH 279
Index 287](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-18-320.jpg)
![Preface
[ ]
FreeSWITCH is not a proxy server. If you need proxy server functionality,
then consider OpenSIPS, Kamailio, or other similar software. FreeSWITCH is a
back-to-back user agent or B2BUA. In this regard, it is similar to Asterisk and
other IP PBX software.
Version and licensing
At the time of this writing this book, the FreeSWITCH developers were putting the
finishing touches on FreeSWITCH version 1.2. While the examples presented in
this book were specifically tested with version 1.0.6, they have also been confirmed
to work with the latest FreeSWITCH development versions that form the basis of
version 1.2. Do not be concerned about the fact that this material does not cover
version 1.2—it certainly does. The FreeSWITCH user interface is very stable
between versions; therefore, this text will be applicable for years to come.
FreeSWITCH is released under the Mozilla Public License (MPL) version 1.1. Since
FreeSWITCH is a library that can be implemented in other software applications and
projects, the developers felt it important to strike a balance between the extremely
liberal BSD license and the so-called viral GPL. The MPL fits this paradigm well
and allows businesses to create commercial products based on FreeSWITCH without
licensing concerns.
However, what about using FreeSWITCH with GPL-based software? It should
suffice if we said that the developers wanted to make sure that anyone, including
proprietary and GPL-based software users, could use FreeSWITCH. The powerful
event socket gives us this functionality—a simple TCP socket-based interface that
allows an external program to control FreeSWITCH. Regardless of the license you
may be using for your own software, you can still connect to a FreeSWITCH server
without any licensing issues.
What this book covers
Chapter 1, Architecture of FreeSWITCH gives a brief, but thorough introduction to the
underlying architecture of FreeSWITCH.
Chapter 2, Building and Installation shows how to download and install FreeSWITCH
on Windows and Unix-like operating systems.
Chapter 3, Test Driving the Default Configuration provides a hands-on look at the
powerful and feature-rich default FreeSWITCH configuration.
Chapter 4, SIP and the User Directory offers an introduction to the concept of users and
the directory as well as brief look at SIP user agents.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-20-320.jpg)
![Preface
[ ]
Chapter 5, Understanding the XML Dialplan explains the basics of creating and editing
Dialplan extensions to add advanced functionality to a FreeSWITCH install.
Chapter 6, Using the Built-In XML IVR Engine discusses how to create menus and
sound phrases for interacting with callers.
Chapter 7, Building IVR Applications with Lua introduces the concept of advanced call
handling using the lightweight scripting language Lua.
Chapter 8, Advanced Dialplan Concepts builds upon the foundation laid in Chapter 5
and shows how to handle more challenging routing scenarios.
Chapter 9, Controlling FreeSWITCH Externally introduces the incredibly powerful
Event Socket and the Event Socket library that can be used to access and control a
FreeSWITCH server.
Chapter 10, Advanced Features and Further Reading highlights some of the more
powerful FreeSWITCH features like conferencing and offers some ideas on where to
learn more about FreeSWITCH.
Appendix A, The FreeSWITCH Online Community gives a brief introduction to the
worldwide online community and the tools used to stay in contact.
Appendix B, The History Of FreeSWITCH is a description of how FreeSWITCH came to
be from one of the authors, Anthony Minessale.
Who this book is for
This book is for prospective FreeSWITCH administrators as well as enthusiasts
who wish to learn more about how to set up, configure, and extend a FreeSWITCH
installation. If you are already using FreeSWITCH, you will find that the information
in this book compliments what you have already learned from your personal
experience.
A solid understanding of basic networking concepts is very important. Previous
experience with VoIP is not required, but will certainly make the learning process
go faster.
Conventions
In this book, you will find a number of styles of text that distinguish between
different kinds of information. Here are some examples of these styles, and an
explanation of their meaning.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-21-320.jpg)
![Preface
[ ]
Code words in text are shown as follows: ��������������������������������������������
If there is a match, (and there always will
be), then this macro plays the vm-goodbye.wav file��
.
A block of code is set as follows:
action application=����������
playback
data=phrase:myphrase:arg1:arg2:arg3/
action application=play_and_get_digits data=2 5 3 7000 #
phrase:myphrase:arg1 /invalid.wav my_var d+/
When we wish to draw your attention to a particular part of a code block, the
relevant lines or items are set in bold:
input pattern=^(1):(.*)$ break_on_match=true
match
action function=play-file data=voicemail/vm-you_have.wav/
action function=say data=$1 method=pronounced
type=items/
action function=play-file data=voicemail/vm-$2.wav/
action function=play-file data=voicemail/vm-message.wav/
/match
/input
Any command-line input or output is written as follows:
freeswitch@localhostversion
FreeSWITCH Version 1.0.6 (exported)
New terms and important words are shown in bold. Words that you see on the
screen, in menus or dialog boxes for example, appear in the text like this: New
users should join only the FreeSWITCH-users list, until they are comfortable with
the project.
Warnings or important notes appear in a box like this.
Tips and tricks appear like this.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-22-320.jpg)
![Preface
[ ]
Reader feedback
Feedback from our readers is always welcome. Let us know what you think about
this book—what you liked or may have disliked. Reader feedback is important for
us to develop titles that you really get the most out of.
To send us general feedback, simply send an e-mail to feedback@packtpub.com,
and mention the book title via the subject of your message.
If there is a book that you need and would like to see us publish, please
send us a note in the SUGGEST A TITLE form on www.packtpub.com or
e-mail suggest@packtpub.com.
If there is a topic that you have expertise in and you are interested in either writing
or contributing to a book, see our author guide on www.packtpub.com/authors.
Customer support
Now that you are the proud owner of a Packt book, we have a number of things to
help you to get the most from your purchase.
Downloading the example code for the book
You can download the example code files for all Packt books you have
purchased from your account at http://www.PacktPub.com. If you
purchased this book elsewhere, you can visit http://www.PacktPub.
com/support and register to have the files e-mailed directly to you.
Errata
Although we have taken every care to ensure the accuracy of our content, mistakes
do happen. If you find a mistake in one of our books—maybe a mistake in the text
or the code—we would be grateful if you would report this to us. By doing so, you
can save other readers from frustration and help us improve subsequent versions
of this book. If you find any errata, please report them by visiting http://www.
packtpub.com/support, selecting your book, clicking on the let us know link, and
entering the details of your errata. Once your errata are verified, your submission
will be accepted and the errata will be uploaded on our website, or added to any list
of existing errata, under the Errata section of that title. Any existing errata can be
viewed by selecting your title from http://www.packtpub.com/support.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-23-320.jpg)
![Preface
[ ]
Piracy
Piracy of copyright material on the Internet is an ongoing problem across all media.
At Packt, we take the protection of our copyright and licenses very seriously. If you
come across any illegal copies of our works, in any form, on the Internet, please
provide us with the location address or website name immediately so that we can
pursue a remedy.
Please contact us at copyright@packtpub.com with a link to the suspected
pirated material.
We appreciate your help in protecting our authors and our ability to bring you
valuable content.
Questions
You can contact us at questions@packtpub.com if you are having a problem with
any aspect of the book, and we will do our best to address it.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-24-320.jpg)
![Architecture of FreeSWITCH
[ ]
Do not be concerned if some of these concepts seem unnaturally abstract. Learning
telephony takes time, especially VoIP. In fact, we recommend that you read this
chapter more than once. Absorb as much as you can on the first pass, then come back
after you complete Chapter 5, Understanding the XML Dialplan. You will be surprised
at how much your understanding of VoIP and FreeSWITCH has improved. Then
come back and skim it a third time after you have completed Chapter 9, Controlling
FreeSWITCH Externally, at this point, you will have a firm grasp of VoIP and
FreeSWITCH concepts. Give yourself plenty of time to digest all of these strange new
concepts, and soon you will find that you are a skilled FreeSWITCH administrator. If
you keep at it, you will be rewarded with a meaningful understanding of this strange
and wonderful world we call telephony.
Telephones and the systems are very complicated and have evolved over the years
into several varieties. The most popular type of phone in the U.K. and the U.S. is the
traditional analog phone, which we affectionately refer to as POTS lines or Plain
Old Telephone Service. From the traditional Ma Bell phone up to the long-range
cordless phones that most of us have today, one thing has remained the same—the
underlying technology. In the last 10-15 years, there has been a convergence
of technology between computers and telephones that has produced a pair of
affordable alternatives to POTS lines—Mobile phones and VoIP phones
(also called Internet Phones).
FreeSWITCH fits into this big tangled mess of various telephone technologies by
bridging them together, so that they can communicate despite being otherwise
completely incompatible. FreeSWITCH also bridges telephone calls with computer
programs that you can write yourself, and controls what happens in ways like never
before. FreeSWITCH is software that runs on Windows and several UNIX varieties
such as Mac OS X, Linux, Solaris, and BSD. This means you can install FreeSWITCH
on your home PC or even a high-end server and use it to process phone calls.
Installing FreeSWITCH is discussed in detail in Chapter 2, Building and Installation.
We will be doing this as soon as we review the basic architecture.
The FreeSWITCH design: modular,
scalable, and stable
The design goal of FreeSWITCH is to provide a modular, scalable system around a
stable switching core, and provide a robust interface for developers to add to and
control the system. Various elements in FreeSWITCH are independent of each other
and do not have much knowledge about how the other parts are working, other
than what is provided in what are called ''exposed functions''. The functionality of
FreeSWITCH can also be extended with loadable modules, which tie a particular
external technology into the core.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-26-320.jpg)
![Chapter 1
[ ]
FreeSWITCH has many different module types that revolve around the central core,
much like satellites orbiting a planet. The list includes:
Module Type: Purpose:
Endpoint Telephone protocols like SIP/H.323 and POTS lines.
Dialplan Parse the call details and decide where to route the call.
Codec Translate between audio formats.
Application Perform a task such as play audio or set data.
Application
Programming Interface
(API)
Export a function that takes text input and returns text output,
which could be used across modules or from an external
connection.
File Provide an interface to extract and play sound from various
audio file formats.
Text-To-Speech (TTS) Interface with text-to-speech engines.
Automated Speech
Recognition ASR
Interface with speech recognition systems.
Directory Connect directory information services, such as LDAP, to a
common core lookup API.
Chat Bridge and exchange various chat protocols.
Say String together audio files in various languages to provide
feedback to say things like phone numbers, time of day, spell
words, and so on.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-27-320.jpg)
![Architecture of FreeSWITCH
[ 10 ]
By combining the functionality of the various module interfaces, FreeSWITCH can
be configured to connect IP phones, POTS lines, and IP-based telephone service. It
can also translate audio formats and interfaces with a custom menu system, which
you can create by yourself. You can even control a running FreeSWITCH server from
another machine. Let's start by taking a closer look at one of the more widely used
modules, namely, the Endpoint module.
Important modules: Endpoint and
Dialplan
Endpoint modules are critically important and add some of the key features which
make FreeSWITCH the powerful platform it is today. The primary role of these
modules is to take certain common communication technologies and normalize
them into a common abstract entity which we refer to as a session. A session
represents a connection between FreeSWITCH and a particular protocol. There are
several Endpoint modules that come with FreeSWITCH, which implement several
protocols such as SIP, H.323, Jingle (Google Talk), and some others. We will spend
some time examining one of the more popular modules named mod_sofia.
Sofia-SIP (http://sofia-sip.sourceforge.net) is an open source project
sponsored by Nokia, which is determined to make a programming interface to the
Session Initiation Protocol or SIP. We use this library in FreeSWITCH in a module
we call mod_sofia. This module registers to all the hooks in FreeSWITCH necessary
to make an Endpoint module, and translates the native FreeSWITCH constructs into
SIP constructs and back again. Configuration information is taken from the central
FreeSWITCH configuration files, which allows mod_sofia to load user-defined
preferences and connection details. This allows FreeSWITCH to accept registration
from SIP phones and devices, register to other SIP Endpoints such as service
providers, send notifications, and provide services to the phones such as voicemail.
When a SIP call is established between FreeSWITCH and another SIP device, it
will show up in FreeSWITCH as an active session. If the call is inbound, it can be
transferred or bridged to interactive voice response (IVR) menus, hold music, or one
or more extensions, though numerous other options are available. Let's examine a
typical scenario where a SIP phone registered as extension 2000 calls extension 2001,
with the hope of establishing a call.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-28-320.jpg)
![Chapter 1
[ 11 ]
First, the SIP phone sends a call setup message to mod_sofia over the network
(mod_sofia is ''listening'' for such messages). After receiving the message,
mod_sofia in turn parses the relevant details and passes the call into the core state
machine in FreeSWITCH. The state machine (in the FreeSWITCH core) then sends the
call into the ROUTING state. The next step is to locate the Dialplan module, based
on the configuration data for the calling Endpoint. The default and most widely used
Dialplan module is the XML Dialplan module. This module is designed to look up
a list of instructions from the central XML registry within FreeSWITCH. The XML
Dialplan module will parse a series of XML extension objects using regular
expression pattern-matching. As we are trying to call 2001, we hope to find an XML
extension testing the destination_number field for something that matches ''2001''
and routes accordingly. The Dialplan is not limited to matching only a single
extension. In fact, in Chapter 5, Understanding the XML Dialplan, you will get an
expanded definition of the term ''extension''. The XML Dialplan module builds
a sort of ''task list'' for the call. Each extension that matches it will have its actions
added to the call's task list.
Assuming FreeSWITCH finds at least one extension, the XML Dialplan will insert
instructions into the session object with the information it needs to try and connect
the call to 2001. Once these instructions are in place, the state of the calling session
changes from ROUTING to EXECUTE where the next handler drills down the list
and executes the instructions obtained by the ROUTING state. This is where the
application interface comes into the picture.
Each instruction is added to the session in the form of an application name and a
data argument that will be passed to that application. The one we will use in this
example is the bridge application. The purpose of this application is to create
another session with an outbound connection, then connect the two sessions for
direct audio exchange. The argument we will supply to bridge will be user/2001,
which is the easiest way to generate a call to extension 2001. A Dialplan entry for
''2001'' might look like this:
extension name=example
condition field=destination_number expression=^2001$
action application=bridge data=user/2001/
/condition
/extension
The extension is named ''example'', and it has a single condition to match. If the
condition is matched, it has a single application to execute. In plain language, the
mentioned extension could be expressed like this: If the caller dialed ''2001'', then
this establishes a connection between the calling party and the endpoint (that is,
telephone) at 2001. Consider how this happens.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-29-320.jpg)
![Architecture of FreeSWITCH
[ 12 ]
Once we have inserted the instructions into the session, the session's state will
change to EXECUTE, and the FreeSWITCH core will use the data collected to perform
the desired action. First, the default execute state handler will parse the command
to execute bridge on user/2001, then it will look up the bridge application and
pass the user/2001 data in. This will cause the FreeSWITCH core to create a
new outbound session of the desired type. User 2001 is also a SIP phone, so the
user/2001 will resolve into a SIP dial string, which will be passed to mod_sofia
to ask it to create a new outbound session.
If the setup for that new session is successful, there will now be two sessions in the
FreeSWITCH core. The bridge application will take the new session and the original
session (the caller's phone) and call the bridge function on it. This allows the audio
to flow in both directions, once the person at extension 2001 actually answers the
phone. If that user was unable to answer or was busy, a timeout (that is, a failure)
would occur and send the corresponding message back to the caller's phone. If a call
is unanswered or an extension is busy, many routing options are possible, including
call forwarding or voicemail.
All of this happens from the simple action of picking up the phone handset and
dialing 2 0 0 1. FreeSWITCH takes all of the complexity of SIP and reduces it to a
common denominator. From there, it reduces the complexity further by allowing us
to configure a single instruction in the Dialplan to connect the phone at 2000 to the
phone at 2001. If we want to allow the phone at 2001 to be able to call the phone at
2000, we can add another entry in the Dialplan going the other way.
extension name=example 2
condition field=destination_number expression=^2000$
action application=bridge data=user/2000/
/condition
/extension
In this scenario, the Endpoint module turned SIP into a FreeSWITCH session and
the Dialplan module turned XML into an extension. The bridge application turned
the complex code of creating an outbound call, and connecting the audio into a
simple application/data pair. Both the Dialplan module and the application module
interface are designed around regular FreeSWITCH sessions. Therefore, not only
does the abstraction make life easier for us at the user level, it also simplifies the
design of the application and the Dialplan because they can be made agnostic of
the actual endpoint technology involved in the call. It is because of this abstraction,
when we make up a new Endpoint module tomorrow for something like Skype
(there is actually such a thing present, by the way), that we can reuse all the same
application and Dialplan modules. The same principle applies to the Say, ASR, TTS,
and other such modules.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-30-320.jpg)
![Chapter 1
[ 13 ]
It is possible that you may want to work with some specific data provided by the
Endpoint's native protocol. In SIP, for instance, there are several arbitrary headers
as well as several other bits of interesting data from the SIP packets. We solve this
problem by adding variables to the channel. Using channel variables, mod_sofia can
set these arbitrary values as they are encountered in the SIP data where you can
retrieve them by name from the channel in your Dialplan or application. This way
we share our knowledge of these special variables with the SIP Endpoint. However,
the FreeSWITCH core just sees them as arbitrary channel variables, which the
core can ignore. There are also several special reserved channel variables that can
influence the behavior of FreeSWITCH in many interesting ways. If you have ever
used a scripting language or configuration engine that uses variables, then you are at
an advantage because channel variables are pretty much the same concept. There is
simply a variable name and a value that is passed to the channel and the data is set.
There is even an application interface for this: the set application that lets you set
your own variables from the Dialplan.
extension name=example 3
condition field=destination_number expression=^2000$
action application=set data=foo=bar/
action application=bridge data=user/2000/
/condition
/extension
The recent example is almost identical to the previous example, but instead of just
placing the call, we first set the variable ''foo'' equal to the value ''bar''. This variable
will remain set throughout the call and can even be referenced at the end of the call
in the detail logs.
The more we build things in small pieces, the more the same underlying resources
can be reused, making the system simpler to use. For example, the codec interface
knows nothing else about the core, other than its own isolated world of encoding and
decoding audio packets. Once a proper codec module has been written, it becomes
usable by any Endpoint interface capable of carrying that codec in its audio stream.
This means that if we get a Text-To-Speech module working, we can generate
synthesized speech on any and all Endpoints that FreeSWITCH supports. It does not
matter which one comes first as they have nothing to do with each other. However,
the addition of either one instantly adds functionality to the other. The TTS module
becomes more useful because it can use more codecs; the codecs have become more
useful because we added a new function that can take advantage of them. The same
idea applies to applications. If we write a new application module, the existing
endpoints will immediately be able to run and use that application.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-31-320.jpg)
![Architecture of FreeSWITCH
[ 14 ]
Complex applications made simple
FreeSWITCH removes much of the complexity of more advanced applications.
Let's look at two examples of a more complex application.
Voicemail
The first application we will discuss is the voicemail application. The general
purpose of this application is probably pretty easy to deduce. It provides voicemail
service. This application is useful to add right after the bridge application as a second
option, in case the call was not completed. We can do this with a careful combination
of application choices, and one of those fancy ''special'' variables that we were
discussing earlier. Let's look at a new version of our last extension that also
allows us to leave a voicemail:
extension name=example 4
condition field=destination_number expression=^2000$
action application=set data=hangup_after_bridge=true/
action application=bridge data=user/2000/
action application=voicemail data=default ${domain} 2000/
/condition
/extension
Here we see two uses of channel variables. First we set hangup_after_bridge=true
telling the system to just hang up once we have had at least one successfully bridged
call to another phone and to disregard the rest of the instructions. We are also using
the domain variable as seen in brackets prefixed with a dollar sign, ${domain}. This
is a special variable that defaults to the auto-configured domain name, which all the
phones are using from the configuration.
In the example, we check if someone is dialing 2000. We then try to bridge the call
to the phone registered to extension 2000. If the call fails or there is no answer, we
will continue to the next instruction, which is to execute the voicemail application.
We provide the information the application needs to know, and which extension
the voicemail is for so it knows how to handle the situation. Next, the voicemail
application plays the pre-recorded greeting or generates one for you using the Say
module's interface we briefly discussed earlier. It strings together sound files to make
a voice say ''The person at extension 2 0 0 0 is not available, please leave a message''.
Next, mod_voicemail prompts you to record a message, and now is your chance to
leave your mark in that person's inbox by leaving a voice message. As an additional
feature, if you are not satisfied with your recording, you can repeat it as many times
as you wish. Once you finally commit, a FreeSWITCH MESSAGE_WAITING event is
fired into the core event system, which is picked up by mod_sofia by way of an event](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-32-320.jpg)
![Chapter 1
[ 15 ]
consumer, where the event information is translated into SIP. If everything goes as
planned, the phone registered on extension 2000 will illuminate its message-waiting
indicator light!
Again in this example, not only have we seen how to play a greeting, record a
message, and send it to a user, we have also uncovered another unsung hero of
the FreeSWITCH core—the event system. The FreeSWITCH event system is not a
module interface like the other examples, it is a core engine that you can use to bind
to named events and react accordingly when an event is received. In other words,
throughout the FreeSWITCH core, there are events that are sent and received.
Modules can bind to (that is ''listen'' for) various events. They can also ''fire'' events
into the event engine; other modules can listen for those events. As we discussed, the
Sofia SIP module binds or subscribes to the event designated for MESSAGE_WAITING
information. This allows our mod_voicemail module to interact with mod_sofia,
without either system having any knowledge about the other's existence. The event
is fired by mod_voicemail, received by mod_sofia, and translated into the proper
SIP message—all seemingly magical, courtesy of the event system.
There are several challenges with such a complex interactive system when
considering all of the possible languages it may need to support as well as what
files to play for the automated messages and how they are strung together. The Say
module supplies a nice way to string files together, but it is somewhat limited to
something specific like spelling a word, counting something, or saying a certain date.
The way we overcome this is by defining a more complex layer on top of the Say
module called Phrase Macros. Phrase Macros are a collection of XML expressions
that pull out a list of arguments by matching a regular expression and executing
a string of commands. This is very similar to how the XML Dialplan works, only
custom-tailored for interactive voice response scenarios (IVR). For example, when
mod_voicemail asks you to record your message, rather than coding in the string
of files to make it say that, the code just calls a Phrase Macro called voicemail_
record_message. This arbitrary string is shared between mod_voicemail and the
Phrase Macro section in the configuration allowing us, the users, to edit the file
without doing any fancy programming.
macro name=voicemail_record_message
input pattern=^(.*)$
match
action function=play-file data=voicemail/vm
record_message.wav/
/match
/input
/macro](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-33-320.jpg)
![Architecture of FreeSWITCH
[ 16 ]
When mod_voicemail executes the voicemail_record_message macro, it first
matches the pattern, which, in this case, is just to match everything, as this particular
macro has no input. If the macro did have input, the pattern matching could be used
to perform different actions based on different input. Once a match is found, the
match tag is parsed in the XML for action tags just like in our Dialplan example.
This macro just plays the file vm_record_message.wav, but more complicated
macros, like the ones for verifying your recording or telling you how many messages
you have in your inbox, may use combinations of various say modules and playing
of audio files. Phrase Macros are discussed in detail in Chapter 6, Using the Built-in
XML IVR Engine and used extensively in Chapter 7, Building IVR Applications
With Lua.
Once again, we have cooperation among the phrase system, the audio file, and
the Say modules loaded by the core being joined together to enable powerful
functionality. The Say modules are written specifically for a particular language or
''voice'' within a language. We can programmatically request to say a particular time
and have it translated into the proper Say module based on input variables. The
Phrase Macro system is a great way to put bigger variable concepts into your code,
which can be easily tweaked later by everyday users. For example, if we wanted to
make a small IVR that asks us to dial a four-digit number and then just read it back
and hang up, we could make one macro called ''myapp_ask_for_digits'' and the
other called ''myapp_read_digits''. In our code, we would execute these macros
by name—the first one when it is time to ask for the digits and the other one to
read back the
digits by passing in the value we entered. Once this is in place, a less-experienced
individual could implement the XML files to play the proper sounds. He/she can use
the Say modules to read back the number, and it could all be working in multiple
languages with no further coding necessary. Voicemail is just one example of
FreeSWITCH in use as an application server. There are endless possibilities
when we use FreeSWITCH to connect phone calls with computers.
Multi-party conferencing
Another popular feature of FreeSWITCH is delivered by the mod_conference
conferencing module. The mod_conference module provides dynamic conference
rooms that can bridge together the audio from several audio channels. This can be
used to hold meetings where there are several callers who want to interact on the
same call. Each new session that connects to the same conference room will join the
others, and instantly be able to talk to all of the other participants at the same time.
By using a Dialplan example, similar to the one we used for bridging to another
phone, we can make an extension to join a conference room:](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-34-320.jpg)
![Chapter 1
[ 17 ]
extension name=example 4
condition field=destination_number expression=^3000$
action application=conference data=3000@default/
/condition
/extension
This is just as simple as bridging a call, but what is special about this extension
is that many callers can call extension 3000 and join the same conference. If three
people joined this conference and one of them decides to leave, the other two would
still be able to continue their conversation. The conference module also has other
special features, such as the ability to play sound files or text to speech to the whole
conference or even just to a single member of the conference. As you may have
guessed, we are able to do this by using the TTS and sound file interfaces provided
by their respective modules. Once again, the smaller pieces come together to extend
the functionality without needing explicit knowledge of the other components
in the system.
The conference module also uses the event system in a special way called custom
events. A module such as mod_conference can reserve a special event namespace
called a subclass when it first loads. When something interesting happens, such
as when a caller joins or leaves a conference, it fires those events on the CUSTOM
event channel in the core. When we are interested in receiving such events, all we
have to do is subscribe to the CUSTOM event supplying an extra subclass string,
which specifies the specific CUSTOM events we are interested in. In this case, it is
conference::maintenance. This makes it possible to look out for important things
such as when someone joins or leaves the conference or even when they start and
stop talking. Conferencing is discussed in detail in Chapter 10, Advanced Features
and Further Reading.
The FreeSWITCH API (FSAPI)
Another very powerful module interface in FreeSWITCH is the FSAPI module. The
principle of this type of interface is very simple—it takes a single string of text as
input, which may or may not be parsed, especially by the following code. The return
value is also a string that can be of any size, from a single character up to several
pages of text, depending on the function that was called. One major benefit of FSAPI
functions is that a module can use them to call routines in another module, without
directly linking into the actual code. The command-line interface of FreeSWITCH or
CLI uses FSAPI functions to pass commands from your prompt.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-35-320.jpg)
![Architecture of FreeSWITCH
[ 18 ]
Here is a small example of how we can execute the status FSAPI command from
the FreeSWITCH CLI:
freeswitch status
API CALL [status()] output:
UP 0 years, 3 days, 23 hours, 31 minutes, 31 seconds, 524 milliseconds,
576 microseconds
438 session(s) since startup
6 session(s) 0/30
1000 session(s) max
What's really happening here is that when we type status and press the Enter key,
the word ''status'' is used to look up the status FSAPI function from the module in
which it was implemented. The underlying function is then called, and the core is
queried for its status message. Once the status data is obtained, the output is written
to a stream that comes back and prints as the result of the command.
We have already learned that a module can create and export FSAPI functions,
which can be executed from anywhere such as the CLI. But wait, there's more!
Modules can also be written to push commands into the FSAPI interface, and send
the result over a specific protocol. There are two modules included in FreeSWITCH
that do just that—mod_event_socket and mod_xml_rpc (mod_event_socket
discussed in detail in Chapter 9, Controlling FreeSWITCH Externally.) Consider the
example of mod_xml_rpc. This module implements the standardized XML-RPC
protocol as a FreeSWITCH module. Clients using an XML-RPC interface can connect
to FreeSWITCH and execute any FSAPI command they choose. So a remote client
could execute an RPC call to status, and get a similar status message to the one we
saw in the previous example. This same module also provides FreeSWITCH with
a general web server, which allows FSAPI commands to be accessed with a direct
URL hit. For example, one could point a browser to http://example.freeswitch.
box:8080/api/status to access the status command directly over the World Wide
Web. By using this technique, it's possible to create FSAPI commands that work
similar to a CGI, providing a dynamic web application that has direct access to
FreeSWITCH internals.
As we can see, the FSAPI interface is very versatile. Now we know it can be used
to provide a CLI interface, a way for modules to call functions from each other
and a way to export WWW or XML-RPC functions. There is still one more use for
FSAPI functions that we have not covered. We touched slightly on the concept of
channel variables earlier, noting that we can use the expression ${myvariable} to
get the value of a certain variable. FSAPI functions can also be accessed this way
in the format ${myfunction()}. This notation indicates that the FSAPI command
''myfunction'' should be called, and that the expression should be replaced with the](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-36-320.jpg)
![Chapter 1
[ 19 ]
output of that function call. Therefore, we can use ${status()} anywhere when
variables are expanded to gain access to the status command. For example:
action application=set data=my_status=${status}/
The value placed in the my_status variable will be the output from the
status command.
The drawback to all the versatility provided by a single module interface is that in
order to achieve all of this, we have to ''loosely type'' the functionality. This means
that there are several cases where a single FSAPI command could easily be accessed,
using all of the ways we have discussed. In addition, there are also some other specific
functions that are specifically designed for a particular access method. For instance,
if we made an FSAPI command that produced HTML intended to be accessed with
a web browser, we would not want to access it from the CLI or by referencing it as a
variable. Similarly, if we made an FSAPI function that computed some kind of value
based on call details, which was designed to be used from the Dialplan, it would
not be very useful at the CLI or from the Web. So, with great power comes great
responsibility, and this is one case where we need to use common sense to decide
when and where to use the proper FSAPI functions to get the most out of them.
The XML registry
We have now discussed many of the fundamental components of the FreeSWITCH
core and how they interact with each other. We have seen how the event system can
carry information across the core, and how the XML Dialplan can query the XML
registry for data. This would be a good time to explain the XML registry a bit more.
The XML registry is a centrally managed XML document that holds all of the critical
data, which FreeSWITCH needs to operate properly. The initial document is loaded
from your hard drive and passed into a special pre-processor. This pre-processor can
include other XML documents and other special operations, such as setting global
variables, which can be resolved by the pre-processor further down in the document.
Once the entire document and all of the included files are parsed, replaced, and
generated into a static XML document, this document is loaded into memory.
The XML registry is divided into several sections—configuration, dialplan,
directory, and phrases. The core and the modules draw their configuration from
the configuration section. The XML Dialplan module draws its Dialplan data from
the dialplan section. The SIP authentication, user lookup, and the voicemail module
read their account information from the directory section. The Phrase Macros
pull their configuration from the phrases section. If we make a change to any of
the documents on the disk, we can reload the changes into memory by issuing the
reloadxml command from the CLI. (This is an example of using the FSAPI interface
to communicate with the FreeSWITCH core.)](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-37-320.jpg)
![Architecture of FreeSWITCH
[ 20 ]
Language modules
One distinct type of module that does not have a direct interface to FreeSWITCH-like
files and Endpoints, but still offers an immensely powerful connection to existing
technology, is the Language module. Language modules embed a programming
language like Lua, JavaScript, or Perl into FreeSWITCH, and transfer functionality
between the core and the language's runtime. This allows things like IVR applications
to be written in the embedded language, with a simple interface back to FreeSWITCH
for all the heavy lifting. Language modules usually register into the core with the
application interface and the FSAPI interface and are executed from the Dialplan.
Language modules offer lots of opportunities and are very powerful. Using language
modules, you can build powerful voice applications in a standard programming
language. In some respects, you can actually control a telephone with a
programming language.
The default configuration
Understanding all of these concepts right off the bat is far from easy, and as the
maintainers of the software, we do not expect most people to have everything
''just click''. This is the main reason that every new layer we put on top of the core,
makes things simpler and easier to learn. The default configuration of FreeSWITCH
is the last line of defense between new users of the software and all of the crazy,
complicated, and sometimes downright evil stuff, better known as telephony.
We try very hard to save the users from such things.
The main purpose of the default configuration in FreeSWITCH is to showcase all
of the hundreds of parameters there are to work with. We present them to you in a
working configuration that you could actually leave untouched and play with a bit
before venturing into the unknown and trying your own hand at changing some of
the options. Think of FreeSWITCH as a Lego set. FreeSWITCH and all of its little
parts are like a brand new bucket Lego bricks, with plenty of parts to build anything
we can imagine. The default configuration is like the sample spaceship that you find
in the instruction booklet. It contains step-by-step instructions on exactly how to
build something you know will work. After you pick up some experience, you might
start modifying your Lego ship to have extra features, or maybe even rebuild the
parts into a car or some other creation. The good news about FreeSWITCH is that it
comes out of the box already assembled. Therefore, unlike the bucket of Lego bricks,
if you get frustrated and smash it to bits, you can just re-install the defaults and you
won't have to build it again from scratch. The default configuration is discussed in
Chapter 3, Test Driving the Default Configuration.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-38-320.jpg)
![Chapter 1
[ 21 ]
Once FreeSWITCH has been successfully built on your system, you simply have to
launch the program without changing one line in the configuration file. You will be
able to point a SIP telephone or software-based SIP soft phone to the address of your
computer and make a test call. If you are brave and have ambition of connecting a
traditional analog phone, you may want to get the SIP thing under your belt first.
This is because it involves a little more work (including purchasing a hardware card
for your computer or a magic device called an ATA—analog telephone adapter).
If you have more than one phone, you should be able to configure them to each
having an individual extension in the range 1000-1019, which is the default extension
number range that is pre-defined in the default configuration. Once you get both
phones registered, you will be able to make calls across them or have them to meet
in a conference room in the 3000-3399 range. If you call an extension that is not
registered or let the phone ring at another extension for too long, the voicemail
application will use the phrase system to indicate that the party is not available,
and ask you to record a message. If you dial 5000, you can see an example of the
IVR system at work, presenting several menu choices demonstrating various other
neat things FreeSWITCH can do out of the box. There are a lot of small changes and
additions that can be made to the default configuration while still leaving it intact.
For example, using the pre-processor directives we went over earlier, the default
configuration loads a list of files into the XML registry from certain places,
meaning that every file in a particular folder will be combined into the final XML
configuration document. The two most important points where this takes place are
where the user accounts and the extensions in the Dialplan are kept. Each of the 20
extensions that are preconfigured with the defaults are stored into their own file.
We could easily create a new file with a single user definition and drop it into place
to add another user, and simply issue the reloadxml at the FreeSWITCH CLI. The
same idea applies to the example dialplan. We can put a single extension into its own
file, and load it into place whenever we want.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-39-320.jpg)
![Architecture of FreeSWITCH
[ 22 ]
Summary
FreeSWITCH is a complex system of moving parts that is intertwined to produce
a solid, stable core with flexible and easy-to-extend add-ons. The core extends its
interfaces to modules. These modules simplify the functionality further and
extend it up to the user. The modules also can bring outside functionality into
FreeSWITCH by translating various communication protocols into a common,
well-known format. We looked at the various module types, and demonstrated
how they revolve around the core and interact with each other to turn simple
abstract concepts into higher-level functionalities. We touched base on a few of
the more popular applications in FreeSWITCH—the conferencing and voicemail
modules and how they, in turn, make use of other modules in the system without
ever knowing it. This agnosticism is accomplished by means of the event system.
We also saw how the default configuration provides several working examples, to
help take the edge off of an otherwise frightening feat of staring down the business
end of a full-featured soft-switch.
Now that we have a general idea of what makes FreeSWITCH tick, we will take
a closer look at some of these concepts with some real-world examples for you to
try. First we obtain a copy of the source code from the Internet, so we can build the
software package and install it. From there, we will test out the configuration, so be
sure to get yourself a SIP phone or at least a soft-phone. Once we try a few things, we
will dive a litter deeper into how things work and create a few things of our own like
an extension or two and an IVR menu. So take a deep breath and get ready to dive
into the world of telephony with FreeSWITCH!](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-40-320.jpg)
![Building and Installation
[ 24 ]
Setting up the FreeSWITCH environment
FreeSWITCH, like many other software applications, requires a suitable
environment. Primarily that means choosing appropriate operating system
for your hardware and having the proper LAN/WAN connectivity and
physical environment.
Operating system
The first question to consider here is: which operating system should be used?
Generally speaking, it is good to use an operating system with which you are
comfortable and familiar. One caveat to consider is 32-bit versus 64-bit. Some users
have reported problems when running a 32-bit OS on a 64-bit hardware platform.
We strongly recommend that you use a 64-bit OS if you have 64-bit hardware.
For those who prefer a Windows environment you can use XP, Vista, Windows
7, Server 2003, or Server 2008. Several users have reported good success with
production systems running on modern hardware, and using Windows Server 2008.
On the other hand, there is a wide variety of Unix-like operating systems available,
many of which are freely downloadable. Most of us have an operating system
(Linux, BSD, Solaris, and so on), and distribution (CentOS, Debian, Ubuntu, and
so on.) that we prefer to use. The FreeSWITCH developers do not advocate any
particular operating system or distribution.
Some have asked which platform is the best for FreeSWITCH. There are
many factors to consider when choosing a platform on which to run a telephony
application. FreeSWITCH is cross-platform, and therefore, it compiles and runs
on numerous systems. However, through hard-earned experience we know
which operating systems and distributions lend themselves to real-time telephony
applications. The bottom line is that you want your system to be stable and
reliable. Our experience is that installation on Red Hat Enterprise Linux (RHEL),
or its free cousin, CentOS, yields the best performance and fewest problems.
Some have characterized RHEL and CentOS as boring and predictable. These
qualities are perfect for running real-time telephony applications like FreeSWITCH.
Operating system prerequisites
Each operating system has its own set of prerequisites. Make sure that you have met
the prerequisites for your platform.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-42-320.jpg)
![Chapter 2
[ 25 ]
Linux/Unix
The following items frequently are already installed on your system. Note that an
SVN or Git client is not required:
SVN: A Subversion (SVN) client gives you access to the current code
repository (recommended for those who simply want the latest code)
Git: A Git client also gives you access to the current code repository
(recommended especially for developers)
GNUMAKE: The GNU version of make
AUTOCONF: Version 2.60 or higher
AUTOMAKE: Version 1.9 or higher
LIBTOOL: Version 1.5.14 or higher
GCC: Version 3.3 or higher
WGET: Any recent version
LIBNCURSES: Any recent version
Mac OS X
It is strongly recommended that Mac users have, at the very least, OS X Version
10.4. Compiling FreeSWITCH on OS X requires the installation of the Apple XCode
Developer Tools. You may download them from http://connect.apple.com. Free
registration is required.
Windows
FreeSWITCH in a Windows environment has two primary requirements. They are
as follows:
1. Microsoft Visual C++ 2008 (or 2008 Express Edition)
2. A file decompression utility
FreeSWITCH in Windows is compiled and built using Microsoft Visual C++ 2008
(MSVC) or Visual C++ 2008 Express Edition (MSVCEE). The Express Edition
is free to download though registration is required. It can be obtained at
http://www.microsoft.com/Express/VC. The other requirement for Windows
is a file decompression utility like WinZip (www.winzip.com) or WinRAR
(www.rarlab.com). A free alternative is 7-Zip (www.7-zip.org). Each of
these utilities will add a right-click menu option to Windows Explorer.
•
•
•
•
•
•
•
•
•](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-43-320.jpg)
![Building and Installation
[ 26 ]
Text editors and XML
Working with FreeSWITCH requires you to have a text editor with which you are
comfortable. Regardless of your editor choice, we strongly recommend that you use
a text editor that supports XML syntax highlighting. You will find that editing XML
configuration files is much easier on the eyes with highlighting turned on.
If you do not already have a preferred editor, then we suggest trying one or two for
your platform. Be aware that if you are in a Linux/Unix environment that does not
have GUI (Graphical User Interface), then your choices will be fewer. However, there
are several excellent text-only editors available:
Emacs—This is a text-only editor available for just about any Unix-like
environment, including Mac OS X. It can highlight source code, XML,
HTML, and more. This is the editor of choice for the FreeSWITCH
development team. (A GUI version of Emacs is also available.)
Vi/Vim—This is a text-only editor available for just about and
Unix-like environment. Like Emacs it can highlight source code
and markup languages. (A GUI version of Vim is also available.)
Notepad++—This is a graphical text editor for Windows environment.
It supports highlighting of many programming and markup languages.
It is a very useful and free text editor for Windows.
Downloading the source
Most open source projects have their source code divided into two general
categories: stable and latest. While the latest FreeSWITCH code is usually quite
stable, we recommend that you begin with the latest stable release. You can update
to the latest trunk at a later point. (See the Building From the latest Code section in
this chapter.) One other point to keep in mind: binary distributions of FreeSWITCH
might be available for your platform. While they are certainly convenient, in our
experience it is easier to troubleshoot, update, and customize your FreeSWITCH
installation when compiling from the source.
Be sure that your system has Internet access because the build process will
occasionally need to download additional files.
•
•
•](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-44-320.jpg)
![Chapter 2
[ 27 ]
The source code can be obtained from the following FreeSWITCH download site:
http://files.freeswitch.org. Locate a file named freeswitch-1.0.6.tar.gz,
and download it into a local directory on your computer, then decompress it.
A typical session in Linux might look like the following:
#cd /usr/src
#wget http://files.freeswitch.org/freeswitch-1.0.6.tar.gz
#tar zxvf freeswitch-1.0.6.tar.gz
This will create a new directory that contains the FreeSWITCH source code, ready
for you to compile on your system. (From now on, this will be referred to as the
FreeSWITCH source directory.)
Windows users should create a new directory and download the source file. See the
Compiling FreeSWITCH For Windows section, later in this chapter.
Building from the latest code
If you prefer to be on the latest version of FreeSWITCH, then you will need a
Subversion (SVN) client or a Git client. The FreeSWITCH developers recently
migrated from Subversion to Git for the development tree. However, they are
maintaining a read-only SVN mirror, so you can still get the latest code via SVN.
You can also get the latest code with a Git client; however, developers who wish to
have commit-access will need a Git client. Most Linux/Unix environments already
have, or can easily have, a Subversion client installed. In Windows, a popular (and
free) Subversion client is TortoiseSVN (tortoisesvn.tigris.org). There is also
TortoiseGit (code.google.com/p/tortoisegit). In Windows, the build procedure
is essentially the same: open the appropriate solution file and then build it.
In Linux/Unix environments it is necessary to bootstrap prior to compiling.
However, there is a shortcut available. The following commands will download and
build a fresh SVN checkout of FreeSWITCH, with the default configuration and all
the sound files:
#cd /usr/src ; wget http://www.freeswitch.org/eg/Makefile ; make
#make all
#cd freeswitch.trunk
#make install
#make cd-sounds-install
#make cd-moh-install](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-45-320.jpg)
![Building and Installation
[ 28 ]
The preceding commands will take some time to complete. You can automate the
process a bit by chaining the commands together with the operator.
Compiling FreeSWITCH for Linux/Unix/
Mac OS X
The install procedure is essentially the same for Linux, Unix, or Mac OS X. However,
make sure that your system has met the prerequisites listed in the previous section.
Compiling FreeSWITCH
Compiling FreeSWITCH requires just a few steps, although it will take some time
depending upon the speed of your system. The basic procedure for compiling
FreeSWITCH is as follows:
Edit modules.conf file to customize which modules are compiled by default
Run configure script
Run make and make install to compile and install
Edit modules.conf.xml to customize which modules are loaded by default
Install the sound and music files
Following are detailed step-by-step instructions for compiling FreeSWITCH.
Step 1: Edit modules.conf
The modules.conf file contains a list of the various FreeSWITCH modules that
will be configured and compiled. The default modules.conf file has a sensible set
of modules, pre-selected to be compiled. However, there is one optional module
that we will enable now. You should have a new subdirectory named freeswitch-
x.y.z, where x.y.z is the version number. For example, if the latest stable version is
1.0.6 then your source directory will be /usr/src/freeswitch-1.0.6. Follow the
steps below:
1. Change directory into the new FreeSWITCH source directory:
#cd /usr/src/freeswitch-1.0.6
2. Open modules.conf in a text editor. Scroll down to the following line:
#asr_tts/mod_flite
•
•
•
•
•](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-46-320.jpg)
![Chapter 2
[ 29 ]
3. Remove the # character from the beginning of the line, then save and
exit. The mod_flite module enables FreeSWITCH to use the open source
Festival Lite text-to-speech (TTS) engine. (The Flite TTS engine does not
produce particularly high quality speech synthesis. However, it is very
handy for doing TTS testing.)
After editing modules.conf we are ready to start the build process.
Removing the # character at the beginning of a line in modules.conf
will cause the module on that line to automatically be built, when
issuing the make command. Likewise, adding a # at the beginning
of the line will prevent the corresponding module from being
built automatically.
Step 2: Run configure script
Like many open source projects, FreeSWITCH in UNIX-like environments makes use
of the now famous configure script. From within the FreeSWITCH source directory,
launch the configure script, as follows:
#./configure
The configure script performs many tasks, including making sure that the
prerequisites have been met. If a prerequisite has not been met then the configure
script will exit, and tell you which dependency has not been met. If this occurs then
you must resolve the issue and rerun the configure script. You will need to make
sure that all of the prerequisites have been met before the configure script will run
to completion.
During the configuration process you will see the configure script run multiple times.
FreeSWITCH makes use of many libraries like Apache Portable Runtime (APR) and
Perl Compatible Regular Expressions (PCRE). Each of these elements has its own
specific configure script that is customized to its own needs.
After some time the configure script finishes, and returns you to the system
prompt. You will undoubtedly see a lot of output on the screen from the
configuration process, but if you do not see any errors then you may proceed
to the compilation process.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-47-320.jpg)
![Building and Installation
[ 30 ]
Step 3: Run make and make install
The configuration process in the previous step actually creates what is called a
Makefile for FreeSWITCH, its libraries, and its various modules. The compilation
and installation of FreeSWITCH are both handled by the make utility. First run make,
and then run make install. Many users will run them both with one command line,
which is as follows:
#make make install
Like the configure script, the make process takes a while, and will stop if there are
any errors. Usually things go well, and at the end of the compilation and installation
you are greeted with the following message:
+-------- FreeSWITCH install Complete ----------+
+ FreeSWITCH has been successfully installed. +
+ +
+ Install sounds: +
+ (uhd-sounds includes hd-sounds, sounds) +
+ (hd-sounds includes sounds) +
+ ------------------------------------ +
+ make cd-sounds-install +
+ make cd-moh-install +
+ +
+ make uhd-sounds-install +
+ make uhd-moh-install +
+ +
+ make hd-sounds-install +
+ make hd-moh-install +
+ +
+ make sounds-install +
+ make moh-install +
+ +
+ Install non english sounds: +
+ replace XX with language +
+ (ru : Russian) +
+ ------------------------------------ +
+ make cd-sounds-XX-install +
+ make uhd-sounds-XX-install +
+ make hd-sounds-XX-install +
+ make sounds-XX-install +
+ +
+ Upgrade to latest: +
+ ---------------------------------- +](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-48-320.jpg)
![Chapter 2
[ 31 ]
+ make current +
+ +
+ Rebuild all: +
+ ---------------------------------- +
+ make sure +
+ +
+ Install/Re-install default config: +
+ ---------------------------------- +
+ make samples +
+ +
+ +
+ Additional resources: +
+ ---------------------------------- +
+ http://www.freeswitch.org +
+ http://wiki.freeswitch.org +
+ http://jira.freeswitch.org +
+ http://lists.freeswitch.org +
+ +
+ irc.freenode.net / #freeswitch +
+ +
+-----------------------------------------------+
If you see a message like the last one then you have successfully compiled
FreeSWITCH, and can proceed to the next step. If an error occurs then the
compilation process will stop and report it. You will need to correct the problem
before you can continue. If the error message is unfamiliar to you then you should
contact the FreeSWITCH community using the resources listed in Appendix A
(The FreeSWITCH Online Community).
Step 4: Edit modules.conf.xml
The modules.conf.xml file contains a list of modules that FreeSWITCH will load
when it is launched. The default modules.conf.xml file corresponds with the
default modules.conf file. The modules that are built by default in modules.conf
are also enabled by default in modules.conf.xml. As we enabled mod_flite to be
built in modules.conf, we need to enable mod_flite in modules.conf.xml, so
that it will be loaded automatically when FreeSWITCH starts. As a rule of thumb,
any module that you wish to load automatically when FreeSWITCH starts must be
enabled in modules.conf.xml.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-49-320.jpg)
![Building and Installation
[ 32 ]
The modules.conf.xml file is located in the conf/autoload_configs subdirectory.
The default location is /usr/local/freeswitch/conf/autoload_configs/
modules.conf.xml. Open the file in a text editor and locate the following line
near the end of the file:
!-- load module=mod_flite/ --
Remove the !-- and -- tags so that it looks like the following:
load module=mod_flite/
Save the file and exit. You are almost ready to start the FreeSWITCH application.
What's the difference between modules.conf and modules.conf.
xml files? The modules.conf file is found in the source directory,
and is used to control FreeSWITCH modules which are compiled when
running make. The modules.conf.xml file is part of the default XML
configuration, and is found in the FreeSWITCH autoload_configs
subdirectory. It controls which modules are loaded when FreeSWITCH
is launched.
Step 5: Install sound and music files
Sound and music files are not absolutely required. However, they are highly
recommended. Without them you will not have music on hold, nor will features
like voicemail and the sample IVR be functional. FreeSWITCH has sample sound
and music files available in four different sampling rates. We recommend installing
all of them so that you can take advantage of high quality audio connections
wherever possible.
To install the sound files just issue the following command in the FreeSWITCH
source directory:
#make cd-sounds-install
To install the music files issue the following command:
#make cd-moh-install
These commands will download and install the sound and music files in 8 kHz, 16
kHz, 32 kHz, and 48 kHz. FreeSWITCH will use the appropriate sampling rate when
playing a sound or music file to a caller.
You are now ready to start FreeSWITCH. The next section covers compiling
FreeSWITCH in the Windows environment, so skip down to the section named
Starting FreeSWITCH.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-50-320.jpg)
![Chapter 2
[ 33 ]
Compiling FreeSWITCH for Windows
As mentioned in the Operating system prerequisites section, FreeSWITCH is built with
MSVC or MSVCEE. The steps presented here are specifically for the Express Edition;
however, the steps for using the standard edition are essentially the same.
Building the solution with MSVC/MSVCEE
There are several small steps to take prior to building with MSVC. They are
as follows:
1. Create a new folder and copy the tar.gz file into it. In our example, we'll use
C:FreeSWITCHfreeswitch-1.0.6.tar.gz.
2. Right-click freeswitch-1.0.6.tar.gz and extract the files with your
decompression utility. You will now have a new file named, freeswitch-
1.0.6.tar.
3. Right-click freeswitch-1.0.6.tar and extract files. This process
will take a few moments. You will then see a window similar to the
following screenshot:
Note: WinRAR decompresses both the .gz and .tar files in a
single step.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-51-320.jpg)
![Building and Installation
[ 34 ]
4. After extraction you will have a new sub-folder named after the latest
version of FreeSWITCH. In our example, we now have a sub-folder
named freeswitch-1.0.6. Double-click on the folder to see the
complete FreeSWITCH source tree. It will be similar to the screen
in the following screenshot:
5. While there are many files, the only ones we care about right now are the
two solution files. For MSVC, the file is named Freeswitch.2008.sln and
for MSVCEE, it is named Freeswitch.2008.express.sln. Double-click the
appropriate solution file for your edition of MSVC. The screenshots in this
example will show MSVC 2008 Express Edition. However, the Standard and
Professional editions will be very similar.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-52-320.jpg)
![Chapter 2
[ 35 ]
6. After the solution file loads, click Build Build Solution or press F7. The
solution will start building. Numerous messages will appear in the Output
window. When the solution has finished building, you will see a message at
the bottom of the Output window as in the following screenshot:
7. Note: The MSVC/EE solution files will automatically perform several steps
that are usually done manually in a Linux/Unix installation. These include
downloading of all the sound and music files, and building optional modules
like Flite (text-to-speech) and PocketSphinx (speech recognition). However,
these optional modules still need to be enabled in modules.conf.xml if you
wish to have them automatically loaded when FreeSWITCH starts. (See the
next screenshot.)
8. Once the solution is built you can close MSVC. All remaining steps are
performed from the Windows Explorer or the Windows command line.](https://image.slidesharecdn.com/1114112-250602213832-fc60fb3b/85/Freeswitch-106-Anthony-Minessale-Darren-Schreiber-Michael-S-Collins-53-320.jpg)
Freeswitch 106 Anthony Minessale Darren Schreiber Michael S Collins
- 1. Freeswitch 106 Anthony Minessale Darren Schreiber Michael S Collins download https://ebookbell.com/product/freeswitch-106-anthony-minessale- darren-schreiber-michael-s-collins-2228224 Explore and download more ebooks at ebookbell.com
- 2. Here are some recommended products that we believe you will be interested in. You can click the link to download. Freeswitch 18 Anthony Minessale Ii Giovanni Maruzzelli https://ebookbell.com/product/freeswitch-18-anthony-minessale-ii- giovanni-maruzzelli-58262808 Freeswitch 12 Anthony Minessale Michael S Collins Darren Schreiber https://ebookbell.com/product/freeswitch-12-anthony-minessale-michael- s-collins-darren-schreiber-4453090 Freeswitch 16 Cookbook Over 45 Practical Recipes To Empower You With The Latest Freeswitch 16 Features Anthony Minessale Ii https://ebookbell.com/product/freeswitch-16-cookbook- over-45-practical-recipes-to-empower-you-with-the-latest- freeswitch-16-features-anthony-minessale-ii-5470250 Freeswitch Cookbook Anthony Minessale Michael S Collins Darren Schreiber https://ebookbell.com/product/freeswitch-cookbook-anthony-minessale- michael-s-collins-darren-schreiber-2627278
- 3. Mastering Freeswitch Anthony Minessale Ii Giovanni Maruzzelli https://ebookbell.com/product/mastering-freeswitch-anthony-minessale- ii-giovanni-maruzzelli-6808768
- 5. FreeSWITCH 1.0.6 Build robust high performance telephony systems using FreeSWITCH Anthony Minessale Michael S. Collins Darren Schreiber BIRMINGHAM - MUMBAI
- 6. FreeSWITCH 1.0.6 Copyright © 2010 Packt Publishing All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the authors, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book. Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information. First published: July 2010 Production Reference: 1190710 Published by Packt Publishing Ltd. 32 Lincoln Road Olton Birmingham, B27 6PA, UK. ISBN 978-1-847199-96-6 www.packtpub.com Cover Image by Leisha Bryant ([email protected])
- 7. Credits Authors Anthony Minessale Michael S. Collins Darren Schreiber Reviewer Justin Zimmer Acquisition Editor Usha Iyer Development Editors Neha Patwari Tarun Singh Technical Editors Rupal J Charumathi Sankaran Copy Editors Neha Shetty Leonard D'Silva Indexer Tejal Daruwale Editorial Team Leader Aanchal Kumar Project Team Leader Priya Mukherji Project Coordinator Prasad Rai Proofreader Lynda Sliwoski Graphics Geetanjali Sawant Production Coordinator Shantanu Zagade Cover Work Shantanu Zagade
- 8. About the Authors Anthony Minessale has been involved in telephony since 2003. Prior to that, he had spent over ten years as a CTO and platform designer for various companies during the height of the Internet revolution. He has spent over half a decade working as the creator and lead developer of the FreeSWITCH open source project and several years before that as a volunteer developer for the Asterisk open source PBX, and is a noted contributor of several features on that project as well. Anthony is the creator and owner of FreeSWITCH Solutions LLC, responsible for the popular annual VoIP conference, ClueCon, held every summer in Chicago. Anthony also works for Barracuda Networks as the director of Engineering for the CudaTEL PBX appliance, a product he and his team handcrafted to work with FreeSWITCH as the telephony engine. I would like to thank the awesome FreeSWITCH community for their dedication to our project and the invaluable feedback they provide on a daily basis. A really big thank you to Michael Collins and Darren Schreiber for helping to put this book together. I would also like to thank Brian West and Michael Jerris for helping make FreeSWITCH even possible with all the time they devote to making it work. Finally I would like to thank the original Asterisk community who inspired us all to relentlessly push forward in open source telephony.
- 9. Michael S. Collins is a telephony and open source software enthusiast. He is a PBX veteran, having worked as a PBX technician for five years and as the head of IT for a call center for more than nine years. Michael is an active member of the FreeSWITCH community. He currently works for Barracuda Networks, Inc. I would like to thank, first and foremost, my wife, Lisa, my daughter, Katherine, and my son, Sean, who keep me going each day. I would also like to thank the many FreeSWITCH experts around the world who are so willing to answer technical questions: Michael Jerris, Moises Silva, Raymond Chandler, Mathieu Réné and more. I would especially like to thank Brian K. West for taking me under his wing and educating me in the ways of VoIP. Finally, I would like to say thank you to Anthony Minessale for authoring an amazing piece of software and inviting me to work with the core FreeSWITCH development team. Darren A. Schreiber is helping pioneer the way to distributed cloud telephony solutions. He is the founder of the 2600hz Project, the TCAI project, and is the author of the latest version of FreePBX, a popular open source telephony management system. He has worked in Enterprise IT for over 15 years and has lead teams in successful projects in telecom, marketing, and web-based SaaS spaces. He has been a serious telephony enthusiast from a young age and has been working extensively with VoIP technologies for the past seven years. Darren graduated from Rensselaer with a degree in Computer Science and Business Entrepreneurship.
- 10. About the Reviewer Justin Zimmer has worked in the contact center technology field for over twelve years. During that time, he has performed extensive software and computer telephony integrations using both PSTN and IP telephony. His current projects include system designs utilizing open source softswitches over more traditional proprietary hardware-based telephony, and the integration of these technologies into market-specific CRM products. As the Technical Partner of Unicore Technologies out of Phoenix, AZ, Justin is developing hosted contact center solutions for the low-end market. Unicore's solutions present contact centers with low startup costs in a turbulent economy, and allows those centers to scale their business while maintaining a consistent and familiar user interface. I'd like to thank the countless community contributors that have provided enough online documentation to make this book as accurate and helpful as possible. And I'd like to thank my wife Nicole for putting up with the extra hours spent reviewing this book, as well as my boys Micah, Caden, and daughter Keira for giving up some of their daddy-time for this project.
- 11. Table of Contents Preface 1 Chapter 1: Architecture of FreeSWITCH 7 A revolution has begun and secrets have been revealed 7 The FreeSWITCH design: modular, scalable, and stable 8 Important modules: Endpoint and Dialplan 10 Complex applications made simple 14 Voicemail 14 Multi-party conferencing 16 The FreeSWITCH API (FSAPI) 17 The XML registry 19 Language modules 20 The default configuration 20 Summary 22 Chapter 2: Building and Installation 23 Setting up the FreeSWITCH environment 24 Operating system 24 Operating system prerequisites 24 Linux/Unix 25 Mac OS X 25 Windows 25 Text editors and XML 26 Downloading the source 26 Building from the latest code 27 Compiling FreeSWITCH for Linux/Unix/Mac OS X 28 Compiling FreeSWITCH 28 Step 1: Edit modules.conf 28 Step 2: Run configure script 29 Step 3: Run make and make install 30 Step 4: Edit modules.conf.xml 31
- 12. Table of Contents [ ii ] Step 5: Install sound and music files 32 Compiling FreeSWITCH for Windows 33 Building the solution with MSVC/MSVCEE 33 Starting FreeSWITCH 37 Running FreeSWITCH in the background 38 Summary 40 Chapter 3: Test Driving the Default Configuration 41 Important concepts to understand 41 Putting FreeSWITCH to work 46 Controlling FreeSWITCH with the CLI 46 Configuring a SIP phone to work with FreeSWITCH 49 SIP settings 50 Testing the default Dialplan 57 Test calls for a single phone 57 Test calls for two or more phones 60 Summary 62 Chapter 4: SIP and the User Directory 63 Understanding the FreeSWITCH user directory 63 Working with the FreeSWITCH user directory 65 User features 66 Adding a user 67 Testing voicemail 70 Groups of users 72 Connecting to the world with gateways 74 Setting up a new gateway 74 Making calls 77 Receiving calls 78 Making calls without a gateway 78 SIP profiles and user agents 79 Summary 80 Chapter 5: Understanding the XML Dialplan 81 FreeSWITCH XML Dialplan elements 82 Call legs and channel variables 82 Accessing channel variables 84 Regular expressions 85 Contexts 86 Default 87 Public 87 Features 87 Extensions 88 Conditions 88 Actions and anti-actions 90
- 13. Table of Contents [ iii ] How Dialplan processing works 91 Creating a new extension 95 Important Dialplan applications 97 bridge 98 playback 98 say 98 play_and_get_digits 99 ivr 100 sleep 101 answer 101 hangup 101 set 101 Dialstring formats 102 Summary 104 Chapter 6: Using the Built-in XML IVR Engine 105 IVR engine overview 106 IVR XML configuration file 106 IVR menu definitions 107 greet-long 108 greet-short 108 invalid-sound 108 exit-sound 109 timeout 109 inter-digit-timeout 109 max-failures 110 max-timeouts 110 digit-len 110 tts-voice 110 tts-engine 110 confirm-key 111 IVR menu destinations 111 menu-exec-app 112 menu-exec-api 112 menu-play-sound 113 menu-back 113 menu-top 113 Routing calls to your IVR 114 Nesting IVRs 114 Using phrases with IVRs 115 Calling Phrase Macros 115
- 14. Table of Contents [ iv ] Phrase Macro examples: voicemail 116 Advanced routing 120 Summary 122 Chapter 7: Building IVR Applications with Lua 123 Getting started with Lua 124 Running Lua scripts from the Dialplan 124 Basic Lua syntax 125 Building voice applications 126 Simple IVR—interacting with the caller 129 Conditions and looping 131 Advanced IVR concepts 140 Connecting to a database with LuaSQL 141 Making a web call with curl 146 Lua patterns versus regular expressions 151 Scripting tips 152 Summary 153 Chapter 8: Advanced Dialplan Concepts 155 Dialplan overview 156 General Dialplan concepts 159 Contexts 160 Conditions 161 Actions 162 Putting it all together 163 XML Dialplan module review 164 Extensions 165 Conditions 166 Special condition variables 169 Inline execution 170 Actions and anti-actions 172 Pitfalls to avoid 172 XML Dialplan commands 174 Hunting versus executing 179 Utilizing variables 184 Testing variables with regular expressions 184 Caller profile fields 184 Channel variables 185 Channel variables and call setup 185 Global variables 187 Dialplan functions 187 Real-time condition evaluation 188 String conditioning 189
- 15. Table of Contents [ ] Database queries 189 SIP contact parameters 190 Set, export, and legs 191 Set versus export 191 Passing variables via call headers 192 XML Dialplan cookbook 192 Match by IP address and call a number 192 Match IP address and Caller ID 194 Match number and strip digits 194 Match number, strip digits, and add prefix 195 Call registered device 195 Try party A, then party B 196 Check for authenticated user 196 Route DIDs to extensions 197 Try a local extension, failback to voicemail 197 Alternate outbound gateways 198 Alternatives to XML 198 YAML 199 Asterisk Dialplan 199 Summary 200 Chapter 9: Controlling FreeSWITCH Externally 201 General overview 202 Event system architecture 203 Event-based modules 203 mod_event_socket 204 Configuring event socket settings 204 Reading events 205 Sending events 208 Events from the Dialplan 209 mod_event_multicast 210 Port/address 210 Bindings 211 TTL 211 mod_erlang_event 211 FreeSWITCH event system commands 211 auth password 211 api 212 bgapi 212 event 213 divert_events 214 filter 214 filter delete 215
- 16. Table of Contents [ vi ] sendevent 215 sendmsg uuid 216 execute 217 hangup 217 nomedia 218 log level 218 nolog 218 noevents 218 Event-based applications 218 FreeSWITCH Console application 219 PHP Socket connections 219 Perl Socket connections 219 Event Socket Library 220 Supported libraries 220 ESLObject 220 eslSetLogLevel($loglevel) 221 ESLevent object 221 serialize([$format]) 221 setPriority([$number]) 221 getHeader($header_name) 221 getBody() 221 getType() 221 addBody($value) 222 addHeader($header_name, $value) 222 delHeader($header_name) 222 firstHeader() 222 nextHeader() 222 ESLconnection object 222 new($host, $port, $password) 222 new($fd) 223 socketDescriptor() 223 connected() 223 getInfo() 223 send($command) 223 sendRecv($command) 223 api($command[, $arguments]) 224 bgapi($command[, $arguments]) 224 sendEvent($send_me) 224 recvEvent() 224 recvEventTimed($milliseconds) 224 filter($header, $value) 224 events($event_type,$value) 225 execute($app[, $arg][, $uuid]) 225 executeAsync($app[, $arg][, $uuid]) 225 setAsyncExecute($value) 225 setEventLock($value) 225 disconnect() 226
- 17. Table of Contents [ vii ] Events in practice 226 Event Socket Library example: running a command 226 Examples of sending events to FreeSWITCH 227 Setting phone lights 227 Rebooting a phone 228 Requesting phone reconfiguration 228 Custom notify messages 228 Summary 229 Chapter 10: Advanced Features and Further Reading 231 Multi-user conferencing 232 Configuration 232 Conference profiles 232 Caller controls 237 Advertise 237 Sending and receiving XMPP events 238 Connecting callers to the conference 238 Controlling active conferences 239 Nibblebill 239 Use cases 240 Billing (pre-pay) 240 Billing (post-pay) 240 Pay-per-call service billing 240 Maximum credit and/or fraud prevention 240 Design goals 241 Installation and configuration 241 Database tables 242 Creating the database table for PostgreSQL 242 Creating the database table for MySQL 243 Billing a call 243 Nibble method (default) 243 Alternative to nibble billings 244 Examples 244 Different rates per user 244 Single rate for all users 245 Different rates per area code 246 Different rates per service delivery 247 Hang up the call when the balance is depleted 248 Application/CLI/API commands 249 Check 249 Flush 249 Pause 250 Resume 250 Reset 250 Adding and deducting funds 250 Enabling session heartbeat 251 Bill based on B leg only 251
- 18. Table of Contents [ viii ] XML/Curl 251 Installation 252 Configuration 253 Bindings 254 HTTP requests 255 HTTP response 255 Optimization 256 Order of requests 256 Request/response examples 256 Dialplan bindings 261 Request 261 Reply 262 Other bindings 262 General Not found reply 262 Debugging 263 Failing back 263 Alternative endpoints 264 Skype and GSM endpoints 264 Skype with mod_skypopen 265 GSM with mod_gsmopen 266 TDM with OpenZAP and FreeTDM 267 Configuration tools and related projects 267 Web GUIs 267 WikiPBX 268 FreePBX v3 268 FusionPBX 269 2600hz 270 Supporting libraries 270 Liverpie (Ruby) 271 FreeSWITCHeR (Ruby) 271 Librevox (Ruby) 271 EventSocket (Python/Twisted) 271 FSSocket (Perl) 272 Summary 272 Appendix A: The FreeSWITCH Online Community 273 The FreeSWITCH mailing lists 273 Talking in real-time via IRC 275 The FreeSWITCH main website and wiki 277 The main FreeSWITCH page—www.freeswitch.org 277 The FreeSWITCH Wiki page—wiki.freeswitch.org 277 The annual ClueCon open source developer conference 278 Appendix B: The History of FreeSWITCH 279 Index 287
- 19. Preface In 1999, the first shot of the telephony revolution was fired when the Asterisk PBX was released to the world. In the ensuing decade, open source telephony took the world by storm, lead by Asterisk and a host of other software packages such as OpenSER and YATE. In 2006, an Asterisk developer named Anthony Minessale announced an ambitious project: a new telephony software engine, built from the ground up. Some thought this was crazy considering the wild success of the Asterisk platform. However, Anthony's vision was to create a telephony platform unlike any in existence—open source or proprietary. In May 2008, this new project reached a critical milestone with the release of FreeSWITCH 1.0.0. Now that FreeSWITCH has been available for several years, some developers have migrated from Asterisk to FreeSWITCH. Others have added FreeSWITCH to an existing environment, having it work together with Asterisk, OpenSER, OpenSIPS, Kamailio, and other telephony applications. Is FreeSWITCH right for you? The correct answer is, of course: It depends. When people ask the FreeSWITCH developers which telephony software they should use, the developers always reply with another correct answer: Use what works for your situation. To know the answer you will need to investigate further. What FreeSWITCH is and what it is not FreeSWITCH is a scalable softswitch. In practical terms this means that it can do anything a traditional PBX can do and much more. It can (and does) act as the core switching software for commercial carriers. It can scale up to handle thousands of simultaneous calls. It can also scale down to act as a simple softphone for your laptop or personal computer. It can also work in a cluster of servers.
- 20. Preface [ ] FreeSWITCH is not a proxy server. If you need proxy server functionality, then consider OpenSIPS, Kamailio, or other similar software. FreeSWITCH is a back-to-back user agent or B2BUA. In this regard, it is similar to Asterisk and other IP PBX software. Version and licensing At the time of this writing this book, the FreeSWITCH developers were putting the finishing touches on FreeSWITCH version 1.2. While the examples presented in this book were specifically tested with version 1.0.6, they have also been confirmed to work with the latest FreeSWITCH development versions that form the basis of version 1.2. Do not be concerned about the fact that this material does not cover version 1.2—it certainly does. The FreeSWITCH user interface is very stable between versions; therefore, this text will be applicable for years to come. FreeSWITCH is released under the Mozilla Public License (MPL) version 1.1. Since FreeSWITCH is a library that can be implemented in other software applications and projects, the developers felt it important to strike a balance between the extremely liberal BSD license and the so-called viral GPL. The MPL fits this paradigm well and allows businesses to create commercial products based on FreeSWITCH without licensing concerns. However, what about using FreeSWITCH with GPL-based software? It should suffice if we said that the developers wanted to make sure that anyone, including proprietary and GPL-based software users, could use FreeSWITCH. The powerful event socket gives us this functionality—a simple TCP socket-based interface that allows an external program to control FreeSWITCH. Regardless of the license you may be using for your own software, you can still connect to a FreeSWITCH server without any licensing issues. What this book covers Chapter 1, Architecture of FreeSWITCH gives a brief, but thorough introduction to the underlying architecture of FreeSWITCH. Chapter 2, Building and Installation shows how to download and install FreeSWITCH on Windows and Unix-like operating systems. Chapter 3, Test Driving the Default Configuration provides a hands-on look at the powerful and feature-rich default FreeSWITCH configuration. Chapter 4, SIP and the User Directory offers an introduction to the concept of users and the directory as well as brief look at SIP user agents.
- 21. Preface [ ] Chapter 5, Understanding the XML Dialplan explains the basics of creating and editing Dialplan extensions to add advanced functionality to a FreeSWITCH install. Chapter 6, Using the Built-In XML IVR Engine discusses how to create menus and sound phrases for interacting with callers. Chapter 7, Building IVR Applications with Lua introduces the concept of advanced call handling using the lightweight scripting language Lua. Chapter 8, Advanced Dialplan Concepts builds upon the foundation laid in Chapter 5 and shows how to handle more challenging routing scenarios. Chapter 9, Controlling FreeSWITCH Externally introduces the incredibly powerful Event Socket and the Event Socket library that can be used to access and control a FreeSWITCH server. Chapter 10, Advanced Features and Further Reading highlights some of the more powerful FreeSWITCH features like conferencing and offers some ideas on where to learn more about FreeSWITCH. Appendix A, The FreeSWITCH Online Community gives a brief introduction to the worldwide online community and the tools used to stay in contact. Appendix B, The History Of FreeSWITCH is a description of how FreeSWITCH came to be from one of the authors, Anthony Minessale. Who this book is for This book is for prospective FreeSWITCH administrators as well as enthusiasts who wish to learn more about how to set up, configure, and extend a FreeSWITCH installation. If you are already using FreeSWITCH, you will find that the information in this book compliments what you have already learned from your personal experience. A solid understanding of basic networking concepts is very important. Previous experience with VoIP is not required, but will certainly make the learning process go faster. Conventions In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning.
- 22. Preface [ ] Code words in text are shown as follows: �������������������������������������������� If there is a match, (and there always will be), then this macro plays the vm-goodbye.wav file�� . A block of code is set as follows: action application=���������� playback data=phrase:myphrase:arg1:arg2:arg3/ action application=play_and_get_digits data=2 5 3 7000 # phrase:myphrase:arg1 /invalid.wav my_var d+/ When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold: input pattern=^(1):(.*)$ break_on_match=true match action function=play-file data=voicemail/vm-you_have.wav/ action function=say data=$1 method=pronounced type=items/ action function=play-file data=voicemail/vm-$2.wav/ action function=play-file data=voicemail/vm-message.wav/ /match /input Any command-line input or output is written as follows: freeswitch@localhostversion FreeSWITCH Version 1.0.6 (exported) New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in the text like this: New users should join only the FreeSWITCH-users list, until they are comfortable with the project. Warnings or important notes appear in a box like this. Tips and tricks appear like this.
- 23. Preface [ ] Reader feedback Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of. To send us general feedback, simply send an e-mail to [email protected], and mention the book title via the subject of your message. If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or e-mail [email protected]. If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors. Customer support Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase. Downloading the example code for the book You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub. com/support and register to have the files e-mailed directly to you. Errata Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www. packtpub.com/support, selecting your book, clicking on the let us know link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata will be uploaded on our website, or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.
- 24. Preface [ ] Piracy Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy. Please contact us at [email protected] with a link to the suspected pirated material. We appreciate your help in protecting our authors and our ability to bring you valuable content. Questions You can contact us at [email protected] if you are having a problem with any aspect of the book, and we will do our best to address it.
- 25. Architecture of FreeSWITCH Welcome to FreeSWITCH! If you are reading this, then, undoubtedly, you are interested in things like telecommunications and Voice over Internet Protocol (VoIP). FreeSWITCH is revolutionary software created during a telephony revolution. Before looking at the architecture of this powerful software, let's take a look at the colorful world of telecommunications. This will help to put FreeSWITCH into perspective. In this chapter, we cover: A telephony revolution Advantages of FreeSWITCH Endpoint and Dialplan modules How FreeSWITCH simplifies complex applications like Voicemail A revolution has begun and secrets have been revealed How and why the telephone works is a mystery to most people. It has been kept secret for years. We just plugged our phones into the wall and they worked, and most people do just that and expect it to work. The telephony revolution has begun, and we have begun to pry the secrets from the clutches of the legacy of the telephony industry. Now, everyday individuals like you and me are able to build phone systems that outperform traditional phone services and offer advanced features for relatively low cost. Some people even use FreeSWITCH to provide telephone services for making a profit. FreeSWITCH has been designed to make all of this easier, so we will go over the architecture to get a better understanding of how it works. • • • •
- 26. Architecture of FreeSWITCH [ ] Do not be concerned if some of these concepts seem unnaturally abstract. Learning telephony takes time, especially VoIP. In fact, we recommend that you read this chapter more than once. Absorb as much as you can on the first pass, then come back after you complete Chapter 5, Understanding the XML Dialplan. You will be surprised at how much your understanding of VoIP and FreeSWITCH has improved. Then come back and skim it a third time after you have completed Chapter 9, Controlling FreeSWITCH Externally, at this point, you will have a firm grasp of VoIP and FreeSWITCH concepts. Give yourself plenty of time to digest all of these strange new concepts, and soon you will find that you are a skilled FreeSWITCH administrator. If you keep at it, you will be rewarded with a meaningful understanding of this strange and wonderful world we call telephony. Telephones and the systems are very complicated and have evolved over the years into several varieties. The most popular type of phone in the U.K. and the U.S. is the traditional analog phone, which we affectionately refer to as POTS lines or Plain Old Telephone Service. From the traditional Ma Bell phone up to the long-range cordless phones that most of us have today, one thing has remained the same—the underlying technology. In the last 10-15 years, there has been a convergence of technology between computers and telephones that has produced a pair of affordable alternatives to POTS lines—Mobile phones and VoIP phones (also called Internet Phones). FreeSWITCH fits into this big tangled mess of various telephone technologies by bridging them together, so that they can communicate despite being otherwise completely incompatible. FreeSWITCH also bridges telephone calls with computer programs that you can write yourself, and controls what happens in ways like never before. FreeSWITCH is software that runs on Windows and several UNIX varieties such as Mac OS X, Linux, Solaris, and BSD. This means you can install FreeSWITCH on your home PC or even a high-end server and use it to process phone calls. Installing FreeSWITCH is discussed in detail in Chapter 2, Building and Installation. We will be doing this as soon as we review the basic architecture. The FreeSWITCH design: modular, scalable, and stable The design goal of FreeSWITCH is to provide a modular, scalable system around a stable switching core, and provide a robust interface for developers to add to and control the system. Various elements in FreeSWITCH are independent of each other and do not have much knowledge about how the other parts are working, other than what is provided in what are called ''exposed functions''. The functionality of FreeSWITCH can also be extended with loadable modules, which tie a particular external technology into the core.
- 27. Chapter 1 [ ] FreeSWITCH has many different module types that revolve around the central core, much like satellites orbiting a planet. The list includes: Module Type: Purpose: Endpoint Telephone protocols like SIP/H.323 and POTS lines. Dialplan Parse the call details and decide where to route the call. Codec Translate between audio formats. Application Perform a task such as play audio or set data. Application Programming Interface (API) Export a function that takes text input and returns text output, which could be used across modules or from an external connection. File Provide an interface to extract and play sound from various audio file formats. Text-To-Speech (TTS) Interface with text-to-speech engines. Automated Speech Recognition ASR Interface with speech recognition systems. Directory Connect directory information services, such as LDAP, to a common core lookup API. Chat Bridge and exchange various chat protocols. Say String together audio files in various languages to provide feedback to say things like phone numbers, time of day, spell words, and so on.
- 28. Architecture of FreeSWITCH [ 10 ] By combining the functionality of the various module interfaces, FreeSWITCH can be configured to connect IP phones, POTS lines, and IP-based telephone service. It can also translate audio formats and interfaces with a custom menu system, which you can create by yourself. You can even control a running FreeSWITCH server from another machine. Let's start by taking a closer look at one of the more widely used modules, namely, the Endpoint module. Important modules: Endpoint and Dialplan Endpoint modules are critically important and add some of the key features which make FreeSWITCH the powerful platform it is today. The primary role of these modules is to take certain common communication technologies and normalize them into a common abstract entity which we refer to as a session. A session represents a connection between FreeSWITCH and a particular protocol. There are several Endpoint modules that come with FreeSWITCH, which implement several protocols such as SIP, H.323, Jingle (Google Talk), and some others. We will spend some time examining one of the more popular modules named mod_sofia. Sofia-SIP (http://sofia-sip.sourceforge.net) is an open source project sponsored by Nokia, which is determined to make a programming interface to the Session Initiation Protocol or SIP. We use this library in FreeSWITCH in a module we call mod_sofia. This module registers to all the hooks in FreeSWITCH necessary to make an Endpoint module, and translates the native FreeSWITCH constructs into SIP constructs and back again. Configuration information is taken from the central FreeSWITCH configuration files, which allows mod_sofia to load user-defined preferences and connection details. This allows FreeSWITCH to accept registration from SIP phones and devices, register to other SIP Endpoints such as service providers, send notifications, and provide services to the phones such as voicemail. When a SIP call is established between FreeSWITCH and another SIP device, it will show up in FreeSWITCH as an active session. If the call is inbound, it can be transferred or bridged to interactive voice response (IVR) menus, hold music, or one or more extensions, though numerous other options are available. Let's examine a typical scenario where a SIP phone registered as extension 2000 calls extension 2001, with the hope of establishing a call.
- 29. Chapter 1 [ 11 ] First, the SIP phone sends a call setup message to mod_sofia over the network (mod_sofia is ''listening'' for such messages). After receiving the message, mod_sofia in turn parses the relevant details and passes the call into the core state machine in FreeSWITCH. The state machine (in the FreeSWITCH core) then sends the call into the ROUTING state. The next step is to locate the Dialplan module, based on the configuration data for the calling Endpoint. The default and most widely used Dialplan module is the XML Dialplan module. This module is designed to look up a list of instructions from the central XML registry within FreeSWITCH. The XML Dialplan module will parse a series of XML extension objects using regular expression pattern-matching. As we are trying to call 2001, we hope to find an XML extension testing the destination_number field for something that matches ''2001'' and routes accordingly. The Dialplan is not limited to matching only a single extension. In fact, in Chapter 5, Understanding the XML Dialplan, you will get an expanded definition of the term ''extension''. The XML Dialplan module builds a sort of ''task list'' for the call. Each extension that matches it will have its actions added to the call's task list. Assuming FreeSWITCH finds at least one extension, the XML Dialplan will insert instructions into the session object with the information it needs to try and connect the call to 2001. Once these instructions are in place, the state of the calling session changes from ROUTING to EXECUTE where the next handler drills down the list and executes the instructions obtained by the ROUTING state. This is where the application interface comes into the picture. Each instruction is added to the session in the form of an application name and a data argument that will be passed to that application. The one we will use in this example is the bridge application. The purpose of this application is to create another session with an outbound connection, then connect the two sessions for direct audio exchange. The argument we will supply to bridge will be user/2001, which is the easiest way to generate a call to extension 2001. A Dialplan entry for ''2001'' might look like this: extension name=example condition field=destination_number expression=^2001$ action application=bridge data=user/2001/ /condition /extension The extension is named ''example'', and it has a single condition to match. If the condition is matched, it has a single application to execute. In plain language, the mentioned extension could be expressed like this: If the caller dialed ''2001'', then this establishes a connection between the calling party and the endpoint (that is, telephone) at 2001. Consider how this happens.
- 30. Architecture of FreeSWITCH [ 12 ] Once we have inserted the instructions into the session, the session's state will change to EXECUTE, and the FreeSWITCH core will use the data collected to perform the desired action. First, the default execute state handler will parse the command to execute bridge on user/2001, then it will look up the bridge application and pass the user/2001 data in. This will cause the FreeSWITCH core to create a new outbound session of the desired type. User 2001 is also a SIP phone, so the user/2001 will resolve into a SIP dial string, which will be passed to mod_sofia to ask it to create a new outbound session. If the setup for that new session is successful, there will now be two sessions in the FreeSWITCH core. The bridge application will take the new session and the original session (the caller's phone) and call the bridge function on it. This allows the audio to flow in both directions, once the person at extension 2001 actually answers the phone. If that user was unable to answer or was busy, a timeout (that is, a failure) would occur and send the corresponding message back to the caller's phone. If a call is unanswered or an extension is busy, many routing options are possible, including call forwarding or voicemail. All of this happens from the simple action of picking up the phone handset and dialing 2 0 0 1. FreeSWITCH takes all of the complexity of SIP and reduces it to a common denominator. From there, it reduces the complexity further by allowing us to configure a single instruction in the Dialplan to connect the phone at 2000 to the phone at 2001. If we want to allow the phone at 2001 to be able to call the phone at 2000, we can add another entry in the Dialplan going the other way. extension name=example 2 condition field=destination_number expression=^2000$ action application=bridge data=user/2000/ /condition /extension In this scenario, the Endpoint module turned SIP into a FreeSWITCH session and the Dialplan module turned XML into an extension. The bridge application turned the complex code of creating an outbound call, and connecting the audio into a simple application/data pair. Both the Dialplan module and the application module interface are designed around regular FreeSWITCH sessions. Therefore, not only does the abstraction make life easier for us at the user level, it also simplifies the design of the application and the Dialplan because they can be made agnostic of the actual endpoint technology involved in the call. It is because of this abstraction, when we make up a new Endpoint module tomorrow for something like Skype (there is actually such a thing present, by the way), that we can reuse all the same application and Dialplan modules. The same principle applies to the Say, ASR, TTS, and other such modules.
- 31. Chapter 1 [ 13 ] It is possible that you may want to work with some specific data provided by the Endpoint's native protocol. In SIP, for instance, there are several arbitrary headers as well as several other bits of interesting data from the SIP packets. We solve this problem by adding variables to the channel. Using channel variables, mod_sofia can set these arbitrary values as they are encountered in the SIP data where you can retrieve them by name from the channel in your Dialplan or application. This way we share our knowledge of these special variables with the SIP Endpoint. However, the FreeSWITCH core just sees them as arbitrary channel variables, which the core can ignore. There are also several special reserved channel variables that can influence the behavior of FreeSWITCH in many interesting ways. If you have ever used a scripting language or configuration engine that uses variables, then you are at an advantage because channel variables are pretty much the same concept. There is simply a variable name and a value that is passed to the channel and the data is set. There is even an application interface for this: the set application that lets you set your own variables from the Dialplan. extension name=example 3 condition field=destination_number expression=^2000$ action application=set data=foo=bar/ action application=bridge data=user/2000/ /condition /extension The recent example is almost identical to the previous example, but instead of just placing the call, we first set the variable ''foo'' equal to the value ''bar''. This variable will remain set throughout the call and can even be referenced at the end of the call in the detail logs. The more we build things in small pieces, the more the same underlying resources can be reused, making the system simpler to use. For example, the codec interface knows nothing else about the core, other than its own isolated world of encoding and decoding audio packets. Once a proper codec module has been written, it becomes usable by any Endpoint interface capable of carrying that codec in its audio stream. This means that if we get a Text-To-Speech module working, we can generate synthesized speech on any and all Endpoints that FreeSWITCH supports. It does not matter which one comes first as they have nothing to do with each other. However, the addition of either one instantly adds functionality to the other. The TTS module becomes more useful because it can use more codecs; the codecs have become more useful because we added a new function that can take advantage of them. The same idea applies to applications. If we write a new application module, the existing endpoints will immediately be able to run and use that application.
- 32. Architecture of FreeSWITCH [ 14 ] Complex applications made simple FreeSWITCH removes much of the complexity of more advanced applications. Let's look at two examples of a more complex application. Voicemail The first application we will discuss is the voicemail application. The general purpose of this application is probably pretty easy to deduce. It provides voicemail service. This application is useful to add right after the bridge application as a second option, in case the call was not completed. We can do this with a careful combination of application choices, and one of those fancy ''special'' variables that we were discussing earlier. Let's look at a new version of our last extension that also allows us to leave a voicemail: extension name=example 4 condition field=destination_number expression=^2000$ action application=set data=hangup_after_bridge=true/ action application=bridge data=user/2000/ action application=voicemail data=default ${domain} 2000/ /condition /extension Here we see two uses of channel variables. First we set hangup_after_bridge=true telling the system to just hang up once we have had at least one successfully bridged call to another phone and to disregard the rest of the instructions. We are also using the domain variable as seen in brackets prefixed with a dollar sign, ${domain}. This is a special variable that defaults to the auto-configured domain name, which all the phones are using from the configuration. In the example, we check if someone is dialing 2000. We then try to bridge the call to the phone registered to extension 2000. If the call fails or there is no answer, we will continue to the next instruction, which is to execute the voicemail application. We provide the information the application needs to know, and which extension the voicemail is for so it knows how to handle the situation. Next, the voicemail application plays the pre-recorded greeting or generates one for you using the Say module's interface we briefly discussed earlier. It strings together sound files to make a voice say ''The person at extension 2 0 0 0 is not available, please leave a message''. Next, mod_voicemail prompts you to record a message, and now is your chance to leave your mark in that person's inbox by leaving a voice message. As an additional feature, if you are not satisfied with your recording, you can repeat it as many times as you wish. Once you finally commit, a FreeSWITCH MESSAGE_WAITING event is fired into the core event system, which is picked up by mod_sofia by way of an event
- 33. Chapter 1 [ 15 ] consumer, where the event information is translated into SIP. If everything goes as planned, the phone registered on extension 2000 will illuminate its message-waiting indicator light! Again in this example, not only have we seen how to play a greeting, record a message, and send it to a user, we have also uncovered another unsung hero of the FreeSWITCH core—the event system. The FreeSWITCH event system is not a module interface like the other examples, it is a core engine that you can use to bind to named events and react accordingly when an event is received. In other words, throughout the FreeSWITCH core, there are events that are sent and received. Modules can bind to (that is ''listen'' for) various events. They can also ''fire'' events into the event engine; other modules can listen for those events. As we discussed, the Sofia SIP module binds or subscribes to the event designated for MESSAGE_WAITING information. This allows our mod_voicemail module to interact with mod_sofia, without either system having any knowledge about the other's existence. The event is fired by mod_voicemail, received by mod_sofia, and translated into the proper SIP message—all seemingly magical, courtesy of the event system. There are several challenges with such a complex interactive system when considering all of the possible languages it may need to support as well as what files to play for the automated messages and how they are strung together. The Say module supplies a nice way to string files together, but it is somewhat limited to something specific like spelling a word, counting something, or saying a certain date. The way we overcome this is by defining a more complex layer on top of the Say module called Phrase Macros. Phrase Macros are a collection of XML expressions that pull out a list of arguments by matching a regular expression and executing a string of commands. This is very similar to how the XML Dialplan works, only custom-tailored for interactive voice response scenarios (IVR). For example, when mod_voicemail asks you to record your message, rather than coding in the string of files to make it say that, the code just calls a Phrase Macro called voicemail_ record_message. This arbitrary string is shared between mod_voicemail and the Phrase Macro section in the configuration allowing us, the users, to edit the file without doing any fancy programming. macro name=voicemail_record_message input pattern=^(.*)$ match action function=play-file data=voicemail/vm record_message.wav/ /match /input /macro
- 34. Architecture of FreeSWITCH [ 16 ] When mod_voicemail executes the voicemail_record_message macro, it first matches the pattern, which, in this case, is just to match everything, as this particular macro has no input. If the macro did have input, the pattern matching could be used to perform different actions based on different input. Once a match is found, the match tag is parsed in the XML for action tags just like in our Dialplan example. This macro just plays the file vm_record_message.wav, but more complicated macros, like the ones for verifying your recording or telling you how many messages you have in your inbox, may use combinations of various say modules and playing of audio files. Phrase Macros are discussed in detail in Chapter 6, Using the Built-in XML IVR Engine and used extensively in Chapter 7, Building IVR Applications With Lua. Once again, we have cooperation among the phrase system, the audio file, and the Say modules loaded by the core being joined together to enable powerful functionality. The Say modules are written specifically for a particular language or ''voice'' within a language. We can programmatically request to say a particular time and have it translated into the proper Say module based on input variables. The Phrase Macro system is a great way to put bigger variable concepts into your code, which can be easily tweaked later by everyday users. For example, if we wanted to make a small IVR that asks us to dial a four-digit number and then just read it back and hang up, we could make one macro called ''myapp_ask_for_digits'' and the other called ''myapp_read_digits''. In our code, we would execute these macros by name—the first one when it is time to ask for the digits and the other one to read back the digits by passing in the value we entered. Once this is in place, a less-experienced individual could implement the XML files to play the proper sounds. He/she can use the Say modules to read back the number, and it could all be working in multiple languages with no further coding necessary. Voicemail is just one example of FreeSWITCH in use as an application server. There are endless possibilities when we use FreeSWITCH to connect phone calls with computers. Multi-party conferencing Another popular feature of FreeSWITCH is delivered by the mod_conference conferencing module. The mod_conference module provides dynamic conference rooms that can bridge together the audio from several audio channels. This can be used to hold meetings where there are several callers who want to interact on the same call. Each new session that connects to the same conference room will join the others, and instantly be able to talk to all of the other participants at the same time. By using a Dialplan example, similar to the one we used for bridging to another phone, we can make an extension to join a conference room:
- 35. Chapter 1 [ 17 ] extension name=example 4 condition field=destination_number expression=^3000$ action application=conference data=3000@default/ /condition /extension This is just as simple as bridging a call, but what is special about this extension is that many callers can call extension 3000 and join the same conference. If three people joined this conference and one of them decides to leave, the other two would still be able to continue their conversation. The conference module also has other special features, such as the ability to play sound files or text to speech to the whole conference or even just to a single member of the conference. As you may have guessed, we are able to do this by using the TTS and sound file interfaces provided by their respective modules. Once again, the smaller pieces come together to extend the functionality without needing explicit knowledge of the other components in the system. The conference module also uses the event system in a special way called custom events. A module such as mod_conference can reserve a special event namespace called a subclass when it first loads. When something interesting happens, such as when a caller joins or leaves a conference, it fires those events on the CUSTOM event channel in the core. When we are interested in receiving such events, all we have to do is subscribe to the CUSTOM event supplying an extra subclass string, which specifies the specific CUSTOM events we are interested in. In this case, it is conference::maintenance. This makes it possible to look out for important things such as when someone joins or leaves the conference or even when they start and stop talking. Conferencing is discussed in detail in Chapter 10, Advanced Features and Further Reading. The FreeSWITCH API (FSAPI) Another very powerful module interface in FreeSWITCH is the FSAPI module. The principle of this type of interface is very simple—it takes a single string of text as input, which may or may not be parsed, especially by the following code. The return value is also a string that can be of any size, from a single character up to several pages of text, depending on the function that was called. One major benefit of FSAPI functions is that a module can use them to call routines in another module, without directly linking into the actual code. The command-line interface of FreeSWITCH or CLI uses FSAPI functions to pass commands from your prompt.
- 36. Architecture of FreeSWITCH [ 18 ] Here is a small example of how we can execute the status FSAPI command from the FreeSWITCH CLI: freeswitch status API CALL [status()] output: UP 0 years, 3 days, 23 hours, 31 minutes, 31 seconds, 524 milliseconds, 576 microseconds 438 session(s) since startup 6 session(s) 0/30 1000 session(s) max What's really happening here is that when we type status and press the Enter key, the word ''status'' is used to look up the status FSAPI function from the module in which it was implemented. The underlying function is then called, and the core is queried for its status message. Once the status data is obtained, the output is written to a stream that comes back and prints as the result of the command. We have already learned that a module can create and export FSAPI functions, which can be executed from anywhere such as the CLI. But wait, there's more! Modules can also be written to push commands into the FSAPI interface, and send the result over a specific protocol. There are two modules included in FreeSWITCH that do just that—mod_event_socket and mod_xml_rpc (mod_event_socket discussed in detail in Chapter 9, Controlling FreeSWITCH Externally.) Consider the example of mod_xml_rpc. This module implements the standardized XML-RPC protocol as a FreeSWITCH module. Clients using an XML-RPC interface can connect to FreeSWITCH and execute any FSAPI command they choose. So a remote client could execute an RPC call to status, and get a similar status message to the one we saw in the previous example. This same module also provides FreeSWITCH with a general web server, which allows FSAPI commands to be accessed with a direct URL hit. For example, one could point a browser to http://example.freeswitch. box:8080/api/status to access the status command directly over the World Wide Web. By using this technique, it's possible to create FSAPI commands that work similar to a CGI, providing a dynamic web application that has direct access to FreeSWITCH internals. As we can see, the FSAPI interface is very versatile. Now we know it can be used to provide a CLI interface, a way for modules to call functions from each other and a way to export WWW or XML-RPC functions. There is still one more use for FSAPI functions that we have not covered. We touched slightly on the concept of channel variables earlier, noting that we can use the expression ${myvariable} to get the value of a certain variable. FSAPI functions can also be accessed this way in the format ${myfunction()}. This notation indicates that the FSAPI command ''myfunction'' should be called, and that the expression should be replaced with the
- 37. Chapter 1 [ 19 ] output of that function call. Therefore, we can use ${status()} anywhere when variables are expanded to gain access to the status command. For example: action application=set data=my_status=${status}/ The value placed in the my_status variable will be the output from the status command. The drawback to all the versatility provided by a single module interface is that in order to achieve all of this, we have to ''loosely type'' the functionality. This means that there are several cases where a single FSAPI command could easily be accessed, using all of the ways we have discussed. In addition, there are also some other specific functions that are specifically designed for a particular access method. For instance, if we made an FSAPI command that produced HTML intended to be accessed with a web browser, we would not want to access it from the CLI or by referencing it as a variable. Similarly, if we made an FSAPI function that computed some kind of value based on call details, which was designed to be used from the Dialplan, it would not be very useful at the CLI or from the Web. So, with great power comes great responsibility, and this is one case where we need to use common sense to decide when and where to use the proper FSAPI functions to get the most out of them. The XML registry We have now discussed many of the fundamental components of the FreeSWITCH core and how they interact with each other. We have seen how the event system can carry information across the core, and how the XML Dialplan can query the XML registry for data. This would be a good time to explain the XML registry a bit more. The XML registry is a centrally managed XML document that holds all of the critical data, which FreeSWITCH needs to operate properly. The initial document is loaded from your hard drive and passed into a special pre-processor. This pre-processor can include other XML documents and other special operations, such as setting global variables, which can be resolved by the pre-processor further down in the document. Once the entire document and all of the included files are parsed, replaced, and generated into a static XML document, this document is loaded into memory. The XML registry is divided into several sections—configuration, dialplan, directory, and phrases. The core and the modules draw their configuration from the configuration section. The XML Dialplan module draws its Dialplan data from the dialplan section. The SIP authentication, user lookup, and the voicemail module read their account information from the directory section. The Phrase Macros pull their configuration from the phrases section. If we make a change to any of the documents on the disk, we can reload the changes into memory by issuing the reloadxml command from the CLI. (This is an example of using the FSAPI interface to communicate with the FreeSWITCH core.)
- 38. Architecture of FreeSWITCH [ 20 ] Language modules One distinct type of module that does not have a direct interface to FreeSWITCH-like files and Endpoints, but still offers an immensely powerful connection to existing technology, is the Language module. Language modules embed a programming language like Lua, JavaScript, or Perl into FreeSWITCH, and transfer functionality between the core and the language's runtime. This allows things like IVR applications to be written in the embedded language, with a simple interface back to FreeSWITCH for all the heavy lifting. Language modules usually register into the core with the application interface and the FSAPI interface and are executed from the Dialplan. Language modules offer lots of opportunities and are very powerful. Using language modules, you can build powerful voice applications in a standard programming language. In some respects, you can actually control a telephone with a programming language. The default configuration Understanding all of these concepts right off the bat is far from easy, and as the maintainers of the software, we do not expect most people to have everything ''just click''. This is the main reason that every new layer we put on top of the core, makes things simpler and easier to learn. The default configuration of FreeSWITCH is the last line of defense between new users of the software and all of the crazy, complicated, and sometimes downright evil stuff, better known as telephony. We try very hard to save the users from such things. The main purpose of the default configuration in FreeSWITCH is to showcase all of the hundreds of parameters there are to work with. We present them to you in a working configuration that you could actually leave untouched and play with a bit before venturing into the unknown and trying your own hand at changing some of the options. Think of FreeSWITCH as a Lego set. FreeSWITCH and all of its little parts are like a brand new bucket Lego bricks, with plenty of parts to build anything we can imagine. The default configuration is like the sample spaceship that you find in the instruction booklet. It contains step-by-step instructions on exactly how to build something you know will work. After you pick up some experience, you might start modifying your Lego ship to have extra features, or maybe even rebuild the parts into a car or some other creation. The good news about FreeSWITCH is that it comes out of the box already assembled. Therefore, unlike the bucket of Lego bricks, if you get frustrated and smash it to bits, you can just re-install the defaults and you won't have to build it again from scratch. The default configuration is discussed in Chapter 3, Test Driving the Default Configuration.
- 39. Chapter 1 [ 21 ] Once FreeSWITCH has been successfully built on your system, you simply have to launch the program without changing one line in the configuration file. You will be able to point a SIP telephone or software-based SIP soft phone to the address of your computer and make a test call. If you are brave and have ambition of connecting a traditional analog phone, you may want to get the SIP thing under your belt first. This is because it involves a little more work (including purchasing a hardware card for your computer or a magic device called an ATA—analog telephone adapter). If you have more than one phone, you should be able to configure them to each having an individual extension in the range 1000-1019, which is the default extension number range that is pre-defined in the default configuration. Once you get both phones registered, you will be able to make calls across them or have them to meet in a conference room in the 3000-3399 range. If you call an extension that is not registered or let the phone ring at another extension for too long, the voicemail application will use the phrase system to indicate that the party is not available, and ask you to record a message. If you dial 5000, you can see an example of the IVR system at work, presenting several menu choices demonstrating various other neat things FreeSWITCH can do out of the box. There are a lot of small changes and additions that can be made to the default configuration while still leaving it intact. For example, using the pre-processor directives we went over earlier, the default configuration loads a list of files into the XML registry from certain places, meaning that every file in a particular folder will be combined into the final XML configuration document. The two most important points where this takes place are where the user accounts and the extensions in the Dialplan are kept. Each of the 20 extensions that are preconfigured with the defaults are stored into their own file. We could easily create a new file with a single user definition and drop it into place to add another user, and simply issue the reloadxml at the FreeSWITCH CLI. The same idea applies to the example dialplan. We can put a single extension into its own file, and load it into place whenever we want.
- 40. Architecture of FreeSWITCH [ 22 ] Summary FreeSWITCH is a complex system of moving parts that is intertwined to produce a solid, stable core with flexible and easy-to-extend add-ons. The core extends its interfaces to modules. These modules simplify the functionality further and extend it up to the user. The modules also can bring outside functionality into FreeSWITCH by translating various communication protocols into a common, well-known format. We looked at the various module types, and demonstrated how they revolve around the core and interact with each other to turn simple abstract concepts into higher-level functionalities. We touched base on a few of the more popular applications in FreeSWITCH—the conferencing and voicemail modules and how they, in turn, make use of other modules in the system without ever knowing it. This agnosticism is accomplished by means of the event system. We also saw how the default configuration provides several working examples, to help take the edge off of an otherwise frightening feat of staring down the business end of a full-featured soft-switch. Now that we have a general idea of what makes FreeSWITCH tick, we will take a closer look at some of these concepts with some real-world examples for you to try. First we obtain a copy of the source code from the Internet, so we can build the software package and install it. From there, we will test out the configuration, so be sure to get yourself a SIP phone or at least a soft-phone. Once we try a few things, we will dive a litter deeper into how things work and create a few things of our own like an extension or two and an IVR menu. So take a deep breath and get ready to dive into the world of telephony with FreeSWITCH!
- 41. Building and Installation FreeSWITCH is open source software. Basically this means that anyone can obtain, read, compile, mangle, fix, or anything that comes to mind, the raw source code of the application. Many users, especially beginners, will find that dealing with source code is somewhat a daunting task, but rest assured, we are doing our best to make this experience as painless as possible. In the future, we will be adding binary packages into various popular Linux distributions, but for the time being, we will explain how to manually obtain and install FreeSWITCH for Unix and Windows. (For the purpose of this chapter, the terms Unix-like and Linux/Unix refer not only to Unix and Linux but also to FreeBSD and Max OSX.) Try not to fret if it seems overwhelming. With a little patience and luck, the whole process will go smoothly. It's not entirely unlike a root canal. It's been said that many root canals are pulled off without a hitch and when they go wrong, they go horribly wrong; and that is where the horror stories, which we all hear, come from. In this chapter, we will discuss how to download and install FreeSWITCH from the source code for Unix-like environments as well as for Windows. We will cover the necessary prerequisites for each operating system. Finally, we will explain how to launch FreeSWITCH and how to run it in the background. In this chapter, we will cover the following: Setting up the FreeSWITCH environment Downloading and installing FreeSWITCH Launching FreeSWITCH and running it in the background The first order of business is to lay the groundwork for our FreeSWITCH installation • • • •
- 42. Building and Installation [ 24 ] Setting up the FreeSWITCH environment FreeSWITCH, like many other software applications, requires a suitable environment. Primarily that means choosing appropriate operating system for your hardware and having the proper LAN/WAN connectivity and physical environment. Operating system The first question to consider here is: which operating system should be used? Generally speaking, it is good to use an operating system with which you are comfortable and familiar. One caveat to consider is 32-bit versus 64-bit. Some users have reported problems when running a 32-bit OS on a 64-bit hardware platform. We strongly recommend that you use a 64-bit OS if you have 64-bit hardware. For those who prefer a Windows environment you can use XP, Vista, Windows 7, Server 2003, or Server 2008. Several users have reported good success with production systems running on modern hardware, and using Windows Server 2008. On the other hand, there is a wide variety of Unix-like operating systems available, many of which are freely downloadable. Most of us have an operating system (Linux, BSD, Solaris, and so on), and distribution (CentOS, Debian, Ubuntu, and so on.) that we prefer to use. The FreeSWITCH developers do not advocate any particular operating system or distribution. Some have asked which platform is the best for FreeSWITCH. There are many factors to consider when choosing a platform on which to run a telephony application. FreeSWITCH is cross-platform, and therefore, it compiles and runs on numerous systems. However, through hard-earned experience we know which operating systems and distributions lend themselves to real-time telephony applications. The bottom line is that you want your system to be stable and reliable. Our experience is that installation on Red Hat Enterprise Linux (RHEL), or its free cousin, CentOS, yields the best performance and fewest problems. Some have characterized RHEL and CentOS as boring and predictable. These qualities are perfect for running real-time telephony applications like FreeSWITCH. Operating system prerequisites Each operating system has its own set of prerequisites. Make sure that you have met the prerequisites for your platform.
- 43. Chapter 2 [ 25 ] Linux/Unix The following items frequently are already installed on your system. Note that an SVN or Git client is not required: SVN: A Subversion (SVN) client gives you access to the current code repository (recommended for those who simply want the latest code) Git: A Git client also gives you access to the current code repository (recommended especially for developers) GNUMAKE: The GNU version of make AUTOCONF: Version 2.60 or higher AUTOMAKE: Version 1.9 or higher LIBTOOL: Version 1.5.14 or higher GCC: Version 3.3 or higher WGET: Any recent version LIBNCURSES: Any recent version Mac OS X It is strongly recommended that Mac users have, at the very least, OS X Version 10.4. Compiling FreeSWITCH on OS X requires the installation of the Apple XCode Developer Tools. You may download them from http://connect.apple.com. Free registration is required. Windows FreeSWITCH in a Windows environment has two primary requirements. They are as follows: 1. Microsoft Visual C++ 2008 (or 2008 Express Edition) 2. A file decompression utility FreeSWITCH in Windows is compiled and built using Microsoft Visual C++ 2008 (MSVC) or Visual C++ 2008 Express Edition (MSVCEE). The Express Edition is free to download though registration is required. It can be obtained at http://www.microsoft.com/Express/VC. The other requirement for Windows is a file decompression utility like WinZip (www.winzip.com) or WinRAR (www.rarlab.com). A free alternative is 7-Zip (www.7-zip.org). Each of these utilities will add a right-click menu option to Windows Explorer. • • • • • • • • •
- 44. Building and Installation [ 26 ] Text editors and XML Working with FreeSWITCH requires you to have a text editor with which you are comfortable. Regardless of your editor choice, we strongly recommend that you use a text editor that supports XML syntax highlighting. You will find that editing XML configuration files is much easier on the eyes with highlighting turned on. If you do not already have a preferred editor, then we suggest trying one or two for your platform. Be aware that if you are in a Linux/Unix environment that does not have GUI (Graphical User Interface), then your choices will be fewer. However, there are several excellent text-only editors available: Emacs—This is a text-only editor available for just about any Unix-like environment, including Mac OS X. It can highlight source code, XML, HTML, and more. This is the editor of choice for the FreeSWITCH development team. (A GUI version of Emacs is also available.) Vi/Vim—This is a text-only editor available for just about and Unix-like environment. Like Emacs it can highlight source code and markup languages. (A GUI version of Vim is also available.) Notepad++—This is a graphical text editor for Windows environment. It supports highlighting of many programming and markup languages. It is a very useful and free text editor for Windows. Downloading the source Most open source projects have their source code divided into two general categories: stable and latest. While the latest FreeSWITCH code is usually quite stable, we recommend that you begin with the latest stable release. You can update to the latest trunk at a later point. (See the Building From the latest Code section in this chapter.) One other point to keep in mind: binary distributions of FreeSWITCH might be available for your platform. While they are certainly convenient, in our experience it is easier to troubleshoot, update, and customize your FreeSWITCH installation when compiling from the source. Be sure that your system has Internet access because the build process will occasionally need to download additional files. • • •
- 45. Chapter 2 [ 27 ] The source code can be obtained from the following FreeSWITCH download site: http://files.freeswitch.org. Locate a file named freeswitch-1.0.6.tar.gz, and download it into a local directory on your computer, then decompress it. A typical session in Linux might look like the following: #cd /usr/src #wget http://files.freeswitch.org/freeswitch-1.0.6.tar.gz #tar zxvf freeswitch-1.0.6.tar.gz This will create a new directory that contains the FreeSWITCH source code, ready for you to compile on your system. (From now on, this will be referred to as the FreeSWITCH source directory.) Windows users should create a new directory and download the source file. See the Compiling FreeSWITCH For Windows section, later in this chapter. Building from the latest code If you prefer to be on the latest version of FreeSWITCH, then you will need a Subversion (SVN) client or a Git client. The FreeSWITCH developers recently migrated from Subversion to Git for the development tree. However, they are maintaining a read-only SVN mirror, so you can still get the latest code via SVN. You can also get the latest code with a Git client; however, developers who wish to have commit-access will need a Git client. Most Linux/Unix environments already have, or can easily have, a Subversion client installed. In Windows, a popular (and free) Subversion client is TortoiseSVN (tortoisesvn.tigris.org). There is also TortoiseGit (code.google.com/p/tortoisegit). In Windows, the build procedure is essentially the same: open the appropriate solution file and then build it. In Linux/Unix environments it is necessary to bootstrap prior to compiling. However, there is a shortcut available. The following commands will download and build a fresh SVN checkout of FreeSWITCH, with the default configuration and all the sound files: #cd /usr/src ; wget http://www.freeswitch.org/eg/Makefile ; make #make all #cd freeswitch.trunk #make install #make cd-sounds-install #make cd-moh-install
- 46. Building and Installation [ 28 ] The preceding commands will take some time to complete. You can automate the process a bit by chaining the commands together with the operator. Compiling FreeSWITCH for Linux/Unix/ Mac OS X The install procedure is essentially the same for Linux, Unix, or Mac OS X. However, make sure that your system has met the prerequisites listed in the previous section. Compiling FreeSWITCH Compiling FreeSWITCH requires just a few steps, although it will take some time depending upon the speed of your system. The basic procedure for compiling FreeSWITCH is as follows: Edit modules.conf file to customize which modules are compiled by default Run configure script Run make and make install to compile and install Edit modules.conf.xml to customize which modules are loaded by default Install the sound and music files Following are detailed step-by-step instructions for compiling FreeSWITCH. Step 1: Edit modules.conf The modules.conf file contains a list of the various FreeSWITCH modules that will be configured and compiled. The default modules.conf file has a sensible set of modules, pre-selected to be compiled. However, there is one optional module that we will enable now. You should have a new subdirectory named freeswitch- x.y.z, where x.y.z is the version number. For example, if the latest stable version is 1.0.6 then your source directory will be /usr/src/freeswitch-1.0.6. Follow the steps below: 1. Change directory into the new FreeSWITCH source directory: #cd /usr/src/freeswitch-1.0.6 2. Open modules.conf in a text editor. Scroll down to the following line: #asr_tts/mod_flite • • • • •
- 47. Chapter 2 [ 29 ] 3. Remove the # character from the beginning of the line, then save and exit. The mod_flite module enables FreeSWITCH to use the open source Festival Lite text-to-speech (TTS) engine. (The Flite TTS engine does not produce particularly high quality speech synthesis. However, it is very handy for doing TTS testing.) After editing modules.conf we are ready to start the build process. Removing the # character at the beginning of a line in modules.conf will cause the module on that line to automatically be built, when issuing the make command. Likewise, adding a # at the beginning of the line will prevent the corresponding module from being built automatically. Step 2: Run configure script Like many open source projects, FreeSWITCH in UNIX-like environments makes use of the now famous configure script. From within the FreeSWITCH source directory, launch the configure script, as follows: #./configure The configure script performs many tasks, including making sure that the prerequisites have been met. If a prerequisite has not been met then the configure script will exit, and tell you which dependency has not been met. If this occurs then you must resolve the issue and rerun the configure script. You will need to make sure that all of the prerequisites have been met before the configure script will run to completion. During the configuration process you will see the configure script run multiple times. FreeSWITCH makes use of many libraries like Apache Portable Runtime (APR) and Perl Compatible Regular Expressions (PCRE). Each of these elements has its own specific configure script that is customized to its own needs. After some time the configure script finishes, and returns you to the system prompt. You will undoubtedly see a lot of output on the screen from the configuration process, but if you do not see any errors then you may proceed to the compilation process.
- 48. Building and Installation [ 30 ] Step 3: Run make and make install The configuration process in the previous step actually creates what is called a Makefile for FreeSWITCH, its libraries, and its various modules. The compilation and installation of FreeSWITCH are both handled by the make utility. First run make, and then run make install. Many users will run them both with one command line, which is as follows: #make make install Like the configure script, the make process takes a while, and will stop if there are any errors. Usually things go well, and at the end of the compilation and installation you are greeted with the following message: +-------- FreeSWITCH install Complete ----------+ + FreeSWITCH has been successfully installed. + + + + Install sounds: + + (uhd-sounds includes hd-sounds, sounds) + + (hd-sounds includes sounds) + + ------------------------------------ + + make cd-sounds-install + + make cd-moh-install + + + + make uhd-sounds-install + + make uhd-moh-install + + + + make hd-sounds-install + + make hd-moh-install + + + + make sounds-install + + make moh-install + + + + Install non english sounds: + + replace XX with language + + (ru : Russian) + + ------------------------------------ + + make cd-sounds-XX-install + + make uhd-sounds-XX-install + + make hd-sounds-XX-install + + make sounds-XX-install + + + + Upgrade to latest: + + ---------------------------------- +
- 49. Chapter 2 [ 31 ] + make current + + + + Rebuild all: + + ---------------------------------- + + make sure + + + + Install/Re-install default config: + + ---------------------------------- + + make samples + + + + + + Additional resources: + + ---------------------------------- + + http://www.freeswitch.org + + http://wiki.freeswitch.org + + http://jira.freeswitch.org + + http://lists.freeswitch.org + + + + irc.freenode.net / #freeswitch + + + +-----------------------------------------------+ If you see a message like the last one then you have successfully compiled FreeSWITCH, and can proceed to the next step. If an error occurs then the compilation process will stop and report it. You will need to correct the problem before you can continue. If the error message is unfamiliar to you then you should contact the FreeSWITCH community using the resources listed in Appendix A (The FreeSWITCH Online Community). Step 4: Edit modules.conf.xml The modules.conf.xml file contains a list of modules that FreeSWITCH will load when it is launched. The default modules.conf.xml file corresponds with the default modules.conf file. The modules that are built by default in modules.conf are also enabled by default in modules.conf.xml. As we enabled mod_flite to be built in modules.conf, we need to enable mod_flite in modules.conf.xml, so that it will be loaded automatically when FreeSWITCH starts. As a rule of thumb, any module that you wish to load automatically when FreeSWITCH starts must be enabled in modules.conf.xml.
- 50. Building and Installation [ 32 ] The modules.conf.xml file is located in the conf/autoload_configs subdirectory. The default location is /usr/local/freeswitch/conf/autoload_configs/ modules.conf.xml. Open the file in a text editor and locate the following line near the end of the file: !-- load module=mod_flite/ -- Remove the !-- and -- tags so that it looks like the following: load module=mod_flite/ Save the file and exit. You are almost ready to start the FreeSWITCH application. What's the difference between modules.conf and modules.conf. xml files? The modules.conf file is found in the source directory, and is used to control FreeSWITCH modules which are compiled when running make. The modules.conf.xml file is part of the default XML configuration, and is found in the FreeSWITCH autoload_configs subdirectory. It controls which modules are loaded when FreeSWITCH is launched. Step 5: Install sound and music files Sound and music files are not absolutely required. However, they are highly recommended. Without them you will not have music on hold, nor will features like voicemail and the sample IVR be functional. FreeSWITCH has sample sound and music files available in four different sampling rates. We recommend installing all of them so that you can take advantage of high quality audio connections wherever possible. To install the sound files just issue the following command in the FreeSWITCH source directory: #make cd-sounds-install To install the music files issue the following command: #make cd-moh-install These commands will download and install the sound and music files in 8 kHz, 16 kHz, 32 kHz, and 48 kHz. FreeSWITCH will use the appropriate sampling rate when playing a sound or music file to a caller. You are now ready to start FreeSWITCH. The next section covers compiling FreeSWITCH in the Windows environment, so skip down to the section named Starting FreeSWITCH.
- 51. Chapter 2 [ 33 ] Compiling FreeSWITCH for Windows As mentioned in the Operating system prerequisites section, FreeSWITCH is built with MSVC or MSVCEE. The steps presented here are specifically for the Express Edition; however, the steps for using the standard edition are essentially the same. Building the solution with MSVC/MSVCEE There are several small steps to take prior to building with MSVC. They are as follows: 1. Create a new folder and copy the tar.gz file into it. In our example, we'll use C:FreeSWITCHfreeswitch-1.0.6.tar.gz. 2. Right-click freeswitch-1.0.6.tar.gz and extract the files with your decompression utility. You will now have a new file named, freeswitch- 1.0.6.tar. 3. Right-click freeswitch-1.0.6.tar and extract files. This process will take a few moments. You will then see a window similar to the following screenshot: Note: WinRAR decompresses both the .gz and .tar files in a single step.
- 52. Building and Installation [ 34 ] 4. After extraction you will have a new sub-folder named after the latest version of FreeSWITCH. In our example, we now have a sub-folder named freeswitch-1.0.6. Double-click on the folder to see the complete FreeSWITCH source tree. It will be similar to the screen in the following screenshot: 5. While there are many files, the only ones we care about right now are the two solution files. For MSVC, the file is named Freeswitch.2008.sln and for MSVCEE, it is named Freeswitch.2008.express.sln. Double-click the appropriate solution file for your edition of MSVC. The screenshots in this example will show MSVC 2008 Express Edition. However, the Standard and Professional editions will be very similar.
- 53. Chapter 2 [ 35 ] 6. After the solution file loads, click Build Build Solution or press F7. The solution will start building. Numerous messages will appear in the Output window. When the solution has finished building, you will see a message at the bottom of the Output window as in the following screenshot: 7. Note: The MSVC/EE solution files will automatically perform several steps that are usually done manually in a Linux/Unix installation. These include downloading of all the sound and music files, and building optional modules like Flite (text-to-speech) and PocketSphinx (speech recognition). However, these optional modules still need to be enabled in modules.conf.xml if you wish to have them automatically loaded when FreeSWITCH starts. (See the next screenshot.) 8. Once the solution is built you can close MSVC. All remaining steps are performed from the Windows Explorer or the Windows command line.
- 54. Exploring the Variety of Random Documents with Different Content
- 55. The character and reputation of these men, as well as others who have been quoted in these pages, must be weighed against the few who, not content with denying the existence of the canali in Mars, have in strong language abused those who accept them as veritable markings on the planet's surface.
- 56. XVII LAST WORDS The uniformity of the course of Nature will appear as the ultimate major premise of all inductions. John Stuart Mill. The final question is, do the lines as depicted and described by various observers exist on the surface of Mars? Those who have made the greatest addition to our knowledge of the character of these lines, and have constructed maps based on Martian latitude and longitude are accredited on other grounds as being endowed with remarkable acuteness of vision coupled with persistence and painstaking care in observation. The most successful work has been accomplished with instruments of fine definition in regions of steady atmosphere and high altitude, or at intervals of clarity and steadiness in regions otherwise unfavorable. Finally, and most convincing of all, Mr. Lowell's assistant, Mr. Lampland, after many attempts has succeeded in photographing the more conspicuous linear markings. The lines do exist essentially as figured by Schiaparelli and Lowell. It now rests with the objectors to suggest any better interpretation of the markings of Mars than that they are the results of intelligent effort. The mediæval attitude of some astronomers regarding this question recalls the story of Scheiner, a Jesuit brother, who, independently of Galileo and Fabricius, discovered spots on the Sun. Eager with enthusiasm he informed his Superior of his remarkable
- 57. discovery and begged to be allowed to publish it to the world. The Superior replied, Go, my son; tranquilize yourself and rest assured that what you take for spots on the Sun are the faults of your glasses or of your eyes. This happened three hundred years ago, and yet to-day a few astronomers of this class still survive. If one will calmly reason about the matter, let him consider a parallel case of interpretation. He digs out from the ground a fragment of stone; its somewhat symmetrical shape suggests to him the idea that it may be a rude stone implement. If he wishes to know what kind of rock it is and its geological age, he refers it to a geologist; if he wishes to know its composition, he asks a mineralogist, who, if necessary, will analyze it for him. If, however, he is curious to know whether its peculiar, fractured surface is due to frost or other natural agency, or whether it is the work of some rude savage, he inquires of an archæologist, who alone will be able to tell him whether it is a worked stone or natural fragment. He will probably tell him whether it was shaped by paleolithic man, and whether it is a rough stone implement or a core, reject or chip. So with the study of Mars, as we have already pointed out, there are certain matters of information about the planet which the astronomer alone can impart, while the superficial markings are just as certainly to be interpreted by another class of students who may or not be familiar with astronomical methods. * * * * * It was quite natural that astronomers, the most conservative of all classes of observers, should have doubted the first announcement of Schiaparelli of the startling discovery of the canali marking the face of the planet, the more so as year after year went by and yet with the utmost efforts of astronomers nothing of the nature of Schiaparelli's lines could be seen. What added greatly to the doubt about the lines, and at the same time strengthened the idea that the lines were illusory, was the subsequent announcement by Schiaparelli — undeterred by the
- 58. universal skepticism — that at times the lines appeared double. What more convincing evidence could be offered than that the phenomenon was purely subjective? A few astronomers expressed their doubts in a courteous though hesitating manner. Professor Young, in his valuable text-book, Elements of Astronomy (1890), in correctly reporting Schiaparelli's discovery says: He is so careful and experienced an observer that his results cannot be lightly rejected; and yet it is not easy to banish a vague suspicion of some error or illusion, partly because his observations have thus far received so little confirmation from others, and partly because his 'canals' are so difficult to explain. They can hardly be rivers, because they are quite straight; nor can they be artificial water-ways since the narrowest of them are forty or fifty miles wide. To add to the mystery, he finds that at certain times many of them become doubled, — the two which replace the former single one running parallel to each other for hundreds, and sometimes thousands, of miles, with a space of 200 or 300 miles between them. He thinks that this gemination of the canals follows the course of the planet's seasons. The overpowering belief that this world alone sustained creatures of intelligence formed an obstructive barrier to any and all attempts made to uphold — at least by analogy — the idea of intelligence in other worlds. One cannot but regret that some philosopher had not, years before Schiaparelli's time, expressed the conviction that Mars might perhaps be more favorable to the existence of intelligent life than our own world, and with this conviction proceed to formulate the conditions which must of necessity exist: namely, that the planet being a much older world than ours, its waters had mostly vanished by chemical combination with the rocks and otherwise. Following this assumption, the philosopher might have insisted that in the last extremity the melting snow caps would be utilized by the supposed intelligences to furnish water for potable and irrigating purposes. The philosopher might have superadded to this idea the prediction that, when telescopes were strong enough and eyes were keen enough, evidence of the
- 59. truth of this supposition would be found in canals of some sort and that such lines should be carefully sought for. Fancy the exultation of Schiaparelli when at last he found the lines precisely as indicated. Such an announcement from so distinguished an astronomer would have been hailed with acclaim. Alas! for the conservatism of astronomers, such powers of prevision are sadly wanting. Le Verrier's prediction of an outer planet was a matter of dead certainty. The perturbations of Uranus could not be accounted for except by the assumption of an outside body, and had it not been for the characteristic reserve of English astronomers, Adams might have had the full credit. So rare are predictions of this nature in the history of astronomy that this instance will probably be quoted to the end of time. The masses, still ignorant of the certainty of mathematical astronomy, regard the prediction of an eclipse as in the nature of a prophecy. The liberal attitude of naturalists stands in marked contrast, and the history of their work is filled with examples of prediction and repeated confirmations. Until the middle of the last century — grounded in the belief of special creation — how wonderfully rapid was the conversion of naturalists to the theory of evolution after Darwin had offered his rational views on the subject. The existence of forms was predicted, based on the idea of evolution, and these have been found again and again. Our museums display in their cases remains of fossil animals which complete many series undreamed of in pre-Darwinian days. This wonderful work has been accomplished without resort to algebraic formulæ, and yet when mathematics can be applied, as it is in the law of variation, quantitative studies in heredity, and statistical methods generally, it is promptly seized upon by the biologist. * * * * * To one unconvinced of the existence of some signs of intelligent activity in Mars the suggestions that have been made to account for certain appearances in the planet will seem absurd. If, on the other hand, he finds himself in agreement with those who believe the markings are the result of intelligent effort, then he is justified in
- 60. using the various artificial markings of the surface of the Earth as standards of comparison in explaining the many curious markings of Mars. Indeed, he is compelled to do so, just as would be demanded of him if he should stand on some high mountain peak in some hitherto unexplored region of Africa and should minutely scan the hazy stretch of plains below. Large white spots in equatorial regions which could not possibly be snow-covered hills, might be masses of white flowers or cloth-covered areas for the better cultivation of certain plants. Lines that dimly stretched across the surface might be rivers, cañons, rifts, or bands of irrigation, according to their character. As we compare the circular markings on the Moon with our terrestrial craters and fissures, and cracks on its surface with similar fissures on the Earth, so we are forced to compare the markings on the surface of Mars with what seems analogous to them on the surface of our own Earth. Once proved that the markings of Mars are due to erosion, cracks, encircling meteors big enough to raise ridges by their attractive force, then all that has been written in demonstration of their artificial character goes for naught. The intelligent reader unprejudiced in the matter will, however, judge for himself the merits of our contention and will determine the reasonableness of the comparisons that have been made by Lowell in solving the mystery of Mars.
- 61. INDEX Algebraic formulæ, 73. American astronomers, Holden, Pickering, Young, Swift, Comstock, Barnard, Wilson, drew the more conspicuous canals, 65. Ancient irrigation, 115. Ants surviving at high altitudes, 157; unique intelligence, 156. Astronomer's chief work, 74; conservatism, 75. Astronomers who have seen the canals, 83. Astronomical subjects remote from Martian studies, 72. Atmosphere and moisture, Barnard and others, 134, 135; Sir Robert Ball, 137. Austria's care of water, 117. Ball, Sir Robert, difficulties of observation, 84; life on Mars quite likely, 68, 69; objection to Mars being inhabited, 121. Barbour, W. D., with a four inch achromatic, 88. Barnard's, Dr., description of dark regions, 43. Bees, wasps, and ants, 156. Canali supposed to mean canals, 39. Canals appear double, 41;
- 62. artificiality of, 42; as distinct as engraved lines, 59; chain of reasoning in regard to, 47; double, 41; of Mars, 40; unchangeable in position, 42. Cassini, 33. Chandler's oscillation of pole, 126. Checkerboard appearance of West, 48. Clerke's, Agnes M., expressions, 55. Clouds in Mars, 139; in Mars, Sir Norman Lockyer, 136. Comments and criticism, 125. Committee of British Astronomical Association, 126. Conception of life in other worlds, 17. Conservatism of astronomers, 185. Cracks all of the same nature, 108; discontinuous, 109; in asphalt pavement, 109. Cultivation under cloth, Porto Rico, 50. Dark regions not seas, 45. Dawes, remarkable distinctness of vision, 89. De la Rive, memoir of Faraday, 76. Denning's, Mr., testimony, 56, 57. Difficulties of seeing, 79. Dighton Rock, 97. Draper, Dr. Henry, Are other worlds inhabited? 87; difficulties of seeing, 87; high altitudes for telescopes, 88. Drawings of Mars by different observers, 98.
- 63. Dust storms in Mars, 140. Earth, a standard, 25, 26, 186; early ideas regarding the, 7; improbability of its being unique, 13. Earth's distance from the sun, 11; temperature above normal, 37. Emerson's expressions, 21. England's unsteady atmosphere, 84. Epicyclic theory of Ptolemy, 8. Evolution of the Solar System, T. J. J. See, 23. Failure of water in England, 116. Faraday's, Michael, attitude, 76. Fauth, Dr. Phil., 63; drawings of Mars, 63. First look at Mars, 80. Fison's, Mr., comments, 97. Flammarion's picture of the Earth from Mars, 169; work on Mars, 51. Fruit trees, Santa Clara Valley, 49. Gill's, Sir David, testimony, 90. Hebraic conceptions, astronomers imbued with, 21. Hebraic conceptions of the universe, 8. Herschel, Sir John, on snow caps, 76. High altitudes favorable to health, 152. Holden, E. S., on nebula of Orion, 96. Howe's, Herbert A., remarks, 65, 66. Huxley's estimate of mathematicians, 74.
- 64. Huyghens, 32. Ice caps of Himalaya, 115. Iles, George, illustration of cooling bodies, 25. Illusions, supposes, 59. Irrelevant criticism, 126. Irrigation, ancient in Arizona, in Egypt, in India, 145; marvels of, 143; notes on, 141. Joly's, Dr. J., theory, 100. Keeler's definition of astrophysics, 77. Lampland, photographs of Mars, 32. Ledger's, Rev. E., canals of Mars, 131. Liberal attitude of naturalists, 185. Life at high altitudes, 150; in other worlds, Garrett P. Serviss, 148; under atmospheric pressure, 153. Lindsay's, Thomas, expressions, 55. Lines of artificial character, 112. Lockyer, Sir Norman, saw clouds in Mars, 136. Lockyer's, W. J., testimony, 89. Lowell, Percival, brief sketch of, 174; different telescopes used by, 82; gives reason why canals cannot always be seen, 93; his acute eyesight, 85, 86; his book on Mars, 31; his various publications, 31; long practice in observing, 85; snow caps prove atmosphere, 135;
- 65. on life on Mars, 32, 67; on twilight atmosphere in Mars, 34. Lung capacity, 155; at high altitudes, 152. Macpherson, Hector, Jr., agrees with Lowell, 68. Mars, appearance of Earth from, 118; beginning of life in, 16; canals, 40; canals continuous, 109; dark regions change with the season, 38; dark regions not seas, 37; desert lands, 39; detached fields of snow, 37; disappearance of southern snow cap, 37; distance from sun, 12; double canals, 45, 46; drawings of, coincided, 81; glints of brilliant light, 37; has it water? 35; has life appeared in? 15; life in, from analogy, 15; much like the world, 16; nearest approach to earth, 32; oases, 44; seasonal changes in, 34; seasons, 33; rarefaction of atmosphere in, 35; rotation of, Cassini, 33; temperature of, 35; terminator of, Douglass, 35; those who see and those who do not see, 85; tilt of axis, 33; white polar caps, 33.
- 66. Maunder, director of committee, 126. Maunders's, E. W., comments, 103. Maunier, Stanislaus, on canal doubling, 119. Maxwell, Clerk, on mathematicians, 74. Mediæval attitude of some astronomers, 181. Michel, Louise, teaching children, 73. Morehouse, George W., believes Mars is inhabited, 67, 68. My own work, 158. Newcomb's, Professor, opinion, 24; other worlds inhabited, 28; Reminiscences, 27. Number of acres under irrigation, 122. Observations of Mars, 1st period, 51; 2d period, 52; 3d period, 53; 4th period, Lowell's work, 54. Orr's, J., theory, 102. Parallel case of interpretation, 181. Patterson's, John A., expressions, 56. Perrotin, brief sketch of, 177. Perrotin and Janssen describes the canals, 63; and Thollon, 58. Perrotin's painstaking care, 63, 64. Phillips', Rev. Theo. E. R., drawing, 62. Pickering, W. H., canals seen by, 63; shows importance of steady atmosphere, 87; observations in Jamaica by, 88; polariscope observations by, 36–38;
- 67. theory of, 105. Planetology, 77. Plurality of worlds, astronomer's belief in, 18; Edward Hitchcock's views of the, 21; Flammarion's views of the, 19; Newcomb's attitude in regard to the, 28; Newcomb's belief in the, 29; O. M. Mitchell's views in regard to the, 19; Sir David Brewster's views of the, 17; Sir Richard Owen's views in regard to the, 19; Tyndall's views of the, 22. Polar snow cap, proof deduced from Lowell, Douglass, and Pickering, 135. Profound changes by man, 123. Railroads in Iowa and Texas, 142. Review of Lowell's book, 66. Rift in Southern Africa, 112. Schiaparelli, abstemiousness when observing, 84; brief sketch of, 172; canals artificial, 62; canali natural, 60; discovery, 57; discovery of canals, 39; does not deny intelligence in Mars, 60; suggestion as to doubling, 120. Sea, so-called, land areas, 39. Seasonal changes, 136. Snow storms in Mars, W. H. Pickering, 138. Solar system a standard for universe, 26. Stars, bright points of light, 7;
- 68. similar to our sun, 9. Stetefeldt's, C. A., views, 129. Study of planetary markings, 70. Sun and planets reduced to minute scale, 11. Temperature under which man exists, 149. Terby, Dr., identifies many canals, 64. Theories regarding canals, 100. Thollon, brief sketch of, 178. Titles of papers in astronomical journals, 71. Todd, Professor, says canals result of design, 68. Turner, H. H., Astronomical Discovery, 78; on the difficulties of seeing, 91. Tycho Brahe, 8. Tyndall on imagination, 77. Tyndall's expressions on the Nebular Theory, 15; reference to Nebular Theory, 24. Unfolding of plant life on the earth, 45. Variation in drawings by different observers, 94, 95; of Milky Way, 95; of Nebula of Orion, 95; of Solar Corona, 95, 96. Variety of conditions under which life exists, 147. Vastness of the universe, 10. Wallace, Alfred Russel, human paradox, 29; review of, in London Nature, 18. Water vapor, no spectroscopic proof of, Campbell, 135. Webb's, Rev. T. W., difficulties of seeing, 91, 92.
- 69. What the Martians might say of us, 166. White spots in equatorial regions of Mars, 48. White weed in New England, 49. Williams, A. Stanley, difficulty in observation, 82. Would the work of man show in Mars? 122. Young, C. A., on snow caps, 76, 126; on Schiaparelli's discovery, 183.
- 70. FOOTNOTES 1 Some of our readers may not know that light travels, in round numbers, at the rate of 186,000 miles a second. 2 The terminator represents the limit of light on that side of the planet in the shade, in other words, where the light terminates. In viewing the Moon, when at quarter or half, the terminator is seen very ragged on account of the illumination of higher points on the surface. If the Moon was as smooth as a billiard ball the terminator would be clear cut. 3 The world in its ignorance of Italian assumed that the word meant exclusively canals, and, if canals, then dug by shovels. What! a canal thirty miles wide and two thousand miles long dug in the snap of the finger? Impossible conception, you say. We shall see later the sober utterances of a member of the British Astronomical Society on this gratuitous assumption, and an equally serious comment by the chief assistant of the Royal Observatory at Greenwich (E. S. M.). 4 The views so long held that the dark shaded regions were bodies of water, or seas, was disproved by the observations of Pickering and Douglass, who distinctly traced the course of the canals across these dark areas. The observations of Dr. E. Barnard certainly sustain the contention that they are land areas and probably depressions, representing ancient ocean beds. Dr. Barnard, using the telescope at the Lick Observatory, says: Under
- 71. the best conditions these dark regions which are always shown, with smaller telescopes, of nearly uniform shade, broke up into a vast amount of very fine details. I hardly know how to describe the appearance of these 'Seas' under these conditions. To those, however, who have looked down upon a mountainous country from a considerable elevation, perhaps some conception of the appearance presented by these dark regions may be had. From what I know of the appearance of the country about Mt. Hamilton, as seen from the Observatory, I can imagine that, as viewed from a very great elevation, this region, broken by cañon, and slope and ridge, would look like the surface of these Martian seas. 5 Sterling Heiley, in Pearson's Magazine, June, 1905. 6 A translation of which may be found in the Popular Science Monthly, Vol. XXXV, p. 532. 7 I may add that in a similar case an American student of Mars moved his telescope to Mexico and remounted it at a cost of some thousands of dollars.
- 72. Transcriber's Notes Punctuation and spelling were made consistent when a predominant preference was found in this book; otherwise they were not changed. Simple typographical errors were corrected; occasional unbalanced quotation marks retained; inconsistent hyphenation retained. Ambiguous hyphens at the ends of lines were retained. Page 146: Quotation mark preceding 'The sale value' has no matching closing mark. Page 192: Stetefelt's is spelled Stetefeldt on page 129. The latter is correct. Page 192: Tycho Brahe probably should be indexed as Brahe, Tycho.
- 73. *** END OF THE PROJECT GUTENBERG EBOOK MARS AND ITS MYSTERY *** Updated editions will replace the previous one—the old editions will be renamed. Creating the works from print editions not protected by U.S. copyright law means that no one owns a United States copyright in these works, so the Foundation (and you!) can copy and distribute it in the United States without permission and without paying copyright royalties. Special rules, set forth in the General Terms of Use part of this license, apply to copying and distributing Project Gutenberg™ electronic works to protect the PROJECT GUTENBERG™ concept and trademark. Project Gutenberg is a registered trademark, and may not be used if you charge for an eBook, except by following the terms of the trademark license, including paying royalties for use of the Project Gutenberg trademark. If you do not charge anything for copies of this eBook, complying with the trademark license is very easy. You may use this eBook for nearly any purpose such as creation of derivative works, reports, performances and research. Project Gutenberg eBooks may be modified and printed and given away—you may do practically ANYTHING in the United States with eBooks not protected by U.S. copyright law. Redistribution is subject to the trademark license, especially commercial redistribution. START: FULL LICENSE
- 74. THE FULL PROJECT GUTENBERG LICENSE
- 75. PLEASE READ THIS BEFORE YOU DISTRIBUTE OR USE THIS WORK To protect the Project Gutenberg™ mission of promoting the free distribution of electronic works, by using or distributing this work (or any other work associated in any way with the phrase “Project Gutenberg”), you agree to comply with all the terms of the Full Project Gutenberg™ License available with this file or online at www.gutenberg.org/license. Section 1. General Terms of Use and Redistributing Project Gutenberg™ electronic works 1.A. By reading or using any part of this Project Gutenberg™ electronic work, you indicate that you have read, understand, agree to and accept all the terms of this license and intellectual property (trademark/copyright) agreement. If you do not agree to abide by all the terms of this agreement, you must cease using and return or destroy all copies of Project Gutenberg™ electronic works in your possession. If you paid a fee for obtaining a copy of or access to a Project Gutenberg™ electronic work and you do not agree to be bound by the terms of this agreement, you may obtain a refund from the person or entity to whom you paid the fee as set forth in paragraph 1.E.8. 1.B. “Project Gutenberg” is a registered trademark. It may only be used on or associated in any way with an electronic work by people who agree to be bound by the terms of this agreement. There are a few things that you can do with most Project Gutenberg™ electronic works even without complying with the full terms of this agreement. See paragraph 1.C below. There are a lot of things you can do with Project Gutenberg™ electronic works if you follow the terms of this agreement and help preserve free future access to Project Gutenberg™ electronic works. See paragraph 1.E below.
- 76. 1.C. The Project Gutenberg Literary Archive Foundation (“the Foundation” or PGLAF), owns a compilation copyright in the collection of Project Gutenberg™ electronic works. Nearly all the individual works in the collection are in the public domain in the United States. If an individual work is unprotected by copyright law in the United States and you are located in the United States, we do not claim a right to prevent you from copying, distributing, performing, displaying or creating derivative works based on the work as long as all references to Project Gutenberg are removed. Of course, we hope that you will support the Project Gutenberg™ mission of promoting free access to electronic works by freely sharing Project Gutenberg™ works in compliance with the terms of this agreement for keeping the Project Gutenberg™ name associated with the work. You can easily comply with the terms of this agreement by keeping this work in the same format with its attached full Project Gutenberg™ License when you share it without charge with others. 1.D. The copyright laws of the place where you are located also govern what you can do with this work. Copyright laws in most countries are in a constant state of change. If you are outside the United States, check the laws of your country in addition to the terms of this agreement before downloading, copying, displaying, performing, distributing or creating derivative works based on this work or any other Project Gutenberg™ work. The Foundation makes no representations concerning the copyright status of any work in any country other than the United States. 1.E. Unless you have removed all references to Project Gutenberg: 1.E.1. The following sentence, with active links to, or other immediate access to, the full Project Gutenberg™ License must appear prominently whenever any copy of a Project Gutenberg™ work (any work on which the phrase “Project Gutenberg” appears, or with which the phrase “Project Gutenberg” is associated) is accessed, displayed, performed, viewed, copied or distributed:
- 77. This eBook is for the use of anyone anywhere in the United States and most other parts of the world at no cost and with almost no restrictions whatsoever. You may copy it, give it away or re-use it under the terms of the Project Gutenberg License included with this eBook or online at www.gutenberg.org. If you are not located in the United States, you will have to check the laws of the country where you are located before using this eBook. 1.E.2. If an individual Project Gutenberg™ electronic work is derived from texts not protected by U.S. copyright law (does not contain a notice indicating that it is posted with permission of the copyright holder), the work can be copied and distributed to anyone in the United States without paying any fees or charges. If you are redistributing or providing access to a work with the phrase “Project Gutenberg” associated with or appearing on the work, you must comply either with the requirements of paragraphs 1.E.1 through 1.E.7 or obtain permission for the use of the work and the Project Gutenberg™ trademark as set forth in paragraphs 1.E.8 or 1.E.9. 1.E.3. If an individual Project Gutenberg™ electronic work is posted with the permission of the copyright holder, your use and distribution must comply with both paragraphs 1.E.1 through 1.E.7 and any additional terms imposed by the copyright holder. Additional terms will be linked to the Project Gutenberg™ License for all works posted with the permission of the copyright holder found at the beginning of this work. 1.E.4. Do not unlink or detach or remove the full Project Gutenberg™ License terms from this work, or any files containing a part of this work or any other work associated with Project Gutenberg™.
- 78. 1.E.5. Do not copy, display, perform, distribute or redistribute this electronic work, or any part of this electronic work, without prominently displaying the sentence set forth in paragraph 1.E.1 with active links or immediate access to the full terms of the Project Gutenberg™ License. 1.E.6. You may convert to and distribute this work in any binary, compressed, marked up, nonproprietary or proprietary form, including any word processing or hypertext form. However, if you provide access to or distribute copies of a Project Gutenberg™ work in a format other than “Plain Vanilla ASCII” or other format used in the official version posted on the official Project Gutenberg™ website (www.gutenberg.org), you must, at no additional cost, fee or expense to the user, provide a copy, a means of exporting a copy, or a means of obtaining a copy upon request, of the work in its original “Plain Vanilla ASCII” or other form. Any alternate format must include the full Project Gutenberg™ License as specified in paragraph 1.E.1. 1.E.7. Do not charge a fee for access to, viewing, displaying, performing, copying or distributing any Project Gutenberg™ works unless you comply with paragraph 1.E.8 or 1.E.9. 1.E.8. You may charge a reasonable fee for copies of or providing access to or distributing Project Gutenberg™ electronic works provided that: • You pay a royalty fee of 20% of the gross profits you derive from the use of Project Gutenberg™ works calculated using the method you already use to calculate your applicable taxes. The fee is owed to the owner of the Project Gutenberg™ trademark, but he has agreed to donate royalties under this paragraph to the Project Gutenberg Literary Archive Foundation. Royalty payments must be paid within 60 days following each date on which you prepare (or are legally required to prepare) your periodic tax returns. Royalty payments should be clearly marked as such and sent to the Project Gutenberg Literary Archive Foundation at the address specified in Section 4,
- 79. “Information about donations to the Project Gutenberg Literary Archive Foundation.” • You provide a full refund of any money paid by a user who notifies you in writing (or by e-mail) within 30 days of receipt that s/he does not agree to the terms of the full Project Gutenberg™ License. You must require such a user to return or destroy all copies of the works possessed in a physical medium and discontinue all use of and all access to other copies of Project Gutenberg™ works. • You provide, in accordance with paragraph 1.F.3, a full refund of any money paid for a work or a replacement copy, if a defect in the electronic work is discovered and reported to you within 90 days of receipt of the work. • You comply with all other terms of this agreement for free distribution of Project Gutenberg™ works. 1.E.9. If you wish to charge a fee or distribute a Project Gutenberg™ electronic work or group of works on different terms than are set forth in this agreement, you must obtain permission in writing from the Project Gutenberg Literary Archive Foundation, the manager of the Project Gutenberg™ trademark. Contact the Foundation as set forth in Section 3 below. 1.F. 1.F.1. Project Gutenberg volunteers and employees expend considerable effort to identify, do copyright research on, transcribe and proofread works not protected by U.S. copyright law in creating the Project Gutenberg™ collection. Despite these efforts, Project Gutenberg™ electronic works, and the medium on which they may be stored, may contain “Defects,” such as, but not limited to, incomplete, inaccurate or corrupt data, transcription errors, a copyright or other intellectual property infringement, a defective or
- 80. damaged disk or other medium, a computer virus, or computer codes that damage or cannot be read by your equipment. 1.F.2. LIMITED WARRANTY, DISCLAIMER OF DAMAGES - Except for the “Right of Replacement or Refund” described in paragraph 1.F.3, the Project Gutenberg Literary Archive Foundation, the owner of the Project Gutenberg™ trademark, and any other party distributing a Project Gutenberg™ electronic work under this agreement, disclaim all liability to you for damages, costs and expenses, including legal fees. YOU AGREE THAT YOU HAVE NO REMEDIES FOR NEGLIGENCE, STRICT LIABILITY, BREACH OF WARRANTY OR BREACH OF CONTRACT EXCEPT THOSE PROVIDED IN PARAGRAPH 1.F.3. YOU AGREE THAT THE FOUNDATION, THE TRADEMARK OWNER, AND ANY DISTRIBUTOR UNDER THIS AGREEMENT WILL NOT BE LIABLE TO YOU FOR ACTUAL, DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE OR INCIDENTAL DAMAGES EVEN IF YOU GIVE NOTICE OF THE POSSIBILITY OF SUCH DAMAGE. 1.F.3. LIMITED RIGHT OF REPLACEMENT OR REFUND - If you discover a defect in this electronic work within 90 days of receiving it, you can receive a refund of the money (if any) you paid for it by sending a written explanation to the person you received the work from. If you received the work on a physical medium, you must return the medium with your written explanation. The person or entity that provided you with the defective work may elect to provide a replacement copy in lieu of a refund. If you received the work electronically, the person or entity providing it to you may choose to give you a second opportunity to receive the work electronically in lieu of a refund. If the second copy is also defective, you may demand a refund in writing without further opportunities to fix the problem. 1.F.4. Except for the limited right of replacement or refund set forth in paragraph 1.F.3, this work is provided to you ‘AS-IS’, WITH NO OTHER WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,
- 81. Welcome to our website – the perfect destination for book lovers and knowledge seekers. We believe that every book holds a new world, offering opportunities for learning, discovery, and personal growth. That’s why we are dedicated to bringing you a diverse collection of books, ranging from classic literature and specialized publications to self-development guides and children's books. More than just a book-buying platform, we strive to be a bridge connecting you with timeless cultural and intellectual values. With an elegant, user-friendly interface and a smart search system, you can quickly find the books that best suit your interests. Additionally, our special promotions and home delivery services help you save time and fully enjoy the joy of reading. Join us on a journey of knowledge exploration, passion nurturing, and personal growth every day! ebookbell.com