# Автоматическая настройка телефонов

## Что делает модуль

Модуль **Автоматическая настройка телефонов** (Autoprovisioning Plug & Play, PnP) избавляет от ручной настройки настольных IP-телефонов. Вместо того чтобы заходить в web-интерфейс каждого аппарата, вы один раз привязываете MAC-адрес к внутреннему номеру — при следующей загрузке телефон сам подтянет SIP-аккаунт, план набора, BLF-кнопки и (по желанию) прошивку с MikoPBX.

**Поддерживаемые производители:** Yealink, Snom, Fanvil, Grandstream, Htek.

Проверенные модели: Yealink T19/T28/T46S/T48S/W52/WP530, Snom D120/D335/D385/D715/D735/D785, Fanvil X1SP/X3SP/X5U, Grandstream серий GXP и GRP, Htek UC9xx. Другие модели тех же вендоров обычно работают тоже — если конкретному аппарату нужны правки, отредактируйте его шаблон (см. *Шаблоны настроек* ниже).

## Системные требования

* Модуль работает **только внутри локальной сети**.
* В сети должен быть разрешён **multicast-трафик на `224.0.1.75:5060`** — именно так телефоны сообщают о себе.
* Телефоны должны иметь доступ к АТС на **SIP `5060`** и на **порт автонастройки HTTP** (по умолчанию `8480`).
* Если включаете канал TFTP, дополнительно нужен **UDP/69**.
* Правила фаервола для порта автонастройки и TFTP открываются **автоматически** при включении модуля.
* В одной сети не должно работать других PnP-серверов — телефон возьмёт настройки у того, кто ответит первым.

## Установка модуля

1. Откройте **Модули → Маркетплейс модулей**.
2. Установите модуль **Автоматическая настройка телефонов** и перезагрузите страницу.
3. Откройте страницу модуля и пройдитесь по вкладкам **до того, как включать модуль**. Воркер автонастройки стартует сразу после включения переключателя.

## Вкладки модуля

На странице модуля шесть вкладок. Пройдитесь по ним в порядке ниже.

### 1. Настройка телефонов

Таблица соответствия «MAC-адрес ↔ внутренний номер». Одна строка — один телефон (по MAC), привязанный к одному пользователю MikoPBX и одному шаблону конфигурации.

| Поле             | Назначение                                                     |
| ---------------- | -------------------------------------------------------------- |
| **Пользователь** | Выберите внутреннего сотрудника MikoPBX из выпадающего списка. |
| **MAC**          | MAC-адрес телефона. Регистр и разделители не важны.            |
| **Шаблон**       | Один из шаблонов с вкладки *Шаблоны настроек*.                 |

Телефоны, обнаруженные модулем по PnP, появляются в этой таблице автоматически — остаётся только назначить им пользователя и шаблон.

### 2. Шаблоны настроек

Текст файла конфигурации, который телефон получит при подключении. Кнопка **Добавить** создаёт пустой шаблон, **Загрузить примеры** — пять готовых шаблонов под Yealink, Fanvil, Snom, Grandstream и Htek. В шаблоне можно поменять что угодно, что поддерживает синтаксис конкретного вендора: кодеки, DTMF, часовой пояс, тексты, BLF-кнопки и т.д.

В шаблонах используются плейсхолдеры — модуль подставляет реальные значения при выдаче файла:

| Плейсхолдер       | Заменяется на                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `{SIP_NUM}`       | Внутренний номер привязанного пользователя.                                                                     |
| `{SIP_USER_NAME}` | Имя SIP-учётной записи.                                                                                         |
| `{SIP_PASS}`      | Пароль SIP-учётной записи.                                                                                      |
| `{PBX_HOST}`      | Значение поля *Адрес регистрации сервера* с вкладки PnP.                                                        |
| `{FIRMWARE_URL}`  | Ссылка на прошивку, подходящую вендору (и модели, если она указана). Пусто, если ни одна прошивка не загружена. |

### 3. Дополнительные URI

Некоторые телефоны запрашивают конфигурацию по фиксированному URL (например, `y000000000028.cfg` у старых прошивок Yealink). На этой вкладке можно сопоставить произвольный URL с шаблоном — когда телефон обращается по этому URL, MikoPBX отдаёт указанный шаблон.

### 4. Телефонная книга

Внешние источники для общей телефонной книги. Каждая строка — другой MikoPBX, чьих сотрудников нужно подмешать в книгу, которая раздаётся вашим телефонам.

Сейчас книга отдаётся в формате **Yealink** (подходит большинству Yealink-совместимых прошивок) и **Grandstream**. Поддержка собственных форматов Fanvil, Snom и Htek в планах.

> На каждой внешней MikoPBX должен быть открыт её порт автонастройки HTTP — без этого подмешать книгу не получится.

### 5. Настройки PnP

Главные параметры модуля.

