Skip to content
Thirdlane

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.

Duplicating Models

You can duplicate a shipped model using the Duplicate as override button in the grid toolbar. The duplicate opens with an editable name field. Choose Global override or Tenant override when saving. Template content becomes fully editable in the duplicate, 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.

Best practices

  • Never edit Shipped (System) models or the files under /etc/asterisk/provisioning/. They are read-only and overwritten on every template-package upgrade. To customize, clone the model into a global or tenant override, which stores your changes safely under /etc/asterisk/user_provisioning/.
  • Clone, then change only what differs. Starting from a shipped model keeps templates, protocol, and firmware settings correct; you adjust only the specific values you need.
  • Use tenant overrides for tenant-specific quirks and global overrides for changes that should apply everywhere, so customizations stay scoped to where they belong.
  • Test a cloned model on one device first before rolling it out, since a template error affects every phone provisioned from that model.