### FreePBX Audio Codecs Configuration

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/guides/freepbx

Defines the order of audio codecs to be used in FreePBX. The specified order is important for compatibility and performance with SIP-HASS.

```text
ulaw
alaw
speex
gsm
g726
g723
```

--------------------------------

### Install Packages with npm

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/docs

Installs necessary packages for the Docusaurus build. This command should be run in the project's root directory after cloning the repository.

```bash
npm install  
```

--------------------------------

### FreePBX Advanced Settings for Websocket

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/guides/freepbx

These are the required advanced settings in FreePBX for enabling websocket communication. Ensure these parameters match the configuration for successful integration.

```text
Enable Static Content: No
Enable the mini-HTTP Server: Yes
Enable TLS for the mini-HTTP Server: Yes
HTTP Bind Port: 8088
HTTPS Bind Port: 8089
HTTPS TLS Certificate Location: /etc/asterisk/keys/intergration/certificate.pem
HTTPS TLS Private Key Location: /etc/asterisk/keys/intergration/webserver.key

SIP DTMF Signaling: auto
SIP encryption: yes
```

--------------------------------

### FreePBX chan_sip Extension Configuration with DTLS

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/guides/freepbx

Detailed options for creating a chan_sip extension in FreePBX, including settings for DTMF signaling, NAT, encryption, and crucial DTLS configurations.

```text
DTMF Signaling: Auto
Trust RPID: Yes
Send RPID: Send P-Asserted_Identity Header
Connection Type: friend
Session Timers: Accept
NAT Mode: Yes - (force_rport,comedia)
Qualify: yes
Transport: All - WSS Primary
Enable AVPF: Yes
Force AVP: Yes
Enable ICE Support: Yes
Enable rtcp Mux: Yes
Enable Encryption: Yes (SRTP only)

Enable DTLS: Yes
Use Certificate: default
DTLS Verify: Fingerprint
DTLS Setup: Act/Pass
DTLS Rekey Interval: 0
```

--------------------------------

### FreePBX chan_sip Settings for TLS

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/guides/freepbx

Configuration for the legacy chan_sip module in FreePBX, specifically focusing on enabling TLS and related security settings for secure communication.

```text
enable TLS: yes
certificate Manager: default
SSL Method: tlsv1
Don't Verify Server: No

Non-Standard g726: No
Reinvite Behavior: No

Bind Port: 5160
TLS Bind Port: 5161
Enable SRV Lookup: No
Enable TCP: No
Call Events: No
```

--------------------------------

### Asterisk Integration Configuration Example

Source: https://tech7fox.github.io/sip-hass-docs/docs/integration/settings

This configuration example shows the required parameters for setting up the Asterisk integration. It includes the host, port, username, and password needed to connect to the Asterisk AMI.

```yaml
host: localhost
port: 5038
username: admin
password: my-password

```

--------------------------------

### Full SIP Core Configuration Example (JSON)

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/settings

A comprehensive example of the SIP Core configuration file in JSON format. This includes settings for ICE configuration, ringtone URLs, backup and user details, video options, auto-answer, and detailed popup configurations with custom buttons and extension mappings.

```json
{
    "ice_config": {
        "iceGatheringTimeout": 1000,
        "iceCandidatePoolSize": 0,
        "iceTransportPolicy": "all",
        "iceServers": [
            {
                "urls": ["stun:stun.l.google.com:19302"]
            }
        ],
        "rtcpMuxPolicy": "require"
    },
    "outgoingRingtoneUrl": "/local/ring-tones/ring-tone.mp3",
    "incomingRingtoneUrl": "/local/ring-tones/calling-tone.mp3",
    "backup_user": {
        "ha_username": "tech7fox",
        "extension": "100",
        "password": "w8woord"
    },
    "users": [
        {
            "ha_username": "Jordy",
            "extension": "101",
            "password": "w8woord"
        },
        {
            "ha_username": "alice",
            "extension": "102",
            "password": "w8woord"
        }
    ],
    "sip_video": false,
    "auto_answer": false,
    "popup_config": {
        "auto_open": true,
        "large": false,
        "buttons": [
            {
                "label": "Open Door",
                "icon": "mdi:door-open",
                "type": "dtmf",
                "data": "1"
            },
            {
                "label": "Switch lights",
                "icon": "mdi:lightbulb",
                "type": "service_call",
                "data": {
                    "domain": "light",
                    "service": "toggle",
                    "entity_id": "light.bedroom_lights"
                }
            }
        ],
        "extensions": {
            "101": {
                "name": "Bob"
            },
            "8001": {
                "name": "Doorbell",
                "camera_entity": "camera.doorbell"
            }
        }
    }
}
```

--------------------------------

### Start Docusaurus Development Server

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/docs

Starts the Docusaurus development server, which automatically reloads the page on file save. This command is used for local testing and development of the documentation website.

```bash
npm start  
```

