Snom Service Hub

Space shortcuts

Content

Page tree


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 or on customer 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.

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 implements with a LED diode.

  • 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 identity the button that should be changed. The name itself is a text. Snom phones can handle numbers from 1 to MaxNumbersOfLinekeys (e.g.: 370: 12 + 3(expansion modules) * 42(keys each)) and the name "dnd".
    Please note that you must only enter an integer number as described above or the word 'dnd' here.

  • 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
    This feature is currently only working on snom820 and snom821. Valid colors values are:

    "local" (which will light up green on 820)
"remote" ( = red on 820) 
"red", "green" and "orange"
  • 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 reasonable 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.

  • Direction
    The direction for a call can be inbound or outbound. The direction depends on the monitored resource.

  • Display-Name
    The Display-Name is a text in UTF-8 format that is associated with the button. Typically, this text is used for the person’s name that is associated with the extension.

  • Action and Number
    Then 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 devices 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".

  • MWI
    If there are messages waiting the PBX will set the number of new and saved messages in the MWI field.

  • Call Forward
    When the user programs call forward, the PBX can send the Forward information. It includes the type of the forwarding and the forwarding destination.

  • Other Actions
    In order to be able to perform other actions like call pickup from the virtual extension board, the possible actions can be listen


Syntax Description

The syntax for the buttons document is below. Please not that the button name (k=1,2,3,...) must be the first entry!

buttons         = *(property) CRLF
 property        = 1*(name | light / color / caller / destination
               / action / release / label / display-name
               / mwi / treatment / extension)
 action          = "a=" ("invite" / "message") CRLF
 light           = "c=" ("off" / "on" / "hold" / "pickup" / "park")
 display-name    = "d=" text CRLF
 forward         = "f=" ("always" / "busy") text CRLF
 caller          = "i=" text CRLF
 direction       = "b=" ("in" / "out") CRLF
 name            = "k=" text CRLF
 label           = "l=" text CRLF
 mwi             = "m=" number "/" number CRLF
 destination     = "n=" text CRLF
 color           = "o=" ("local" / "remote" / other-color) CRLF
 release         = "r=" ("ignore" / "hangup" / "engage") CRLF
 state           = "s=" *("dnd" / "logoff" / "offline") CRLF
 treatment       = "t=" token " " text CRLF
 type            = "x=" ("ext" / "queue" / "group" / "line" / "flag" / "conf" / "mwi") CRLF
 other-color     = "#" 6*HEXDIG
 token           = 1*TEXT-ASCII
 text            = TEXT-UTF8-TRIM
TEXT-UTF8-TRIM  = 1*TEXT-UTF8char *(*LWS TEXT-UTF8char)
TEXT-ASCII      = %x21-7E
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

Sipsak Example

This example shows how you can turn the LED from Function key 1 on (or off)

Phone configuration:

Setup Function key 1 in "Function Keys" as in the following image:


Set in your identity configuration, on SIP tab "Support broken Registrar" to on:


Set in the advanced configuration, on SIP/RTP tab "Network identity (port):" to 5060:


Set in the advanced configuration, on QoS/Security tab " Filter Packets from Registrar:" to off:

In this example the phone have the IP-address 192.168.0.11, the PC where sipsak is installed have the IP-address 192.168.0.12.


Create a file with the name led.txt and the following content:

MESSAGE $user$@$dsthost$;transport=udp SIP/2.0
From: sip:sipsak@$srchost$:1036;tag=38473
To: $user$@$dsthost$
Call-ID: 6algjorv@test
CSeq: 59620 MESSAGE
Max-Forwards: 70
Contact: < $user$@$dsthost$;transport=udp>
Subject: buttons
Content-Type: application/x-buttons
Content-Length: 10

k=1
c=on

The value "Content-Length:" must be the count of every following character and all CR. In this example, there is a CR after c=on.

Now you can use the created file with sipsak to send the notify to the phone:

sipsak -G --hostname 192.168.0.12 -s sip:<identity>@192.168.0.11 --filename led.txt

Remember to set <identity> to whatever is your identity in your phone, e.g. 1004.

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 registrar sends the initial state for all available keys:

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 MESSAGE
 Max-Forwards: 70
 Contact: <sip:172.20.25.102:5061;transport=tls>
 Subject: buttons
 Content-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 MESSAGE
 Max-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 a Shared Line

