upnp_da11

UPnP Device architecture 1.1

for more information about UPnP Device Architecture1.1 see: http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf

Caution

1. this library is tested with ** nodejs 6.5**
2. tests weree running under ** raspbian** (debian jessie for raspberry pi 3).
3. this version only support multicast discovering

1. version

• 0.1.x step 1 : UPnP Device Architechture 1.1 ** Discover **
• 0.2.x step 2 : UPnP Device Architechture 1.1 ** Description **

Step 1 in UPnP networking is discovery. When a device is added to the network, the UPnP discovery protocol allows that device to advertise its services to control points on the network. Similarly, when a control point is added to the network, the UPnP discovery protocol allows that control point to search for devices of interest on the network. The fundamental exchange in both cases is a discovery message containing a few essential specifics about the device or one of its services, e.g., its type, identifier, and a pointer to more detailed information.

Step 2 in UPnP networking is description. After a control point has discovered a device, the control point still knows very little about the device. For the control point to learn more about the device and its capabilities, or to interact with the device, the control point must retrieve the device's description from the URL provided by the device in the discovery message. Devices may contain other logical devices, as well as functional units, or services. The UPnP description for a device is expressed in XML and includes vendor-specific manufacturer information like the model name and number, the serial number, the manufacturer name, URLs to vendor-specific Web sites, etc. The description also includes a list of any embedded devices or services, as well as URLs for control, eventing, and presentation. For each service, the description includes a list of the commands, or actions, to which the service responds, and parameters, or arguments for each action; the description for a service also includes a list of variables; these variables model the state of the service at run time, and are described in terms of their data type, range, and event characteristics.

2. install

npm install upnp_da11

3. documentation

3.1. initialization

• include upnp_da11 package:

var upnp = require("upnp_da11");

3.2. Step discover

• get an instance of SSDPprocessor class:

var ssdp = upnp.getSSDP();

• Get a listener to ssdp messages

var listener = ssdp.getListener();

You're now ready to listen ssdp "NOTIFY" and "M-SEARCH" messages sent by upnp devices:

listener.on("RAW",(msg)=>{
  ... something to do ...
});

** msg isn't parsed ** msg is the buffer received on UDP socket.

You should prefer to receive a json object?

3.2.1. NOTIFY * HTTP/1.1

listener.on("NOTIFY * HTTP/1.1",(notify)=>{
  ... something to do ...
]); 

notify is an instance of ** NotifyMessage ** class

notify json object notify has getter:

• notify.host
• notify.cacheControl
• notify.location
• notify.NT
• notify.NTS
• notify.Server
• notify.USN
• notify.BooIdUpnpOrg
• notify.ConfigIdUpnpOrg
• notify.SearchPortUpnpOrg

3.2.2. M-SEARCH * HTTP/1.1

listener.on("M-SEARCH * HTTP/1.1",(msearch)=>{
  ... something to do ...
});

msearch is an instance of MsearchMessage class.

msearch json object has getter:

• msearch.host
• msearch.man
• msearch.ST
• msearch.userAgent

There is a third type of message received: those concerning upnp devices you are looking for:

3.2.3. HTTP/1.1 200 OK

This type of hearder is a reponse to a multicast search message:

ssdp.search(... search target... );

search target may be a string:

ssdp.search("upnp:rootdevice");

But I do prefer use helper's class:

