From Snom User Wiki

Contents 1 Overview 2 Terminology 3 Requirements 3.1 Legacy Feature Set 3.2 Device Abstraction 3.3 Scalability 4 Device Model 4.1 Lamp 4.2 Label 4.3 Key 4.4 Key Information 5 Protocol Description 5.1 Format 5.2 Properties 5.2.1 Name 5.2.2 Light 5.2.3 Color 5.2.4 Label 5.2.5 Caller-ID 5.2.6 Action and Number 5.2.7 Button Release 5.3 Syntax Description 6 Examples 6.1 Extension Monitoring 6.2 Seizing Shared Line 6.3 Turning DND On and Off

Overview

Since the invention of the private branch exchange (PBX) telephone systems, users expect that desktop phones have buttons where they can see if other extensions are busy or lines have been seized. This document addresses this requirement in the scope of devices that use the session initiation protocol (SIP, see RFC 3261). It introduces a new document type that contains the necessary information and that can be exchanged between the endpoint and the SIP-enabled PBX.

Terminology

SIP-PBX: This term refers to a component that implements the behavior of a SIP-enabled PBX. It can be a software or a hardware device and it can be hosted remotely or on customer’s premises.

• Endpoint: An endpoint is a SIP-enabled device that implements the handset functionality in a PBX environment. It can be either software or hardware-based.
• Busy Lamp Field: This feature shows if another endpoint is in use. It might be a passive monitoring tool or it might allow taking over calls from the endpoint.

Requirements

Most telephone systems that were using digital switching technology were offering a feature set that assumed that the desktop telephones had a number of lights and keys. These keys were used to implement features like busy lamp field, call parking and pickup, line monitoring and other things.

Legacy Feature Set

It must be possible to implement the following features:

• Extension Monitoring: It must be possible to see if an extension is connected, ringing or holding a call. If the call is ringing or the call is on hold it must be possible to pick up the call for or from that extension.
• Line Monitoring: It must be possible to emulate central office lines. That means it must be possible to see the call status of a line, seize a line, put a call on hold and pick up a call.
• Non-Call Related Features: It must be possible to control flags with the keys, for example for turning DND mode on and off or to open a door.
• Push to Talk: When a user pushes a button down, he should be able to start talking while lifting it up should clear the call.
• Web-related features: It must also be possible to address features that use the HTTP protocol to retrieve information. For example, a address book lookup can be a web-related feature.

Device Abstraction

The messages should be as independent from the device as possible. It must be possible to create device-dependent profiles that deal with the layout of the keys.

It must be possible to automatically provision the devices for usage of the buttons. The provisioning process is not the scope of this document. However, the provisioning must take care of button configuration.

Scalability

Many office devices have a lot of keys. Large installations have a potentially large number of handsets with buttons. It must be possible to update these keys with a reasonable effort and it must be possible for embedded devices to parse the document fast enough. It must also be possible to set buttons using multicast messages (which rules out device-dependent document version numbers).

Device Model

We assume that the device has one or more buttons. A button has several properties which are described below. It is not necessary that all buttons support all features. For example, it is possible that a phone has LED lights and keys, but no display associated with the button.

Lamp

One lamp can render one color at a time. It must have at least a “on” and an “off” state, and it may have additional features like colors. It has the possibility to indicate further information by slow and fast blinking. Typically, a lamp is implemented with an LED.

Label

A key might have a small display next to it, called a "label". Some devices support this feature, so that the user does not have to print a label on paper for the key. This display can be used to provide additional information to the lamp, for example the extension number or the function of the key.

Key

The key has two states, up and down. The user can push the key and release the key. The key is associated with a lamp and typically located physically next to the lamp.

Key Information

Along with the key, the device may render additional information that belongs to the key. The device that renders the information is not attached to the lamp. For example, information could be the caller-ID for an incoming call and it is displayed on the main screen of the device.

Protocol Description

Format

The document contains of CRLF-separated lines. Empty lines indicate the beginning of a new lamp description, so that one document can contain several lamp descriptions. There is no line continuation; a CRLF combination is the clear indication that the line ends.

Each line may contain description entries for the lamp. If an entry is not present, then a default value shall apply. The previously stored value for that property will be overwritten in any case.

Text is encoded in UTF-8 format. It may not contain special characters like CR, LF or TAB; but it may contain space and UTF-8 encoded characters.

Properties

Name

The Name property is used to identify the button that should be changed. The name itself is text based. It may be a number, but it can also be any other UTF-8 encoded text. The naming is a matter of provisioning.

Light

The Light property describes in what state the lamp should be. There is a set of predefined light modes that any device must support:

