remote-phone-control 0.1.0

Description:

remotephonecontrol 0.1.0

Remote Phone Control - v0.1.0
Some SIP hardphone brands support the features Action URIs and Action URLs on some or all of their phone models. Action URIs are used to remote control a phone by sending it HTTP GET requests. E.g., place a call. Action URLs are used to communicate events occuring on a phone to an HTTP service. E.g. an incoming call.

This Python package primarily serves as a remote controller and a listener for the call related commands to and events from a phone. Its main intent and focus is to automate the testing of call scenarios.

Supported phones
In principle, Remote Phone Control, could be extended to support any phone that provides the Action URI and Action URL features. Currently, only the SNOM models noted under the Stack heading are tested and supported.
Action URIs and methods
These are HTTP GET requests with query parameters to control a phone, make it do something. remote_phone_control hides the URIs and query parameters in a phone class object, e.g. Snom, and its methods. The methods are mapped to and use corresponding URI and query parameters. The table below lists currently implemented methods for Snom class objects. The method names are quite self explanatory. A description is provided if more clarification is needed. Consult SNOM Remote phone control via http for reference.



Method
Arguments
Returns
Description




callout
number: str
bool



pickup
None
bool



hangup
None
bool



hangup_onhook
None
bool



hangup_all
None
bool



senddtmf
digits: str
bool
Send in-band DTMF


senddtmf_sipinfo
digits: str
bool
Send DTMF using SIP-INFO


expect
event: Literal['incoming', 'connect', 'disconnect'], timeout: int = event_wait_timeout
bool
Returns True if your expectation was correct. The default timeout to wait for the event is 15 seconds


clear_events
None
None
Call this together with hangup_all in case a test goes awry and phones are left with dangling, standing calls.


set_disable_speaker
value: Literal['on', 'off']
bool
Turn audible cues/ the speaker on or off


set_setting
setting: str, value: str
bool
setting is the name of the phone setting you want to set to value. For settings name reference browse to the phone's settings page: http://<phone's ip-address>/settings.htm


press_px
x: str
bool
Simulates pressing a free programmable function key


transfer
None
bool



reboot
None
bool



stop
None
None
When you're done consuming Snom, you MUST call stop to stop the Snom's Action Server



Action URLs and handled events
A phone will send an HTTP GET request to the Action URL when triggered by an event. The remote_phone_control package is the endpoint, target, of the request. It will parse and process the request.
Event to Action URL mappings
The events currently handled by remote_phone_control are per the following table.



Event
Description
Action URL used by the phone




Incoming call
There is an incomming call, the phone is ringing
http://<remote_phone_control ip-address>:<port>/event?ip=$phone_ip&event=incoming&local=$local&remote=$remote


On Connected
Fired when a call is established
http://<remote_phone_control ip-address>:<port>/event?ip=$phone_ip&event=connected&local=$local&remote=$remote


On Disconnected
A call is ended
http://<remote_phone_control ip-address>:<port>/event?ip=$phone_ip&event=disconnected&local=$local&remote=$remote



With remote_phone_control you can use these events as verification points when testing a call. E.g., when a phone is called, we can verify if there is an incoming call. When the call is answered, we can check if there's an established call.
For further reference on Action URL s consult SNOM Action URLs
Action URL, format and query parameters
The Action URL is configured on the phone. remote_phone_control will configure this automatically on the phone given the ip-address of the phone. See Usage for an example.
Below, the format used by remote_phone_control to set the Action URL on the phone.
http://<Remote Phone Controller ip-address>:<port>/event?ip=$phone_ip&event=<event>&local=$local&remote=$remote


<Remote Phone Controller ip-address>: The ip-address of the node where a remote_phone_control package is run.
<port>: The Action server port served by remote_phone_control
$phone_ip: A phone variable that will be replaced by the phone's ip-address
<event>: indicates to remote_phone_control what event triggered the request

Currently remote_phone_control parses and handles the following <event>s

incoming
connected
disconnected




$local: A phone variable that will be replaced by the local sip-id related to the event
$remote: A phone variable that will be replaced by the remote sip-id related to the event

Stack
This was used to develop and test the package. Not to say that other combinations of, e.g., Python, Ubuntu, phone models, phone firmware might also work. The SNOM models used are not very recent though. End of life even. So, no guarantees that the package will work for newer models unmodified. But my first impression after skimming through the documentation of recent SNOM models is that the Action URI and Action URL support looks very similar.

Python: 3.8.10
Ubuntu: 20.04.6 LTS
This Python package was tested with the following SIP hardphones


SNOM



Model
Firmware




300
8.7.3.19, 8.7.3.25 8.7.5.17


