====== Using FreeSwitch ======

I'm completely new to [[http://freeswitch.com|FreeSwitch]], so I'm documenting my experience of trying to get it to do something useful, in the hopes that this will help others coming at it for the first time too.

This refers to FreeSwitch version 1.10.6 [[.FreeSwitch|installed]] under Devuan 3 Beowulf.

===== Documentation =====

FreeSwitch documentation is awful.  Information __is__ available, and a lot of it is on FreeSwitch's website, but finding anything is a nightmare; the indexing is terrible.  There's certainly no "start here and we'll lead you through the basics and point you at more so you can then explore on your own".

Here are some pointers to (external to this wiki) links of useful stuff I've found:

  * [[https://freeswitch.org/confluence/display/FREESWITCH/Introduction|Intro]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Dialplan|Dialplan introduction]]
  * A diagrammatic [[https://freeswitch.org/confluence/display/FREESWITCH/Life+Cycle+of+a+Call|life cycle of a call]]
    * [[https://freeswitch.org/confluence/display/FREESWITCH/Call+States|A list of call states]] with no explanation about them
    * [[https://freeswitch.org/confluence/display/FREESWITCH/Channel+States|Channel states]] with descriptions
  * A list of [[https://freeswitch.org/confluence/display/FREESWITCH/Variables+Master+List|FreeSwitch variables]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Channel+Variables|Channel variables]]
    * [[https://freeswitch.org/confluence/display/FREESWITCH/Manipulating+Channel+Variables|Manipulating them]]
  * FreeSwitch uses [[https://freeswitch.org/confluence/display/FREESWITCH/XML+Dialplan|XML for its dialplans]]
  * FreeSwitch's [[https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Client-and-Developer-Interfaces/1048948/|command line interface]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_dptools|Commands you can call]] from dialplans
    * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_commands|Calling API commands]] from a dialplan
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Modules|A list of modules]] and ways of creating dialplans
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Configuration|Configuring FreeSwitch]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/FreeSWITCH+PBX+Example|Configuration examples]]
  * Doing [[https://freeswitch.org/confluence/display/FREESWITCH/Multiple+Companies|multi-tenant]] with FreeSwitch
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Sofia+SIP+Stack|FreeSwitch's SIP stack]] is called "Sofia"
    * Some extremely terse documentation about [[https://freeswitch.org/confluence/display/FREESWITCH/mod_sofia|configuration parameters]]
    * Sofia [[https://freeswitch.org/confluence/display/FREESWITCH/Sofia+SIP+Stack#SofiaSIPStack-AddingRequestHeaders|Request headers]]
    * Sofia [[https://freeswitch.org/confluence/display/FREESWITCH/Sofia+SIP+Stack#SofiaSIPStack-AddingResponseHeaders|Response headers]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Gateways+Configuration|Gateways]] (trunks)
  * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_event_socket|How to connect to FS]] from something else
    * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_commands|What you can do]] once connected
    * Talking to the Event Socket [[https://freeswitch.org/confluence/display/FREESWITCH/Perl+ESL|with Perl]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Script+Language+Choice|Scripting languages]]
    * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_lua|Lua]]
      * [[https://freeswitch.org/confluence/display/FREESWITCH/Serving+Configuration+with+Lua|Configuation]] with lua
    * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_perl|Perl]]
    * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_python|Python]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/CDR|CDRs]]
    * CDRs [[https://freeswitch.org/confluence/display/FREESWITCH/mod_odbc_cdr|via ODBC]]
  * FreeSwitch [[https://freeswitch.org/confluence/display/FREESWITCH/High+Availability|High Availability]]
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Events|FreeSwitch Events - intro]]
    * Section 2.1 lists the categories you can specify with "events plain XXX" etc.
  * [[https://freeswitch.org/confluence/display/FREESWITCH/Event+List|FreeSwitch Events - detail]]
    * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_logfile|Logging the events]] (but, not yet, logging the dialplan actions)
  * [[https://freeswitch.org/confluence/display/FREESWITCH/FreeSWITCH+Databases|Databases]] in FreeSwitch
    * FreeSwitch keeps its [[https://freeswitch.org/confluence/display/FREESWITCH/ODBC+DSN|internal configuration]] in a database
    * Dialplan [[https://freeswitch.org/confluence/display/FREESWITCH/mod_db|database operations]]
    * [[https://freeswitch.org/confluence/display/FREESWITCH/Databases|A smaller page]] with a later datestamp
    * [[https://freeswitch.org/confluence/display/FREESWITCH/Using+ODBC+in+the+core|ODBC]]
      * [[https://freeswitch.org/confluence/display/FREESWITCH/mod_odbc_query|Queries]] (not available with standard Debian packages)
    * [[https://freeswitch.org/confluence/display/FREESWITCH/Lua+with+Database|Lua and databases]]
    * [[https://freeswitch.org/confluence/display/FREESWITCH/Lua+FreeSWITCH+Dbh|Using databases with lua]] for dialplan apps, directories, and something on-the-fly
      * FreeSwitch [[https://asterisk-pbx.ru/wiki/blog/freeswitch_directory_mysql_storage_with_lua_dbh|Directory in database]] via lua

===== NAT =====

If you've done anything with SIP previously, you probably know that NAT can be a problem that needs to be dealt with (but there are ways to do that).

FreeSwitch has found a way to make NAT [[.usingFreeSwitch:FreeSwitchNAT|even more of a problem]] than usual.

===== Useful bits and pieces =====

  * How to dial out to a SIP server with credentials in the dialplan (no pre-defined gateway needed)<code><action application="bridge" data="{sip_auth_username=${sip_user},sip_auth_password=${sip_pass}}sofia/GW/${destination_number}@${SIP_server}"/></code>
    * That will dial to ${destination_number} via ${SIP_server} using credentials ${sip_user} and ${sip_pass}
    * You need to have a gateway profile named GW, but it doesn't need to have anything defined in it
    * You might need to do<code><action application="set" data="effective_caller_id_number=${sip_user}"/></code>just beforehand, depending on how fussy the remote server is

===== Message waiting (MWI) =====

FreeSwitch can register as a client to a SIP server (ie: pretend to be a telephone), and it is far more capable in this regard than Asterisk is.

Asterisk can REGISTER (to receive calls), and it can send INVITEs (to place calls), although the latter is a bit buggy because it fails if you have a ! or a : in the SIP password.

However, that's it - Asterisk can't do anything else - it has no clue about presence, it can't do message waiting, it can't send hold or resume commands, and it can't send refer commands (for transfers).

FreeSwitch can do all of the above, albeit with certain caveats.

The biggest one for me is that FreeSwitch can SUBSCRIBE for presence Events, and it works.  It can also SUBSCRIBE for [[https://www.rfc-editor.org/rfc/rfc3842.html|message-summary]] Events (MWI), and that works.  It completely ignores unsolicited MWI, which is the standard way in which telephones and PBXs tend to do it.

If your PBX won't accept a SUBSCRIBE for message-summary Events (which Bicom PBXware doesn't, for example) then you can't get FreeSwitch and the PBX to exchange MWI information.

**The following is not yet correct.**

The answer is to make a surprisingly small change to the FreeSwitch source code and [[.deb-build:freeswitch|recompile]] it.

Edit the file **src/mod/endpoints/mod_sofia/sofia.c**

Find the section containing:<code>        if (!sofia_private || zstr(sofia_private->gateway_name)) {
                if (profile->debug) {
                        switch_log_printf(SWITCH_CHANNEL_SESSION_LOG(session), SWITCH_LOG_DEBUG, "Gateway information missing Subscription Event: %s\n",
                                                          sip->sip_event->o_type);
                }
                goto error;
        }</code>

Change this to:<code>        if (!sofia_private || zstr(sofia_private->gateway_name)) {
                if (profile->debug) {
                        switch_log_printf(SWITCH_CHANNEL_SESSION_LOG(session), SWITCH_LOG_DEBUG, "Gateway information missing Subscription Event: %s\n",
                                                          sip->sip_event->o_type);
                }
                if (strcasecmp(sip->sip_event->o_type, "message-summary")) goto error;
        }</code>

FreeSwitch will now continue to output the message **Gateway information missing Subscription Event: message-summary** when an unsolicited MWI NOTIFY comes in, but now it will fire a NOTIFY_IN event which you can handle (for example with an [[https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod_lua_1048944/#event-hooks|Event hook]]).

----
[[.:|Go up]]\\
Return to [[:|main index]].