2_ipbx_asterisk.md

Setting up a VoIP communication between a Raspberry Pi and an IP phone using an Asterisk IP PBX server

Guillaume Nibert
Supervisor: Dr. Ahmed Lounis

Context

1. SIP protocol and VoIP communication

2. Implementation of an Asterisk IP PBX server

In large organisations (companies, public services, etc.), there are mainly two types of telephone communication: internal communication and external communication. The agents therefore have an internal fixed telephone capable of making calls to another internal fixed telephone or an external (public) telephone. For this to work, a PBX, also known as a Private Branch Exchange, is needed.

The PBX (below) has many advantages, including:

• financially, the bill is reduced, as internal calls do not go through the public network (Orange, formerly France Telecom in France);
• more internal numbers can be allocated without difficulty;
• it is possible to offer services such as conference calls, call forwarding, call transfer;
• and, of course, linking an internal line to an external line.

(Figure 5 - PBX Matra MC6500 serie)
Attribution: the original uploader was After310 at French Wikipedia, CC BY-SA 3.0, via Wikimedia Commons

A comprehensive list of the functions of a traditional PBX can be found on Wikipedia (1).

Now that the overall operation of this system has been presented, how can communication using SIP protocol be achieved?

Historically, there have been three main phases in the evolution of telephone communications:

1. The public switched telephone network (PSTN) which is analogue. In this network, the SIP protocol cannot be used because SIP is a digital protocol.
2. The Integrated Services Digital Network (ISDN) is a digital network whose network stack is based on the OSI model. Starting at Layer 3 (transport), the following protocols are used: Q.931 (2), X.25 layer 3 (3). Here it is Layer 3 which is problematic: SIP relies on IP to function.
3. Voice over IP, over the Internet, is digital. SIP can work in this case. The associated PBX is an IP PBX (Internet Protocol private branch exchange).

There are many IP PBXs in the world. Asterisk has the distinction of being the world's number one in terms of usage. It has a free version and a proprietary version. And it offers interoperability with older networks (PSTN and ISDN) by means of hardware cards and software modules. This last point is probably a major factor in its success: companies that still use old equipment, and that, in a perspective of modernisation, migrate to recent equipment, probably use several systems (PSTN, ISDN or VoIP), Asterisk will make it possible to manage these three systems simultaneously.

So let's proceed with the installation of Asterisk.

Technology choices

• OS: Debian 10, it is free and is mainly used as a server in the computer world. It is a system with regularly updated packages in terms of stability and security.
• Asterisk: 18 LTS release compiled from source. The version in the Debian repositories is old (16 for Debian 10) and although it is also an LTS version, the fact that it is already compiled offers less flexibility in terms of adding modules. In addition, the module that handled SIP in the 16 release has been deprecated since the 17 release (4) in favour of a new module (PJSIP) that can handle SIP as well as NAT traversal functions with SIP (5).

Prerequisite

Have an up-to-date Debian 10 machine (without GUI) connected to the local network and to the internet, also with SSH access (see appendix A1 of the PDF report for the detailed implementation of this prerequisite).

Consider in this section the following information from this machine:

IP address	User	Password
192.168.1.80	asterisktz	voiputc
	root	voiputc

Installation of Asterisk

Note: the libraries allowing the management of telephone interface cards from Digium (the company maintaining Asterisk) and the management of protocols used in ISDN networks will not be installed.

1. Connect via SSH to the asterisk machine.

# ssh login@vm_ip_address -p 22
ssh asterisktz@192.168.1.80 -p 22

2. Install the packages allowing the compilation of Asterisk and the prerequisites.

sudo apt update && sudo apt install linux-headers-$(uname -r) build-essential autoconf libglib2.0-dev libtool net-tools

3. Reboot the Debian machine and connect again via SSH.

sudo reboot

# SSH reconnection
ssh asterisktz@192.168.1.80 -p 22

4. Go to the directory /usr/src and download Asterisk 18 at this address: https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-18-current.tar.gz.

cd /usr/src
sudo wget https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-18-current.tar.gz

5. Decompress the archive.

sudo tar -zxvf asterisk-18-current.tar.gz

6. Run the install_prereq script installing the prerequisites. Note: To find out the minor version number, type ls. In this report, it is Asterisk 18.2.

cd asterisk-18.2.0/contrib/scripts/
sudo ./install_prereq install

