# intercom

This repository contains a **template** for creating a home intercom system
using Cisco 7941G phones and Asterisk.

* [Asterisk](https://www.asterisk.org/) is used as the SIP server.
* `tftpd-hpa` is used for serving configuration and firmware for the phones.
* [NGINX](https://nginx.org/) is used for serving the phone directory.

## Prerequisites

* **A basic knowledge of computer networking.**
* At least two Cisco 7941G phones. These are fairly cheap on eBay and often come
  up in office clearance sales.
* A way of powering the phones (PoE is preferred - the mains adapters are often
  more expensive than the phones).
* A machine to run Asterisk, TFTP and NGINX. I use a spare Raspberry Pi 4B,
  which is overpowered for the task. The machine should be running Debian 12.
  Ideally it should be a fresh image, and it definitely should not already run
  NGINX, TFTP or Asterisk.

## Guide

A few steps are required to deploy the system.

### Find the Cisco SIP firmware

See [`roles/tftp/files/firmware/README.md`](roles/tftp/files/firmware/README.md).

### Configure static IP addresses

Both the phones and your server(s) for hosting Asterisk/TFTP/NGINX should have
static IP addresses configured on your router, and you should know them.

This step depends on your router (but I configure it in the interface's DHCP in
OPNsense).

### Set up `hosts.ini`

Add your hosts to the inventory in [`inventories/production/hosts.ini`](inventories/production/hosts.ini).

### Configure variables

You will need to edit the following files, adjusting them for your own configuration:

* [`inventories/production/group_vars/all.yml`](inventories/production/group_vars/all.yml)

### Deploy the configuration to your server(s)

```bash
ansible-playbook -i inventories/production/hosts.ini site.yml
```

## Debugging

### Phone logs

The phones this playbook configures have HTTP web interfaces, which contain
log files ("Console Logs" in the left hand menu).

The "log_n_" files sometimes include useful information, such as:

```
NOT 04:07:19.594520 JVM: Startup Module Loader|cip.cfg.h:? - Config handleTftpResponse, status=0 for file=ram/SEP001234.cnf.xml
ERR 04:07:19.596632 JVM: Startup Module Loader|cip.xml.at:  - XML Parser Exception: Too few 'provisioning' elements in '/device/phoneServices': occurs=0 minOccurs=1 (line=50)
ERR 04:07:19.598909 JVM: Startup Module Loader|cip.cfg.h:? - ERROR PARSING CONFIG file:ram/SEP001234.cnf.xml
NOT 04:07:19.601557 JVM: Startup Module Loader|cip.cfg.h:? - Config processConfigNoError() result code=CONFIG_FILE_BAD_FORMAT
```

### Observing traffic on the Asterisk server

It can be useful to watch network traffic on the Asterisk server using `tcpdump`:

```bash
tcpdump -i any -n port 5060 and udp
```

You might look for information such as "401 Unauthorized" errors, for example:

```
22:21:34.732807 wlan0 In  IP 192.168.1.50.49157 > 192.168.1.49.5060: SIP: INVITE sip:1@192.168.1.49;user=phone SIP/2.0
22:21:34.735313 wlan0 Out IP 192.168.1.49.5060 > 192.168.1.50.5060: SIP: SIP/2.0 401 Unauthorized
```

The error above was due to an old dialplan causing the phone in question to
immediately ring "1" when the "1" button was pressed.