chan_celliax and chan_skypiax,

1

• chan_celliax and chan_skypiax,
• how to add Gsm and Skype
• capabilities to Asterisk
• INDIA, October 2008

2
AGENDA

• Asterisk overview
• Asterisk's Channel Drivers overview
• Hardcore Asterisk development challenges
• how chan_celliax works audio, signaling, dsp
• hardware audiocables, datacables, cellphones
• how chan_skypiax works audio, signaling
• celliax and skypiax dialplan usage
• celliax and skypiax AMI manager usage
• directoriax, app_directory on steroids
• QA Session

3
One Picture....
4
...a thousand words
5
Asterisk Overview

• Software PBX
• Interfaces to PSTN, VoIP
• IVR, VoiceMail, Directory
• Platform for Application Development (AGI, AMI)?
• Enterprise Solutions
• Carrier Solutions
• Value Added Solutions

6
Asterisk's Channel Drivers

• Each channel driver implements the functions to
  be used by Asterisk (call, answer, dial, etc)?
• Into the driver, a loop thread monitors all its
  physical interfaces, accepting interface events
  (RING, DOWN, etc)?
• When a call incomes or is originated, the driver
  creates an instance that mediates between
  Asterisk and the interested interface. That
  particular interface is no more in the monitored
  pool
• When the call is finished, that interface go back
  into the monitored pool

7
Hardcore Asterisk Development challenges

• Little Documentation on core development (lots on
  applications dev)?
• Real Time, delays, jitter, lag, etc
• Audio, echo, compression, analysis
• Locks, threads, mutexes
• Resources, RAM, CPU, IRQs, etc

8
chan_celliax Features Overview

• Works well on Linux and Windows XP/Vista
  (CygWin)?
• A Datacable to the (USB) serial port and an
  Audiocable to the soundcard, to interface the
  physical cellphone
• Incoming and Outgoing call using most popular
  (cheap) cellphones and other communication
  devices
• Incoming and Outgoing SMSs
• Cellphone phonebook entries import into dialplan
  and Directoriax
• Export from Directoriax to cellphone phonebook
  entries (one click dial from the cellphone)?

9
Celliax in Action!
10
AudioCables

• You need an audiocable between the cellphone used
  as celliax physical interface and the soundcard
  of the PC running Asterisk
• You can buy it or build it (little soldering
  needed)?
• For cellphones using standard 3pole 2.5mm
  handsfree jack you can start from a cheap headset
  cut it before the microphone and solder two 3pole
  3.5mm jacks
• For Nokias using 4pole 2.5mm handsfree jack more
  work is needed
• electrical schemas are availables at
  www.celliax.org
• Professionally manufactured audiocables will be
  available November 2008 at www.celliax.org

11
DataCables

• You better have a datacable between the cellphone
  used as physical interface and the serial port
  (or USB) of the PC running Asterisk
• chan_celliax can work without datacable, but it
  cannot originate calls, will have no information
  at all on the incoming calls (autoanswered by the
  cellphone) , will rely on a period of silence to
  notice a remote hangup
• Most cellphones has datacables available, at
  least aftermarket (notably Nokia models)?
• Datacables for the cellphones most used with
  chan_celliax will be available at www.celliax.org

12
chan_skypiax Features Overview

• Works well on Linux and Windows XP/Vista
  (CygWin)?
• Uses the original Skype client as interface to
  the Skype VoIP service
• Incoming and Outgoing calls to/from Skype clients
• Incoming and Outcoming calls to/from SkypeOut
  numbers
• Skype Client Contacts entries import into
  dialplan and Directoriax
• Export from Directoriax to cellphone phonebook
  entries (one click dial from the cellphone)?

13
Implementation 1 (monitors)?

• When not in a call, we need to monitor various
  sources of events
• Serial Port (for datacable incoming
  signaling/indications)?
• Skype Client (for Skype incoming
  signaling/indications)?
• Cellphone Audio (for sensing a RING if we do not
  have serial indications, eg Nokia 3310, or no
  datacable)?
• We've got a loop monitor thread for each kind of
  events' sources

14
Implementation 2 audio

• Soundcard interfacing APIs (for chan_celliax)
  tend to be platform specific, CygWin has only a
  very rough OSS-like layer, MacOS is specific, etc
• Chan_celliax uses Portaudio, the opensource
  multiplatform audio library (runs on whatever
  -)?
• On chan_celliax, additional Acoustic Echo
  Cancelling is performed by the speexdsp
  opensource library
• Chan_skypiax gets its audio from/to the Skype
  client through TCP ports
• Incoming audio is analyzed to recognize silence
  and DTMFs by the spandsp opensource library

15
Implementation 3 serial

• Serial interfacing is fairly portable, very well
  implemented by CygWin on Windows
• Celliax uses various kind of serial signaling
• AT standard commands, for the most part of
  cellphones