* **Шаблон Extension** — комбинация цифр, которую сотрудник набирает с телефона, чтобы привязать его к своему номеру. Установщик заполняет это значение чем-то вроде `*123*200` — свободный feature-код плюс типичная длина внутреннего номера. Поменяйте по вкусу.
* **Адрес регистрации сервера** — IP-адрес или DNS-имя этой АТС. Телефоны используют это значение как свой SIP-сервер и адрес, с которого качают конфигурацию. Адрес должен быть доступен из сети каждого телефона.
* **Порт автонастройки HTTP** — TCP-порт, на котором модуль раздаёт файлы конфигурации. По умолчанию `8480`. Отдельный порт без обязательного HTTPS-редиректа — работает даже на АТС, где админка форсирует HTTPS.
* **Чёрный список MAC** — MAC-адреса, которые игнорируются. **Чёрный список побеждает белый.**
* **Белый список MAC** — MAC-адреса, которым разрешено получать настройки автоматически. Если оба списка пусты, обслуживаются все телефоны в локальной сети.
* **Дополнительные параметры** — дополнительные строки конфигурации для каждого вендора, разбитые по INI-секциям. Подробности — в разделе *Дополнительные параметры* ниже.
* **Включить раздачу по TFTP (UDP/69)** — поднимает встроенный TFTP-сервер. Телефоны, которые предпочитают DHCP option 66 вместо multicast-PnP (типично для Snom и некоторых прошивок Fanvil), будут забирать конфигурацию по TFTP. Включайте только в доверенной локальной сети — TFTP передаётся без шифрования.

### 6. Прошивки

Встроенное хранилище файлов прошивок для телефонов. Перетащите файл прошивки в область загрузки, укажите вендора и модель, сохраните — MikoPBX начнёт раздавать этот файл и подставит ссылку на него в плейсхолдер `{FIRMWARE_URL}`.

| Поле        | Заметки                                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| **Вендор**  | `yealink`, `snom`, `fanvil`, `grandstream` или `htek`.                                                               |
| **Модель**  | Произвольная строка (например, `T46S`). Можно оставить пустым — тогда это «прошивка по умолчанию» для всего вендора. |
| **Версия**  | Произвольная строка (например, `66.86.0.15`).                                                                        |
| **Заметка** | Комментарий администратора.                                                                                          |
| **Файл**    | Сам файл прошивки.                                                                                                   |

**Ограничения:** до **80 МБ на файл**, **300 МБ суммарно** на всё хранилище.

**Допустимые расширения файла по вендору:**

| Вендор      | Расширения     |
| ----------- | -------------- |
| Yealink     | `.rom`, `.bin` |
| Snom        | `.bin`, `.fw`  |
| Fanvil      | `.z`, `.bin`   |
| Grandstream | `.bin`         |
| Htek        | `.rom`, `.bin` |

В каждой строке есть кнопки «Изменить» и «Удалить»; при редактировании можно загрузить новый файл на замену.

Когда телефон забирает свою конфигурацию, модуль ищет подходящую прошивку — сначала по совпадению вендора и модели, потом по вендору без модели (fallback). Найденный URL попадает в шаблон через `{FIRMWARE_URL}`. Кроме того, генераторы каждого вендора добавляют свою «родную» строку прошивки автоматически:

* **Yealink** — `firmware.url = …`
* **Snom** — `<firmware perm="RW">…</firmware>`
* **Fanvil** — `App URL : …`
* **Grandstream** — `<P192>…</P192>` плюс `<P237>1</P237>` (принудительная проверка прошивки при каждой загрузке)
* **Htek** — `auto_image_url = …`

## Дополнительные параметры

Поле **Дополнительные параметры** на вкладке *Настройки PnP* принимает строки для конкретных вендоров, сгруппированные в INI-секции. Каждая секция «вмешивается» в сгенерированную конфигурацию соответствующего вендора.

### Yealink

```ini
[yealink]
features.headset_prior = 1
features.intercom.allow = 1
```

### Snom

`[snom]` — для строк внутри корневого узла `<settings>`, `[snom-phone-settings]` — для строк внутри `<phone-settings>`.

```ini
[snom]
time_24_format = on

[snom-phone-settings]
dialplan_active = on
```

### Fanvil

Fanvil раскладывает конфигурацию по именованным модулям. Дополняйте их секциями `[fanvil]`, `[fanvil-sip]`, `[fanvil-tele]` или `[fanvil-autoupdate]`.

```ini
[fanvil-sip]
SIP1 Default DTMF = AUTO
```

### Grandstream

Grandstream использует XML P-коды. Добавляйте или переопределяйте код через `[grandstream]`:

```ini
[grandstream]
<P3>caller_id</P3>
```

## Привязка телефона по star-коду

Когда модуль включён, шаблон из поля *Шаблон Extension* (например, `*123*200`) становится рабочим внутренним номером. Сотруднику достаточно набрать его с нового телефона:

1. Телефон делает вызов на эту комбинацию.
2. MikoPBX по исходящему IP вычисляет MAC, добавляет телефон в *Настройку телефонов*.
3. Телефон автоматически перезагружается и при следующей загрузке забирает свежую конфигурацию.

После этого пользователь привязан к телефону — действий администратора не требуется.

## Поиск неисправностей

