PagingServer

SIP-based Announcement / PA / Paging / Public Address Server system.

Main component of this project is a script to run PJSUA_ SIP client connected to a PulseAudio_ sound server routing audio to whatever sound cards and speaker sets.

It picks up calls, plays klaxon on speakers, followed by the announcement made in that call. Music plays in-between announcements.

Script controls PJSUA and PulseAudio (muting/unmuting streams there) to make them work to that effect.

|

.. contents:: :backlinks: none

Usage

After installation (see below), the script should be configured, providing it with at least the SIP account data for the general usage.

Configuration file (ini format_) locations:

• paging.conf
• /etc/paging.conf
• callpipe.conf
• /etc/callpipe.conf
• Paths specified on the command line.

All files will be looked up and parsed in that order, values in next ones overriding corresponding ones in the previous and defaults.

See output of paging --help for info on how to specify additional configuration, more up-to-date list of default paths, as well as general information for all the other options available.

Provided paging.example.conf_ file has all the available configuration options and their descriptions.

To see default configuration options, use paging --dump-conf-defaults, and run paging --dump-conf ... to see the actual options being picked-up and used at any time.

There are two general (supported) ways to start and run the script:

• In the foreground (non-forking).
• As a systemd service.

Both are described in more detail below.

Start/run in the foreground

First - make sure PulseAudio_ and its ALSA_ backend are configured (and unmuted,
in case of ALSA) as they should be and pulse server can run/runs for same user
that this script will be running as.

How to do that is out of scope for this README.

Then just run the thing as::

  % paging

Can be used directly from terminal, or with any init system or daemon manager,
including systemd, upstart, openrc, runit, daemontools, debian's
"start-stop-daemon", simple bash scripts, etc.

For systemd in particular, see the "Running as a systemd service" section below.

Running from terminal to understand what's going on, these options might be also
useful::

  % paging --debug
  % paging --debug --pjsua-log-level 10
  % paging --dump-conf

See also "Installation" and "Audio configuration" sections below.


Running as a systemd service

This method should be preferred, as it correctly notifies init when service is actually ready (i.e. pjsua inputs/outputs initialized), so that others can be scheduled around that, and primes watchdog timer, detecting if/when app might hang due to some bug.

Provided paging.service file (in the repository, just an ini file) should be installed to /etc/systemd/system, and assumes following things:

• PagingServer app should be run as a "paging" user, which exists on the system (e.g. in /etc/passwd).

• "paging.py" script, its "entry point" or symlink to it is installed at /usr/local/bin/paging.

• Configuration file can be read from one of default paths (see above for a list of these).

• Optional python-systemd_ module dependency is installed.

With all these correct, service can then be used like this:

• Start/stop/restart service::

  % systemctl start paging % systemctl stop paging % systemctl restart paging

• Enable service(s) to start on OS boot::

  systemctl enable paging

• See if service is running, show last log entries: systemctl status paging

• Show all logs for service since last OS boot: journalctl -ab -u paging

• Continously show ("tail") all logs in the system: journalctl -af

• Brutally kill service if it hangs on stop/restart: systemctl kill -s KILL paging (will be done after ~60s by systemd automatically).

See systemctl(1) manpage_ for more info on such commands.

If either app itself is installed to another location (not /usr/local/bin/paging) or extra command-line parameters for it are required, ExecStart= line can be altered either in installed systemd unit file directly, or via systemctl edit paging.

systemctl daemon-reload should be run for any modifications to /etc/systemd/system/paging.service to take effect.

Similarly, User=paging line can be altered or overidden to change system uid to use for the app.

If python-systemd module is unavailable, following lines should be dropped from the paging.service::

Type=notify WatchdogSec=...

And --systemd option removed from ExecStart= line, so that app would be started as a simple non-forking process, which will then be treated correctly by systemd without two options above.

Installation

This is a regular package for Python 2.7 (not 3.X), but with some extra run-time requirements (see below), which can't be installed from PyPI.

Package itself can be installed at any time using pip_, e.g. via pip install PagingServer (this will try to install stuff to /usr!!!).

Unless you know python packaging though, please look at pip2014.com, python packaging tutorial, documentation below for easy installation (from packages/repo) on specific systems.

