Category:HowTo:LED Remote Control

From Snom User Wiki

(Redirected from Features/LED Remote Control)
Jump to: navigation, search

Contents

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.

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

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.


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

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

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 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:

Image:message_setup_index.jpg

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

Image:sipsack_led_notify_01.jpg

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

Image:sipsack_led_notify_02.jpg

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

Image:sipsack_led_notify_03.jpg

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.

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


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:

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

Image:message_setup_index.jpg


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

This category currently contains no pages or media.

Personal tools
Interoperability