Skip to main content

Python 3 library for accessing uPnP devices.

Project description

Build Status

uPnPclient

uPnP client library for Python 3.

This library can be used to discover and consume uPnP devices and their services.

It's originally based on Ferry Boender's work and his blog post entitled Exploring UPnP with Python.

Installation

pip install upnpclient

Usage

Typical usage:

In [1]: import upnpclient

In [2]: devices = upnpclient.discover()

In [3]: devices
Out[3]: 
[<Device 'OpenWRT router'>,
 <Device 'Harmony Hub'>,
 <Device 'walternate: root'>]

In [4]: d = devices[0]

In [5]: d.WANIPConn1.GetStatusInfo()
Out[5]: 
{'NewConnectionStatus': 'Connected',
 'NewLastConnectionError': 'ERROR_NONE',
 'NewUptime': 14851479}

In [6]: d.WANIPConn1.GetNATRSIPStatus()
Out[6]: {'NewNATEnabled': True, 'NewRSIPAvailable': False}

In [7]: d.WANIPConn1.GetExternalIPAddress()
Out[7]: {'NewExternalIPAddress': '123.123.123.123'}

If you know the URL for the device description XML, you can access it directly.

In [1]: import upnpclient

In [2]: d = upnpclient.Device("http://192.168.1.1:5000/rootDesc.xml")

In [3]: d.services
Out[3]: 
[<Service service_id='urn:upnp-org:serviceId:Layer3Forwarding1'>,
 <Service service_id='urn:upnp-org:serviceId:WANCommonIFC1'>,
 <Service service_id='urn:upnp-org:serviceId:WANIPConn1'>]

In [4]: d.Layer3Forwarding1.actions
Out[4]: 
[<Action 'SetDefaultConnectionService'>,
 <Action 'GetDefaultConnectionService'>]

In [5]: d.Layer3Forwarding1.GetDefaultConnectionService()
Out[5]: {'NewDefaultConnectionService': 'uuid:46cb370a-d7f2-490f-ac01-fb0db6c8b22b:WANConnectionDevice:1,urn:upnp-org:serviceId:WANIPConn1'}

Sometimes the service or action name isn't a valid property name. In which case, service and actions can be accessed other ways:

In [1]: d["Layer3Forwarding1"]["GetDefaultConnectionService"]()
Out[1]: {'NewDefaultConnectionService': 'uuid:46cb370a-d7f2-490f-ac01-fb0db6c8b22b:WANConnectionDevice:1,urn:upnp-org:serviceId:WANIPConn1'}

To view the arguments required to call a given action:

In [1]: d.WANIPConn1.AddPortMapping.argsdef_in
Out[1]: 
[('NewRemoteHost',
  {'allowed_values': set(), 'datatype': 'string', 'name': 'RemoteHost'}),
 ('NewExternalPort',
  {'allowed_values': set(), 'datatype': 'ui2', 'name': 'ExternalPort'}),
 ('NewProtocol',
  {'allowed_values': {'TCP', 'UDP'},
   'datatype': 'string',
   'name': 'PortMappingProtocol'}),
 ('NewInternalPort',
  {'allowed_values': set(), 'datatype': 'ui2', 'name': 'InternalPort'}),
 ('NewInternalClient',
  {'allowed_values': set(), 'datatype': 'string', 'name': 'InternalClient'}),
 ('NewEnabled',
  {'allowed_values': set(),
   'datatype': 'boolean',
   'name': 'PortMappingEnabled'}),
 ('NewPortMappingDescription',
  {'allowed_values': set(),
   'datatype': 'string',
   'name': 'PortMappingDescription'}),
 ('NewLeaseDuration',
  {'allowed_values': set(),
   'datatype': 'ui4',
   'name': 'PortMappingLeaseDuration'})]

and then to call the action using those arguments:

