Xtensiontasten

Die Telefone der D-Serie verfügen über 18 bzw. 60 eingebaute Xtensiontasten. Jede Xtension verfügt ebenfalls über 60 Tasten. Im D-100/D-200 sind die Tasten neben dem Display angeordnet, im D-400/D-600 werden sie als Touch-Flächen auf dem Display realisiert. Die Tasten sind in drei Ebenen angeordnet, die auf jedem Modul separat gewechselt werden können. Die Nummerierung ist dabei durchlaufend, also z.B. beim D-100

  • Taste 1-6 (Ebene 1)
  • Taste 7-12 (Ebene 2)
  • Taste 13-18 (Ebene 3)

Die Tasten können flexibel konfiguriert werden. Zur Erleichterung werden eine Reihe von Vorlagen (Templates) angeboten.

Eine Taste können Sie konfigurieren mit

  • Aktionen
  • Reaktionen
  • Speziellen Funktionen

Aktionen sind Dinge, die ausgelöst werden, wenn eine Taste gedrückt wird. Eine Taste kann mehrere Aktionen auslösen.

Reaktionen sind Ereignisse die den LED-Status der Taste modifizieren. Mehrere Reaktionen können den LED-Status einer Taste festlegen. Die LED nimmt immer den Stand an, der als letztes gesetzt wurde.

Beispiel:

Eine Taste hat eine Aktion:

  • HTTP Request

und zwei Reaktionen:

  • statisch: LED auf rot
  • als Antwort auf HTTP-Request: grün

Die LED ist zuerst rot. Wenn eine Antwort auf den HTTP-Request eintrifft, wird die LED auf grün gesetzt.

Aktionen

  • setting
  • httpRequest
  • invite
  • intent
  • dialog

setting

Setzt eine lokale Konfigurationseinstellung.

Um diese Funktionstaste zu konfigurieren, definieren Sie den XPath und eine Liste mit Werten im XML-Code. Bei jedem Drücken der Funktionstaste stellt das Telefon den nächsten Wert in der Liste ein. Jeder Wert kann die LED auf einen bestimmten Wert setzen.

Beispiel: Umschalten des zuerst verwendeten Codecs zwischen G.722 und G.711

<key>
 <keyConfiguration>
   <function>
     <invocations>
       <invocation>
         <setting path="indentities//audiocodec[1]">
           <value color="green">G.722</value>
           <value color="red=">G.711</value>
         </setting>
       </invocation>
     </invocations>
   </function>
 </keyConfiguration>
</key>

httpRequest

Sendet einen HTTP(S)-Request.

Sie können die HTTP-Methoden GET und POST verwenden. Zusätzlich geben Sie die URI an, die aufgerufen werden soll.

Sie können zusätzliche Header mit übertragen lassen. Ausserdem können Sie den Inhalt des POST-Requests angeben.

Die Antwort des HTTP-Servers kann den LED an der Taste auf einen bestimmten Wert setzen.

Beispiel:

<key>
 <keyConfiguration>
   <function>
     <invocations>
       <invocation>
         <http>
           <request httpMethod="get">
             <uri>http://192.168.0.239/log</uri>
             <httpHeader header="called" value="77"/>
           </request>
         </http>
       </invocation>
     </invocations>
   </function>
 </keyConfiguration>
</key>

invite

Wählt eine Nummer über eine Identity.

Wenn Sie keine Identity angeben, wird die Standard-Identity verwendet.

Beispiel:

<key>
  <keyConfiguration>
    <function>
      <invocations>
        <invocation>
          <invite>
            <uri>77</uri>
          </invite>
        </invocation>
      </invocations>
    </function>
  </keyConfiguration>
</key>

intent

Startet eine App im Android-System über einen ''Intent''

Sie können für den Intent eine Aktion und ein oder mehrere Extras vorgeben.

Beispiel:

<key>
  <keyConfiguration>
    <function>
      <invocations>
        <invocation>
          <intent>
            <action>android.intent.action.CALL<action>
            <data>content://call_log/calls/1</data>
          </intent>
        </invocation>
      </invocations>
    </function>
  </keyConfiguration>
</key>

dialog

Zeigt einen Text kurz im Telefon-Display an.

Der Telefonbenutzer muss diesen Text nicht bestätigen.

Beispiel:

<key>
  <keyConfiguration>
    <function>
      <invocations>
        <invocation>
          <dialog>Funktion vom Systemverwalter gesperrt.</dialog>
        </invocation>
      </invocations>
    </function>
  </keyConfiguration>
</key>

