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.
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.
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.
| 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" |
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.
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 |
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. |
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 |
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.
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 |