In [1]: d.WANIPConn1.AddPortMapping(
   ...:     NewRemoteHost='0.0.0.0',
   ...:     NewExternalPort=12345,
   ...:     NewProtocol='TCP',
   ...:     NewInternalPort=12345,
   ...:     NewInternalClient='192.168.1.10',
   ...:     NewEnabled='1',
   ...:     NewPortMappingDescription='Testing',
   ...:     NewLeaseDuration=10000)
Out[1]: {}

Similarly, the arguments you can expect to receive in response are listed:

In [1]: d.WANIPConn1.GetGenericPortMappingEntry.argsdef_out
Out[1]: 
[('NewRemoteHost',
  {'allowed_values': set(), 'datatype': 'string', 'name': 'RemoteHost'}),
 ('NewExternalPort',
  {'allowed_values': set(), 'datatype': 'ui2', 'name': 'ExternalPort'}),
 ('NewProtocol',
  {'allowed_values': {'TCP', 'UDP'},
   'datatype': 'string',
   'name': 'PortMappingProtocol'}),
 ('NewInternalPort',
  {'allowed_values': set(), 'datatype': 'ui2', 'name': 'InternalPort'}),
 ('NewInternalClient',
  {'allowed_values': set(), 'datatype': 'string', 'name': 'InternalClient'}),
 ('NewEnabled',
  {'allowed_values': set(),
   'datatype': 'boolean',
   'name': 'PortMappingEnabled'}),
 ('NewPortMappingDescription',
  {'allowed_values': set(),
   'datatype': 'string',
   'name': 'PortMappingDescription'}),
 ('NewLeaseDuration',
  {'allowed_values': set(),
   'datatype': 'ui4',
   'name': 'PortMappingLeaseDuration'})]

HTTP Auth/Headers

You may pass a requests compatible authentication object and/or a dictionary containing headers to use on the HTTP calls to your uPnP device.

These may be set on the Device itself on creation for use with every HTTP call:

device = upnpclient.Device(
    "http://192.168.1.1:5000/rootDesc.xml"
    http_auth=('myusername', 'mypassword'),
    http_headers={'Some-Required-Header': 'somevalue'}
)

Or on a per-call basis:

device.Layer3Forwarding1.GetDefaultConnectionService(
    http_auth=('myusername', 'mypassword'),
    http_headers={'Some-Required-Header': 'somevalue'}
)

If you've set either at Device level, they can be overridden per-call by setting them to None.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

upnpclient-1.0.3.tar.gz (17.5 kB view details)

Uploaded Source

Built Distribution

upnpclient-1.0.3-py3-none-any.whl (18.1 kB view details)

Uploaded Python 3

File details

Details for the file upnpclient-1.0.3.tar.gz.

File metadata

  • Download URL: upnpclient-1.0.3.tar.gz
  • Upload date:
  • Size: 17.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.4 CPython/3.8.0 Linux/4.15.0-1077-gcp

File hashes

Hashes for upnpclient-1.0.3.tar.gz
Algorithm Hash digest
SHA256 641f05fa4b8e5c5b5cc4561dab49fe5c4774d26e51378671efad4023249e69b8
MD5 f936c8de89705555f6bd736a66d3af5d
BLAKE2b-256 dd694d38d9fa757c328df93e7037eb8c1da8ca48e62828c23ba3c421e9335e30

See more details on using hashes here.

File details

Details for the file upnpclient-1.0.3-py3-none-any.whl.

File metadata

  • Download URL: upnpclient-1.0.3-py3-none-any.whl
  • Upload date:
  • Size: 18.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.4 CPython/3.8.0 Linux/4.15.0-1077-gcp

File hashes

Hashes for upnpclient-1.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 1fb1b58af8eae9bb31758152e762f13aaf8608c89110e6d1a1d7d979677ac0df
MD5 e50b09ba2c022ab32105299f03a65bbc
BLAKE2b-256 f2af6e2365c5955b7b006b95b5e9e0e2f278c310ed56ed7768a7a4fc1d66e01a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page