The LED Remote Control can also be used to enable shared lines. Here is an example of extensions 402 add 404 sharing the same line. (using 'pbxnsip' IP PBX) First, the registrar sends a document to both devices that sets the code to seize the line:

Extension 404 receives:

MESSAGE sip:404@192.168.168.179:2049;line=lsya6qco SIP/2.0
Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK- 1a64743e72cf5c427eb84769aaf20942;rport
From: <sip:404@lab.example.local>;tag=1055271156
To: <sip:404@lab.example.local>
Call-ID: vd0vx77u@pbx
CSeq: 659894852 MESSAGE
Max-Forwards: 70
Contact: <sip:192.168.168.254:5060;transport=udp>
Subject: buttons
Content-Type: application/x-buttons
Content-Length: 36

k=2
n=*602co2
a=seize
l=(co2)

Extension 402 receives:

MESSAGE sip:402@192.168.168.174:1026;line=lkijv265 SIP/2.0
Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK-cf31d87399a21f65b5ed05261a40b674;rport
From: "test two" <sip:402@lab.example.local>;tag=595214548
To: "test two" <sip:402@lab.example.local>
Call-ID: 33una09m@pbx
CSeq: 941367575 MESSAGE
Max-Forwards: 70
Contact: <sip:192.168.168.254:5060;transport=udp>
Subject: buttons
Content-Type: application/x-buttons
Content-Length: 36

k=2
n=*602co2
a=seize
l=(co2)

The owner of extension 404 decides to seize the line and sends a message to the registrar:

MESSAGE sip:404@lab.example.local SIP/2.0
Via: SIP/2.0/UDP 192.168.168.179:2049;branch=z9hG4bK-cr9drb5v0e5s;rport
From: "404" <sip:404@lab.example.local>;tag=xt6v6wiw19
To: <sip:*602co1@lab.example.local>;tag=4bmp7edhiz
Call-ID: 3c2677851b18-e6amwgoglprw
CSeq: 1 MESSAGE
Max-Forwards: 70
Proxy-Require: buttons
Content-Type: application/x-buttons
Content-Length: 65

k=1
a=seize
t=<urn:uuid:074b68b9-bff6-450c-bc50-4c44de86c11f>

The registrar sends all the extensions (in our case 402 and 404) the message that the corresponding led must be turned on (c=on) because the line has been seized:

Extension 404 receives:

MESSAGE sip:404@192.168.168.179:2049;line=lsya6qco SIP/2.0
Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK-418c1f6ba64938e7f06c3d2cbc1742d7;rport
From: <sip:404@lab.example.local>;tag=2088697387
To: <sip:404@lab.example.local>
Call-ID: iotsiv8r@pbx
CSeq: 710797425 MESSAGE
Max-Forwards: 70
Contact: <sip:192.168.168.254:5060;transport=udp>
Subject: buttons
Content-Type: application/x-buttons
Content-Length: 44

k=1
c=on
n=*603co1
a=release
l=(co1)

Extension 402 receives:

MESSAGE sip:402@192.168.168.174:1026;line=lkijv265 SIP/2.0
Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK-b3f0a2dcde374d38c8639b9014be72e9;rport
From: "test two" <sip:402@lab.example.local>;tag=161479004
To: "test two" <sip:402@lab.example.local>
Call-ID: fd030tf2@pbx
CSeq: 1140889180 MESSAGE
Max-Forwards: 70
Contact: <sip:192.168.168.254:5060;transport=udp>
Subject: buttons
Content-Type: application/x-buttons
Content-Length: 44

k=1
c=on
n=*603co1
a=release
l=(co1)

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:

MESSAGE sip:404@lab.example.local SIP/2.0
Via: SIP/2.0/UDP 192.168.168.179:2049;branch=z9hG4bK-8zk1koi94fn3;rport
From: "404" <sip:404@lab.example.local>;tag=zbjfdm9vbn
To: <sip:*603co2@lab.example.local>;tag=5z3zroft6v
Call-ID: 3c2677851b18-e6amwgoglprw
CSeq: 1 MESSAGE
Max-Forwards: 70
Proxy-Require: buttons
Content-Type: application/x-buttons
Content-Length: 67

k=2
a=release
t=<urn:uuid:074b68b9-bff6-450c-bc50-4c44de86c11f>

The registrar then releases the line and updates the devices 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

Further Information


Related articles