320
8.7.3.19, 8.7.3.25 8.7.5.17


360
8.7.3.19, 8.7.3.25







Installation
From PyPI
(venv) $ pip install remote-phone-control

From GibHub
(venv) $ pip install git+https://github.com/p4irin/remote_phone_control.git

Verify
(venv) $ python
Python 3.8.10 (default, May 26 2023, 14:05:08)
[GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import remote_phone_control
>>> remote_phone_control.__version__
'0.0.1'
>>> import remote_phone_control.snom
>>> dir(remote_phone_control.snom)
['ActionServer', 'Literal', 'Snom', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'requests']
>>>

Usage
Preconditions
A list of what to account for in order to remote control phones for test automation.

Networking

Preferably use a setup where the node, on which remote_phone_control is running, the phones, the registrar and the call proxy are on the same subnet
If remote_phone_control, the phones, the registrar and the call proxy are on different subnets, make sure they can see, reach each other. E.g., look at you're routing configuration.
No firewall between remote_phone_control and phones
No firewall on remote_phone_control 's node, Ubuntu, as mentioned under Stack
No NAT between remote_phone_control and phones


The phones MUST be provisioned and working

Are registered
Can call each other
Can, optionally, call out to PSTN
Can, optionally, receive incoming calls originating from the PSTN


What data you need

ip addresses of the phones
the username and password of the phones
allocate, list an Action server port for each phone. Each phone will be controlled by a separate instance of a phone class object, e.g. Snom, that will also handle a phone's events through an Action URL
ip address of remote_phone_control 's node. This will be used as the Action server's ip-address for each phone object as you can control several phones from the same node.
a sip-id (outgoing URI) on the phone to use for call operations.



Basic examples
The examples given are included in the package's source as unit tests, in the tests sub directory. The package's tests use Python's standard library unit testing framework. For simplicity's sake, the examples below do not.
Imports and Snom instances
These imports and Snom instantiations must precede all the standalone examples.
import time
from remote_phone_control.snom import Snom


snom_a = Snom(
"nnn.nnn.nnn.nnn", # ip-address of a SNOM phone
"nnn.nnn.nnn.nnn", # Action Server's ip-address
nnnn, # Action Server's listening port
"username", # username to access the SNOM
"password", # password to access the SNOM
"outgoing URI", # a sip-id configured on the SNOM
"extension" # the SNOM's extension
)

snom_b = Snom(
"nnn.nnn.nnn.nnn",
"nnn.nnn.nnn.nnn",
nnnn,
"username",
"password",
"outgoing URI",
"extension"
)

N.B.

The Action Server's ip-address is the ip-address of the node where remote_phone_control is used. Remember, the Action Server is served by remote_phone_control.
The Action Server's listening port MUST be unique for each Snom instance
The outgoing URI is the sip account used for calling

Example: Call out to PSTN
E.g., set your mobile phone to auto answer and call it.
assert snom_a.callout('PSTN number to call') == True
assert snom_a.expect('connect') == True
time.sleep(5) # Represents a 5 seconds conversation
assert snom_a.hangup() == True
assert snom_a.expect('disconnect') == True

snom_a.stop()

SNOM A calls SNOM B, B answers, call is established, B ends the call
snom_a.callout("Extension of SNOM B")
assert snom_b.expect('incoming') == True
snom_b.pickup()
assert snom_b.expect('connect') == True
time.sleep(5) # Represents a 5 seconds conversation
snom_b.hangup()
assert snom_b.expect('disconnect') == True

snom_a.stop()
snom_b.stop()

A calls B, B rejects the call
snom_a.callout("Extension of SNOM B")
assert snom_b.expect('incoming') == True
# Reject the incoming call
snom_b.hangup()
assert snom_a.expect('disconnect')

snom_a.stop()
snom_b.stop()

An actual use case
To get a feel of how you can use this package. It proofed very useful in automating end to end regression tests of a cloud hosted call center web app where an agent is tied to a browser interface, the GUI, and a SIP phone. Call actions displayed and performed on the GUI should be in sync with the actual state of the phone and vice versa. Using Selenium, call actions are executed on the GUI and the state of the phone checked against the expectation using the package. Using the package, call actions are executed on the phone and the GUI state checked using Selenium. Inbound calls, with an external origin, i.e. PSTN, and several other scenarios are checked against both the state of the GUI and the phone. Gluing it all together with Python's standard library unittest framework.
Reference

SNOM

Remote phone control via http
Action URLs
http://<phone's ip-address>/settings.htm


Yealink

Action URI
How to dial or place a call using remote control?


Python

Requests: HTTP for Humans