--------------------------------

### SIP-HASS Integration Configuration Example

Source: https://tech7fox.github.io/sip-hass-docs/docs/tutorial/integration

This snippet shows the configuration parameters required to set up the SIP-HASS integration with an Asterisk server. It includes host, port, username, and password.

```yaml
host: localhost
port: 5038
username: admin
password: my-password # The password you set in the add-on configuration

```

--------------------------------

### Create SIP Example Popup (JavaScript)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/guides/popup

This code defines a LitElement component for a standalone SIP Core popup. It handles SIP Core events like call start, end, and updates to display call duration, remote name, and extension. The component includes styling for the dialog and its elements. Dependencies include LitElement and Home Assistant's custom element tags.

```javascript
import {
    LitElement,
    html,
    css,
} from "https://cdn.jsdelivr.net/npm/lit-element@4.2.0/+esm";


class SIPExampleDialog extends LitElement {
    sipCore;
    open = false;
    hass = sipCore.hass;
    config = sipCore.config.popup_config;

    constructor() {
        super();
        this.setupButton();

        // bind openPopup and closePopup to this instance
        this.openPopup = this.openPopup.bind(this);
        this.closePopup = this.closePopup.bind(this);
    }

    static get styles() {
        return css`
        ha-icon[slot="meta"] {
            width: 18px;
            height: 18px;
        }

        ha-icon {
            display: flex;
            align-items: center;
            justify-content: center;
        }

        ha-dialog {
            --dialog-content-padding: 0;
            --mdc-dialog-min-width: 600px;
        }

        @media (max-width: 600px), (max-height: 600px) {
            ha-dialog {
                --dialog-surface-margin-top: 0px;
                --mdc-dialog-min-width: calc( 100vw - env(safe-area-inset-right) - env(safe-area-inset-left) );
                --mdc-dialog-max-width: calc( 100vw - env(safe-area-inset-right) - env(safe-area-inset-left) );
                --mdc-dialog-min-height: 100%;
                --mdc-dialog-max-height: 100%;
                --vertical-align-dialog: flex-end;
                --ha-dialog-border-radius: 0;
            }
        }

        .accept-button {
            color: var(--label-badge-green);
        }

        .deny-button {
            color: var(--label-badge-red);
        }

        .deny-button, .accept-button, .audio-button {
            --mdc-icon-button-size: 64px;
            --mdc-icon-size: 32px;
        }

        .row {
            display: flex;
            flex-direction: row;
            justify-content: space-between;
        }

        .bottom-row {
            display: flex;
            justify-content: space-between;
            padding: 12px 16px;
            border-top: 1px solid var(--divider-color);
        }

        .content {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 300px;
            width: 100%;
        }

        .form {
            display: flex;
            flex-direction: column;
            padding: 16px;
        }

        ha-select {
            margin: 8px 0;
        }
        `;
    }

    updateHandler = (event) => {
        if (!this.sipCore) {
            this.sipCore = window.sipCore;
        }
        this.requestUpdate();
    }

    connectedCallback() {
        super.connectedCallback();
        window.addEventListener('sipcore-update', this.updateHandler);
        window.addEventListener('sipcore-call-started', this.openPopup);
        window.addEventListener('sipcore-call-ended', this.closePopup);
    }

    disconnectedCallback() {
        super.disconnectedCallback();
        window.removeEventListener('sipcore-update', this.updateHandler);
        window.removeEventListener('sipcore-call-started', this.openPopup);
        window.removeEventListener('sipcore-call-ended', this.closePopup);
    }

    openPopup() {
        this.open = true;
        this.requestUpdate();
    }

    closePopup() {
        this.open = false;
        this.requestUpdate();
    }

    render() {
        if (!this.sipCore) {
            return html`<div>Loading...</div>`;
        }

        return html`
        <ha-dialog ?open=${this.open} @closed=${this.closePopup} hideActions flexContent .heading=${true} data-domain="camera">
        <ha-dialog-header slot="heading">
        <ha-icon-button
        dialogAction="cancel"
        slot="navigationIcon"
        label="Close">
        <ha-icon .icon=${"mdi:close"}></ha-icon>
        </ha-icon-button>
        <div slot="title" class="row">
        <span>Custom call dialog</span>
        <span style="color: gray;">${this.sipCore.callDuration}</span>
        </div>
        </ha-dialog-header>
        <div tabindex="-1" dialogInitialFocus>
        <div class="content">
        ${this.sipCore.callState}
        <br>
        ${this.sipCore.remoteName}
        <br>
        ${this.sipCore.remoteExtension}
        <br>
        ${this.config.test_value}
        </div>
        <div class="bottom-row">