Reaktionen

  • presence
  • http
  • ledSetting

presence

Presence ist die Kombination aller Information über die Erreichbarkeit eines Kontaktes. Diese beinhalten

  • Sip Subscriptions
  • entgangene Anrufe (TODO: gibs das wirklich? Beispiel oder weglassen)
  • XMPP-Presence-Status (TODO: gibs das wirklich? Beispiel oder weglassen)

Beispiel: Das folgende Beispiel zeigt die Verbindung von einer invite Aktion und der presence Reaktion um eine Zielwahltaste abzubilden.

<key>
  <keyConfiguration>
    <function>
      <invocations>
        <invocation>
          <invite>
            <uri>77</uri>
          </invite>
        </invocation>
      </invocations>
      <reactions>
        <reaction>
          <presence>
            <subscribe type="dialog">
              <uri>77</uri>
            </subscribe>
          </presence>
        </reaction>
      </reactions>
    </function>
  </keyConfiguration>
</key>
Sip Subscriptions

Sip subscriptions are one variant of a presence-reaction. Actually the only one at the moment. Currently only subscriptions of type „dialog“ are supported. The phone will start a SIP-subsription for every unique dialog-subscriptions it finds within its key-configurations.

multiple SIP-Registrations

You can specify which SIP-Registration to use if you have more than one. Do so by adding the Line-Property (see example below). The line-id's are the index of the identity within the identites-configuration [todo: link-to-wiki]. The first index has the number 1. If you have multiple SIP-Registrations but you don't supply the id to use, the subscription is issued using the currenty select default outgoing identity that is seen in the Phone's idle screen. A change of the default outgoing identity changes will NOT cause any re-subscribtions. So you really should define the identity if you use more than one.

dialog notifies

The PBX will send SIP notifies when a subscription is first established and whenever the dialog-state (sip dialogs aka calls) of the monitored party changes. The telephone protects itself of getting overwhelmed with analyzing too many dialog-notifies at a time. It only processes a maximum of 10 Notifies per second, all the others are queued and processed later. If the phone might discard notifies entirely if it gets bombarded with too many notifies so that the queue raises above 100.

Example of a dialog subscription configuration:

<subscribe type="dialog">
  <uri>42</uri>  
  <line>
    <id>1</id>
  </line>
</subscribe>

http

Wartet auf einen HTTP-Request.

Auf der defnierten URI wartet das Telefon auf Requests von einem Client. Die URI befindet sich in einem speziellen Bereich des Webservers. Dieser ist unter /api/v1/exec/<URI> zu finden.

In der Konfiguration können SIe eine Zuordnung von Header-Wert und LED Farbe beschreiben.

Beispiel:

<key>
  <keyConfiguration>
    <function>
      <reactions>
        <reaction>
          <http>
            <path>uri-77</path>
            <headers> 
              <led color="red">
              <header header="state" value="busy"/>
            </headers>
            <headers> 
              <led color="off>
              <header header="state" value="available"/>
            </headers>
          </http>
        </reaction>
      </reactions>
    </function>
  </keyConfiguration>
</key>

ledSetting

Setzt einmalig eine LED-Farbe.

Dies kann verwendet werden:

  • zum direkten Provisionieren des LED-Zustands
  • zum Setzen des Initialzustand

Beispiel:

<key>
  <keyConfiguration>
    <function>
      <reactions>
        <reaction>
          <ledSetting color="red" blinking="true"/>
        </reaction>
      </reactions>
    </function>
  </keyConfiguration>
</key>

Spezielle Funktionen

line

Die Funktion Line schaltet die Standard-Identity um. Diese wird für alle nicht genauer spezifizierten Wahlvorgänge genutzt.

Über den Parameter component können Sie eine andere auf dem Telefon vorhandene Telefonie-App angeben. Ansonsten beschreibt die Taste eine interne Identity des Telefons.

Beispiel:

<key>
  <keyConfiguration>
    <line>
      <id>61</id>
    </line>
  </keyConfiguration>
</key>

Programmiert ein eigenes Lua-Skript auf die Taste.

Dieses Skript kann die LED der Taste setzen und auf Betätigung der Taste reagieren. Über vom System bereitgestellte Schnittstellen können Rufe ausgelöst, Subscriptions eingelegt und ausgewertet und HTTP-Requests ausgelöst.

Für jede Taste existiert eine eigene Lua-Umgebung, in der Variablen und Funktionen angelegt werden können. Diese bleiben bestehen, solange die Taste belegt ist. Wird die Taste gedrückt, wird die Funktion `onKeyUp` (ohne Parameter) aufgerufen.

