FreeSWITCH          




Page tree
Skip to end of metadata
Go to start of metadata

About

GSMopen is a  FreeSWITCH™ endpoint (channel driver) that allows an SMS message to be sent to and from FreeSWITCH as well as incoming and outgoing GSM voice calls that can be bridged, originated, answered, etc. as in all other endpoints, e.g. sofia/SIP). An SMS on FreeSWITCH is handled following the CHAT API (like the text messaging in mod_sofia, mod_skypopen, and mod_dingaling).

Status

GSMopen is in "beta" status.

UNLOCK THE DONGLE

Is your dongle unlocked?

 Click here to expand Table of Contents

Quick Start Guide

Steps needed to use GSMopen:

  • Compile and install FreeSWITCH
  • Compile and install the prerequisites (gsmlib and libctb)
  • Compile and install mod_gsmopen
  • Install and edit mod_gsmopen config file
  • Connect one or more Huawei USB dongles (or other GSM modems) to the FreeSWITCH server machine
  • Be sure the dongle has the "voice" capability UNLOCKED, or unlock it with dc-unlocker ( http://www.dc-unlocker.com/ ).
  • Start FreeSWITCH
  • Load mod_gsmopen in FreeSWITCH
  • Profit!

UNLOCK THE DONGLE

UNLOCK THE DONGLE!!!

Be sure the dongle has the "voice" capability unlocked, or unlock it with dc-unlocker ( http://www.dc-unlocker.com/ )

What Is GSMopen

GSMopen is an endpoint (channel driver) that allows an SMS to be sent to and from FreeSWITCH as well as incoming and outgoing GSM voice calls (that can be bridged, originated, answered, etc. as in all other endpoints, e.g. sofia/SIP). An SMS on FreeSWITCH is handled following the CHAT API (like the text messaging in mod_sofia, mod_skypopen, and mod_dingaling).

Preferred GSM modem to use for voice calls (and SMS) is Huawei E1550 dongle, or compatible.

GSMopen works in FreeSWITCH on Linux and Windows, native at 8khz (GSM is 8khz compressed audio). It probably works on *BSD and OSX too.

GSMopen operates on GSM cellular/mobile connections in the same way that OpenZAP operates on analog lines. One interface (a GSM modem) is needed for each channel. For example, two concurrent calls would need two channels as well as two USB GSM dongles connected to the FreeSWITCH server box.

Obviously you must have credit on the SIM(s) inside the modems to make and receive calls, just like you need credits for your regular cell phone to work.

GSMopen uses very low CPU, so it works with the less powerful server platforms without problems (e.g. embedded appliances).

GSMopen has been contributed to the community by: Giovanni Maruzzelli (gmaruzz a|~t gmail dot com) with a lot of help from the core developer team and hints, patches, suggestions, bug reports, feature requests from the superlative FS community.

GSMopen is fully integrated with Mod_sms so you can use it for your messaging system pleasure.

DATA CONNECTION Concurrent on Same Dongle

Tarmo Aia wrote: The only working (voice) dongle what i have tested is E173, with that there is no need to to anything extraordinary. Just standard setup. The tests reveal that if You have 3G coverage, the data and voice would be concurrent, if you have below 3G (2,5 or 2 or 1G) in the very moment when you start voice calling over GSM dongle, the data would be disconnected. The data connection would be restored after the call is hung up - actually this is very logical because when the dongle is using 2G or similar coverage, the frequency for calling and data transmitting is the same. I suspect that if you call with 3G coverage, the call would go in the 1G frequency. If you are more interested I can put the dongle to the radio lab and do some measurements ;-) About setup: I'm using FS 1.2-stable, for bringing up data connection i use wvdial, config would be like: (/etc/wvdial.conf)

 

 

To run data just type wvdial xxx (the xxx should be your provider or smth)

 

In the test machine, config files for FS were pretty out-of-the-box, in gsmopen.conf i just changed the interface control ports to right ones. Hope it was enough information,

Hardware Requirements

The CPU load generated by the GSMopen endpoint is very low, so if a server is able to run FS, it will have no problems using GSMopen channels.

You will need at least one physical interface to connect to a GSM network.

Compatibility List

Preferred GSM modem to use with GSMopen is Huawei E1550 dongle, or compatible.

Please add to this list; probably most dongles are compatible.

  • E1550
  • E1552
  • E169
  • E1692
  • E171
  • E173
  • E175X
  • E1752C
  • E1762
  • E180
  • K3520
  • K3715
  • K3765

Look for "Huawei modem" on Ebay or similar sites. Eg: http://www.aliexpress.com/wholesale?isFreeShip=y&SearchText=huawei%2Be1550&CatId=0&manual=y

Anyway, if other brands or models have the basic USB interfaces (serial + audio) but requires different modem commands, I will add support to them. Open a Jira for it, or contact me directly.

USB Power

MORE THAN ONE DEVICE on an USB bus without dedicated power supply can have intermittent failure, because dongles can use all of the power! If you use more than one device, use an external power supply connected to a.c. mains to supply your USB hub. Each dongle requires about 500mA / 0.5W to be safe.

 

Voice calls and SMS

 

If you have trouble with voice calls, please check that the dongle has the "voice" capability and that "voice" capability is unlocked. To check the capability existence and status, and unlock it if needed, you can use dc-unlocker client for windows ( http://www.dc-unlocker.com/ , client and checking are free, small fee to unlock).

SMS ONLY (no voice calls)

  • Any GSM modem (secondhand cellphone or a professional modem) that accepts AT commands and its data cable to connect it to the server.

Dialplan

How to use GSMopen for outbound voice calls from FreeSWITCH™.

Like other endpoints it's easy to build up useful dialplans using GSMopen. You can use the standard format with the interface name:

gsmopen/interface1/3472665618

To call the number "3472665618" using the gsmopen interface named "interface1"

Dialplan snippet:

GSMopen Dialplan Example

 

The "ANY" and "RR" interfaces

The poor man's interface grouping.

You can also use the "ANY" or "RR" interfaces

gsmopen/ANY/3472665618
gsmopen/RR/3472665618

Use the ANY alias to call "3472665618" using the first available (idle, not in a call) gsmopen interface, automatically selected (thx Seven Du).

Use the RR alias to select the interface using a Round Robin algorithm to distribute calls more fairly between all the available interfaces.

Dialplan snippet:

GSMopen Round Robin Dialplan Example

 

CONFIGURATION FILE and incoming voice calls

IMEI and IMSI automatic device discovery (only on Linux)

These two new configuration parameters allow for startup automatic discovery and configuration of command (controldevice_name) and audio (controldevice_audio_name) devices.

Eg: in an interface definition you can specify the IMEI of the dongle, or the IMSI of the SIM card contained into the dongle, or both, and mod_gsmopen will scan the system looking for the correct devices.

Values automatically discovered at startup override controldevice_name and controldevice_audio_name. This means that if discovery works you can omit controldevice_name and controldevice_audio_name from the interface definition.

If BOTH IMEI and IMSI are specified in one interface description, they MUST be BOTH correct. You can specify just one, if you prefer.

Configuration File

GSMopen is very configurable.

Almost any single AT command used to manage call flow and to understand signaling and status can be customized.

There are default values for all values, so you can leave the configuration file almost empty (you lazy!).

gsmopen.conf.xml  Expand source

 


Following are all the various configurable parameters you can set for each interface (with their default values):

GSMopen Defaults  Expand source

 

Incoming Voice Calls

Each incoming voice call that arrives on the interface will be directed to the destination extension in the context context.

So, please edit or add those fields to the config file to adapt it to your needs. The default config file works with the default, out-of-the-box, demo FreeSWITCH dialplan.

Multiple Concurrent Incoming Calls to the Same GSM Number

This is possible, if the carrier supports call forwarding. You must set up call forwarding on BUSY, NOT REACHABLE state. Remember to switch off CALL WAITING.

Each physical interface (eg: GSM modem) has its own SIM, with just one number. You must have one interface for each concurrent call.

When a call is made by a remote party to a number, the carrier sends the call to the SIM that bears that number. If that SIM is busy or unreachable, the carrier will redirect the call to the forwarded number. Same way you can add additional SIM cards / phones - forward them.

The carrier can limit maximum call forwarding chain length. If you experience that situation, please add that information here.

API and CLI Commands

 GSMopen adds various commands to the standard FreeSWITCH API and Commands.

They can all be used both through the command line and via API / ESL / whatever.

Integration with mod_sms

GSMopen is fully integrated with mod_sms so you can use it for your messaging system pleasure.

GSM Commands

"gsm" commands are intended to be used from the FS command line ("gsm remove" and "gsm reload" can be useful from Event socket as well).

console interface_name

You begin typing "gsm console interface_name" to direct the "current console" to sending messages to interface_name. From now on, you can type "gsm AT_command" and AT_command string will be sent to the modem identified by interface interface_name.

gsm console interface1
gsm ATI

list

"gsm list" gives the list and status of all the running GSMopen interfaces (a star marks the interface from which "RR" - see below - will start hunting an IDLE one), statistics about inbound failed and total calls, outbound failed and total calls per each interface.

gsm list

remove

gsm remove <interface_name | interface_id>

This command removes the gsmopen interface with name interface_name or with id interface_id, if that interface is idle.

gsm remove interface1

Muhammad Shahzad and Seven Du contributed code for adding and removing interfaces on the fly.

reload

gsm reload

This command re-reads GSMopen configuration file gsmopen.conf.xml and adds ONLY the non running interfaces it found in that file. All existing running interfaces are not affected.

gsmopen Commands

"gsm remove" and "gsm reload" (see abvoe) can be useful from API / ESL / whatever as well.

"gsmopen" commands are intended to be used by programs (API / ESL / whatever) and have the format: "gsmopen interface_name AT_command_string". They send the AT_command string to the modem identified by interface interface_name.

gsmopen interface2 ATI

This allows you to use directly the entire power of the AT command set of your GSM modem or cellphone. For example, to prototype a new feature, do customization, etc. Typing "console loglevel 9" at the FS command line allows you to see the AT answers from the GSM modem.

gsmopen_boost_audio

This command affects the volumes of incoming and outbound audio at the sample level, in code. This command may be useful to interactively (trial and error during a call) find the best audio gain setting for your setup, then you write the found values in the config file. Boost can be for playback or for capture, and can be negative or positive (expressed in deciBel units). Syntax is:

gsmopen_boost_audio interface_name [<play|capt> <value_in_deciBels>]

where the boost value can range from -40dB to +40dB

Example:

gsmopen_boost_audio interface3 play -10

The example will lower by 10 decibels the volume of the playback in interface3

gsmopen_dump

This command generates (fires) a CUSTOM event of type gsmopen::dump_event that reports a lot of useful information about the interface interface_name.

If interface_name is "list", gsmopen_dump will fire as many events as the number of running interfaces, one for each of them.

gsmopen_dump interface1

Or,

gsmopen_dump list

For the event description, see below, Events.

gsmopen_sendsms

It supports full UTF8 SMS text, although the FS command line only accepts ASCII. Please use ESL or API to send UTF8 text.

gsmopen_sendsms interface_name destination_number SMS_text

Example:

gsmopen_sendsms interface1 3472665618 this is a nice SMS text

chat

GSMopen answers to the FreeSWITCH standard "chat" command too, and uses its arguments to execute a gsmopen_sendsms command. So, if you have a messaging application that uses the chat command with Sofia/SIP or Jingle, no need to recode it with special cases for SMS messages :-)

It uses SMS as protocol specification. e.g., from command line:

chat SMS|interface3|3472665618|ciao amore

ussd on chat

You can send ussd to operator, using the special destination "ussd". Eg:

chat SMS|interface3|ussd|*141#

Events

GSMopen generates (fires) various CUSTOM events in addition to the standard FreeSWITCH events on voice calls (like the other endpoints) and MESSAGE (chat) events on incoming SMS (like Sofia and Jingle).

Voice Calls

Standard CODEC and CHANNEL_* events.

See Event list

MESSAGE (SMS)

The Event type generated by an incoming SMS is of type MESSAGE (like in Jingle and Sofia).

The interesting fields are:

GSMopen Event Fields

And obviously the body, encoded in UTF8, that contains the SMS text.

UTF8 Encoding

The body is UTF8 encoded, gives you ASCII for ASCII, and UTF8 for all the rest.

This is a telnet session to the Events port (8021) asking for authorization, asking for events of type message in plain format, then an incoming SMS as reported with Events plain.

 

GSMopen Event Query  Expand source

gsmopen::dump_event

CUSTOM events of type gsmopen::dump_event are fired in response to a gsmopen_dump command or API call (e.g., from command line or via script or through the ESL). This event reports a lot of useful information on the state of the interface which name was given as argument to the command; if that name is "list" the command will fire as many gsmopen::dump_event as interfaces are running, one for each of them.

This is an example of the gsmopen::dump_event fired in response to:

gsmopen_dump interface2001

Event:

GSMopen dump_event  Expand source

 

 

During a call (while a call is active on the interface) a lot of useful info is added (courtesy of Math ;-)

The command used to generate the event is the same, but the interface is in an active call, executing a JavaScript app:

GSMopen dump_event During Active Call  Expand source

 

gsmopen::alarm

CUSTOM events of subtype gsmopen::alarm are automatically fired when something bad happens to an interface, usually resulting in the interface being unavailable for service.

Most interesting fields are:

alarm_code       integer      refers to the type of alarm
alarm_message    string       descriptive text

alarm_code possible values are defined below:

GSMopen alarm_code Events

Other fields are the same as in the dump_event event. During a call, the alarm event also gets the additional fields.

This is an example of an alarm event for an interface that fails to initialize at startup (because the physical serial port does not exist):

GSMopen Alarm Event  Expand source

Building

Known Issues

Be sure the dongle has the "voice" capability unlocked, or unlock it with dc-unlocker ( http://www.dc-unlocker.com/ ).

Linux, *BSD, etc

Which Linux distro? Desktop or Server?

Desktop operating systems and distros are completely unsupported.

If you want to use desktop operating systems you have to find the way yourself, sorry.

Only operating systems supported by GSMopen are 64 bit servers: LTS ubuntu 12.04, centos 6, SL6, Debian 6, running directly on the hardware (eg: no Virtual Machines), or in OpenVZ containers running on Debian 6 or Centos 6 .

Prerequisites

CentOS 5.x

CentOS 5.x DOES NOT WORK with Huaweis and mod_gsmopen, use CentOS 6.x

CentOS 6.x, RHEL6.x, Scientific 6 Server 64-bit

Before building GSMopen module do:

GSMopen Pre-Build

 

Despite the name of the directory, it works well particularly for CentOS ;)

Check if the library is added by running

ldconfig -p | grep gsm

If you don't see any records, correct it after reading this post http://linux.101hacks.com/unix/ldconfig/ e.g. adding new rule file in /etc/ld.so.d/. Then re-run ldconfig

then:

Make GSMopen

 

Ubuntu LTS 12.04 Server 64-bit

Before building GSMopen module do:

GSMopen Pre-Build

 

then:

Make GSMopen

You may need to reboot to have your dongle recognized

Debian 6 (Squeeze) Server 64-bit

Before building GSMopen module do:

Debian GSMopen Pre-Build

 

then:

Debian Make GSMopen

You may need to reboot to have your dongle recognized

Build and Install

After installing prerequisites (see above), go into mod_gsmopen directory and type:

 

Configuration File

Install and edit the gsmopen configuration file:

GSMopen Config File

Determine the correct device files to use for controldevice_name and controldevice_audio_name

Connect to your usb device /dev/ttyUSBx and then call the modem's number. If you see "RING" then that device should be the controldevice_name. Usually the highest number is the control device. controldevice_audio_name is usually the device one less than the controldevice_name.

Start FS and Load GSMopen

Launch FreeSWITCH:

/usr/local/freeswitch/bin/freeswitch

Then activate debug logging in console and logfile, and load mod_gsmopen:

 

Windows

GSMopen runs very well on Windows.

GSMopen (mod_gsmopen) is NOT automatically built when you build FreeSWITCH on Windows.

Prerequisites on Windows

Build FreeSWITCH on Windows

You will need the Visual C compiler from Microsoft, commercial version, or the free (as in beer) Visual C Express (requires registration). They both give the same results in our case (eg: no need to buy the commercial version just for GSMopen).

After having downloaded the FS sources from Stash or the packaged FS source release, follow the instructions on how to build FS on Windows. Using Visual C (Express or not):

  • Open Freeswitch.sln
  • Right–click the main solution node at the top of the Solution Explorer
  • Right–click and select Build

This will build FreeSWITCH WITHOUT GSMopen. You must now build the prerequisites (see below) and after prerequisites are built, eventually build mod_gsmopen.

GSMopen on Windows

After having built FreeSWITCH, go into FreeSWITCH source directory, eg: c:\freeswitch, and then go to

cd src/mod_gsmopen/gsmlib/gsmlib-1.10-patched-13ubuntu/win32 

Using Visual C (Express or not):

  • Open gsmlib.sln (Note: if you are using 2008 Pro or higher or 2010 Pro or higher this step is not needed; see below)
  • Right–click the main solution node at the top of the Solution Explorer
  • Right–click and select Build

ERRORS ARE OK!, we're only interested in building the library, and it will be built OK. Errors come from application building; we're not interested in the application here.

Then you must start a Visual Studio Command Prompt (from the "Visual Studio Tools" Start Menu). Inside the Command Prompt window go to

c:/freeswitch/src/mod/endpoints/mod_gsmopen/libctb-0.16/build

Inside the Command Prompt window execute:

GSMopen Visual Studio Command Window

Visual Studio Pro Users

If you have Visual Studio 2008 Pro or 2010 Pro you must execute the above nmake command then build mod_gsmopen (gsmlib will be built automatically as a dependency).

Build and Install GSMopen on Windows

Go back to the Visual C compiler from Microsoft, commercial version, or the free (as in beer) Visual C Express (requires registration). They both give the same results in our case (eg: no need to buy the commercial version just for GSMopen).

  • Open Freeswitch.sln
  • Right–click the main solution node at the top of the Solution Explorer
  • Click on "Add" and choose "Existing Project" (Note: If you have VS2008 Pro or higher or VS2010 Pro or higher this step is not needed)
  • Navigate to c:/freeswitch/src/mod/endpoints/mod_gsmopen/ and select "mod_gsmopen.2008.vcproj"
  • mod_gsmopen is added to the FreeSWITCH solution tree
  • Right–click on "mod_gsmopen" and choose "Build"

Configuration File on Windows

Install and edit the gsmopen configuration file:

copy c:/freeswitch/src/mod/endpoints/mod_gsmopen/configs/gsmopen.conf.xml c:/freeswitch/Debug/conf/autoload_configs/
notepad c:/freeswitch/Debug/conf/autoload_configs/gsmopen.conf.xml

Start FS and Load GSMopen on Windows

Launch FreeSWITCH:

c:/freeswitch/Debug/freeswitch.exe 

Then activate debug logging in console and logfile, and load mod_gsmopen:

 

How to Report Bugs and Request Features

Be sure the dongle has the "voice" capability unlocked, or unlock it with dc-unlocker ( http://www.dc-unlocker.com/ ).

You can file bug reports, hints, suggestions, feature requests, improvements, patches, etc to Jira open an account there if you don't have it (it's free ;-) ).