```

--------------------------------

### Create Standalone SIP-HASS Card (JavaScript)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/guides/standalone

This JavaScript code defines a LitElement-based custom card for Home Assistant. It interacts with the SIP Core instance to display call status and control calls (answer, end, start). Ensure sip-hass-card is installed and running.

```javascript
import { LitElement, html, css } from "https://cdn.jsdelivr.net/npm/lit-element@4.2.0/+esm";  
  
  
class ExampleCard extends LitElement {  
    sipCore;  

    static styles = css`  
        ha-card {  
            padding: 16px;  
            font-family: Arial, sans-serif;  
        }  

        .status {  
            margin-bottom: 16px;  
        }  

        .buttons {  
            display: flex;  
            gap: 8px;  
        }  

        button {  
            padding: 8px 16px;  
            font-size: 14px;  
            cursor: pointer;  
        }  
    `;  

    connectedCallback() {  
        super.connectedCallback();  
        window.addEventListener("sipcore-update", this.updateHandler);  
    }  

    disconnectedCallback() {  
        super.disconnectedCallback();  
        window.removeEventListener("sipcore-update", this.updateHandler);  
    }  

    updateHandler = () => {  
        if (!this.sipCore) {  
            this.sipCore = window.sipCore;  
        }  
        this.requestUpdate();  
    };

    setConfig(config) {  
        // Validate the config here  
    }  

    render() {  
        if (!this.sipCore) {  
            return html`<div>Loading...</div>`;  
        }  

        return html`  
            <ha-card>  
                <div class="status">  
                    <strong>Call State:</strong> ${this.sipCore.callState}<br />  
                    <strong>Call Duration:</strong> ${this.sipCore.callDuration}<br />  
                    <strong>Remote Name:</strong> ${this.sipCore.remoteName || "N/A"}<br />  
                </div>  
                <div class="buttons">  
                    <button @click=${() => this.sipCore.answerCall()}>Answer Call</button>  
                    <button @click=${() => this.sipCore.endCall()}>End Call</button>  
                    <button @click=${() => this.sipCore.startCall("8001")}>Call Extension 8001</button>  
                </div>  
            </ha-card>  
        `;  
    }  
}

customElements.define("sip-example-card", ExampleCard);
window.customCards = window.customCards || [];
window.customCards.push({
    type: "sip-example-card",
    name: "SIP Example Card",
    preview: true,
    description: "SIP Example Card",
});

