GSMopen
From FreeSWITCH Wiki
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 and mod_dingaling).
GSMopen can be compiled in an SMS only form (eg: no audio support, no voice calls support, works just as an SMS gateway), and therefore does not require sound cards or sound support in the server or libraries.
GSMopen uses a GSM modem and the server sound subsystem as a physical interface to the GSM network, using native serial commands (AT or FBUS) for call control and the native sound interface (e.g. ALSA, winmme) for audio I/O.
GSMopen can use the following physical interfaces: a cell phone + sound card; an embedded combined device; or a cell phone via blue tooth.
For production deployment and/or multi-line setups an embedded combined device is recommended.
GSMopen has the ability to nearly completely customize the serial commands it sends to the device, so it can be used with any GSM device that accepts AT commands.
GSMopen works in FreeSWITCH only on Linux at the moment (and will also be ported to Windows soon), native at 8khz (GSM is 8khz compressed audio).
GSMopen works on Asterisk at 8khz, on Linux and Windows (through CygWin).
GSMopen operates on GSM cellular/mobile connections in the same way that OpenZAP operates on analog lines. An interface (a GSM modem and a sound I/O)is needed for each channel. For example, two concurrent calls would need two channels as well as two GSM modems and sound I/Os connected to the FreeSWITCH server.
Obviously you must have credit on the SIM(s) inside the interface(s) 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). There are many ways to compile GSMopen, some of them (e.g.: no_cplus_plus and or no_portaudio) are targeted toward the lesser powerful platforms.
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's team, and hints, patches, suggestions, bug reports, features requests from the superlative FS community.
STATUS
GSMopen is "beta" status.
But 'it works for me' and in various installations, without problems.
History
GSMopen is the successor of Celliax.
Celliax was born in 2004 as an Asterisk channel driver for using cheap cellphones as GSM interfaces. First kind of serial signaling to be implemented was FBUS (the proprietary protocol of old Nokia cellphones), and it was possible thanks to the open source community efforts to document that undisclosed binary serial protocol (particularly the gammu and gnokii projects). Then was implemented the AT protocol used by most part of non old Nokia cellphones. In parallel was developed the hardware design for the audio cable from the hands free jack to the soundcard (including an hardware filter for the GSM band and the TDM frequency bursts that goes into audio spectrum, microphone bias voltage decoupling, etc). Data cables are available ready made from original cellphone manufacturer and aftermarket. A DECT interface was contributed that allows for interfacing a DECT chipset and system. After a while to Celliax was added the Skype capability (that was later spun off to be chan_skypiax).
Last touch was adding the acoustic echo canceling from the speexdsp library, that allowed for the use of cellphones that generate "comfort echo" (good for you when you use the cellphone in the way was designed to be used, bad if you use it as an interface: it generates echo :) ). Celliax was working well, and was quickly adopted by hardware manufacturers that made combined devices containing all the needed hardware in a black box, with just one USB cable. And without echo.
Starting in 2009 Celliax becomes GSMopen, the development platform becomes FreeSWITCH (keeping compatibility with Asterisk), and the focus is toward cheap embedded combined devices (more simple, reliable and robust than cellphones, but cellphones are still supported).
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.
Voice calls and SMS
A physical interface can be one of the following:
- cellphone + datacable for that cellphone (often to USB port of FS server) + audiocable from the handsfree jack of the cellphone to the soundcard on the FS server + soundcard on the FS server
- bluetooth cellphone that will connect to the bluetooth interface (internal or as USB dongle) on the FS server
- embedded combined device (black box) that contains in one only package one or more cellphone_modem(s)/soundcard(s), with one only USB cable connected to the FS server
SMS ONLY (no voice calls)
- Any GSM modem (secondhand cellphone or a professional modem) that accepts AT commands + its datacable to connect it to the server.
Dialplan, and how to use GSMopen for outbound voice calls
Dialplan
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:
<!-- dial 3472665618 via gsmopen using interface1 interface to go out -->
<extension name="gsmopen">
<condition field="destination_number" expression="^2909$">
<action application="bridge" data="gsmopen/interface1/3472665618"/>
</condition>
</extension>
The "ANY" and "RR" interfaces, poor man interface grouping
You can also use the "ANY" or "RR" interfaces
gsmopen/ANY/3472665618 gsmopen/RR/3472665618
To call "3472665618" using the first available (idle, not in a call) gsmopen interface, automatically selected (thx Seven Du).
"ANY" and "RR" are now just aliases, and will choose an available idle interface based on a round robin algorithm (so to distribute calls more fairly between all the available interfaces).
Dialplan snippet:
<!-- dial 3472665618 via gsmopen RR interface -->
<extension name="gsmopen">
<condition field="destination_number" expression="^2908$">
<action application="bridge" data="gsmopen/RR/3472665618"/>
</condition>
</extension>
CONFIGURATION FILE and incoming voice calls
GSMopen is very configurable.
Almost any single AT command used to manage callflow 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!).
This is the minimum possible configuration file (/usr/local/freeswitch/conf/autoload_configs/gsmopen.conf.xml), it will create an interface with id=1 and name "interface0", managing the default /dev/ttyACM0 serial port, plughw:1 as audio input and audio output devices, destination "5000", context "default", dialplan "XML", using a plethora of other default configs optimized for most GSM modems and embedded combined devices:
<configuration name="gsmopen.conf" description="GSMopen Configuration">
<per_interface_settings>
<interface id="1" name="interface0">
</interface>
</per_interface_settings>
</configuration>
This is a more explicit config file, for two physical interfaces, as you see, you just have to specify the serial device and the capture and playback audio devices for each interface (global_settings are applied instead of defaults where a single interface does not states otherwise):
<configuration name="gsmopen.conf" description="GSMopen Configuration">
<global_settings>
<param name="debug" value="8"/>
<param name="dialplan" value="XML"/>
<param name="context" value="default"/>
<param name="hold-music" value="$${moh_uri}"/>
<param name="destination" value="9999"/>
</global_settings>
<!-- one entry here per gsmopen interface -->
<per_interface_settings>
<interface id="1" name="interface0">
<param name="hold-music" value="$${moh_uri}"/>
<param name="dialplan" value="XML"/>
<param name="context" value="default"/>
<param name="destination" value="5000"/>
<param name="alsacname" value="plughw:1"/>
<param name="alsapname" value="plughw:1"/>
<param name="controldevice_name" value="/dev/ttyACM0"/>
</interface>
<interface id="3" name="interfaceNICE">
<param name="hold-music" value="$${moh_uri}"/>
<param name="dialplan" value="XML"/>
<param name="context" value="default"/>
<param name="destination" value="9996"/>
<param name="alsacname" value="plughw:2"/>
<param name="alsapname" value="plughw:2"/>
<param name="controldevice_name" value="/dev/ttyACM1"/>
</interface>
</per_interface_settings>
</configuration>
Following are all the various configurable parameters you can set for each interface (with their default values):
context = "default" dialplan = "XML" destination = "5000" controldevice_name = "/dev/ttyACM0" digit_timeout = NULL max_digits = NULL hotline = NULL dial_regex = NULL hold_music = NULL fail_dial_regex = NULL enable_callerid = "true" at_dial_pre_number = "ATD" at_dial_post_number = ";" at_dial_expect = "OK" at_hangup = "ATH" at_hangup_expect = "OK" at_answer = "ATA" at_answer_expect = "OK" at_send_dtmf = "AT+VTS" at_preinit_1 = "" at_preinit_1_expect = "" at_preinit_2 = "" at_preinit_2_expect = "" at_preinit_3 = "" at_preinit_3_expect = "" at_preinit_4 = "" at_preinit_4_expect = "" at_preinit_5 = "" at_preinit_5_expect = "" at_postinit_1 = "at+cmic=0,9" at_postinit_1_expect = "OK" at_postinit_2 = "AT+CKPD=\"EEE\"" at_postinit_2_expect = "OK" at_postinit_3 = "AT+CSSN=1,0" at_postinit_3_expect = "OK" at_postinit_4 = "at+sidet=0" at_postinit_4_expect = "OK" at_postinit_5 = "at+clvl=99" at_postinit_5_expect = "OK" at_query_battchg = "AT+CBC" at_query_battchg_expect = "OK" at_query_signal = "AT+CSQ" at_query_signal_expect = "OK" at_call_idle = "+MCST: 1" at_call_incoming = "+MCST: 2" at_call_active = "+CSSI: 7" at_call_failed = "+MCST: 65" at_call_calling = "+CSSI: 1" at_indicator_noservice_string = "CIEV: 20" at_indicator_nosignal_string = "CIEV: 50" at_indicator_lowsignal_string = "CIEV: 5;1" at_indicator_lowbattchg_string = "CIEV: 0;1" at_indicator_nobattchg_string = "CIEV: 0;0" at_indicator_callactive_string = "CIEV: 3;1" at_indicator_nocallactive_string = "CIEV: 3;0" at_indicator_nocallsetup_string = "CIEV: 6;0" at_indicator_callsetupincoming_string = "CIEV: 6;1" at_indicator_callsetupoutgoing_string = "CIEV: 6;2" at_indicator_callsetupremoteringing_string = "CIEV: 6;3" alsacname = "plughw:1" alsapname = "plughw:1" at_early_audio = "0" at_after_preinit_pause = "500000" at_initial_pause = "500000" at_has_clcc = "0" at_has_ecam = "0" alsa_period_size = "160" alsa_periods_in_buffer = "4" gsmopen_sound_rate = "8000" alsa_play_is_mono = "1" alsa_capture_is_mono = "1" capture_boost = "5" playback_boost = "10" no_sound = "0" portaudiocindex = "1" portaudiopindex = "1" speexecho = "1" speexpreprocess = "1" gsmopen_serial_sync_period = "300"
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 simple and easy, if carrier support 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 + sound I/O) 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 SIM is busy or unreachable, carrier will redirect call to forwarded number. Same way you can add additional SIM cards / phones - forward them.
Carrier can limit maximal 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/socket/ESL/whatever.
gsm
"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).
You begin typing "gsm console interface_name" to direct the "current console" to sending messages to interface_name. Starting now on, you can type "gsm AT_command" and AT_command string will be sent to the modem related to interface interface_name.
gsm console interface1 gsm ATI
"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
Muhammad Shahzad and Seven Du contributed code for adding and removing interfaces on the fly.
remove
gsm remove <interface_name | interface_id>
This command remove the gsmopen interface with name interface_name or with id interface_id, if that interface is idle.
gsm remove interface1
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
"gsm remove" and "gsm reload" (see before) can be useful from API/socket/ESL/whatever as well.
"gsmopen" commands are intended to be used by programs (API/socket/ESL/whatever) and have the format: "gsmopen interface_name AT_command_string". They send the AT_command string to the modem related to interface interface_name.
gsmopen interface2 ATI
This allow you to use directly the entire power of the AT command set of your GSM modem or cellphone, for eg. to prototype a new feature, do customization, etc 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 DO NOT affect the volumes as set by the audio mixer of the soundccard, eg: alsamixer. You MUST set the best volumes with alsamixer, then you can refine it with this command). This command is mainly useful to interactively (trial and error during a call) find the best audio boost 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> <in decibels: -40 ... 0 ... +40>]
eg:
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 fires 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
eg:
gsmopen_sendsms interface1 3472665618 this is a nice SMS text
chat
GSMopen answers to the FreeSWITCH standard "chat" command too, and use its arguments to execute a gsmopen_sendsms command. So, if you got a messaging applications that uses chat command with Sofia/SIP or Jingle, no need to recode it with special cases for SMSs :).
It uses SMS as protocol specification. Eg, from command line:
chat SMS|interface3|3472665618|ciao amore
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 SMSs (like Sofia and Jingle).
Voice Calls
Standard CODEC and CHANNEL_* events.
See Event_list
MESSAGE (SMSs)
The Event type generated by an incoming SMS is of type MESSAGE (like in Jingle and Sofia).
The interesting fields are:
login: the interface name that received the SMS from: the sender's number, urlencoded date: the date of the received message, urlencoded datacodingscheme: which kind of alphabet was used to send the message servicecentreaddress: address of SC used to send the message messagetype: numeric, usually 0, kind of message during-call: bool, the message was received while a voice call was ongoing?
And obviously the body, encoded in utf8, that contains the SMS's text.
NB: The body is UTF8 encoded, gives you ASCII for ASCII, and UTF8 for all the rest.
This is an incoming SMS as reported with Events plain.
Content-Length: 628 Content-Type: text/event-plain Event-Name: MESSAGE Core-UUID: 28d9e2e2-068d-11df-8f99-e9d7ea2264f4 FreeSWITCH-Hostname: hardy64 FreeSWITCH-IPv4: 192.168.0.12 FreeSWITCH-IPv6: %3A%3A1 Event-Date-Local: 2010-01-24%2017%3A26%3A11 Event-Date-GMT: Sun,%2024%20Jan%202010%2016%3A26%3A11%20GMT Event-Date-Timestamp: 1264350371003052 Event-Calling-File: mod_gsmopen.cpp Event-Calling-Function: sms_incoming Event-Calling-Line-Number: 3120 proto: SMS login: interface3 from: %2B393472665618 date: 2010/1/24,17%3A24%3A52 datacodingscheme: _undef_ servicecentreaddress: _undef_ messagetype: 0 subject: SIMPLE%20MESSAGE during-call: false Content-Length: 12 Ciao bello!
gsmopen::dump_event
CUSTOM events of type gsmopen::dump_event are fired in response to a gsmopen_dump command or API call (eg, from command line or via script or through the ESL). This events 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 fires 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:
Content-Length: 990 Content-Type: text/event-plain Event-Subclass: gsmopen%3A%3Adump_event Event-Name: CUSTOM Core-UUID: 28d9e2e2-068d-11df-8f99-e9d7ea2264f4 FreeSWITCH-Hostname: hardy64 FreeSWITCH-IPv4: 192.168.0.12 FreeSWITCH-IPv6: %3A%3A1 Event-Date-Local: 2010-01-24%2017%3A51%3A02 Event-Date-GMT: Sun,%2024%20Jan%202010%2016%3A51%3A02%20GMT Event-Date-Timestamp: 1264351862152937 Event-Calling-File: mod_gsmopen.cpp Event-Calling-Function: dump_event_full Event-Calling-Line-Number: 3008 interface_name: interface2001 interface_id: 1 active: 1 not_registered: 0 home_network_registered: 1 roaming_registered: 0 got_signal: 2 running: 1 imei: 353579017208923 imsi: 222018302196169 controldev_dead: 0 controldevice_name: /dev/ttyACM2 no_sound: 0 alsacname: plughw%3A2 alsapname: plughw%3A2 playback_boost: 1619.086162 capture_boost: 910.479058 dialplan: XML context: default destination: 2000 ib_calls: 0 ob_calls: 0 ib_failed_calls: 0 ob_failed_calls: 0 interface_state: 0 phone_callflow: 0 session_uuid_str: _undef_ during-call: false
During a call (while a call is active on the interface) a lot of useful infos are added (courtesy of Math ;) ).
Command used to generates the event is the same, but the interface is in an active call, executing a javascript app:
Content-Length: 2399 Content-Type: text/event-plain Event-Subclass: gsmopen%3A%3Adump_event Event-Name: CUSTOM Core-UUID: 28d9e2e2-068d-11df-8f99-e9d7ea2264f4 FreeSWITCH-Hostname: hardy64 FreeSWITCH-IPv4: 192.168.0.12 FreeSWITCH-IPv6: %3A%3A1 Event-Date-Local: 2010-01-24%2017%3A55%3A40 Event-Date-GMT: Sun,%2024%20Jan%202010%2016%3A55%3A40%20GMT Event-Date-Timestamp: 1264352140851653 Event-Calling-File: mod_gsmopen.cpp Event-Calling-Function: dump_event_full Event-Calling-Line-Number: 3008 interface_name: interface2001 interface_id: 1 active: 1 not_registered: 0 home_network_registered: 1 roaming_registered: 0 got_signal: 2 running: 1 imei: 353579017208923 imsi: 222018302196169 controldev_dead: 0 controldevice_name: /dev/ttyACM2 no_sound: 0 alsacname: plughw%3A2 alsapname: plughw%3A2 playback_boost: 1619.086162 capture_boost: 910.479058 dialplan: XML context: default destination: 2000 ib_calls: 1 ob_calls: 0 ib_failed_calls: 0 ob_failed_calls: 0 interface_state: 2 phone_callflow: 5 session_uuid_str: 45fbda50-0909-11df-8f99-e9d7ea2264f4 during-call: true Channel-State: CS_EXECUTE Channel-State-Number: 4 Channel-Name: gsmopen/interface2001 Unique-ID: 45fbda50-0909-11df-8f99-e9d7ea2264f4 Call-Direction: inbound Presence-Call-Direction: inbound Answer-State: answered Channel-Read-Codec-Name: L16 Channel-Read-Codec-Rate: 8000 Channel-Write-Codec-Name: L16 Channel-Write-Codec-Rate: 8000 Caller-Username: gsmopen Caller-Dialplan: XML Caller-Caller-ID-Name: GSMopen%3A%20%2B393472665618 Caller-Caller-ID-Number: %2B393472665618 Caller-Destination-Number: 2000 Caller-Unique-ID: 45fbda50-0909-11df-8f99-e9d7ea2264f4 Caller-Source: mod_gsmopen Caller-Context: default Caller-Channel-Name: gsmopen/interface2001 Caller-Profile-Index: 1 Caller-Profile-Created-Time: 1264352127793104 Caller-Channel-Created-Time: 1264352127793104 Caller-Channel-Answered-Time: 1264352133281836 Caller-Channel-Progress-Time: 1264352127803152 Caller-Channel-Progress-Media-Time: 0 Caller-Channel-Hangup-Time: 0 Caller-Channel-Transfer-Time: 0 Caller-Screen-Bit: true Caller-Privacy-Hide-Name: false Caller-Privacy-Hide-Number: false variable_read_codec: L16 variable_read_rate: 8000 variable_write_codec: L16 variable_write_rate: 8000 variable_channel_name: gsmopen/interface2001 variable_endpoint_disposition: ANSWER variable_instance_id: 100 variable_current_application_data: freedomfone/leave_message/main.js%20100 variable_current_application: javascript
gsmopen::alarm
CUSTOM events of subtype gsmopen::alarm are automatically fired when something bad happens to an interface, usually resulting in the interface being no more available 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 as follow:
0 ALARM_FAILED_INTERFACE 1 ALARM_NO_NETWORK_REGISTRATION 2 ALARM_ROAMING_NETWORK_REGISTRATION 3 ALARM_NETWORK_NO_SERVICE 4 ALARM_NETWORK_NO_SIGNAL 5 ALARM_NETWORK_LOW_SIGNAL
Other fields as in the dump_event event. During a call, the alarm event too 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 do not exists):
Content-Length: 1023 Content-Type: text/event-plain Event-Subclass: gsmopen%3A%3Aalarm Event-Name: CUSTOM Core-UUID: 28d9e2e2-068d-11df-8f99-e9d7ea2264f4 FreeSWITCH-Hostname: hardy64 FreeSWITCH-IPv4: 192.168.0.12 FreeSWITCH-IPv6: %3A%3A1 Event-Date-Local: 2010-01-24%2017%3A38%3A15 Event-Date-GMT: Sun,%2024%20Jan%202010%2016%3A38%3A15%20GMT Event-Date-Timestamp: 1264351095120533 Event-Calling-File: mod_gsmopen.cpp Event-Calling-Function: dump_event_full Event-Calling-Line-Number: 3005 alarm_code: 0 alarm_message: gsmopen_serial_init%20failed interface_name: interface4001 interface_id: 2 active: 0 not_registered: 0 home_network_registered: 0 roaming_registered: 0 got_signal: 0 running: 0 imei: _undef_ imsi: _undef_ controldev_dead: 0 controldevice_name: /dev/ttyACM0 no_sound: 0 alsacname: plughw%3A1 alsapname: plughw%3A1 playback_boost: 10.000000 capture_boost: 5.000000 dialplan: XML context: default destination: 2000 ib_calls: 0 ob_calls: 0 ib_failed_calls: 0 ob_failed_calls: 0 interface_state: 0 phone_callflow: 0 session_uuid_str: _undef_ during-call: false
AUDIO SETUP
Linux (ALSA)
You will have to adjust the levels of the ALSA device used by each GSMopen interface.
You can do it using alsamixer -V all -c #num_alsa_card (eg: for the first additional soundcard other than the one embedded in the mainboard - so, for the second soundcard)
alsamixer -V all -c 1
Please note that ALSA enumerates soundcards starting from zero (so, the first soundcard is 0, the fourth is 5, etc).
Be sure to activate 'capture' on microphone, to mute the playback on microphone, and to set the levels in a comfortable zone.
In the GSMopen directory there is an automated script that do it all for you on the first 8 soundcards: is aptly named setmixers.
Also, to minimize the CPU usage by ALSA, please create a file /etc/asound.conf (or add this line to an existing one):
defaults.pcm.rate_converter "linear"
MULTIPLE LINES HARDWARE SETUP
Because of limitations in the USB "regular" hubs, if you want to connect more than 3 sound devices (or embedded combined devices) to an USB hub it is of paramount importance that you use "Multi-TT" USB hubs (eg: google for "multi-TT USB hub").
TO DO
Requests, suggestions, ideas (feel free to add here, but best is to add on Jira - see below 'BUGS and Feature Requests'):
KNOWN ISSUES
USB serial devices changing names
On Debian, there has been a report that certain times the same hardware serial device can show up as ttyACM# and at other times (eg: reboot, unplug and plug again, etc) as ttyUSB#. This seems to be a problem with the operating system itself. Best way to react to this is probably to blacklist one of the serial driver modules or force the cdc_acm to be loaded first. Please anyone in the knows add here.
SMS delayed reception
When using interfaces that do not support AT+CNMI (unsolicited signaling about incoming SMSs), GSMopen polls the interface memory or SIM each 30 seconds, to check for unread SMSs. So, in the worst case, using an interface that do not supports AT+CNMI, there will be a delay of 30 seconds from the actual incoming SMS and that SMS to be seen by GSMopen.
Building
Linux
Which libraries are needed
There are many ways to build GSMopen in Linux, but the various additional libraries are part of the FreeSWITCH source distribution, and are built by default when you build FreeSWITCH. Or are part of the mod_gsmopen svn download, and you will build them from sources before building the module.
The only distro packages specially needed by GSMopen are the ALSA development lib and utilities (for the mixer, that you'll use to set the volumes on playback and capture).
If you are on Ubuntu, Debian, or derivative:
apt-get install libasound2-dev alsa-utils
If you are on CentOS, RedHat, or derivative:
yum -y install alsa-lib-devel alsa-utils
For other distros, please add here.
Preparations, GSMopen source download
First you build FreeSWITCH in your preferred way, downloading the sources from tgz package release or (preferred) from svn.
Then, you test the freshly installed FreeSWITCH, and made sure it works.
Then you go in the endpoint subdir of the FreeSWITCH sources (eg: /usr/src/freeswitch.trunk/src/mod/endpoints ) and:
svn co http://svn.freeswitch.org:81/svn/freeswitch/branches/gmaruzz/mod_gsmopen mod_gsmopen
This will download the sources needed to build GSMopen on your machine, actually will download the sources needed for gsmlib too, and you'll need gsmlib if you want to build with gsmlib support.
Go into in the freshly created mod_gsmopen directory.
cd mod_gsmopen
Different kinds of build
At the moment of this writing, there are many different ways to build GSMopen, time will be the judge of the popular and useful ones (if any).
Build kinds are:
- With audio support (voice calls and SMSs)
- With ALSA and gsmlib (for SMS binary PDU decoding), compiled as C++ module (requires C++ runtime, C++ libraries, etc)
- With PortAudio and gsmlib (for SMS binary PDU decoding), compiled as C++ module (requires C++ runtime, C++ libraries, etc). This build uses libspeexdsp to cancel the sidetone produced by cellphones used as physical interface, that will be otherwise perceived as echo by the remote party. If you use a GSM module, embedded device, or if you can set off the sidetone in the cellphone you use as interface, you don't need echo canceling.
- With ALSA without gsmlib (uses text mode SMS encoding and decoding, compiled as plain C module, does not require any C++ lib or runtime)
- With PortAudio without gsmlib (uses text mode SMS encoding and decoding, compiled as plain C module, does not require any C++ lib or runtime). This build uses libspeexdsp to cancel the sidetone produced by cellphones used as physical interface, that will be otherwise perceived as echo by the remote party. If you use a GSM module, embedded device, or if you can set off the sidetone in the cellphone you use as interface, you don't need echo canceling.
- Without audio support (SMSs only, no voice calls) You choose one of those builds if you don't have sound device or are not interested in voice calls)
- With gsmlib (for SMS binary PDU decoding), compiled as C++ module (requires C++ runtime, C++ libraries, etc)
- Without gsmlib (uses text mode SMS encoding and decoding, compiled as plain C module, does not require any C++ lib or runtime)
Build it, install it, copy config file
If you choose a build kind that include gsmlib, before building GSMopen module do (despite the name of the directory, works for all distros, particularly CentOS ;) ):
cd gsmlib/gsmlib-1.10-patched-12ubuntu1 ./configure make make install
Build kinds locations:
- With audio support (voice calls and SMSs)
- With ALSA and gsmlib is in the main directory (eg: /usr/src/freeswitch.trunk/src/mod/endpoints/mod_gsmopen )
- With PortAudio and gsmlib is in portaudio_gsmlib_cplusplus_noalsa/mod_gsmopen
- With ALSA without gsmlib is in alsa_nogsmlib_nocplusplus/mod_gsmopen
- With PortAudio without gsmlib is in portaudio_nogsmlib_nocplusplus_noalsa/mod_gsmopen
- Without audio support (SMSs only, no voice calls)
- With gsmlib is in noaudio_gsmlib_cplusplus/mod_gsmopen
- Without gsmlib is in noaudio_nogsmlib_nocplusplus/mod_gsmopen
(Pardon me for the lame directory naming).
After having made your mind on the kind of build you want, go into its directory and type:
make clean make install
Install and edit the gsmopen configuration file:
cd /usr/src/freeswitch.trunk/src/mod/endpoints/mod_gsmopen/configs/ cp gsmopen.conf.xml /usr/local/freeswitch/conf/autoload_configs/ vi /usr/local/freeswitch/conf/autoload_configs/gsmopen.conf.xml
If you use old secondhand Motorola cellphone as physical interface, use the gsmopen.conf.xml.motorola instead, it has workaround for its many deficiencies.
Start FS and load gsmopen!
/usr/local/freeswitch/bin/freeswitch load mod_gsmopen
Windows
GSMopen do not runs on Windows at the moment. But soon it will!
How to Report Bugs and Feature Requests
You can file bug reports, hints, suggestions, feature requests, improvements, patches, etc to http://jira.freeswitch.org/browse/GSMOPEN open an account there if you don't have it (it's free ;-) ).
That's the best way to give us info on bugs:
1) from the FS CLI: "console loglevel 9" 2) load mod_gsmopen 3) reproduce the bug 4) attach the *complete, since beginning* console output as a file attachment to the Jira bug
If the bug involves crashes, core dumps, etc, please read this guide on how to report it http://wiki.freeswitch.org/wiki/Reporting_Bugs , then file a Jira to mod_gsmopen with all relevant info.
How to Find Help
You can drop in the IRC channels #freeswitch, #freeswitch-dev and #gsmopen on irc.freenode.net to ask questions and discuss issues. The original developer of GSMopen is called "gmaruzz" in the IRC channel.
You can use the forum at http://www.gsmopen.org
You can also write to the FS users' and developers' mailing lists: http://lists.freeswitch.org/mailman/listinfo