/** select one of these helpers */ 
ssdp.search(upnp.getSTall()); 
ssdp.search(upnp.getSTroot()); /
ssdp.search(upnp.getSTdeviceType(deviceType);
ssdp.search(upnp.getSTserviceType(serviceType);
ssdp.search(upnp.getSTuuid(uuid);
ssdp.search(upnp.getSTvendorDeviceType(domain,deviceType);
ssdp.search(upnp.getSTvendorServiceType(domain,serviceType);

Now you have to listen for ssdp messages:

listener.on("HTTP/1.1 200 OK",(msearchOK)=>{
  ... something to do ...
});

msearchOK is an instance of MSOKMessage class.

msearchOK json object has getter:

• msearchOK.date
• msearchOK.cacheControl
• msearchOK.location
• msearchOK.ext
• msearchOK.ST
• msearchOK.Server
• msearchOK.USN
• msearchOK.BooIdUpnpOrg
• msearchOK.ConfigIdUpnpOrg
• msearchOK.SearchPortUpnpOrg

3.2.4. sample

var upnp = require("upnp_da11"); 	//require package
var ssdp = upnp.getSSDP();		//get ssdp object
var listener = ssdp.getListener();	//get listener of ssdp object
ssdp.search(upnp.getSTall());		//search all devices

listener.on("RAW",(msg)=>{
  console.log(msg.toString());
});

listener.on("NOTIFY * HTTP/1.1",(notify)=>{
  console.log("NOTIFY * HTTP/1.1 host             : " + notify.host);
  console.log("NOTIFY * HTTP/1.1 cacheControl     : " + notify.cacheControl);
  console.log("NOTIFY * HTTP/1.1 location         : " + notify.location);
  console.log("NOTIFY * HTTP/1.1 NT               : " + notify.NT);
  console.log("NOTIFY * HTTP/1.1 NTS              : " + notify.NTS);
  console.log("NOTIFY * HTTP/1.1 Server           : " + notify.Server);
  console.log("NOTIFY * HTTP/1.1 USN              : " + notify.USN);
  console.log("NOTIFY * HTTP/1.1 BooIdUpnpOrg     : " + notify.BooIdUpnpOrg);
  console.log("NOTIFY * HTTP/1.1 ConfigIdUpnpOrg  : " + notify.ConfigIdUpnpOrg);
  console.log("NOTIFY * HTTP/1.1 SearchPortUpnpOrg: " + notify.SearchPortUpnpOrg); 
  console.log("\n\r");
})

listener.on("M-SEARCH * HTTP/1.1",(msearch)=>{
  console.log("M-SEARCH * HTTP/1.1 host     : " + msearch.host);
  console.log("M-SEARCH * HTTP/1.1 man      : " + msearch.man);
  console.log("M-SEARCH * HTTP/1.1 ST       : " + msearch.ST);
  console.log("M-SEARCH * HTTP/1.1 userAgent: " + msearch.userAgent);
  console.log("\n\r");
  })

listener.on("HTTP/1.1 200 OK",(msearchOK)=>{
  console.log("HTTP/1.1 200 OK date             : " + msearchOK.date);
  console.log("HTTP/1.1 200 OK cacheControl     : " + msearchOK.cacheControl);
  console.log("HTTP/1.1 200 OK location         : " + msearchOK.location);
  console.log("HTTP/1.1 200 OK ext              : " + msearchOK.ext);
  console.log("HTTP/1.1 200 OK St               : " + msearchOK.ST);
  console.log("HTTP/1.1 200 OK Server           : " + msearchOK.Server);
  console.log("HTTP/1.1 200 OK USN              : " + msearchOK.USN);
  console.log("HTTP/1.1 200 OK BooIdUpnpOrg     : " + msearchOK.BooIdUpnpOrg);
  console.log("HTTP/1.1 200 OK ConfigIdUpnpOrg  : " + msearchOK.ConfigIdUpnpOrg);
  console.log("HTTP/1.1 200 OK SearchPortUpnpOrg: " + msearchOK.SearchPortUpnpOrg); 
  console.log("\n\r");
})

3.3 step description

When step 1 discover gave you a device URL, you can obtain full description of device with class UPnPDeviceDescription.

3.3.1 UPnPDeviceDescription

To get an instance of UPnPDeviceDescription :

var device = upnp.getUPnPdeviceDescription(...url of device description);

Three methods are usefull to get the device's description:

1. getXMLDescription
2. getJSONDescription
3. getDevice

caution: These 3 methods return promises;

3.3.1.1 get xml description

device.getXMLDescription()
.then(function(xml){
 ... do something with xml ....
})

3.3.3.2 get parsed xml into json object

device.getXMLDescription()
.then(device.getJSONDescription)
.then(function(json){
 ... do something with json object
})

3.3.3.3 get device object

device.getXMLDescription()
.then(device.getJSONDescription)
.then(device.getDevice)
.then(function(json){
  console.log(json);  
});

3.3.2. sample: get all "rootdevice"

var upnp = require("upnp_da11"); 
var ssdp = upnp.getSSDP();
var listener = ssdp.getListener();
ssdp.search(upnp.getSTroot());

listener.on("HTTP/1.1 200 OK",(msearchOK)=>{
  var device = upnp.getUPnPdeviceDescription(msearchOK.location);
  device.getXMLDescription()
  .then(device.getJSONDescription)
  .then(device.getDevice)
  .then(function(json){
    console.log(json);  
  })
  console.log("\n\r");
})