• FBUS2 proprietary commands, for various Nokia
  models
• Other serial commands/signaling protocols, eg.
  for DECT modules (would be very nice to have
  IDEN)?
• Each kind of signaling has its own functions,
  over a common serial layer for physical I/O

16
Implementation 4 Skype API

• Skype API is a proprietary, text based protocol
  for communication between the Skype client and
  other external software (eg chan_skypiax)?
• On Windows is implemented through Windows
  Messages, on Linux using X Events
• For both Linux and Windows, chan_skypiax creates
  a fake window with its own message loop, then
  dispatch messages to the monitor or to the
  appropriate interface thread
• Eg skypiax sends PING to Skype client, Skype
  client sends PONG back to skypiax
• Skype API is fairly complete, can manage calls,
  call progress, messaging, etc

17
CLI commands 1 Celliax interface stuff

• From the Asterisk CLI console, you can give
  various commands to interact with chan_celliax
• celliax_usage give a list of chan_celliax CLI
  commands and dialplan applications
• celliax_console shows or sets the chan_celliax
  interface on which further commands are acting
  upon
• celliax_dial, celliax_hangup during a call,
  sends DTMF to the interface (not to remote party)
  or hangup the call. Useful for no_serial tests
  without cellphone (only headset/mic)?
• celliax_playback_boost, celliax_capture_boost
  shows or sets the audio scaling
• celliax_echo shows or sets the Acoustic Echo
  Cancellation parameters
• celliax_sendsms sends an SMS
• celliax_at sends an AT command to the cellphone

18
CLI commands 2 Skypiax interface stuff

• From the Asterisk CLI console, you can give
  various commands to interact with chan_celliax
• skypiax_usage give a list of chan_skypiax CLI
  commands
• skypiax_console shows or sets the chan_skypiax
  interface on which further commands are acting
  upon
• skypiax_dial, skypiax_hangup during a call,
  sends DTMF to the interface (not to remote party)
  or hangup the call?
• skypiax_playback_boost, skypiax_capture_boost
  shows or sets the audio scaling
• skypiax_skype sends a Skype protocol command to
  the Skype client

19
CLI commands 3 Celliax directory stuff

• celliax_dir_import imports entries from the
  cellphone phonebook into the directoriax.conf
  file
• addreplace appends to the existing file or
  substitute it
• fromcellfromcsv the entries are sourced from
  the cellphone phonebook or from a csv file (eg
  pda, smartphones)?
• celliax_dir_export exports the extensions from
  the directoriax.conf into the cellphone
  phonebook, prefixing each one with the interface,
  cellphonenumber, and a pause, so you can
  one-click dial from the remote cellphone
• tocell write only to cellphone phonebook now
  (soon also to csv files)?
• cellphonenumber the number at which the
  interface answers

20
CLI commands 4 Skypiax directory stuff

• skypiax_dir_import imports entries from the
  Skype client Contacts' List into the
  directoriax.conf file
• addreplace appends to the existing file or
  substitute it

21
Applications 1 - Directoriax

• Directoriax(vmcontextdialcontextf)?
• it works very similar to the Asterisk standard
  directory application, but it reads the specific
  directoriax.conf that is populated by the
  celliax_import and skypiax_import CLI command
  with entries from the Skype Client Contacts list
  and/or from the cellphone phonebook
• it asks you to digit the first three letter of
  the person you want to call, tells you who it is,
  and if you confirm, make the call (through Skype
  or whatever) to him
• vmcontext is the celliax_dir.conf section we want
  to use
• dialcontext is the context used to make calls
• f is for use the first name (as opposed to last
  name) of the directory entry
• At startup, it populates a configurable dialplan
  context with short extensions that call its own
  entries

22
Applications 2 - celliax_sendsms

• Celliax_SendSMS(interface/remote_number,text)?
• Sends an SMS to the cellphone at remote_number
  with content text, using the given interface
• interface is the name of the chan_celliax
  interface we want to use for sending the SMS, eg.
  nicephone
• remote_number is the number of the cellphone to
  which we want to send the SMS to
• text is the content of the SMS, all standard
  dialplan escaping rules apply, eg DATETIME
  "This a SMS test\, we\'re testing\, yes\, we\'re
  testing..."

23
Dialplan (extensions.conf)?

• Contexts
• directoriax
• is created by app_directoriax at startup
• contains the short extensions to call the entries
  from the directoriax.conf
• if included in the default incoming call context,
  allows one-click dial to its extensions from
  cellphones which phonebooks has been populated by
  celliax_dir_export
• Dial
• standard Asterisk usage, eg dial(Celliax/nicephon
  e/3334445)? dial(Skypiax/skypeclient/echo123)?
• Directoriax, Celliax_sendsms
• see before, Applications

24
Asterisk Manager Interface (AMI)