### Телефон не подхватывает конфигурацию

1. **Проверьте адрес.** Зайдите в web-интерфейс телефона и убедитесь, что в качестве сервера автонастройки указан IP вашей АТС. Чаще всего «не та подсеть» или DHCP option 66 указывает в другое место.
2. **Проверьте порт.** Из той же сети, где стоит телефон, откройте в браузере `http://<ip-атс>:8480/`. Не должно быть «соединение отклонено». Если есть — порт автонастройки закрыт: проверьте правила фаервола и что переключатель модуля включён.
3. **Проверьте списки MAC.** Если MAC телефона в чёрном списке (или есть непустой белый список и MAC в него не входит), модуль не отдаст конфигурацию.
4. **Перезагрузите телефон.** Некоторые прошивки запрашивают новый конфиг только при включении питания.

### Yealink — снимите лог

1. В web-интерфейсе телефона откройте **Settings → Configuration**.
2. Установите уровень логирования **6**.
3. Перезагрузите телефон и выгрузите лог.

В логе обратите внимание на строки `Connect Error`:

```
LIBD[528]: HTTP<5+notice> URL :
LIBD[528]: HTTP<3+error > Connect Error
AUTP[528]: AUTP<3+error > http to file failed, code = -3, msg = Connect Failed
```

`Connect Error` означает, что телефон не смог дотянуться до АТС по HTTP — перепроверьте *Адрес регистрации сервера* и порт автонастройки.

### Подробное логирование PnP

Чтобы увидеть каждый PnP-пакет, который видит модуль, вставьте в **Дополнительные параметры**:

```ini
[debug]
verbose = 1
```

Модуль начнёт логировать каждый multicast-пакет, найденный MAC и решение по чёрному/белому списку. В обычной эксплуатации флаг лучше держать выключенным — лог получается шумным.

### Прошивки

* Телефон не обновляется. Проверьте, что плейсхолдер `{FIRMWARE_URL}` реально оказался в конфигурации, которую получил телефон (скачайте файл с `http://<ip-атс>:8480/...` в браузере). Если он пустой — вы не загрузили строку прошивки для этого вендора.
* Форма загрузки отклоняет файл. Проверьте список допустимых расширений выше и ограничения по размеру.

### TFTP

Если включили раздачу по TFTP, а телефон всё равно не забирает конфигурацию, проверьте, что DHCP option 66 (имя TFTP-сервера) на вашем роутере указывает на IP АТС, и что между сетью телефона и АТС не блокируется UDP/69.

## Справочно: что модуль генерирует «из коробки»

Ниже — полное содержимое файла конфигурации, который модуль создаёт по пустому шаблону (без правок шаблона и без *Дополнительных параметров*). Удобно использовать как референс при отладке: скачайте файл, который реально получил телефон (`http://<ip-атс>:8480/...`), и сравните с подходящим примером ниже.

### Yealink

```ini
#!version:1.0.0.1
account.1.enable = 1
account.1.label = Askozia (204)
account.1.display_name = 204
account.1.auth_name = 204
account.1.user_name = 204
account.1.password = 1c9709222690713dd
account.1.sip_server_host = 172.16.156.223
account.1.sip_server_port = 5060
account.1.transport = 0
account.1.codec.1.enable = 1
account.1.codec.1.payload_type = PCMU
account.1.codec.1.priority = 1
account.1.codec.1.rtpmap = 0
account.1.cid_source = 4
voice_mail.number.1 = *001
phone_setting.lcd_logo.mode = 0
auto_provision.dhcp_option.enable = 0
features.intercom.allow = 1
features.intercom.mute = 0
features.intercom.tone = 1
features.intercom.barge = 1
features.dtmf.transfer = ##
features.dtmf.replace_tran = 1
features.headset_prior = 1
```

### Snom

```xml
<?xml version="1.0" encoding="utf-8"?>
<settings>
    <time_24_format perm="R">off</time_24_format>
    <phone-settings>
        <user_pname idx="1" perm="RW">203</user_pname>
        <user_name idx="1" perm="RW">203</user_name>
        <user_realname idx="1" perm="RW">Irina Smirnova</user_realname>
        <user_pass idx="1" perm="RW">3256157a99f176eb959ef9c1fdd947f0</user_pass>
        <user_host idx="1" perm="RW">172.16.32.225</user_host>
        <user_srtp idx="1" perm="RW">off</user_srtp>
        <user_mailbox idx="1" perm="RW">*001</user_mailbox>
    </phone-settings>
</settings>
```

### Fanvil

```
<<VOIP CONFIG FILE>>Version:2.0002
PNP Enable         :0
<SIP CONFIG MODULE>
SIP1 Enable Reg    :1
SIP1 Phone Number  :203
SIP1 Display Name  :Irina Smirnova
SIP1 Register Addr :172.16.156.223
SIP1 Register Port :5060
SIP1 Register User :203
SIP1 Register Pswd :3256157a99f176eb959ef9c1fdd947f0
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mikopbx.com/mikopbx/modules/miko/module-autoprovision.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.