• "on" should turn the light on without any blinking.
• "off" should turn the light off without any blinking.
• "hold" indicates that there is a call on hold associated with the button.
• "pickup" indicates that there is a ringing call that can be picked up.
• "park" indicates that there is a call that can be retrieved from a park orbit.
• "message" is used to indicate that there is a message waiting.
• "offline" indicates that the remote resource is offline (for example, on “do not disturb”).
• "error" indicates that there is a error condition (for example, a trunk line is offline).

Color

Many devices use LED with more than one color. Typically this feature is used to inform the user about local or remote hold.

The Color property may contain a 24-bit encoded RGB value or an explicit remote or local indication. It is up to the device on how to indicate local or remote, for example by using the value #00FF00 for local and #FF0000 for remote.

Label

The Label property is usually a short text like “234” or “DND”. The text for the label is encoded in UTF-8 format. Devices that do not support the complete UTF-8 character set must select a suitable replacement for characters that cannot be displayed.

Caller-ID

As the Label, the Caller-ID is a text in UTF-8 format that is associated with the button. Typically, this text is longer than the Label and displayed in a different part of the device.

Action and Number

When the user presses the key, the device will either dial a number or send a message to the registrar.

• If the Action is set to "invite", then the device initiates a call. The destination of the call is provided in the Number property.
• If the Action is set to "message", then the device will send an instant message to the provided number. The message will not contain any message; the destination must be able to tell by the number what the action's purpose is.

The default for this property is "invite".

The Number tells the device what number to dial. If the Number is not available, the device will not perform any action.

Button Release

Usually the event to initiate the Action is the pushing of a button. However, some applications require that actions take place upon the release of a button, for example the push to talk application.

If the property is set to "hangup" then the endpoint must terminate the started call when the button is released. If the property is set to "ignore" then the releasing of the button does not matter. Setting the value to "engage" means that the pushing of the button should be ignored and the endpoint should wait until the button is released before the action should be performed. The default value is "ignore".

Syntax Description

The syntax for the buttons document is as follows:

buttons = *(property) CRLF
property = 1*(name | light / color / caller / number / action / release / label) 
name = "k=" text CRLF
light = "c=" ("off" / "on" / "hold" / "pickup" / "park" / "message" / "offline" / "error") CRLF
color = "o=" ("local" / "remote" / other-color) CRLF
caller = "i=" text CRLF
number = "n=" text CRLF
action = "a=" ("invite" / "message") CRLF
release = "r=" ("ignore" / "hangup" / "engage") CRLF
label = "l=" text CRLF
other-color = "#" 6*HEXDIG
text = TEXT-UTF8-TRIM
TEXT-UTF8-TRIM = 1*TEXT-UTF8char *(*LWS TEXT-UTF8char)
TEXT-UTF8char = %x20-7E / UTF8-NONASCII
UTF8-NONASCII = %xC0-DF 1UTF8-CONT / %xE0-EF 2UTF8-CONT / %xF0-F7 3UTF8-CONT / %xF8-Fb 4UTF8-CONT / %xFC-FD 5UTF8-CONT
UTF8-CONT = %x80-BF
LWS = [*WSP CRLF] 1*WSP
WSP = %x20

Examples

Extension Monitoring

The device registers:

REGISTER sip:localhost SIP/2.0
Via: SIP/2.0/TLS 172.20.25.101:2048;branch=z9hG4bK-2kecpl491c02;rport
From: "44"  <sip:44@localhost>;tag=3k4xrbtmm9
To: "44" <sip:44@localhost>
Call-ID:3c358c7680cb-j9yamlvac7ak
CSeq: 4655 REGISTER
Max-Forwards: 70
Contact: <sip:44@172.20.25.101:2048;transport=tls;line=44qsudyt>;+sip.instance="<urn:uuid:b255d09d-7a6e-4ad3-9ffb-eeacc9f87d52>"
Supported: buttons
Expires: 3600
Content-Length: 0

The registrar answers:

SIP/2.0 200 Ok
Via: SIP/2.0/TLS 172.20.25.101:2048;branch=z9hG4bK-zwua4nsg3ene;rport=4392
From: <sip:44@localhost>;tag=m6b9kc2vom
To: <sip:44@localhost>;tag=651e0392d2
Call-ID: 3c358c388712-ebd63gd3yujl
CSeq: 2 SUBSCRIBE
Contact: <sip:172.20.25.102:5061;transport=tls>
Required: buttons
Expires: 0
Content-Length: 0

The registrar sends the initial state for all available keys:

MESSAGE sip:44@172.20.25.101:2048;transport=tls;line=44qsudyt SIP/2.0
Via: SIP/2.0/TLS 172.20.25.102:5061;branch=z9hG4bK-6fa3b6d82ceb544b5912c20f0dba8efc;rport
From: <sip:44@localhost>;tag=38473
To: <sip:44@localhost>
Call-ID: 6algjorv@pbx
CSeq: 59620 MESSAGE
Max-Forwards: 70
Contact: <sip:172.20.25.102:5061;transport=tls>
Subject: buttons
Content-Type: application/x-buttons
Content-Length: xxx

