Developer Documentation

The UPnP Event Proxy is a daemon which works around a ​known bug in the MiOS web server implementation (namely, that it does not accept NOTIFY HTTP messages).

The proxy runs a simple Lua web server at Vera startup, which listens for a small set of HTTP commands, which are either NOTIFY messages, or requests from Vera plugins to be informed when a NOTIFY message is received. When the proxy receives a NOTIFY message, it sends a Luup ​action message to the plugin so that it can act upon the notification.

Typical use case

NOTIFY is one of the message types defined in the UPnP standard, and is used when a UPnP device needs to tell a UPnP control point about a state variable that has changed. For example, a UPnP device such as a WeMo? motion sensor may have detected motion, or a UPnP media device such as a Sonos may have had its volume level changed by the user.

MiOS plugins that interact with UPnP devices may wish to be informed of these events, so that they can modify the dashboard UI to match, or so that they can fire a scene trigger.

The UPnP mechanism that the plugin uses is to send a UPnP SUBSCRIBE message to the UPnP device. Inside this SUBSCRIBE message is the URL that the device should try to contact whenever the event occurs. The UPnP device will immediately return a unique string, a subscription identifier (SID). Any time that the event occurs, the UPnP device will send a NOTIFY message to the callback URL, quoting this SID, so that the receiver knows which device has had the event.

The MiOS LuaUPnP process cannot receive NOTIFY messages, so the plugin instead nominates the UPnP Event Proxy daemon as the callback URL. The plugin must also inform the UPnP Event Proxy daemon of the SID, and which Luup action on the plugin to invoke when the event occurs.

Registering a subscription with the proxy

TODO

Receiving an event notification from the proxy

TODO

Renewing the subscription

TODO

Cancelling the subscription

TODO

Avoiding deadlocks

TODO