Skip to main content
At the end of this tutorial, an Android emulator on your computer rings for a call while the app is closed, woken by a real push from Google. You need no phone and no paid account, because Firebase Cloud Messaging is free and the emulator receives its pushes. Asterisk, pgw, and the open-source Linphone app all run on one computer and talk over its LAN address. pgw serves a self-signed certificate, so you build Linphone with certificate checks turned off.
Never turn off certificate checks in a build that you distribute.

Before you begin

Install these tools:
  • Android Studio and JDK 17.
  • Docker.
  • openssl.
  • The pgw binary for your computer, from the download page. Put it in a new folder, name it pgw, and make it executable, as in step 1 of the quickstart. Run every pgw and Docker command of this tutorial in that folder.
  • A Google account for the Firebase console.

Step 1: Create a Firebase project

Google delivers pushes only for apps that belong to a Firebase project. The project gives you google-services.json, which goes into the app so that it can receive pushes, and a service account key, which goes to pgw so that it can send them.
1

Create the project

In the Firebase console, create a project. It needs no billing account and no Google Analytics.
2

Add an Android app

Add an Android app with your package name, such as com.example.linphone, and download google-services.json.
3

Note the project ID and number

In Project settings, on the General tab, note the project ID and the project number.
4

Create a service account key

On the Service accounts tab, choose Generate new private key. Save the file as sa.json in the folder that holds the pgw binary.

Step 2: Build Linphone

The Linphone app in Google Play belongs to its publisher’s Firebase project, so pgw can’t push to it. So you build your own copy, which belongs to your Firebase project.
1

Clone Linphone for Android

2

Set the package name

In app/build.gradle.kts, set applicationId to your package name. If the debug build adds an applicationIdSuffix, remove the suffix, or register the full name as a second Android app in Firebase.
3

Add the Firebase file

Copy google-services.json to app/.
4

Change the default settings

In app/src/main/assets/linphonerc_default, add these settings. Replace 192.168.1.20 with your computer’s LAN IP address. If push_notification_domains already exists, add your address to its list.
5

Build the app

Step 3: Start the emulator

1

Create a device

In Android Studio, open Device Manager, and create a device with a system image labeled Google Play. Images without Google Play services don’t receive FCM pushes.
2

Install the app

Start the emulator, and install the app.

Step 4: Start Asterisk

Asterisk runs in a container, with one user, alice, whose password is alicepw.
1

Create the configuration

In the folder that holds the pgw binary, create a folder named asterisk with these three files.asterisk/Dockerfile:
asterisk/modules.conf:
asterisk/pjsip.conf:
2

Start Asterisk

Asterisk logs errors about configuration files that this setup doesn’t have. They don’t affect the tutorial.
3

Check the user

The list shows the endpoint alice.

Step 5: Start and configure pgw

pgw needs an upstream, which tells it where the PBX is, and an app record, which tells it how to push to your Linphone build.
1

Start pgw

Start pgw with your LAN IP address as its hostname. On macOS, ipconfig getifaddr en0 prints the address. If it prints nothing, try en1.
pgw logs pgw ready when its listeners are open.
2

Create the tenant, upstream, and app

Run these commands in a second terminal, in the same folder. Set --bundle-id to the full package name of your build, and replace <project-id> and <project-number> with the values from the Firebase console.
The upstream accepts calls from all private ranges, because the source address of Asterisk’s calls depends on Docker’s network. Use these ranges only on your own computer.

Step 6: Add the SIP account in Linphone

1

Open Linphone

Open Linphone in the emulator, and allow notifications.
2

Add the account

Add a third-party SIP account.
3

Check the registration

The list shows one binding for alice.

Step 7: Call the app

With the app closed, the only way that the call can reach it is a push, so this call tests the push.
1

Close Linphone

Swipe Linphone away from Recents. Don’t use Force stop, because a force-stopped app receives no pushes.
2

Call alice from Asterisk

The emulator rings.
3

Check the push

The first event in items is the newest. It has the type call and the status code 200.
The call can connect with no audio, because Asterisk sends media from the container’s internal address, which the emulator can’t reach. This tutorial tests the push, not the audio.

Clean up

1

Stop pgw

Press Ctrl+C in pgw’s terminal.
2

Remove what the tutorial created

If it doesn’t work

Next steps

Configure an Android app

Repeat the Firebase setup for your own Android app.

Install pgw on a server

Run pgw with a public certificate, so that builds with certificate checks can connect.