k=1
 
k=2

k=3
l=42

k=4
c=on
n=79
a=invite
l=Office Hours

The device acknowledges the message from registrar:

SIP/2.0 200 Ok
Via: SIP/2.0/TLS 172.20.25.102:5061;branch=z9hG4bK-6fa3b6d82ceb544b5912c20f0dba8efc;rport=5061
From: <sip:44@localhost>;tag=38473
To: <sip:44@localhost>
Call-ID: 6algjorv@pbx
CSeq: 59620 MESSAGE
Content-Length: 0

Then there is a call coming in for that extension. The registrar sends a message to the phone.

MESSAGE sip:44@172.20.25.101:2048;transport=tls;line=44qsudyt SIP/2.0
Via: SIP/2.0/TLS 172.20.25.102:5061;branch=z9hG4bK-4787b876bfb9e8c4f88d92ba60ae841a;rport
From: <sip:44@localhost>;tag=3190
To: <sip:44@localhost>
Call-ID: dff6oe9e@pbx
CSeq: 10489 MESSAGEMax-Forwards: 70
 Contact: <sip:172.20.25.102:5061;transport=tls>
Subject: buttonsContent-Type: application/x-buttons
Content-Length: 42

k=3
l=42
c=pickup
i=19781234567
n=*6013
a=invite

The phone changes the state of the key, shows the caller-ID of the incoming call and acknowledges the message:

SIP/2.0 200 Ok
Via: SIP/2.0/TLS 172.20.25.102:5061;branch=z9hG4bK-7503bc4aa511b81660f727778b046e7b;rport=5061
From: <sip:44@localhost>;tag=9305
To: <sip:44@localhost>
Call-ID: y8ix5y63@pbx
CSeq: 20986 MESSAGE
Content-Length: 0

In the meantime, the user of the device decides not to pick up that call. If the user would pick up the call, the device would send out an INVITE request that dials *6013 in the domain of the registrar. Instead, the original caller cancels the call and clears the line. The registrar also clears the line by sending a message to the device:

MESSAGE sip:44@172.20.25.101:2048;transport=tls;line=44qsudyt SIP/2.0
Via: SIP/2.0/TLS 172.20.25.102:5061;branch=z9hG4bK-2909fe081f8466c9836c3b673f284842;rport
From: <sip:44@localhost>;tag=17820
To: <sip:44@localhost>
Call-ID: umceg9jb@pbx
CSeq: 35160 MESSAGEMax-Forwards: 70
Contact: <sip:172.20.25.102:5061;transport=tls>
Subject: buttons
Content-Type: application/x-buttons
Content-Length: 7

k=3
l=42

The device clears the LED and acknowledges the message:

SIP/2.0 200 Ok
Via: SIP/2.0/TLS 172.20.25.102:5061;branch=z9hG4bK-0e03052c9f670a0be768b95cc95d1700;rport=5061
From: <sip:44@localhost>;tag=62275
To: <sip:44@localhost>
Call-ID: umceg9jb@pbx
CSeq: 35160 MESSAGE
Content-Length: 0

Seizing Shared Line

In this example, only the documents are shown. The SIP message flow is similar to the previous example.

First, the registrar sends a document to the device that sets the code to seize the line.

k=co1
a=message
n=*602co1

The user decides to seize the line and sends a message to the registrar:

MESSAGE sip:*602co1@localhost SIP/2.0Via: SIP/2.0/TLS 172.20.25.101:2048;branch=z9hG4bK-g4gdihbkjd;rport
From: <sip:44@localhost>;tag=17820
To: <sip:44@localhost>
Call-ID: wefdapdg@pbx
CSeq: 54654 MESSAGE
Max-Forwards: 70
 Contact: <sip:44@172.20.25.101:2048;transport=tls;line=44qsudyt>
Subject: buttons
Content-Length: 0

The registrar sends a document to the device that sets the code to seize the line. The same document will also be sent to other devices that show the same line:

k=co1
a=message
c=on
n=*603co1

If the user would place a call, the registrar associates the call with the seized line. However the user changes his mind and wants to release the line. The device then sends a similar message like above, but using the changed destination. The registrar then releases the line and updates the device with the original document shown on the top of this example.

Turning DND On and Off

From a device perspective, there is only little difference between seizing a line and turning DND on and off. First, the registrar would send a document like this:

k=4
l=DND
n=*78
a=message

The user decides to seize the line and sends a message to the registrar. The registrar answers with an updated button state:

k=4
c=offline
l=DND
n=*79
a=message