> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial: Test a real push on the Android emulator

> Run pgw and Asterisk on your computer, install a Linphone build in the Android emulator, and receive a call through a real FCM push.

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.

> [!WARNING]
>
> 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](https://pgw.sipmicro.services/#download). Put it in a new folder, name it `pgw`, and make it executable, as in step 1 of the [quickstart](https://docs.pgw.sipmicro.services/quickstart.md). 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](https://console.firebase.google.com), 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**

```bash theme={null}
git clone https://github.com/BelledonneCommunications/linphone-android.git
```

**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.

```ini theme={null}
[sip]
verify_server_certs=0
verify_server_cn=0

[net]
push_notification_domains=192.168.1.20
```

**5. Build the app**

```bash theme={null}
./gradlew assembleDebug
```

## 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.

```bash theme={null}
adb install -r app/build/outputs/apk/debug/*.apk
```

## 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`:

```dockerfile theme={null}
FROM alpine:edge
RUN apk add --no-cache asterisk
ENTRYPOINT ["asterisk", "-f"]
```

`asterisk/modules.conf`:

```ini theme={null}
[modules]
autoload=yes
```

`asterisk/pjsip.conf`:

```ini theme={null}
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0:5060

[alice]
type=endpoint
context=default
disallow=all
allow=ulaw
auth=alice
aors=alice
rewrite_contact=no

[alice]
type=auth
auth_type=userpass
username=alice
password=alicepw

[alice]
type=aor
max_contacts=2
support_path=yes
remove_existing=no
```

**2. Start Asterisk**

```bash theme={null}
docker build -t pgw-asterisk asterisk
docker run -d --name pgw-asterisk -p 5070:5060/udp -v "$PWD/asterisk:/etc/asterisk:ro" pgw-asterisk
```

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

**3. Check the user**

```bash theme={null}
docker exec pgw-asterisk asterisk -rx "pjsip show endpoints"
```

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`.

```bash theme={null}
export LAN_IP=$(ipconfig getifaddr en0)
openssl rand -base64 32 > master.key
chmod 600 master.key
export PGW_BOOTSTRAP_TOKEN=$(openssl rand -base64 32)
echo "$PGW_BOOTSTRAP_TOKEN" > bootstrap.token
PGW_MASTER_KEY_FILE=master.key PGW_HOSTNAME=$LAN_IP PGW_DATA_DIR=data PGW_LOG_LEVEL=debug ./pgw serve
```

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.

```bash theme={null}
export LAN_IP=$(ipconfig getifaddr en0)
export PGW_BOOTSTRAP_TOKEN=$(cat bootstrap.token)
export PGW_API_KEY="$(./pgw bootstrap --name demo)"
./pgw upstream create --name asterisk --host $LAN_IP --port 5070 --invite-source-cidrs 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
./pgw app create --platform android --bundle-id com.example.linphone --fcm-project-id <project-id> --fcm-project-number <project-number> --fcm-service-account-file sa.json
```

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.

| Field | Value |
| - | - |
| Username | `alice` |
| Password | `alicepw` |
| Domain | Your LAN IP address |
| Transport | TLS |
| Outbound proxy | `sip:<LAN IP address>:5061;transport=tls` |
| Push notifications | On |

**3. Check the registration**

```bash theme={null}
./pgw binding list
```

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**

```bash theme={null}
docker exec pgw-asterisk asterisk -rx "channel originate PJSIP/alice application Wait 30"
```

The emulator rings.

**3. Check the push**

```bash theme={null}
curl -s -H "Authorization: Bearer $PGW_API_KEY" http://127.0.0.1:8080/api/v1/push-events
```

The first event in `items` is the newest. It has the type `call` and the status code `200`.

> [!NOTE]
>
> 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**

```bash theme={null}
docker rm -f pgw-asterisk
docker rmi pgw-asterisk
rm -rf data master.key sa.json bootstrap.token asterisk
```

## If it doesn't work

| Problem | Cause | Solution |
| - | - | - |
| Linphone gets no push token | The emulator has no Google Play services, or no Google account. | Use a Google Play system image, and sign in to a Google account in the emulator. |
| Linphone doesn't register | Linphone rejected pgw's certificate, or can't reach the LAN IP address. | Check the `[sip]` settings in `linphonerc_default`, and rebuild. Check that no firewall blocks port 5061. |
| REGISTER gets `555` | pgw has no app that matches the package name and Firebase project that Linphone sent. | Check that `--bundle-id` is the build's full package name, and that `--fcm-project-number` is the number from the Firebase console. |
| The call doesn't reach pgw | Asterisk can't reach pgw's hostname, or pgw refused the call's source address. | Check that `PGW_HOSTNAME` is the LAN IP address, and read pgw's debug log. |
| No push arrives | FCM refused the push. | Check the `error` field in the push log. Check that the service account belongs to the build's Firebase project. |

## Next steps

> [card] [Configure an Android app](https://docs.pgw.sipmicro.services/apps/android.md)
>
> Repeat the Firebase setup for your own Android app.

> [card] [Install pgw on a server](https://docs.pgw.sipmicro.services/deploy/install.md)
>
> Run pgw with a public certificate, so that builds with certificate checks can connect.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.