Category:HowTo:LED Remote Control
From Snom User Wiki
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.
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
Virtual Extension Board
When the extension board runs on a standard computer with color display and rich rendering options, there are a number of additional requirements:
- Display Name: Users want to see the real name associated with the extension in addition to the extension number.
- Status: Users also want to see if the extension has its "do not disturb" status set and if the extension is logged in as agent.
- Redirection: If a call has been redirected, the number where the call has been redirected to should be shown.
- Direction: If should be possible to see if someone called or has been called.
- Mailbox Status: If there are messages waiting, the virtual extension board can also display that information.
- Queue Status and Park Orbits: When monitoring queues, it is interesting to see the Name, caller-ID and the waiting time of the caller.
There are several actions that a virtual extension board can perform:
- Starting and stopping call recording: The operator may start and stop call record by clicking on the call associated with the extension.
- Picking up calls: It must be possible to perform remote picking up of calls and send them to an associated handset.
- Moving calls: It must also be possible to distribute calls for example from a queue to an extension.
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 with the keys. It must be possible to automatically provision the devices for the usage of the buttons. The provisioning process is not scope of this document. However, the provisioning must take care about
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
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.
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.
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.
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.
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.
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.
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.
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).
"local" (which will light up green on 820) "remote" ( = red on 820) "red", "green" and "orange"
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.
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.
The direction for a call can be inbound or outbound. The direction depends on the monitored resource.
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.
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".
If there are messages waiting the PBX will set the number of new and saved messages in the MWI field.
When the user programs call forward, the PBX can send the Forward information. It includes the type of the forwarding and the forwarding destination.
In order to be able to perform other actions like call pickup from the virtual extension board, the possible actions can be listen
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)
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 wit 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:firstname.lastname@example.org: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:email@example.com: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=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:firstname.lastname@example.org: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:email@example.com: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
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
Using with snom ONE
If you are using snom ONE provisioning, there is nothing that must set manually on the phone.
But if you are not using provisioning and you want set this up manually, you must:
- first set user_proxy_require to "buttons", and then Re-register the phone.
- Setup the Function key in "Function Keys" as in the following image:
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:firstname.lastname@example.org:2049;line=lsya6qco SIP/2.0 Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK- 1a64743e72cf5c427eb84769aaf20942;rport From: <sip:email@example.com>;tag=1055271156 To: <sip:firstname.lastname@example.org> 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:email@example.com:1026;line=lkijv265 SIP/2.0 Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK-cf31d87399a21f65b5ed05261a40b674;rport From: "test two" <sip:firstname.lastname@example.org>;tag=595214548 To: "test two" <sip:email@example.com> 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:firstname.lastname@example.org SIP/2.0 Via: SIP/2.0/UDP 192.168.168.179:2049;branch=z9hG4bK-cr9drb5v0e5s;rport From: "404" <sip:email@example.com>;tag=xt6v6wiw19 To: <sip:*firstname.lastname@example.org>;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:email@example.com:2049;line=lsya6qco SIP/2.0 Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK-418c1f6ba64938e7f06c3d2cbc1742d7;rport From: <sip:firstname.lastname@example.org>;tag=2088697387 To: <sip:email@example.com> 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:firstname.lastname@example.org:1026;line=lkijv265 SIP/2.0 Via: SIP/2.0/UDP 192.168.168.254:5060;branch=z9hG4bK-b3f0a2dcde374d38c8639b9014be72e9;rport From: "test two" <sip:email@example.com>;tag=161479004 To: "test two" <sip:firstname.lastname@example.org> 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:email@example.com SIP/2.0 Via: SIP/2.0/UDP 192.168.168.179:2049;branch=z9hG4bK-8zk1koi94fn3;rport From: "404" <sip:firstname.lastname@example.org>;tag=zbjfdm9vbn To: <sip:*email@example.com>;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
This category currently contains no pages or media.