Skip to content
Platform Documentation

Phone Models

The Phone Models screen (under Provisioning in the navigation tree) allows you to view all installed device models and manage overrides. Each model defines the template files, protocol, firmware, and other settings used when provisioning phones of that type.

Model Scopes

Three levels are shown in the UI (internal values in parentheses):

  • Shipped (system) — Installed by Template Bundles and read-only. Stored under /etc/asterisk/provisioning/ (for example models.d/). Duplicate or clone a shipped model to create an editable global or tenant override.

  • Global override (custom) — Stored in /etc/asterisk/user_provisioning/models.txt and applies to all tenants.

  • Tenant override (tenant) — Stored in /etc/asterisk/user_provisioning/{tenant}/models.txt and applies only to that tenant.

Filtering

The filter bar at the top allows you to search models by scope, name, or label. Enter your filter criteria and click Select to apply, or Clear to reset.

Model Form

Click “Add” to create a new model, or double-click an existing model to edit it. The form has four tabs:

General

Set the basic model properties:

  • Name — Unique model identifier (alphanumeric characters, hyphens, and underscores). Read-only after creation.
  • Label — Human-readable display name (e.g., “Yealink T54W”).
  • Lines — Number of line keys the phone supports.
  • Protocol — (Optional) Override the global Default Protocol. If left as “Default”, the system-wide setting is used. Options: HTTP, HTTPS, FTP, FTPS, TFTP.
  • Firmware — (Optional) Firmware version string (e.g., 96.86.0.30). Makes ${FIRMWARE} and ${FIRMWARE_URL} template variables available.
  • Firmware Dir — (Optional) Firmware subdirectory on the server. Auto-derived from model name if not specified.
  • Translation Map — The Translation Map used by this phone model.
  • Check Sync — Command sent to the phone after provisioning files are generated.
  • Output — The output filename pattern for the main provisioning file (supports variables like ${mac}).
  • Repeat Registrations — Whether to repeat registration entries for each line.

Templates

View and edit the template file references:

  • Phone Template — Main device configuration template.
  • Line Template — Template processed for each configured line.
  • BLF Template — Template for Busy Lamp Field buttons.
  • Speed Dial Template — Template for Speed Dial buttons.
  • Line Key Template — Template for line key assignments.
  • N/A Template — Template for unassigned buttons.

I/O Files

Manage additional input/output file pairs and post-provisioning commands:

  • Input/Output Pairs — Additional template files to process. Each input file is processed with variable substitution and written to the corresponding output filename.
  • Commands — Shell commands executed after provisioning completes (e.g., scripts to generate vendor-specific configuration files).

Template Content

View and edit the actual content of template files referenced by this model:

  1. Select a template file from the dropdown to load its content.
  2. The Source field shows the file path where the template was found (shipped catalog path, global override file, or tenant override file).
  3. For shipped models, the content is displayed read-only.
  4. For global or tenant overrides, you can edit the content directly. Changes are saved under /etc/asterisk/user_provisioning/, keeping the original shipped template intact.
  5. If you have unsaved changes when switching to a different template file, you will be prompted to confirm before the new file loads.

Cloning Models

You can clone any model (including shipped models) using the Clone button. The cloned model opens with an editable name field. Choose Global override or Tenant override when saving. Template content becomes fully editable in the cloned copy, without affecting the original shipped model.

Model INI Format

Models are stored as INI sections in models.txt files. Here is an example:

[yealink-t54w]
label=Yealink T54W
lines=16
protocol=https
firmware=96.86.0.30
firmware_dir=FIRMWARE-YEALINK
check_sync=yealink-check-cfg
translationmap=yealink
phone_template=yealink_device_t54w.cfg
line_template=yealink_line.cfg
blf_template=yealink_blf.cfg
speeddial_template=yealink_speeddial.cfg
linekey_template=yealink_linekey.cfg
output=${mac}.cfg

Model keys like protocol, firmware, and firmware_dir are plain configuration values — the provisioning system reads them and makes them available as template variables (${PROTO}, ${FIRMWARE}, ${FIRMWARE_URL}, etc.) for use in .cfg template files. Some model keys like output can themselves use ${...} variables (e.g., output=${mac}.cfg) when the value needs to vary per device.

For a full explanation of how model definitions feed into template variable substitution, and for the complete list of available template variables, see Device Provisioning.

In addition to built-in variables, administrators can define Custom Variables in Provisioning Settings. Custom variables are global name-value pairs that become available as ${VARIABLE_NAME} in all templates.