API

This part of the documentation lists the full API reference of all public classes and functions.

Classes

class ssdpy.SSDPClient(proto='ipv4', port=1900, ttl=2, iface=None, timeout=5, address=None, *args, **kwargs)

Send an M-SEARCH request and gather responses.

Parameters:

  • st (str) – The Search Target, used to narrow down the responses that should be received. Defaults to “ssdp:all” which should get responses from any SSDP-enabled device.

  • mx (int) – Maximum wait time (in seconds) that devices are allowed to wait before sending a response. Should be between 1 and 5, though this is not enforced in this implementation. Devices will randomly wait for anywhere between 0 and ‘mx’ seconds in order to avoid flooding the client that sends the M-SEARCH. Increase the value of ‘mx’ if you expect a large number of devices to answer, in order to avoid losing responses.

Returns:

A list of all discovered SSDP services. Each service is represented by a dict, with the keys being the lowercase equivalents of the response headers.

class ssdpy.SSDPServer(usn, proto='ipv4', device_type='ssdp:rootdevice', port=1900, iface=None, address=None, max_age=None, location=None, al=None, extra_fields=None)

A server that can listen to SSDP M-SEARCH requests and responds with appropriate NOTIFY packets when the ST matches its device_type.

Example usage:

>>> server = SSDPServer("my-service", device_type="my-device-type")
>>> server.serve_forever()

This will listen to SSDP M-Searches (discovery) and respond with

Parameters:

  • usn (str) – A unique service name, which identifies your service.

  • proto (str, optional) – Protocol to use, either ipv4 or ipv6. Defaults to ipv4.

  • device_type (str, optional) – The device type to respond as. Defaults to ssdp:rootdevice which is the base type for ssdp devices.

  • port (int, optional) – Port to listen on. SSDP works on port 1900, which is the default value here.

  • iface (bytes, optional) – Interface to bind to. When not provided, the operating system decides which interface should handle multicasts and binds to it.

  • address (str, optional) – A specific address to bind to. This is required when using IPv6, since you will have a link-local IP address in addition to at least one actual IP address.

  • max_age (int) – The maximum time, in seconds, for clients to cache notifications.

  • location (str) – Canonical URL of the service.

  • al (str) – Canonical URL of the service, but only supported in the IETF version of SSDP. Should be the same as location.

  • extra_fields (dict) – Extra header fields to send. UPnP SSDP section 1.1.3 allows for extra vendor-specific fields to be sent in the NOTIFY packet. According to the spec, the field names MUST be in the format of token.`domain-name`, for example myheader.philips.com. SSDPy, however, does not check this and allows any field name - as long as it’s ASCII.

serve_forever()

Start listening for M-SEARCH discovery attempts and answer any that refers to our device_type or to ssdp:all. This will block execution until an exception occurs.

Functions

ssdpy.client.discover()

An ad-hoc way of discovering all SSDP services without explicitly initializing an SSDPClient.

Returns:

A list of all discovered SSDP services, each service in a dictionary.

Helpers

ssdpy.protocol.create_msearch_payload(host, st, mx=1)

Create an M-SEARCH packet using the given parameters. Returns a bytes object containing a valid M-SEARCH request.

Parameters:

  • host (str) – The address (IP + port) that the M-SEARCH will be sent to. This is usually a multicast address.

  • st (str) – Search target. The type of services that should respond to the search.

  • mx (int) – Maximum wait time, in seconds, for responses.

Returns:

A bytes object containing the generated M-SEARCH payload.

ssdpy.protocol.create_notify_payload(host, nt, usn, location=None, al=None, max_age=None, extra_fields=None)

Create a NOTIFY packet using the given parameters. Returns a bytes object containing a valid NOTIFY request.

The NOTIFY request is different between IETF SSDP and UPnP SSDP. In IETF, the ‘location’ and ‘al’ fields serve the same purpose, and can be provided together (if so, they should point to the same location) or not at all. In UPnP, the ‘location’ field MUST be provided, and ‘al’ is ignored. Sending both ‘location’ and ‘al’ is the more widely supported option. It does not, however, mean that all SSDP implementations would accept a packet with both. Therefore the option to send just one of these fields (or none at all) is supported. If in doubt, send both. If your notifications go ignored, opt to not send ‘al’.

Parameters:

  • host (str) – The address (IP + port) that the NOTIFY will be sent about. This is usually a multicast address.

  • nt (str) – Notification type. Indicates which device is sending the notification.

  • usn (str) – Unique identifier for the service. Usually this will be composed of a UUID or any other universal identifier.

  • location (str) – A URL for more information about the service. This parameter is only valid when sending a UPnP SSDP packet, not IETF.

  • al (str) – Similar to ‘location’, but only supported on IETF SSDP, not UPnP.

  • max_age (int) – Amount of time in seconds that the NOTIFY packet should be cached by clients receiving it. In UPnP, this header is required.

  • extra_fields – Extra header fields to send. UPnP SSDP section 1.1.3 allows for extra vendor-specific fields to be sent in the NOTIFY packet. According to the spec, the field names MUST be in the format of token.`domain-name`, for example myheader.philips.com. SSDPy, however, does not check this. Normally, headers should be in ASCII - but this function does not enforce that.

Returns:

A bytes object containing the generated NOTIFY payload.