During the installation of the prerequisites a window appears asking to select the telephone number code. Select 33 for France and validate with <Ok>. You can find an international list of area codes on this site: https://countrycode.org/.

(Figure 6 - Area code setting)

7. Checking the required dependencies.

cd ../..
sudo ./configure

If the operation is successful, you will get a message similar to this one with the Asterisk logo:

                .$$$$$$$$$$$$$$$=..      
              .$7$7..        .7$$7:.    
            .$7$7..           .7$$7:.
          .$$:.                 ,$7.7
        .$7.     7$$$$           .$$77
     ..$$.       $$$$$            .$$$7
    ..7$   .?.   $$$$$   .?.       7$$$.
   $.$.   .$$$7. $$$$7 .7$$$.      .$$$.
 .777.   .$$$$$$77$$$77$$$$$7.      $$$,
 $$$~      .7$$$$$$$$$$$$$7.       .$$$.
.$$7          .7$$$$$$$7:          ?$$$.
$$$          ?7$$$$$$$$$$I        .$$$7
$$$       .7$$$$$$$$$$$$$$$$      :$$$.
$$$       $$$$$$7$$$$$$$$$$$$    .$$$.
$$$        $$$   7$$$7  .$$$    .$$$.
$$$$             $$$$7         .$$$.
7$$$7            7$$$$        7$$$
 $$$$$                        $$$
  $$$$7.                       $$  (TM)
   $$$$$$$.           .7$$$$$$  $$
     $$$$$$$$$$$$7$$$$$$$$$.$$$$$$
       $$$$$$$$$$$$$$$$.

configure: Package configured for:
configure: OS type : linux-gnu
configure: Host CPU : x86_64
configure: build-cpu:vendor:os: x86_64 : pc : linux-gnu :
configure: host-cpu:vendor:os: x86_64 : pc : linux-gnu :

If it went wrong, here is a link to the documentation:
https://wiki.asterisk.org/wiki/display/AST/Checking+Asterisk+Requirements.

8. Selecting the options to be installed for Asterisk. Ensure that the terminal is at least 80x27 in size.

sudo make menuselect

A window appears allowing you to choose the options.

Go to the Core Sound Package section to install the French sounds (or another language if you prefer):

• Deselect the CORE-SOUNDS-EN-GSM. These are the English sounds with the GSM audio codec.
• Select the CORE-SOUNDS-FR-ULAW and CORE-SOUNDS-FR-ALAWpackages.These are the French sounds with ULAW and ALAW codecs (supported by the Alcatel IP Touch 4018EE (6)). These codecs are defined by the ITU G.711 standard: https://www.itu.int/rec/T-REC-G.711-198811-I/en. The ALAW codec is used in Europe and Africa. The ULAW codec in North America and Japan (7).

(Figure 7 - Selection of Asterisk sound modules)

Then in the Extra Sound Packages section, select the EXTRA-SOUNDS-FR-ULAW and EXTRA-SOUNDS-FR-ALAW packages.

(Figure 8 - Selection of Asterisk extra sound modules)

Confirm by pressing the F12 key.

9. Compile the program with the previously chosen options and install Asterisk.

sudo make

The compilation takes time depending on the power of the machine. Once successful...

+--------- Asterisk Build Complete ---------+
+ Asterisk has successfully been built, and +
+ can be installed by running:              +
+                                           +
+                make install               +
+-------------------------------------------+
+--------- Asterisk Build Complete ---------+

...the installation of Asterisk can begin.

sudo make install

The installation ends with this message:

 +---- Asterisk Installation Complete -------+
 +                                           +
 +    YOU MUST READ THE SECURITY DOCUMENT    +
 +                                           +
 + Asterisk has successfully been installed. +
 + If you would like to install the sample   +
 + configuration files (overwriting any      +
 + existing config files), run:              +
 +                                           +
 + For generic reference documentation:      +
 +    make samples                           +
 +                                           +
 + For a sample basic PBX:                   +
 +    make basic-pbx                         +
 +                                           +
 +                                           +
 +-----------------  or ---------------------+
 +                                           +
 + You can go ahead and install the asterisk +
 + program documentation now or later run:   +
 +                                           +
 +               make progdocs               +
 +                                           +
 + **Note** This requires that you have      +
 + doxygen installed on your local system    +
 +-------------------------------------------+