Die Umgebung ist Lua 5.2. Es stehen die Basisfuntionen sowie die Module ''bit32'', ''math'', ''string'' und ''table'' zur Verfügung.

Zusätzlich existieren die folgenden zusätzlichen Funktionen:

Diese Dokumentation entstand vor der Festlegung auf deutsch für das Entwickler-Wiki und ist daher auf Englisch. Die Formatierung orientiert sich an der Lua-Dokumentation (siehe Links oben), insbesondere die Groß- und Kleinschreibung der Überschriften.

Configuration

config.set(path, value)

Set a config value under path.

config.get(path)

Get a config value under path. Returns a string.

config.unregister(path, function)

Unregister callback function for the specified path.

config.register(path, function)

Register for notifications on the specified path.

The callback function is called with the changed path as first parameter. The return value is ignored.

HTTP Client Functions

http.request( url[, callback, [[[method, ] content, ] headers]])

Perform HTTP request manually specifying method, content and headers. Method defaults to GET. This function is called by get, post and put.

The response goes to the supplied callback function, which is called with three parameters:

  • responseCode is an integer HTTP response code (200, 404, …)
  • responseBody is a string with the content of the response body
  • responseHeaders is a table mapping string keys to string values

Any return value from the function is ignored.

You can optionally supply request headers as a table mapping string keys to string values.

http.get(url [, callback [, headers]])

Perform HTTP GET for url. See function request for details.

http.post(url [, callback [, content [, headers]]])

Perform HTTP POST for url, optionally sending content. See function request for details.

http.put(url [, callback [, content [, headers]]])

Perform HTTP PUT for url, optionally sending content. See funtion request for details.

JSON Functions

json.eval(str)

Parse a string and return a Lua table of the contents.

json.insert(object, [index,] value)

Insert a new element into a table representing a JSON array.

Also available on objects returned by functions of this module.

json.object([table])

Create a JSON object, optionally passing content as a lua table.

json.array([table])

Create a JSON array, optionally passing content as a lua table, which must have the semantics of a Lua array (integer keys starting at 1 and consecutive).

json.tostring(obj)

Return string representation of JSON object.

Also available as the __tostring metamethod on objects returned by functions of this module.

Key and Led Functions

Set LED corresponding to the key to the specified color. Allowed values are red, green, yellow and off. blink is a boolean, defaulting to false.

SIP Functions

sip.subscribe(uri [, type [, line]], callback)

Subscribe a resource. Type is an integer describing the Subscription type. Currently only 0 is supported for the dialog package. line is the number of the identity to use for subscription, defaults to the currently selected identity if not specified.

Return value is a userdata representing the subscription which can be used for unsubscribe.

On incoming Notify-messages the callback is called with three parameters:

  • data is the raw content of the notify message
  • url is the subscribed url as a string
  • identity is the number of the identity to use

The return value of the callback is ignored.

sip.unsubscribe(handle)

Unsubscribe a resource previously subscribed with subscribe.

sip.invite(uri [, pickup ][, line])

Send an invite, optionally attempting pickup if second parameter is true. identity is the number of the identity to use, defaults to the currently selected identity if not specified.

XML Functions

xml.new(tableOrTag)

Construct new XML object. If tableOrTag is a table, use it (and setup metatable for object-like access). If tableOrTag is a string, use it as the tag.

xml.append(obj, tableOrTag)

Construct new XML object like new and append it to the child elements of obj.

Also available on objects returned by function of this module.

Returns the newly created element.

xml.tag(obj [,tag])

Returns or sets the tag of the object. If tag is nil, returns the current tag, otherwise sets it to tag.

Also available on objects returned by functions of this module.

xml.appendtext(obj, text)

Append text to the xml object obj.

Also available on objects returned by functions of this module.

Returns the object.

xml.find(obj [, tag[, key[, value]]])

Find an element with tag tag and attribute key with value value. tag can be nil or "" to find an element with any tag. If key is not nil or "", the element must have an attribute with this key. If value is not nil, the attribute must have this value.

Also available on objects returned by functions of this module.

Returns the found object or nil if not found.

xml.tostring(obj)

Return string representation of XML object.

Also available as the __tostring metamethod on objects returned by functions of this module.

Beispiele