• CELLIAXsendsms command
• Action CELLIAXsendsms
• Interface (celliax interface you want to
  use)
• Number (recipient number you want to
  send the SMS to)
• Text (text of the SMS to be sent)
• ActionID (Action ID for this AMI
  transaction)
• CELLIAXincomingsms event
• Originate (Dial a call) and all standard AMI
  commands for both celliax and skypiax

25
Installation 1 Add to an existing Asterisk

• Linux
• If you have previously installed Asterisk from
  sources, or from your distro package (with the
  latter you need the asterisk-devel package too)
• You can just download the sources and compile
  just the chan_celliax, chan_skypiax and
  app_directoriax, then add them and their config
  files to your installation
• Follow the README complete instructions
• Compatible with Asterisk 1.2, 1.4 and 1.6.0 series

26
Installation 2 Complete preconfigured Asterisk
1.2

• Linux and Windows (CygWin)
• If you want an installation complete with
  asterisk, celliax, skypiax, directoriax,
  configurations, dialplan and some ad hoc
  configuration utilities
• Download the sources
• Follow the complete README
• Compile and install the needed libraries
• Compile and install Asterisk
• Launch it -)

27
Installation 3 on TrixBox, PIAF, Elastix, etc

• In a short while there will be automatic scripts
  available on www.celliax.org
• Scripts will download, compile, and install
  celliax, skypiax and directoriax on your existing
  installation
• Add skypiax and celliax to FreePbx and FOP

28
celliax.conf file 1

• Each section between brackets defines an
  interface, eg nicephone is the
  Celliax/nicephone
• The first interface defined in celliax.conf sets
  the defaults for all the following interfaces.
  Defaults can be overridden by each interface
• The most important KeyValue couple are
• control_device_protocolatfbus2no_serial...
• control_device_name/dev/ttyUSB0/dev/ttyACM0...
  
• portaudio_capture_device_id
• portaudio_playback_device_id

29
celliax.conf file 2

• Many other keyvalue couples allows for fine
  tuning of each interface
• serial speed
• most AT commands and indications can be specified
  to accommodate for cellphones non ETSI standard
• need_acoustic_ring can be enabled to accommodate
  for cellphones that do not give incoming RING
  serial indication, or when no datacable is used
  (eg. Nokia 3310 or a cellphone with autoanswer
  enabled)?
• dsp_silence_threshold can be set to determine how
  much noise is no more silence
• playback_boost scales the audio signal

30
Troubleshooting 1 Celliax Audio

• For Celliax, you need to setup the Audio Mixer
• You need working audio incoming from microphone
  (capture-recording) and outgoing from
  speakers-headset (playback)?
• Check that the Microphone is muted for playback
  (or it will loop back to you)?
• Check that the Microphone is selected for capture
• Check if your microphone needs an audio boost
  from the mixer
• Eventually, play with scaling up or down audio
  capture and playback signals in the config file
  or through CLI commands

31
Troubleshooting 2 Celliax Serial

• For Celliax, you need to check the serial port
  the cellphone datacable is connected to
• Check that the controldev_protocol for this
  interface in the celliax.conf file is correct
• Check that the control_device_name for this
  interface in the celliax.conf config file is
  correct
• Check that the serial speed for this interface in
  the celliax.conf config file is supported by the
  cellphone (FBUS2 always uses 115200)?
• Check that the device has been correctly created
  by the operating system (on Linux you can use
  dmesg, on Windows use Control Panel for ports
  and modems)?

32
Troubleshooting 3 Celliax permissions

• Various Linux distro do not allows general
  permissions to write and read the sound and
  serial devices
• Often those permissions are reset at each reboot
• Check that the user Asterisk is running as has
  the needed permissions
• Make a startup script (an rc.local, or an
  Asterisk launching script) that gives to the
  Asterisk user all the necessary permission, eg
• chown -R asterisk.asterisk /dev/snd
• See the How To on www.celliax.org

33
Troubleshooting 4 debug logging

• Chan_celliax and chan_skypiax have very fine
  grained debug messages
• in the config file, activate the desired
  debug_yes for each category you want messages
  about (skype, at commands, pbx functions,
  interface state, locking, etc)?
• then activate debug in Asterisk itself, via CLI
  command or at startup (set debug 100 or with
  the -ddddd startup option)?
• do not forget to allow debug messages in console
  or in the logfiles, edit logger.conf

34
TODO

• Mac OSX
• CSV files import export to directory
• FBUS2 commands on recent cellphones
• AT command compatibility with verious cellphones
• Documentation
• Test, test, test
• How to contribute
• checkout the latest sources from svn trunk
• send patches to the celliax-dev mailing list
• ask for a committing svn account

35
Thank you for your attention!

• for more info www.celliax.org
• Giovanni Maruzzelli
• gmaruzz_at_celliax.org