LuaUPNP

14 May 2020 Link

On This Page



Description

LuaUPNP is a Lua module that provides the minimal functions required for any Lua program to:
  1. Detect and search for UPNP devices on the network
  2. Get all command information for all known UPNP devices
  3. Send SOAP commands and receive responses from UPNP devices

Its dependencies are LuaSocket 3.0 or above and LXML (for parsing the UPnP XML responses)

Usage

To use LuaUPNP do the following:
     upnp = require("LuaUPNP")
This puts the module table in upnp which has the functions required.

API and objects

The module generates and manages 2 types of objects:
  1. UPnP object
    This provides functions necessary to search and find all UPnP objects and contains variables that configure the UPnP search.
  2. UPnP host object
    This object holds all the information about the UPnP host as well as provides functions to get information about the host or to send SOAP commands to the host.

UPnP object

Creation

To create a new UPnP object use the function:
  • new(ip,port,iface) -> (upnp Object: table)
ip, port, iface are all optional parameters. Their default values are:
		ip = "239.255.255.250"
		port = 1900
		iface = "*"

Member functions

  1. close() - close the server client sockets opened in the object.
    Usage:
    upnpObject:close()
    The function does not return anything
  2. pcap() - listen passively for any UPnP announcement packets to detect UPnP devices. If any new hosts are found they are added to the hosts table.
    Usage:
    upnpObject:pcap(timeout)
    The timeout parameter is optional and specifies the total time for which to listen in seconds. The function does not return anything.
  3. msearch() - send a search request over the UPnP multicast address to get responses from all UPnP devices. If any new hosts are found they are added to the hosts table.
    Usage:
    upnpObject:msearch(timeout, searchType, searchName)
    All 3 parameters are optional.
    1. timeout like in pcap specifies the total time for which to listen
    2. searchType and searchName if specified are placed in the ST header of the msearch message.

Member Objects

The following objects are in the upnpObject
  1. hosts - array of host objects. This array contains all found UPNP host objects. The structure of this object is described below.
  2. clnt - client socket used to receive msearch responses
  3. srvr - server socket used listen for UPnP hosts in pcap
  4. msearchHeaders - table containing headers sent during msearch. By default it contains the following:
    MAN = '"ssdp:discover"', MX = "3"

Member Variables

  1. ip - multicast ip for uPnP. Set by default to 239.255.255.250
  2. port - uPnP port. Set by default to 1900.
  3. iface - interface for UPnP. This is used by srvr object to join the UPnP multicast group with this interface. Set by default to "*" to bind to all local interfaces.

uPnP host object

Creation

On doing msearch or pcap the hosts array is populated with discovered hosts

Member Functions

  1. getInfo() - get the full information for the host. This populates all the devices tables for the host containing all the services, state variables and actions for the device.
    Usage:
    hostObject:getInfo()
    If successful then returns true, otherwise nil and a error message.
  2. send(devName, serviceName, actionName) - send a SOAP command with the info in the parameters
    Usage:
    hostObj:send(deviceName,serviceName, actionName,{[Arg1]=Arg1_Value, [Arg2]=Arg2_Value})
    If successful it returns the response SOAP XML followed by the return tags that are expected in the message if any.

Member Variables

  1. xmlFile - full url path of xmlFile describing the service
  2. host - url of host
  3. page - xml file name NOTE: Usually: xmlFile = protocol.."://"..host.."/"..page
  4. upnpType - info of the SERVER tag in the xmlFile
  5. protocol - such as http
  6. enumerated - Boolean variable, if true then all information already enumerated using getInfo()
  7. serverType - Type of server returned as the server field in the header when the service XML is downloaded
  8. devices[] - Table containing list of devices with their data structure of their offered services (populated when getInfo() called). Table keys are the device names which are extracted from the text of the deviceType tag by picking the text after 'device:'. This is from the xmlFile of the host object
    1. .deviceType - Info in the deviceType tag of the device XML file
    2. .friendlyName - Info from the same name XML tag if existed
    3. .modelDescription - Info from the same name XML tag if existed
    4. .modelName - Info from the same name XML tag if existed
    5. .modelNumber - Info from the same name XML tag if existed
    6. .modelURL - Info from the same name XML tag if existed
    7. .presentationURL - Info from the same name XML tag if existed
    8. .UDN - Info from the same name XML tag if existed
    9. .UPC - Info from the same name XML tag if existed
    10. .manufacturer - Info from the same name XML tag if existed
    11. .manufacturerURL - Info from the same name XML tag if existed
    12. .services[] - Table containing list of services with their data structure offered by the device. Table keys are the service names which are extracted from the text of the serviceType tag by picking the text after 'service:'. This is from the xmlFile of the host object.
      1. .serviceType - Info in the serviceType tag of the device XML file
      2. .serviceId - Info from the same name XML tag if existed
      3. .controlURL - Info from the same name XML tag if existed
      4. .eventSubURL - Info from the same name XML tag if existed
      5. .SCPDURL - Info from the same name XML tag if existed
      6. .actions[] - Table containing list of actions with their data structure of arguments in the service extracted from the XML in SCPDURL of the service description. Table keys are the action names which is the text of the name tag of the action.
        1. .arguments[] - Table containing the list of arguments the action takes and their description. Table keys are the argument names which is the text of the name tag of the argument
          1. .direction - Info from the same name XML tag if existed
          2. .relatedStateVariable - Info from the same name XML tag if existed
        2. .serviceStateVariables[] - Table containing list of service state variables with their data structure of values in the service extracted from the XML in SCPDURL of the service description. Table keys are the state variable names which is the text of the name tag of the stateVariable
          1. .sendEvents - Info from the same name XML tag if existed
          2. .dataType - Info from the same name XML tag if existed
          3. .defaultValue - Info from the same name XML tag if existed
          4. .allowedValues[] - Array containing allowed values for the state variable
          5. .allowedValueRange - Table with 1st element the minimum value and 2nd element as maximum value