<key>
  <keyConfiguration>
    <lua>
      <code>
      --[===]simple script used for setting LED's[===]--
      local state = 0
      --[===]onKeyUp is called when the key is released[===]--
      function onKeyUp()
        state = (state + 1) % 7
        if state == 0  then
            --[===]set the configured key LED to off[===]--
            key:setLed( "off" )
        elseif state == 1 then
            key:setLed( "red" )
        elseif state == 2 then
            key:setLed( "red", true )
        elseif state == 3 then
            key:setLed( "orange" )
        elseif state == 4 then
            key:setLed( "orange", true )
        elseif state == 5 then
            key:setLed( "green" )
        else
            key:setLed( "green", true )
        end
    end</code>
    </lua>
  </keyConfiguration
</key>
TODO weitere Beispiele, z.B. CFU oder Zielwahl

Die Tastenfiguration ist sehr flexibel, aber für den Benutzer nicht zumutbar. Der Benutzer möchte eine Funktion nach bekannten Namen auswählen und die nötigen Parameter eingeben können.

Durch Vorlagen (Templates) können Sie eine Summe von Aktionen und Reaktionen zusammen mit einstellbaren Parametern definieren. Das Telefon fraget Endkunden im UI abgefragt werden und dann auf die Taste programmiert werden.

Ein Template besteht aus einer unparametrisierten Konfiguration und einer Liste von Parametern. Diese können teilweise optional sein. Die zu konfigurierenden Parameter werden als ''XPath'' beschrieben.

Die definierten Templates sind Teil der Konfiguration des Telefons. Sie können also vom Einrichter überschrieben, angepasst oder durch eigene Templates ergänzt werden. Der Name des verwendeten Templates wird im Parameter templateName in der Konfiguration der Taste abgelegt. Dies erlaubt eine nachträgliche Modifikation der Parameter auf der Taste.

Beispiel: Template für Zielwahl

<template>
  <name>speed_dial</name>
  <description>Dial a specific Number</description>
  <keyConfiguration>
    <function>
      <invocations>
        <invocation>
          <invite>
            <uri/>
          </invite>
        </invocation>
      </invocations>
      <reactions>
        <reaction>
          <presence>
            <subscribe type="dialog">
              <uri/>
            </subscribe>
          </presence>
        </reaction>
      </reactions>
    </function>
  </keyConfiguration>
  <parameter path="//uri" description="speed_dial_uri"/>
</template>

Hier würde bei der Konfiguration der Paramater speed_dial_uri abgefragt und alle <uri>-Elemente mit dem abgefragten Wert gefüllt.

Beispiel:LUA Template Teilnehmer CFU in Auerswald TK-Anlage

<template>
  <name>
    <text>Int. CFU in TK</text>
  </name>
  <keyConfiguration>
    <lua>
      <code>
        local valid = false
        local active = false
        local on = "*21*"
        local off = "#21#"
        local userpath = "/identities/identity["..identity.."]/"
        local host = config.get(userpath .. "host")
        local user = config.get(userpath .. "username")
 
        local function updateLed()
          if valid then
            if active then
              key:setLed( "green" )
            else
              key:setLed( "off" )
            end
          else
            key:setLed( "red", true )
          end
        end
 
        local unescape = function(url)
          return url:gsub("%%(%x%x)", function(x) return string.char(tonumber(x, 16)) end )
        end
 
        local function check_sub(data, uri, handle)
          local x = xml.eval(data)
          local test_uri_on = "sip:"..on..target.."#"..user.."@"..host
          if unescape(uri) == test_uri_on then
            for _,dlg in ipairs(x) do
              state = dlg:find("state") 
                if state and state[1] == "trying" then 
                  active = true
                elseif state and state[1] == "terminated" then
                  active = false
                end
              end
            end
          updateLed()
        end
 
        local function check_valid()
          if identity == "" or target== "" then
            valid = false
          else
            valid = true
          end
        end
 
        local function sub()
          sip.subscribe(on..target.."#"..user,"0",identity,check_sub)
        end
 
        function onKeyUp()
          if active and valid then
            sip.invite(off.."#"..user)
          elseif valid then
            sip.invite(on..target.."#"..user)
          end
        end
 
        check_valid()
        sub()
      </code>
      <params>
        <param name="identity"/>
        <param name="target"/>
      </params>
    </lua>
  </keyConfiguration>
  <parameters>
    <parameter>
      <path>//param[@name="identity"]/value</path>
      <name>
        <text>identity</text>
      </name>
    </parameter>
    <parameter>'
      <path>//param[@name="target"]/value</path>
       <name>
         <text>target</text>
       </name>
     </parameter>
   </parameters>
 </template>

Hier würde bei der Konfiguration die Paramater identity und target abgefragt und dem LUA Code als Variable zur Verfügung gestellt.