Python clients for HNAP devices

Generic HNAP client and specialized clients for motion sensors, sirens, routers, water detectors and more.

Async devices

All network operations are asynchronous. Pass a DeviceType to construct a known device without querying it first:

import asyncio

from hnap import DeviceConfig, DeviceFactory, DeviceType

async def main():
    config = DeviceConfig(hostname="192.0.2.10", password="secret")
    siren = await DeviceFactory(DeviceType.SIREN, config=config)

    async with siren:
        settings = await siren.call("GetSirenAlarmSettings")
        print(settings)

asyncio.run(main())

To use your own aiohttp.ClientSession, pass it to SoapClient. The session remains caller-owned and is closed by its context manager:

import asyncio

import aiohttp
from hnap import DeviceConfig, SoapClient


async def main():
    config = DeviceConfig(hostname="192.0.2.10", password="secret")
    async with aiohttp.ClientSession() as http_client:
        async with SoapClient(config, http_client=http_client) as client:
            print(await client.device_info())


asyncio.run(main())

DeviceConfig retains connection settings independently of authentication state. Authentication is handled automatically when a protected operation needs it; you do not need to call authenticate() first. Operations are not retried after transport errors because the device may have completed an action even if its response was lost.

SoapClient creates an aiohttp.ClientSession when await client.start() is called, when the client or device is entered as an async context manager, or before its first network request. Sessions created by HNAP are closed by await client.close() or on context-manager exit. You can instead supply an existing session via http_client; caller-supplied sessions remain caller-owned and are not closed by the SOAP client or device.

Device operations such as is_playing(), play(), beep(), and get_clients() must be awaited. Cached device information is retrieved with await device.get_info().

Command-line interface

The hnap command requires a hostname and password (or HNAP_PASSWORD) and provides three subcommands:

hnap --hostname 192.0.2.10 --password secret inspect
hnap --hostname 192.0.2.10 --password secret monitor --seconds 10
hnap --hostname 192.0.2.10 --password secret call GetDeviceSettings --param Module 1

inspect reports the device's module types and settings. monitor calls IsDeviceReady immediately and repeats every 30 seconds by default; use --seconds to change the interval. call invokes a raw SOAP action and accepts repeated --param NAME VALUE arguments.

Useful links

• Product page
• REST API in NodeJS
• https://github.com/waffelheld/dlink-device-tracker
• https://github.com/bikerp/dsp-w215-hnap
• https://github.com/postlund/dlink_hnap
• API for smart plugs: https://github.com/bikerp/dsp-w215-hnap/blob/master/js/soapclient.js