Module "upnp.devicefactory"

Device factory for generating standardized services and devices (xml's + implementation code). This module has methods for creating services and devices from standard elements (provided the required modules to support that device/service) are available.

Functions

devicefactory.builddevice (domain, devicetype, version, customtable) Creates a (standard) device, customizes it, generates xml's, parses them and returns the UPnP device object.
devicefactory.createdevice (domain, devicetype, version) Creates the requested device table (if available).
devicefactory.createservice (domain, servicetype, version) Creates the requested service table (if available).
devicefactory.customizedevice (device, customtable) Customizes a device by dropping optional elements (statevariables and/or actions) and adding the implementation functions/methods.
devicefactory.customizeservice (service, customtable) Customizes a service by dropping optional elements (statevariables and/or actions) and adding the implementation functions/methods.
devicefactory.emptydevice () Creates an empty device table.
devicefactory.emptyservice () Creates an empty service table.


Functions

devicefactory.builddevice (domain, devicetype, version, customtable)
Creates a (standard) device, customizes it, generates xml's, parses them and returns the UPnP device object. This method takes a number of steps to create a fully functional device;

  1. Creates a device table for a standard device (devicefactory.createdevice()) or takes a device table
  2. Drops optionals as set in the customtable parameter (devicefactory.customizedevice()) and adds the implementations of device/variable/action methods from the customtable to the device table
  3. Creates the XML's for the device and its services (xmlfactory.rootxml())
  4. Writes the XML's to the webroot directory, so they are accessible (xmlfactory.writetoweb())
  5. Parses the XML's into a root-device object structure, whilst adding the custom implementations as set in the devicetable (upnp.classes.device:parsefromxml())
  6. sets the devicexmlurl on the device and returns the device object

      7. Parameters:

      • domain: domainname of the type to create, alternatively, the full deviceType contents or a device table. In the latter 2 cases the devicetype and version arguments can be omitted.
      • devicetype: [optional] name of the type to create, or nil if the domain contains the full type identifier
      • version: [optional] version number of the type to create, or nil if the domain contains the full type identifier
      • customtable: [optional] table with customizations (see devicefactory.customizedevice())

      Return value:

      device a upnp.classes.device object representing the device, or nil + errormsg

      Example:

      -- three ways to create the same device, all without customization/implementation
      devicefactory.builddevice("schemas.upnp.org", "BinaryLight", "1", {} )
        -- or full schema and no customtable
      devicefactory.builddevice("urn:schemas-upnp-org:device:BinaryLight:1")
        -- or a device table and empty customtable
      local d = require("upnp.devices.urn_schemas-upnp-org_device_Basic_1")()
      devicefactory.builddevice(d, {})
devicefactory.createdevice (domain, devicetype, version)
Creates the requested device table (if available). The output can be used as input for the xmlfactory. For the parameters check the device property deviceType in the device xml of the UPnP architecture documents.

Parameters:

  • domain: domainname of the type to create, alternatively, the full deviceType contents
  • devicetype: name of the type to create, or nil if the domain contains the full type identifier
  • version: version number of the type to create, or nil if the domain contains the full type identifier

Return value:

device table, or nil + errormsg

Example:

-- two ways to create the same device
devicefactory.createdevice("schemas.upnp.org", "BinaryLight", "1")
  -- or
devicefactory.createdevice("urn:schemas-upnp-org:device:BinaryLight:1")
devicefactory.createservice (domain, servicetype, version)
Creates the requested service table (if available). The output can be used as input for the xmlfactory. See createdevice() for more details.

Parameters:

  • domain: domainname of the type to create, alternatively, the full serviceType contents
  • servicetype: name of the type to create, or nil if the domain contains the full type identifier
  • version: version number of the type to create, or nil if the domain contains the full type identifier

Return value:

service table, or nil + errormsg
devicefactory.customizedevice (device, customtable)
Customizes a device by dropping optional elements (statevariables and/or actions) and adding the implementation functions/methods. Includes any underlying services and sub-devices. On device level you can set device properties like friendlyName, etc. A service can be dropped by including an element with its serviceId, set to false. A device can be dropped by including an element with its deviceType, set to false. The start() and stop() methods on device level can also be provided. For implementing code for statevariables and actions, see devicefactory.customizeservice
NOTE: the subdevices are indexed by deviceType in the customtable hence if a device contains 2 sub-devices of the same type, things might go berserk!

Parameters:

  • device: the device table where elements need to be dropped from (typically this is the table returned from devicefactory.createdevice()).
  • customtable: a table containing the elements to drop by serviceId (for services) or deviceType (for devices), with value false.

Return value:

device table, but it will have been modified, might also throw an error

Example:

-- example customtable for a 'urn:schemas-upnp-org:device:DimmableLight:1' device
local customtable = {
    -- customize device level first
    friendlyName = "This is my new UPnP device",
    start = function(self)   -- implement startup behaviour
      self:superclass().start(self)
      print("myDevice is now starting...")
    end,
    stop = function(self)    -- implement device shutdown behaviour
      print("myDevice is now stopped")
      self:superclass().stop(self)
    end,
    -- customize services next
    serviceList = {
      ["urn:upnp-org:serviceId:Dimming:1"] = {
        serviceStateTable = {
          StepDelta = false,
        },
        actionList = {
          StepUp = false,
          StepDown = {
            execute = function(self, params)
              print ("method being executed now!")
            end,
          },
        },  -- actionList
      },  -- dimming service
    },  -- serviceList
  },  -- customtable
--
-- go create a dimmable light and then customize it
local myDevTable = devicefactory.customizedevice(devicefactory.createdevice("schemas.upnp.org", "DimmableLight", "1") , customtable)
devicefactory.customizeservice (service, customtable)
Customizes a service by dropping optional elements (statevariables and/or actions) and adding the implementation functions/methods.

Parameters:

  • service: the service table to be customized (typically this is the table returned from devicefactory.createservice()).
  • customtable: a table containing the elements to customize by name, with value false to drop, or a table containing the execute, beforeset, afterset functions.

Return value:

service table, but it will have been modified, might also throw an error

Example:

-- example customtable for a 'urn:schemas-upnp-org:service:Dimming:1' service
local customtable = {
    serviceStateTable = {
        StepDelta = false,  -- remove this variable
    },
    actionList = {
        StepUp = false,     -- remove this action
        StepDown = {        -- implement the action behaviour
          execute = function(self, params)
            print ("method being executed now!")
          end,
        },
    },
}
devicefactory.emptydevice ()
Creates an empty device table.

Return value:

new table with two empty subtables; serviceList and deviceList.
devicefactory.emptyservice ()
Creates an empty service table.

Return value:

new table with two empty subtables; actionList and serviceStateTable.

Valid XHTML 1.0!