====================== Node-RED voipio-socket ====================== A set of `Node-RED `_ nodes that integrates websocket connections of a `innovaphone `_ pbx with myApps into Node-RED. Installation ============ Ideally, install from the package manager inside Node-RED. Alternatively, install from `npm `_:: npm install trizwo-node-red-contrib-voipio-socket Successfully Tested With ------------------------ - Pbx Version 13r2 sr11 - Pbx Version 13r3 beta1 Usage ===== You need access to the pbx to be able to set up app one or more app objects. An app platform is not required. The package installs several nodes in your node palette: .. thumbnail:: images/nodepalette.png To get started you need a ``AppService`` node first. .. thumbnail:: images/edit_appservice.png In its settings you assign a websocket path and the password that the app objects needs to log in to your AppService. Then go to the Pbx and create a App Object with the Url and password entered above: .. thumbnail:: images/pbxappobject_1.png .. thumbnail:: images/pbxappobject_2.png Please note that this example uses unencrypted http connections. In production, you will probably use https instead. Which of the APIs need to be enabled depends on your usecase. For demo purposes, we enable all of the them. If everything went well, the Pbx App object should now be connected to the Node-RED AppService and we see an active connection on the AppService node. .. thumbnail:: images/appservice_with_connection.png Example: Boolean State via PbxApi ================================= This example is shipped with the nodes in Node-RED and can be imported as a ready-to-use flow via the top right menu ``Import/Examples/Boolean Example``. .. thumbnail:: images/example_pbxapi_boolean.png 1. the connection to and from the Pbx Object -------------------------------------------- We use an ``AppService node`` as described above so that a Pbx object establishes a connection to Node-RED. When a pbx connects, the AppService node handles the authentication. If the authentication is successful, a message is sent on the output of the AppService. 2. when a pbx object is connected, subscribe for the presence ------------------------------------------------------------- We use a ``filter node``, that only passes messages with the ``OnPbxConnect`` topic. .. thumbnail:: images/filter_onpbxconnect.png This message is then used as event to send back a ``SubscribePresence`` to the pbx on this connection. .. thumbnail:: images/message_subscribe_presence.png With this type of messages we register the node for Presence Updates of a Pbx object with the ``businesshours``. When an object's Presence changes, a event sent from the pbx to Node-RED and the AppService node send it then to the flow. The ``PresenceUpdate`` messages from the Pbx will contain the value from the ``src=businesshours`` parameter. We will use this later to map incoming updates to a subcription. 3. when a message with a PresenceUpdate comes in ------------------------------------------------ When a ``PresenceUpdate`` message is received from the Pbx, this message comes out of the AppService node. We then use a filter node again to allow only these types of messages with the subject through. .. thumbnail:: ./images/filter_pbxapi.png The ``PresenceUpdate`` messages contain the current status of the Pbx object for which the subscription has been set up. The presence updates of Boolean objects will contain a note depending on the state. If the Boolean is true, the message contains a Presence with the note parameter set to ``#badge:✓``. If the Boolean is false, the parameter note is missing on the message. This can then be translated to a Javascript true/false with a function node. .. thumbnail:: images/function_translate_booleanpresence_to_truefalse.png On the output of this function node we will now receive messages with ``msg.payload`` = true or false. .. thumbnail:: images/status_boolean_truefalse.png And with the message we can switch anything in Node-RED as we like. .. thumbnail:: images/switch_anything_in_nodered.png * switch a Hue light on or off * switch only the color of a hue light from red to green or back. * send the boolea nstate to a backend REST Api via HTTP GET/POST * toggle a switch in the Node-RED Dashboard * send the boolean state to a MQTT Broker License ======= GNU GENERAL PUBLIC LICENSE This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. Support ======= If you need advice or help with configuring or would like to have new features built in, there is the possibility of commercial support for a fee. In this case please contact ``trizwo GmbH IT & Communication``, Glinde, Germany. Information on how to contact us can be found on our website `trizwo.de `_. Authors ======= - Rico Schulte, trizwo GmbH IT & Communication `support@trizwo.de `_ `trizwo.de `_