```

--------------------------------

### Example URL for Auto Call

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/auto_call

This example demonstrates how to use the 'call' parameter in the URL to trigger an automatic call to a specified extension when the SIP-HASS card loads.

```text
https://my-ha.duckdns.org/phone-lovelace?call=555
```

--------------------------------

### SIP User Configuration Example

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/settings

An example configuration snippet for defining a SIP user in Home Assistant. It specifies the user's display name, SIP extension, Home Assistant username, and password. This configuration is part of a larger YAML structure.

```yaml
},
"users": [
    {
        "ha_username": "Jordy",
        "extension": "101",
```

--------------------------------

### Copy Configuration File (Bash)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/add-on/docker

Copies the example JSON configuration file to a new file named 'config.json'. This allows users to set their own values for the add-on's configuration without modifying the original example file. No external dependencies are required beyond standard shell commands.

```bash
cp asterisk/config.json.example asterisk/config.json
```

--------------------------------

### Home Assistant Dashboard Card Configuration (YAML)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/guides/standalone

This is a YAML configuration snippet for adding the custom 'sip-example-card' to a Home Assistant dashboard. It specifies the card type to be used.

```yaml
type: "custom:sip-example-card"

```

--------------------------------

### SIP-HASS Call Card Configuration Example

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/cards-popups/call-card

This YAML configuration demonstrates how to set up the SIP-HASS custom card in Home Assistant. It includes examples of defining extensions with optional camera entities and custom buttons for service calls or DTMF input. Ensure your Home Assistant is configured with SIP Core and relevant entities.

```yaml
type: custom:sip-call-card
extensions:
  "101":
    name: Jordy
  "102":
    name: Desk Phone
    override_icon: mdi:deskphone
  "8001":
    name: Doorbell
    camera_entity: camera.doorbell
buttons:
  - label: Open Door
    icon: mdi:door-open
    type: service_call
    data:
      domain: light
      service: toggle
      entity_id: light.bedroom_lights
  - label: DTMF 1
    icon: mdi:1
    type: dtmf
    data:
      dtmf: "1"

```

--------------------------------

### SIP-HASS Contacts Card Configuration Example

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/cards-popups/contacts-card

This YAML configuration demonstrates how to set up the SIP-HASS Contacts Card. It includes mapping extensions, specifying names, icons, status entities, and enabling edit functionality. This card requires Home Assistant and the SIP-HASS integration.

```yaml
type: custom:sip-contacts-card
extensions:
  "102":
    name: Jordy
    status_entity: binary_sensor.100_registered
    override_icon: mdi:account
  "103":
    name: Desk phone
    override_icon: mdi:deskphone
  "8001":
    name: Doorbell
    override_icon: mdi:doorbell-video
  "0612345678":
    name: Test
    override_icon: mdi:dialpad
    edit: true
debug: false
hide_me: false
state_color: true

```

--------------------------------

### Asterisk .conf Codeblock Styling

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/docs

Example of styling Asterisk configuration files (.conf) within markdown using the 'editorconfig' language identifier for syntax highlighting. This helps differentiate configuration code from regular text.

```markdown
``editorconfig title="pjsip_custom.conf"  
[context] ; comment  
key=value  
``  

```

--------------------------------

### Asterisk Dialplan for Text-to-Speech

Source: https://tech7fox.github.io/sip-hass-docs/docs/integration/guides/text-to-speech

Defines an Asterisk dialplan extension named 'speech' with an extension '123' that answers an incoming call and executes the googletts.agi script. This script will convert provided text to speech. It requires Googletts to be installed.

```asterisk
[speech]                                              ; The context  
exten => 123,1,Answer()                               ; Answer the call  
exten => 123,n,agi(googletts.agi,"${TEXT}","${LANG}") ; Execute the googletts agi script with the TEXT and LANG variables  

```

--------------------------------

### Home Assistant Automation for Static Route on Startup

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/vpn

An automation for Home Assistant that triggers on startup to execute the `add_vpn_rtp_route` shell command. This ensures that the necessary static route for VPN RTP traffic is established every time Home Assistant restarts, maintaining VoIP call functionality.

```yaml
alias: Add static routes on Home Assistant startup
description: "Add the necessary static route for VOIP calls to work over VPN after a HA restart"
triggers:
  - event: start
    trigger: homeassistant
conditions: []
actions:
  - action: shell_command.add_vpn_rtp_route
    data: {}
mode: single

```

--------------------------------

### Define SIP Example Dialog Custom Element

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/guides/popup

Defines a custom HTML element 'custom-call-dialog' for handling SIP calls within Home Assistant. It includes methods for answering, ending calls, and setting up UI elements like icon buttons. This element extends a base class and interacts with a 'sipCore' object.

```javascript
class SIPExampleDialog extends LitElement {
    static get properties() {
        return {
            open: {
                type: Boolean,
                observer: (nv, ov) => {
                    console.log("open changed from", ov, "to", nv);
                }
            },
            sipCore: {},
            config: {}
        };
    }

    render() {
        return html`
            <ha-dialog trap-focus @closed=${this.closePopup} .open=${this.open} heading="SIP Call">
            <ha-icon-button  
            class="accept-button"  
            label="Answer call"  
            @click=${() => this.sipCore.answerCall()}>
            <ha-icon .icon=${"mdi:phone"}></ha-icon>
            </ha-icon-button>  
            <ha-icon-button  
            class="deny-button"  
            label="End call"  
            @click=${() => {
                this.sipCore.endCall();
                this.closePopup();
            }}>
            <ha-icon .icon=${"mdi:phone-off"}></ha-icon>
            </ha-icon-button>  
            </div>
            </div>
            </ha-dialog>
        `;
    }

    setupButton() {
        const homeAssistant = document.getElementsByTagName("home-assistant")[0];
        const panel = homeAssistant?.shadowRoot?.querySelector("home-assistant-main")
        ?.shadowRoot?.querySelector("ha-panel-lovelace");

        if (panel === null) {
            console.debug("panel not found!");
            return;
        }

        const actionItems = panel?.shadowRoot?.querySelector("hui-root")?.shadowRoot?.querySelector(".action-items");

        if (actionItems?.querySelector("#sipcore-call-button")) {
            return;
        }

        const callButton = document.createElement("ha-icon-button");
        callButton.label = "Open Call Popup";
        const icon = document.createElement("ha-icon");
        icon.style = "display: flex; align-items: center; justify-content: center;";
        icon.icon = "mdi:phone";
        callButton.slot = "actionItems";
        callButton.id = "sipcore-call-button";
        callButton.appendChild(icon);
        callButton.addEventListener("click", () => {
            this.open = true;
            this.requestUpdate();
        });
        actionItems?.appendChild(callButton);

        window.addEventListener("location-changed", () => {
            console.debug("View changed, setting up button again...");
            this.setupButton();
        })
    }

    closePopup() {
        this.open = false;
    }
}

customElements.define("custom-call-dialog", SIPExampleDialog);

```

--------------------------------

### Run Docker Container (Bash)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/add-on/docker

Runs the Docker container for the 'asterisk' service using Docker Compose. This command starts the service defined in 'docker-compose.yml' after it has been built. It requires Docker and Docker Compose to be installed. The container will run in the foreground by default.

```bash
docker-compose up asterisk
```

--------------------------------

### ICE Configuration Snippet (JSON)

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/settings

An example snippet for configuring ICE (Interactive Connectivity Establishment) settings within SIP Core. This includes parameters for controlling the ICE gathering process, specifying transport policies, and defining STUN/TURN servers for NAT traversal.

```json
"ice_config": {
    "iceGatheringTimeout": 1000,
    "iceCandidatePoolSize": 0,
    "iceTransportPolicy": "all",
    "iceServers": [
        {
            "urls": ["stun:stun.l.google.com:19302"]
        }
    ],
    "rtcpMuxPolicy": "require"
}
```

--------------------------------

### SIP Core Configuration for Custom Popup

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/guides/popup

Configures SIP Core to utilize a custom popup component. This involves updating the 'sip-config.json' file to specify the 'popup_override_component' and potentially passing configuration details in 'popup_config'.

```json
{
    "popup_override_component": "custom-call-dialog",
    "popup_config": {
        "test_value": "This is a test value"
    },
    ... rest of your configuration ...
}
```

--------------------------------

### Conditional Content with Tabs in MDX

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/docs

Demonstrates how to use Docusaurus's Tab component within MDX files to display content conditionally based on user selection. This is useful for differentiating instructions for different PBX systems like add-ons versus custom PBX setups.

```jsx
<Tabs groupId="pbx">  
  <TabItem value="addon" label="Add-on" default>  
    For the add-on, simply turn on <code>video_support</code> and restart.  
  </TabItem>  
  <TabItem value="custom" label="Custom PBX">  
    If you have a custom PBX, add <code>video_support=on</code> to your <b>SIP</b> endpoint. If you have something like <b>FreePBX</b>, turn on the <b>video support</b> option.  
  </TabItem>  
</Tabs>  

```

--------------------------------

### Send Originate Action via SIP-HASS

Source: https://tech7fox.github.io/sip-hass-docs/docs/integration/services/send_action

This example demonstrates how to use the asterisk.send_action service to initiate an outbound call (Originate). It requires specifying the target channel, context, extension, priority, caller ID, and a timeout in milliseconds.

```yaml
service: asterisk.send_action
data:
  action: Originate
  parameters:
    channel: PJSIP/100
    context: default
    exten: "101"
    priority: "1"
    callerid: Home Assistant
    timeout: 60000
```

--------------------------------

### Build Docker Image (Bash)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/add-on/docker

Builds the Docker image for the 'asterisk' service using Docker Compose. This command reads the 'docker-compose.yml' file to understand the build context and dependencies. It requires Docker and Docker Compose to be installed and configured.

```bash
docker-compose build asterisk
```

--------------------------------

### Manage SIP Calls

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/api/classes/SIPCore

Methods for managing SIP calls, including answering, ending, and starting calls. These methods typically return Promises, indicating asynchronous operations. They interact with the underlying SIP call state and remote participants.

```typescript
answerCall(): Promise<void>;
```

```typescript
endCall(): Promise<void>;
```

```typescript
startCall(extension): Promise<void>;
```

--------------------------------

### Conference Dialplan for Doorbell

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/doorbell

Configures `confbridge.conf` for conference rooms and users, and `extensions.conf` to route doorbell calls to a conference bridge. This allows multiple users to answer the doorbell simultaneously.

```asterisk-conf
[admin_user]  
type=user  
marked=yes  
admin=yes  
music_on_hold_when_empty=yes  
quiet=yes  
  
[default_user]  
type=user  
wait_marked=yes  
end_marked=yes  
music_on_hold_when_empty=yes  
quiet=yes  
  
[myconferenceroom]  
type=bridge  
max_members=10  

```

```asterisk-conf
; for the doorbell  
exten => 777,1,Progress()  
exten => 777,2,Wait(1)  
exten => 777,3,ConfBridge(1,myconferenceroom,default_user)  
  
; for the other user  
exten => 888,1,Progress()  
exten => 888,2,Wait(1)  
exten => 888,3,ConfBridge(1,myconferenceroom,admin_user)  

```

--------------------------------

### Basic Dialplan for SIP Doorbell

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/doorbell

A simple dialplan configuration for `extensions.conf` that uses the `Dial` function to connect incoming calls to a registered SIP endpoint. This is suitable for devices that are always online.

```asterisk-conf
exten => _X!,1,Dial(${PJSIP_DIAL_CONTACTS(${EXTEN})})  

```

--------------------------------

### Asterisk pjsip Extension Template for NAT Traversal

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/vpn

Modifies the Asterisk pjsip extension template to enable specific NAT traversal and RTP handling settings. These parameters, `rtp_symmetric`, `force_rport`, `rewrite_contact`, and `direct_media=no`, are essential for maintaining stable VoIP connections over VPNs.

```ini
[sipjs-ext-endpoint](!)   ; <- This is the template header, it should already exist and you should add the following lines under it
rtp_symmetric=yes
force_rport=yes
rewrite_contact=yes
direct_media=no

```

--------------------------------

### RetryDial Function for SIP Doorbell

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/doorbell

Demonstrates the use of the `RetryDial` function in `extensions.conf` for making calls with specified waiting music, retry intervals, and a maximum number of attempts. This is an alternative to manual redial loops.

```asterisk-conf
exten => 777,1,Progress()  
exten => 777,n,RetryDial(wait.wav,4,10,PJSIP/100)   

```

--------------------------------

### Define Custom Button for SIP-HASS Call Popup (JSON)

Source: https://tech7fox.github.io/sip-hass-docs/docs/card/cards-popups/call-popup

Example of a custom button configuration for the SIP-HASS call popup. This snippet defines a button with a label, icon, type (service_call), and associated data for triggering a service.

```json
{
    "label": "Switch lights",
    "icon": "mdi:lightbulb",
    "type": "service_call",
    "data": {
        "domain": "light",
        "service": "toggle"
    }
}
```

--------------------------------

### Send Hangup Action via SIP-HASS

Source: https://tech7fox.github.io/sip-hass-docs/docs/integration/services/send_action

This example shows how to use the asterisk.send_action service to terminate an active call (Hangup). It requires specifying the channel on which to perform the hangup action.

```yaml
service: asterisk.send_action
data:
  action: Hangup
  parameters:
    channel: PJSIP/100
```

--------------------------------

### Configure PJSIP Endpoint for Doorbell

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/doorbell

Defines a SIP endpoint for a doorbell device in `pjsip_custom.conf`. This configuration includes settings for audio codecs, DTMF mode, caller ID, and authentication, allowing the doorbell to register with the SIP server.

```asterisk-conf
[8000]  
type = endpoint  
context = default  
disallow = all  
allow = alaw,ulaw          ; Audio codecs  
allow=h264                 ; Video codecs  
direct_media_method=invite  
dtmf_mode=info  
callerid="Doorbell" <8000>  
force_rport=no  
aors= 8000  
auth = auth8000  
  
[8000]  
type = aor  
max_contacts = 1  
  
[auth8000]  
type=auth  
auth_type=userpass  
password=mypassword        ; Set your password here  
username=8000  

```

--------------------------------

### Home Assistant Service Call for SIP Origination

Source: https://tech7fox.github.io/sip-hass-docs/docs/integration/guides/text-to-speech

Configures a Home Assistant service call to the Asterisk integration to originate a call. This service call specifies the channel to call, the context and extension in the dialplan, caller ID, timeout, and variables to pass to the dialplan, including the text to be spoken and language.

```yaml
service: asterisk.send_action  
data:  
  action: Originate  
  parameters:  
    channel: PJSIP/100                          # The device it will call  
    context: speech                             # The context we created in the dialplan  
    exten: 123                                  # The extension inside that context  
    priority: 1                                 # Priority of the call  
    callerid: 'Home Assistant'                  # The callerID it calls as  
    timeout: 60000                              # Time until giving up in ms  
    variable: "TEXT='Hello world!',LANG=en"     # Variables that you can use in the dialplan  

```

--------------------------------

### Home Assistant Shell Command for VPN RTP Route

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/vpn

Defines a shell command in Home Assistant's `configuration.yaml` to add a static route for VPN traffic. This command ensures that RTP packets destined for the VPN subnet are correctly routed via the specified gateway, which is essential for VoIP calls over the VPN.

```yaml
shell_command:
  add_vpn_rtp_route: ip route add 172.27.66.0/24 via 172.30.33.3

```

--------------------------------

### Redial Dialplan with Loop for Doorbell

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/doorbell

Implements a redial mechanism in `extensions.conf` that repeatedly attempts to dial SIP endpoints for a specified duration if they are not initially registered. This is useful for ensuring calls reach devices like softphones or SIP cards.

```asterisk-conf
exten => s,1,NoOp()   
 same => n,Set(COUNT=1)  
 same => n,While($[ ${COUNT} < 60 ])  
 same => n,Set(DIALGROUP(mygroup,add)=PJSIP/6001)   
 same => n,Set(DIALGROUP(mygroup,add)=PJSIP/100)   
 same => n,Dial(${DIALGROUP(mygroup)},60)  
 same => n,Set(HANGUPCAUSEKEYS=${HANGUPCAUSE_KEYS()})  
 same => n,Set(HANGUP_CAUSE=${HANGUPCAUSE})  
 same => n,GotoIf($["${HANGUP_CAUSE}" == "21"]?exitdialplan)  
 same => n,GotoIf($["${HANGUP_CAUSE}" == "0"]?exitdialplan)    
 same => n,Wait(1)   
 same => n,SET(COUNT=$[${COUNT} + 1]  
 same => n,EndWhile()  
 same => n,Verbose(2, HANGUP_CAUSE=${HANGUPCAUSE})  
 same => n(exitdialplan),NoOp(Exiting dialplan: HANGUP_CAUSE=${HANGUPCAUSE})   
 same => n,Hangup()  

```

--------------------------------

### Asterisk pjsip Transport and Local Network Configuration

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/vpn

Configures the Asterisk pjsip transport to listen on UDP port 5060 and defines local network subnets, including the VPN client subnet, to be treated as internal traffic. This is crucial for proper NAT traversal and call handling over the VPN.

```ini
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0:5060  ; Binds to all IP addresses on port 5060
; --- Network and NAT Configuration ---
; This is the most critical part for your use case.
; Add your local LAN and the VPN subnet here.
; Asterisk will treat any traffic from these networks as internal.
local_net=192.168.1.0/24   ; Your main LAN subnet - CHANGE THIS IF YOU USE A DIFFERENT NETWORK
local_net=172.27.66.0/24   ; The VPN clients virtual addresses subnet - ASSUMING YOU'RE USING THE DEFAULT WIREGUARD ADD-ON SETTINGS

```

--------------------------------

### Access Asterisk CLI using Docker

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/troubleshooting

This command allows you to access the Asterisk Command Line Interface (CLI) for debugging purposes. It requires the enhanced SSH & Web terminal addon to be installed and protection mode disabled. The command executes the asterisk CLI within the specified Docker container.

```bash
docker exec -it addon_b35499aa_asterisk asterisk -rvvvvddd
```

--------------------------------

### Asterisk extensions.conf Redial Logic with PJSIP

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/doorbell

This Asterisk dialplan configuration allows an extension (8002) to continuously attempt to connect to specified PJSIP endpoints until one of them answers. If no endpoint answers, it will loop back to the dialing stage. The call is only terminated when answered and then hung up. This is useful for ensuring notifications reach a dashboard, with the first to answer taking precedence.

```asterisk-dialplan
exten => 8002,1,Ringing() ; ghost extension number used only for the purpose of redirect, there is no trunk in sip/psjip.conf , this is setup on your VTO config.  
exten => 8002,n(dialing),Dial(${PJSIP_DIAL_CONTACTS(100)}& ${PJSIP_DIAL_CONTACTS(104)}) ;this is so you can dial multiple extensions.  
exten => 8002,n(busy),Playtones(dial) ;the call connects and custom sound is played, but we make it sound the same with the dial ringtone  
exten => 8002,n,Goto(dialing) ; then it repeats itself  
exten => 8002,n,HangUp()  
```

--------------------------------

### WireGuard Add-on iptables Rules for VPN Traffic Routing

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/guides/vpn

Configures iptables rules within the WireGuard add-on to manage network traffic forwarding and Network Address Translation (NAT) for VPN clients. These rules allow traffic to be accepted, forwarded, and masqueraded, ensuring that VPN clients can communicate with the Asterisk server and vice-versa, including specific handling for RTP traffic.

```bash
post_up: >
  iptables -A FORWARD -i %i -j ACCEPT ; 
  iptables -A FORWARD -o %i -j ACCEPT ; 
  iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE ; 
  iptables -t nat -I POSTROUTING 1 -p udp -s 172.30.32.1 -d  172.27.66.0/24 --sport 10000:20000 -j SNAT --to-source <YOUR HOME ASSISTANT IP ADDRESS HERE> ; 
  iptables -t nat -I POSTROUTING 1 -p udp -s 172.27.66.0/24 -d <YOUR HOME ASSISTANT IP ADDRESS HERE> --dport 10000:20000 -j RETURN    
post_down: >
  iptables -D FORWARD -i %i -j ACCEPT ; 
  iptables -D FORWARD -o %i -j ACCEPT ; 
  iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE ; 
  iptables -t nat -D POSTROUTING 1 -p udp -s 172.30.32.1 -d  172.27.66.0/24 --sport 10000:20000 -j SNAT --to-source <YOUR HOME ASSISTANT IP ADDRESS HERE> ; 
  iptables -t nat -D POSTROUTING 1 -p udp -s 172.27.66.0/24 -d <YOUR HOME ASSISTANT IP ADDRESS HERE> --dport 10000:20000 -j RETURN    

```

--------------------------------

### Asterisk Add-on Configuration (YAML)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/add-on/introduction

This YAML configuration defines the settings for the Asterisk add-on in Home Assistant. It specifies the add-on's name, version, slug, description, repository URL, supported architectures, and the Docker image to be used. The `image` option is commented out, suggesting it should be overridden during local testing.

```yaml
name: Asterisk  
version: 1.3.2  
slug: asterisk  
description: PBX server for SIP devices like doorbells and phones  
url: https://github.com/TECH7Fox/Asterisk-add-on  
#image: "ghcr.io/tech7fox/{arch}-addon-asterisk"  
arch:  
  - armhf  
  - armv7  
  - aarch64  
  - amd64  
  - i386  

```

--------------------------------

### SIP Core Configuration Template (JSON)

Source: https://tech7fox.github.io/sip-hass-docs/docs/tutorial/card

This JSON template outlines the complete configuration settings for SIP Core in Home Assistant. It includes parameters for ICE configuration, backup user details, user accounts, video settings, auto-answer preferences, and popup configurations. Ensure sensitive information like passwords and usernames are replaced with your actual credentials.

```json
{
    "ice_config": {
        "iceGatheringTimeout": 1000,
        "iceCandidatePoolSize": 0,
        "iceTransportPolicy": "all",
        "iceServers": [
            {
                "urls": ["stun:stun.l.google.com:19302"]
            }
        ],
        "rtcpMuxPolicy": "require"
    },
    "backup_user": {
        "ha_username": "myusername",
        "extension": "100",
        "password": "mypassword"
    },
    "users": [
        {
            "ha_username": "myusername",
            "extension": "100",
            "password": "mypassword"
        }
    ],
    "sip_video": false,
    "auto_answer": false,
    "popup_config": {
        "auto_open": true,
        "large": false,
        "buttons": [],
        "extensions": {}
    }
}

```

--------------------------------

### SIPCore Initialization and Update

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/api/classes/SIPCore

Methods related to the initialization and update process of the SIPCore. `init()` is an asynchronous operation likely responsible for setting up the SIP user agent and establishing connections. `triggerUpdate()` dispatches a custom event for external updates.

```typescript
init(): Promise<void>;
```

```typescript
triggerUpdate(): void;

```

--------------------------------

### Initialize SIPCore

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/api/classes/SIPCore

Constructor for the SIPCore class. Initializes the SIP Core functionality. No external dependencies are explicitly mentioned for this constructor.

```typescript
new SIPCore(): SIPCore;
```

--------------------------------

### Asterisk Add-on Configuration

Source: https://tech7fox.github.io/sip-hass-docs/docs/tutorial/add-on

Configuration parameters for the Asterisk add-on. This includes settings for AMI password, auto-generated extensions, video support, SSL certificate generation, and optional mailbox settings. It's important to set secure passwords for AMI and extensions.

```yaml
ami_password: my-secret-password
auto_add_secret: my-secret-password
video_support: false
auto_add: true
generate_ssl_cert: false
certfile: fullchain.pem
keyfile: privkey.pem
log_level: info

# These settings are optional
mailbox: false
mailbox_port: 12345
mailbox_extension: '100'
mailbox_password: my-secure-password
mailbox_google_api_key: my-google-stt-key


```

--------------------------------

### Configure Parking Spaces (res_parking.conf)

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/parking

This configuration file defines the parameters for parking extensions, including the extension numbers for parking and pickup, the context for parked calls, timeout settings, and music on hold class. It allows customization of parking behavior.

```ini
[default]
 parkext => 700
 parkpos => 701-703
 context => parkedcalls
 parkingtime => 60
 comebacktoorigin = no
 comebackcontext = parkedcallstimeout
 parkedmusicclass = default

```

--------------------------------

### Manage Audio Devices and Playback

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/card/api/classes/SIPCore

Methods for managing audio devices and controlling audio playback for SIP calls. `getAudioDevices` retrieves available audio devices, while `playIncomingRingtone`, `stopIncomingRingtone`, `playOutgoingTone`, and `stopOutgoingTone` manage ringtones and tones. These operations may involve browser Media APIs.

```typescript
getAudioDevices(audioKind): Promise<MediaDeviceInfo[]>;

```

```typescript
playIncomingRingtone(): void;
```

```typescript
stopIncomingRingtone(): void;
```

```typescript
playOutgoingTone(): void;
```

```typescript
stopOutgoingTone(): void;
```

--------------------------------

### Dialplan for Parking and Pickup (extensions.conf)

Source: https://tech7fox.github.io/sip-hass-docs/docs/add-on/parking

This dialplan configuration demonstrates how to implement call parking and pickup using Asterisk's dialplan. Extension 444 is used to park a call, and extension 555 is used to retrieve the first parked call from a specified parking position.

```asterisk
; this extension parks the call.
exten => 444,1,Park(,s)

; this extension get's the first parked call. 701 is the parking position.
exten => 555,1,ParkedCall(default,701)

```

--------------------------------

### Register Ingress Entry with Supervisor API (Bash)

Source: https://tech7fox.github.io/sip-hass-docs/docs/developers/add-on/ingress

This script snippet registers the add-on's ingress entry with the Home Assistant Supervisor API. It retrieves the ingress entry information and posts it to the 'text.asterisk_addon_ingress_entry' entity. This allows other Home Assistant components, like SIP Core, to discover and utilize the ingress connection.

```bash
INGRESS_ENTRY=$(api_call -X GET http://supervisor/addons/self/info | jq -r .data.ingress_entry)  
bashio::log.info ingress_entry: $INGRESS_ENTRY  
api_call -X POST http://supervisor/core/api/states/text.asterisk_addon_ingress_entry -d '{"state": "'${INGRESS_ENTRY}'"}'  

```