---
title: roUPnPController
slug: develop/roupnpcontroller
docTags: 
createdAt: 2025-03-26T17:39:55.201Z
---

This object establishes and maintains a UPnP Control Point. It must exist for the entirety of UPnP discovery operations. Refer to the [UPnP Device Architecture](http://www.upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf) document for more information about UPnP discovery protocols. 

Object Creation: The *roUPnPController* object is created without any parameters.

```none
CreateObject("roUPnPController")
```

## ifUPnPController

**SetDebug(debug As Boolean) As Void**

Enables detailed debugging in the UPnP engine.

**Search(searchTarget As String, mx As Integer) As Boolean**

Issues a Search request for a UPnP device. The parameters correspond to the ST (Search Target) and MX (Maximum wait time) header values that are sent with a UPnP M-SEARCH command. Responses to the Search request will generate messages in the form of roUPnPSearchEvent objects.

:::hint{type="info"}
The most common value for the searchTarget parameter is "upnp\:rootdevice". This allows you to search all root devices, identify which devices you wish to interact with, and then get the roUPnPDevice and UPnPService instances for these embedded devices and services.
:::

**RemoveDevice(udn As String) As Boolean**

Forces removal of the specified device from the Control Point device list. The passed string must include "`uuid:"` prepended to the UDN value.

## ifMessagePort

Specifies the port that will receive events generated by the *roUPnPController *instance.

## ifUserData

**SetUserData(user\_data As Object)**

Sets the user data that will be returned when events are raised.

**GetUserData() As Object**

Returns the user data that has previously been set via `SetUserData()`. It will return `Invalid` if no data has been set.

## UPnP Controller Operation

The *roUPnPController *object maintains a list of all currently detected UPnP devices accessible via the local network. To maintain this list, the *roUPnPController* object follows these generally accepted control-point practices:

- If an `ssdp:alive` multicast notification is received from a device that is not part of the list, it is queried for its device information and added to the list. However, the `ssdp:alive` message is not intended as the primary means for device discovery; rather, this behavior is intended to keep the list up-to-date and remove devices that disappear without an `ssdp:byebye` notification.
- If an `ssdp:byebye` multicast notification is received form a device that is part of the list, it will be removed from the list.
- The UPnP Controller allows a client to issue a Search request for UPnP devices. All devices on the network are expected to respond directly to the requesting device. If a response is received from a device that is not part of the list, it is queried for its device information and added to the list.
- UPnP devices report a "time-to-live" for notifications. For UPnP NOTIFY and search-response messages, this is contained in the "Cache-Control: max-age" header. Typically, this "time-to-live" is 20 or 30 minutes, though some devices have much shorter time values. Every device is configured to expire after its "time-to-live" is reached, at which point it is removed from the device list. The counter is reset (i.e. the device is renewed) after each receipt of an `ssdp:alive` message.

BrightScript does not allow direct access to its internal DeviceList. Rather, it raises events in the form of *roUPnPSearchEvent *objects when devices are added or removed from the list. These objects can, in turn, be used to retrieve *roUPnPDevice *objects containing all device information.

The controller also raises events whenever it receives a NOTIFY multicast message or a response to an M-SEARCH message (i.e. a response to a controller search request). These events return associative arrays containing headers from the NOTIFY multicast message or from the HTTP response to the M-SEARCH message.

The associative arrays may also contain additional non-header items. For an SSDP multicast message notification (type 0), the associative array will contain an "ssdpType" key, the value of which designates whether it is a NOTIFY or M-SEARCH message. In most cases, it is best to ignore M-SEARCH messages, unless you are implementing a UPnP device (the UPnP controller object does allow this).

During an M-SEARCH request, a "new device" notification (type 2) will only be sent when a device is added to the controller's internal list. Once a device is part of the device list, subsequent M-SEARCH requests will only return type 1 (search response) values for that device. This type 1 response returns an associative array with message headers, but not an roUPnPDevice object (which is used to contain a complete set of device information).

:::hint{type="info"}
See the roUPnPSearchEvent page for more information about the messages sent by the UPnP Controller.
:::