A simple UPnP command-line client, intended for scripting. It uses Intel’s Developer Tools for UPnP™ Technologies library (which happened to work with my TV, contrary to the one supplied with Windows 10) and is therefore written in C#.
On Linux:
$ sudo apt-get install mono-xbuild # FIXME: and a lot of other stuff
$ git clone --recursive https://github.com/yath/upnpc
$ cd upnpc
$ xbuild [/p:Configuration=Debug|Release] # (default is Debug)
# or, if you prefer:
$ make bin/Debug/upnpc.exe
$ ls bin/Debug
On Windows:
- Get prerequisites (FIXME)
- Open an MSBuild Command Prompt
> cd \proj
> …\path\to\git.exe clone --recursive https://github.com/yath/upnpc
> cd upnpc
> msbuild [/p:Configuration=Debug|Release] # (default is Debug)
> dir bin\Debug
upnpc is intended to be used in scripts; for fiddling around with your device and see its services and actions, use “Device Spy” from Intel’s Tools for UPnP Technologies or Coherence’s UPnP Inspector.
The Wikipedia page on UPnP should
provide a rough introduction to the general architecture, but the tl;dr is: UPnP uses
some weird discovery mechanism based on Zeroconf and XML that is best left to a library;
a device is identified by its UDN (a UUID, essentially, therefore in flags abbreviated
with an i) and its URN (something like urn:com.foobar…). Two devices can share the same
URN if they are exposing the same behaviour, but the UDN is intended to be distinct.
A device then exposes one or more services that are identified by another set of UDN
and URN. These services provide variables and actions that may be called or set, respectively,
and are identified by a human-readable string (e.g. SetMainTVChannel, TVSource, …).
upnpc accepts “Windows-style” options, i.e. introduced with a / and parameters
introduced by a :.
/r:1000: The interval to send discovery requests at, in milliseconds/dt:30000: The discovery timeout im milliseconds/vd: Verbose discovery (boolean). If set, prints out additional debugging information during discovery
The default specifies that a discovery request is sent every second; if no
matching device is found within 30 seconds, the program will exit
unsuccessfully. The /vd flag may be specified to print out devices and
services found during discovery.
-
/du:urn:com.foo.bar:…: Match a device by the specified URN -
/di:10b07600-cafebabe-…Match a device by the specified UDN (i.e. UUID) -
/df:MyAwesomeDevice: Match a device by its friendly name (case-sensitive) -
/su:urn:com.foo.barservice:…Match a service by the specified URN -
/si:10b07600-deadbeef-…: Match a service by the specified UDN (UUID)
Either one of /si or /su needs to be specified. The device matching flags
are entirely optional and can be used to further constraint the match, if
you happen to have more than one device providing a specific service on your
network.
/a:MyAwesomeAction: Call the specified action on the service/sv:variable=value: Set a variable before calling the action/gv:variable: Print (Get) a variable’s content before exiting/ev:variable=expected_value: Expect the specified variable to contain the specified content after calling the action; otherwise, exit unsuccessfully./dv: Dump variables (boolean). If set, dumps all variables belonging to the specified action.
The /a option is mandatory and specifies the service to be called. Actions
take a set of (optional) input variables and may set output variables as
a result of their call (usually a success status). The input variables may
be set with /sv, output variables may be dumped to stdout with /gv.
Additionally, /ev defines an assertion of a variable’s content to
equal the specified value; this may used for checking the action’s
success status.
When compiled (or ran?) with Mono, it’s painfully slow. I haven’t yet looked into it yet, though.
Sebastian Schmidt <[email protected]>, 2016. MIT License due to the UPnP
library, but feel free to do what you want with upnpc’s code itself. No
warranties for destroying your home equipment, aquarium, or anything at all.