jakobhellermann / rupnp

Rust library for the universal plug and play protocol.

rupnp

An asynchronous library for finding UPnP control points, performing actions on them and reading their service descriptions. UPnP stand for Universal Plug and Play and is widely used for routers, WiFi-enabled speakers and media servers.

Spec: http://rupnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v2.0.pdf

Example usage:

The following code searches for devices that have a RenderingControl service and print their names along with their current volume.

use futures::prelude::*;
use std::time::Duration;
use rupnp::ssdp::{SearchTarget, URN};

const RENDERING_CONTROL: URN = URN::service("schemas-upnp-org", "RenderingControl", 1);

#[tokio::main]
async fn main() -> Result<(), rupnp::Error> {
    let search_target = SearchTarget::URN(RENDERING_CONTROL);
    let devices = rupnp::discover(&search_target, Duration::from_secs(3)).await?;
    pin_utils::pin_mut!(devices);

    while let Some(device) = devices.try_next().await? {
        let service = device
            .find_service(&RENDERING_CONTROL)
            .expect("searched for RenderingControl, got something else");

        let args = "<InstanceID>0</InstanceID><Channel>Master</Channel>";
        let response = service.action(device.url(), "GetVolume", args).await?;

        let volume = response.get("CurrentVolume").unwrap();

        println!("'{}' is at volume {}", device.friendly_name(), volume);
    }

    Ok(())
}

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Please use rustfmt before any pull requests.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

rupnp's Issues

It is not possible to specify a TTL for the discover function

When broadcasting to discover new devices, it is useful to be able to specify a TTL, which is an UPnP feature that allows finding devices that are in more than one hop of distance from the host (e.g. a multi-router home network). This is related to this similar issue in the ssdp-client library.

Considering that the ssdp_client::search function now have the TTL option, the fix is as simple as exposing the TTL parameter to therupnp::discover function.

SCPD fails when an allowedValueRange maximum is an empty string

In trying to set up a system with a friend's router (so I am unable to rigorously test), I found that when parsing StateVariables when calling service.scpd(), I got this error: Invalid response: cannot parse integer from empty string

Turns out, in their WANIPConn1 service, the Uptime state variable had no maximum defined. Specifically:

<stateVariable sendEvents="no">
  <name>Uptime</name>
  <dataType>ui4</dataType>
  <defaultValue>0</defaultValue>
  <allowedValueRange>
    <minimum>0</minimum>
    <maximum/>
    <step>1</step>
  </allowedValueRange>
</stateVariable>

When parsing, maximum here causes the parsing to fail.

The specific router is a TP-Link TD-W9970, model number 4.0.
It also reproduces on the TP-Link Archer VR1600v (unknown model version)

I'm not sure how this would best be represented, but if informed how to I'm happy to do a PR myself.

The specific error location is in scpd::state_variable::range_from_xml() when parsing maximum by calling utils::parse_node_text().

Bump to a new release as abde2a contains an important fix

I am behind the Huawei EchoLife HG8245H router and the Service::action function is returning HttpErrorCode(500) when I'm on commit 2209da6 (one with the 1.0.0 tag).

Fortunately for me, this issue has been fixed by @stanislav-omelchenko in commit abde2a3.

Could you please bump the version in crates to contain this fix?

Discovery fails if a device does not have a servicelist

When a device, like a Philips Hue bridge, has no services to advertise, the method devices.try_next() throws an unrecoverable error:

Error: XmlMissingElement("device", "serviceList")

aborting any further device discovery on the network, unless I am missing something?

Thanks for a very well designed library!