Here's the best way to give us info on bugs:

1) from the FS CLI: "console loglevel 9"
2) from the FS CLI: "fsctl loglevel 9"
3) from the FS CLI: "unload mod_gsmopen"
4) from the FS CLI: "load mod_gsmopen"
5) reproduce the bug
6) attach the *complete, since the beginning* 
   console output (or freeswitch.log file) 
   as a file attachment to the Jira bug. 
   Please do not cut and paste console output 
   or freeswitch.log in the Jira message. ATTACH it.

If the bug involves crashes, core dumps, etc, please read this guide on how to report it Reporting Bugs to JIRA , then file a JIRA to mod_gsmopen with all relevant info.

How to Find Help

Be sure the dongle has the "voice" capability unlocked, or unlock it with dc-unlocker ( http://www.dc-unlocker.com/ ).

You can drop in the IRC channels #freeswitch on irc.freenode.net to ask questions and discuss issues. The original developer Giovanni Maruzzelli of GSMopen is called "gmaruzz" in the IRC channel.

You can also write to the FS users' and developers' mailing lists: http://lists.freeswitch.org/mailman/listinfo but PLEASE do not write to both; choose either IRC or the mailing list to avoid overloading the volunteer users who provide support.

UNLOCK THE DONGLE FIRST

UNLOCK THE DONGLE!!!

Be sure the dongle has the "voice" capability unlocked, or unlock it with dc-unlocker ( http://www.dc-unlocker.com/ ).

Troubleshooting

Intermittent failures

MORE THAN ONE DEVICE on a USB bus without a dedicated power supply can have intermittent failure, because dongles can use all of the power! Remember, this dongle is a tiny cellular radio and needs plenty of current to transmit. If you use more than one device, use an external (or many, cascaded) power supplies, powered from the wall to supply the USB hub. That's perfectly OK.

VMWare support

Be sure to check your VMWare host supports DirectPath I/O. Check in vCenter under the host's Configuration/Advanced Settings/DirectPath I/O. If it says "Host does not support passthrough configuration" you wont be able to make it work.

See Also

mod_sms

https://txlab.wordpress.com/2014/12/22/connecting-yeastar-tg200-gsm-gateway-with-freeswitch/ — article on using Yeastar TG200 GSM gateway by Stanislav Sinyagin