10. Create the sample configuration files in the /etc/asterisk folder.

sudo make samples

11. Install the start-up scripts.

sudo make config
sudo ldconfig

12. Setting up the automatic start of the Asterisk service when the machine is launched.

cd
sudo groupadd asterisk
sudo useradd -r -d /var/lib/asterisk -g asterisk asterisk
sudo usermod -aG audio,dialout asterisk
sudo chown -R asterisk.asterisk /etc/asterisk
sudo chown -R asterisk.asterisk /var/{lib,log,spool}/asterisk
sudo chown -R asterisk.asterisk /usr/lib/asterisk

sudo nano /etc/default/asterisk

Uncomment the lines AST_USER="asterisk" and AST_GROUP="asterisk" (remove the # before each line). Save with Ctrl + O. Exit with Ctrl + X.

(Figure 9 - Setting asterisk as the default user of the Asterisk service)

sudo nano /etc/asterisk/asterisk.conf

Uncomment the lines (remove the semicolon ; before each line). Save with Ctrl + O. Exit with Ctrl + X.

runuser = asterisk ; The user to run as.
rungroup = asterisk ; The group to run as.

(Figure 10 - Setting asterisk as the default user of the Asterisk service)

13. Start the Asterisk service

sudo systemctl start asterisk

You can now check its current status with the following command:

sudo systemctl status asterisk

(Figure 11 - Launch of the Asterisk service with errors)

At this stage, if there are these two red lines, they can be corrected in this way (fix from https://www.clearhat.org/blog/post/a-fix-for-apt-install-asterisk-on-ubuntu-18-04):

sudo systemctl stop asterisk

sudo sed -i 's";\[radius\]"\[radius\]"g' /etc/asterisk/cdr.conf

sudo sed -i 's";radiuscfg => /usr/local/etc/radiusclient-ng/radiusclient.conf"radiuscfg => /etc/radcli/radiusclient.conf"g' /etc/asterisk/cdr.conf

sudo sed -i 's";radiuscfg => /usr/local/etc/radiusclient-ng/radiusclient.conf"radiuscfg => /etc/radcli/radiusclient.conf"g' /etc/asterisk/cel.conf

sudo systemctl start asterisk

(Figure 12 - Launch of the Asterisk service without errors)

14. Automatic start of the Asterisk service.

sudo /lib/systemd/systemd-sysv-install enable asterisk

Asterisk is operational. Let's move on to user creation and SIP configuration!

SIP configuration and user creation

So we have an operational server, we must now configure SIP and create users. We will create 3 users with the following characteristics:

	Alcatel phone	Raspberry Pi	Test
Purpose	Dedicated account for the Alcatel IP Touch 4018 EE phone	Dedicated account for the Raspberry Pi	Dedicated account for testing
Display name	Alcatel IP Touch	Raspberry Pi	Guillaume Nibert
Phone number	5001	5002	5003
Login	alcaltel	rpi	guillaume
Password	11111111	22222222	33333333

There are two configuration files to edit:pjsip.conf and extensions.conf. The first one is used to create accounts, configure the operation of SIP (UDP/TCP), the authentication systems... and the second to define the behaviour of the system, more precisely the dialling plan (similar to routing if we were talking about IP packets). This "routing" is done according to telephone numbers (identifiers). These files are present in /etc/asterisk and in the asterisk_sip directory of the Git repository.

SIP configuration - pjsip.conf

1. Rename the pjsip.conf configuration file to pjsip_original.conf.

sudo mv /etc/asterisk/pjsip.conf /etc/asterisk/pjsip_original.conf

2. Create a pjsip.conf file...

sudo nano /etc/asterisk/pjsip.conf

...and write the following content:

conf
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0
 
; Basic templates, they will be copied for each user
 
[endpoint_basic](!)
type=endpoint         ; endpoint (phone/rpi/pc...)
context=plan-num      ; uses the dial plan defined in extensions.conf
disallow=all          ; disabling all audio codecs
allow=ulaw            ; except the ULAW codec
allow=alaw            ; and the ALAW codec
language=fr
 
[authentication](!)
type=auth             ; type of section: authentication
auth_type=userpass    ; password authentication
 
[aor_template](!)
type=aor              ; find out where the endpoint can be contacted 
max_contacts=1
 
; Definitions of user accounts associated with equipment
 
[alcatel](endpoint_basic)
auth=alcatel
aors=alcatel
callerid="Alcaltel IP Touch" <5001> ; to have the name of the caller displayed
[alcatel](authentication)
password=11111111
username=alcatel
[alcatel](aor_template)
 
[rpi](endpoint_basic)
auth=rpi
aors=rpi
callerid="Raspberry Pi" <5002>
[rpi](authentication)
password=22222222
username=rpi
[rpi](aor_template)
 
[guillaume](endpoint_basic)
auth=guillaume
aors=guillaume
callerid="Guillaume Nibert" <5003>
[guillaume](authentication)
password=33333333
username=guillaume
[guillaume](aor_template)

The creation of the accounts and the configuration of SIP is complete. Let's move on to the dial plan.

Dial plan - extensions.conf

1. Rename the extensions.conf configuration file to extensions_original.conf.

sudo mv /etc/asterisk/extensions.conf /etc/asterisk/extensions_original.conf

2. Create an extensions.conf file...

sudo nano /etc/asterisk/extensions.conf

...and write the following content:

conf
[plan-num]
exten => 5001,1,Answer(500)
exten => 5001,2,Dial(PJSIP/alcatel,25)
exten => 5001,3,Hangup()
 
exten => 5002,1,Answer(500)
exten => 5002,2,Dial(PJSIP/rpi,25)
exten => 5002,3,Hangup()
 
exten => 5003,1,Answer(500)
exten => 5003,2,Dial(PJSIP/guillaume,25)
exten => 5003,3,Hangup()
 
; 1, 2 and 3 correspond to the priorities of the Answer(),
; Dial() and Hangup() application calls. 1 being the highest priority.
; We can also write 1,n,n where the first n corresponds to 2 and the second
; to 3.

"The Answer() application takes a delay (in milliseconds) as its first parameter. Adding a short delay is often useful to ensure that the endpoint has time to start processing the audio before starting the communication via the Dial() application. Otherwise, you may not hear the very beginning" (8). Hangup() as the name suggests hangs up the current call.

The dial plan is complete. The SIP accounts have been created. We can now proceed to the configuration of a SIP client on the Raspberry Pi.

3. Installation and configuration of a SIP client on the Raspberry Pi

4. IP phone configuration

5. Communication tests

6. JavaScript SIP client using WebRTC

Conclusion

Abbreviations

References on this page

(1): Wikipedia, Business telephone system, 21^st january 2022, available at: https://en.wikipedia.org/wiki/Business_telephone_system.

(2): ITU Telecommunication Standardization Sector, ISDN user-network interface layer 3 specification for basic call control, ITU, May 1998, available at: https://www.itu.int/rec/T-REC-Q.931-199805-I/en.

(3): ITU Telecommunication Standardization Sector, Interface between Data Terminal Equipment (DTE) and Data Circuit-terminating Equipment (DCE) for terminals operating in the packet mode and connected to public data networks by dedicated circuit, ITU, October 1996, available at: https://www.itu.int/rec/T-REC-X.25-199610-I/en.

(4): Matt Fredrickson, PSA: chan_sip status changed to “deprecated” & Asterisk 17.0.0-rc2 Release, Asterisk.org, 25^th september 2019, available at: https://www.asterisk.org/deprecating-chan_sip-asterisk-17-0-0-rc2-release/.

(5): Y. Yeryomin, F. Evers and J. Seitz, II. The NAT and firewall problem In: Solving the firewall and NAT traversal issues for SIP-based VoIP, International Conference on Telecommunications, p.1-2, July 2008, DOI: 10.1109/ICTEL.2008.4652645, available at: https://www.researchgate.net/publication/224341038_Solving_the_firewall_and_NAT_traversal_issues_for_SIP-based_VoIP.

(6): Alcatel-Lucent, Audio characteristics In: Alcatel-Lucent IP Touch 4008/4018 Extended Edition Phones, p.2, 2013, available at: https://assets.bmdstatic.com/assets/Data/brochure/SKU01413265_2.pdf.

(7): Wikipedia, G.711, 20^th august 2021, available at: https://en.wikipedia.org/wiki/G.711.

(8): Malcolm Davenport, Answer, Playback, and Hangup Applications In: Asterisk Documentation, Asterisk.org, 19^th december 2013, available at: https://wiki.asterisk.org/wiki/display/AST/Answer%2C+Playback%2C+and+Hangup+Applications.