Requirements

* `Python 2.7`_ (NOT 3.X).

* PJSUA_ (PJSIP User Agent) and its python bindings.

  Can be packaged as "pjsip", "pjsua" or "pjproject" in linux distros.

  Python bindings (from the same tarball) can also be packaged separately as
  "python-pjproject" or something like that.

  If either of those isn't available, be sure to build and install pjsua AND its
  python bindings manually from the same sources, and NOT e.g. install pjsua
  from package and then build bindings separately.

* PulseAudio_

* `pulsectl python module`_

* (optional) ffmpeg_ binary - if audio samples are not wav files (will be
  converted on every startup, if needed).

* (optional) python-systemd_ - only if ``--systemd`` option is used (e.g. with
  shipped .service file).

  Developed and shipped separately from main systemd package since v223
  (2015-07-29), likely comes installed with systemd prior to that.

  Would probably make sense to install that module from OS package, which should
  be available if systemd is used there as init by default.

* (optional) raven_ python module - for reporting any errors via sentry.


Debian Jessie

• Installing everything via debian packages from third-party repository.

  Running this one-liner should be the easiest way by far::

  wget -O- https://raw.githubusercontent.com/AccelerateNetworks/PagingServer/master/setup-scripts/install.debian_jessie.from_debs.sh | bash

  Or, if wget ... | bash sounds too scary, same exact steps as in that script are::

  apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 3D021F1F4C670809

  echo 'deb http://paging-server.ddns.net/ jessie main' >/etc/apt/sources.list.d/paging-server.list

  apt-get update

  apt-get install --no-install-recommends pulseaudio pulseaudio-utils alsa-utils

  apt-get install paging-server python-systemd

  useradd -rm -s /bin/false -G audio paging

  install -o root -g paging -m640 -T /usr/share/doc/paging-server/paging.example.conf /etc/paging.conf

  Configure, set-levels and unmute alsa/pulse, if necessary (depends heavily on the specific setup)::

  alsamixer

  nano /etc/pulse/default.pa

  Then edit config in /etc/paging.conf and start/enable the daemon::

  nano /etc/paging.conf

  systemctl start paging

  systemctl enable paging

  See "Usage" section for more details on how to run the thing.

  Packages here are built with install.debian_jessie.sh_ script described in the next section.

• Building/installing everything on-site with one script.

  It's possible to install all required packages, building missing ones where necessary by running install.debian_jessie.sh_ script from the repository as a root user (as it runs apt-get and such)::

  wget https://raw.githubusercontent.com/AccelerateNetworks/PagingServer/master/setup-scripts/install.debian_jessie.sh

  bash install.debian_jessie.sh -x

  (running without -x flag will issue a warning message and exit)

  It's safe to run the script several times or on a machine where some of the requirements (see the list above) are installed already - should skip steps that are already done or unnecessary.

  Script builds everything into deb packages, stores each in /var/tmp/PagingServer.debs, and installs them.

  Also creates apt-get-installed.list file in the same directory, where every package name it has passed to apt-get (i.e. packages that it has installed via apt-get) is recorded, in case there might be a need to clean these up later.

  After successful installation, enable/run the service as described in "Usage" section.

• Manual installation.

  Follow roughly same steps as what install.debian_jessie.sh_ script does.

Other systems

Just build/install all the requirements above from OS packages or however.



Audio configuration
-------------------

Overview of the software stack related to audio flow:

* PJSUA picks-up the calls, decoding audio streams from SIP connections.

* PJSUA outputs call audio to via PortAudio_.

* PortAudio can use multiple backends on linux systems, including:

  * ALSA_ libs (and straight down to linux kernel)
  * OSS (/dev/dsp*, only supported through emulation layer in modern kernels)
  * JACK sound server
  * PulseAudio_ sound server (through ALSA compatibility layer)

  In this particular implementation, PulseAudio backend is assumed.

* PulseAudio serves as a "hub", receiving streams from music players (mpd_
  instances), klaxon sounds, calls picked-up by PJSUA.

  Depending on PulseAudio and music players' configuration, these outputs can be
  then mixed toge