search

jimmywarting / wemo-client

JavaScript client library for controlling and subscribing to Wemo Devices
MIT License
132 stars 40 forks source link
maintainer-wanted wemo-client wemo-link wemo-maker wemo-switch

readme

Wemo Client for Node.js

Low-level client library for controlling recent Wemo devices including Bulbs. Supports event subscriptions to get live updates from devices.

Build Status codecov

Supported Devices

Install

$ npm install wemo-client

Usage

import Wemo from 'wemo-client'
const wemo = new Wemo()

wemo.discover((err, deviceInfo) => {
  console.log('Wemo Device Found: %j', deviceInfo)

  // Get the client for the found device
  const client = wemo.client(deviceInfo)

  // You definitely want to listen to error events (e.g. device went offline),
  // Node will throw them as an exception if they are left unhandled
  client.on('error', err => {
    console.log('Error: %s', err.code)
  })

  // Handle BinaryState events
  client.on('binaryState', value => {
    console.log('Binary State changed to: %s', value)
  })

  // Turn the switch on
  client.setBinaryState(1)
})

API

Wemo

new Wemo([opts])

Create the Wemo instance. An optional object containing options can be specified. Available options include port which will provide a port to bind to for listening to UPnP events (the default is to listen on any available randomly selected port.) Discovery options for node-ssdp can also be specified as discover_opts. The listen_interface option can be used to specify which network interface to listen on. If listen_interface is not specified then by default the server will listen on all interfaces, however, Wemo subscription messages will only be sent to the first non-internal IPv4 address returned by os.networkInterfaces() after being sorted by compatible network which may or may not be what you want.

Example of options:

{
  port: 1234,
  discover_opts: {
    unicastBindPort: 1235
  },
  listen_interface: 'wlan0'
}

DEVICE_TYPE

Static map of supported models and device types.

discover(cb)

Discover Wemo devices via UPnP. A deviceInfo will be passed to cb that can be used to get a client for the device found.

Due to the nature of UPnP it may be required to call this method multiple times to discover actually all devices connected to the local network.

The callback will only be called for newly found devices (those that have not been detected by a previous call to discover). Except for devices that have been lost in an error state as those will reappear again when coming back online (e.g. because their IP/port have changed).

load(setupUrl, cb)

API breaking in: v0.13

Allows to skip discovery if the setupUrl of a Wemo is already known. A deviceInfo will be passed to cb that can be used to get a client for the device found. The err field will be non-null in the event of an error.

client(deviceInfo)

Get a single instance of WemoClient for the device specified by deviceInfo.

WemoClient

Event: error (err)

An error occured while handling the event subscriptions or calling a device action. When err.code is one of ECONNREFUSED, EHOSTUNREACH or ETIMEDOUT the device likely went offline.

When using any subscriptions, make sure to also listen to error events. Node will throw an exception if error events are left unhandled. See also: Building Robust Node Applications: Error Handling

Event: binaryState (value)

Binary state of a device has been updated, e.g. a motion sensor detected motion or a plug is switched on.

client.on('binaryState', value => {
  console.log('Device turned %s', value === '1' ? 'on' : 'off')
})

Event: statusChange (deviceId, capabilityId, value)

Capability of a device connected via Wemo Bridge changed its status.

Event: attributeList (name, value, prevalue, timestamp)

Attribute of a device has changed. This applies to Wemo Maker, Wemo Humidifier, and Wemo Heater (may not be exhaustive).

Event: insightParams (binaryState, instantPower, data)

Wemo Insight Switch sent new power consumption data.

endDeviceInfos = await client.getEndDevices()

Get bulbs connected to a Wemo Bridge. An endDeviceInfo for every device paired is returned as an array, e.g.:

[{
  friendlyName: 'Color Bulb',
  deviceId: 'EA103EA2B2782FFF',
  capabilities: {
    '10006': '1',
    '10008': '121:0'
  },
  deviceType: 'dimmableLight'
}]

Device groups are treated as if they were single devices – a sole endDeviceInfo is returned per group.

Notice: The capabilities property may represent outdated values due to some odd behavior of the device API. Please refer to getDeviceStatus or Event: statusChange to obtain the current state of the device.

const state = client.getBinaryState()

Get the device's binary state.

The state (1 = on, 0 = off).

response = await client.setBinaryState(value)

Turn the device on or off. Will also cause a binaryState event to be triggered.

brightness = await client.getBrightness()

Get the device's brightness level (0 - 100).

response = await client.setBrightness(value)

Set the device brightness level. Will also cause a binaryState event to be triggered.

attributes = await client.getAttributes()

Get the device attributes of a Wemo Maker.

deviceStatus = await client.getDeviceStatus(deviceId)

Gets the device Status of a device connected via Wemo Bridge, e.g. a bulb.

The deviceStatus is a map of device capabilities and values, e.g.:

{
  '10006': '1', // on = 1, off = 0, offline = empty
  '10008': '121:0', // brightness 0-255
  '30008': '0:0', // no sleep timer active
  '30009': '', // unknown
  '3000A': '' // unknown
}

response = await client.setDeviceStatus(deviceId, capability, value)

Controls a capability of a device connected via Wemo Bridge, e.g. a bulb.

Known capabilities (depends on device):

response = await client.setLightColor(deviceId, red, green, blue)

Convenience function for setting the color of a RGB light.

const insight = await client.getInsightParams()

Get power consumption data for a Wemo Insight Switch

awiat client.setAttributes(attributes)

Sets attributes on a device (Heater, Humidifier), used for setting FanMode, Mode, TimeRemaining, and SetTemperature (not exhaustive) to a value.

You can set any number of attributes in this manner, and if you do not specify an attribute, it is left unchanged on the device.

Debugging

Wemo Client uses debug, so just run with environmental variable DEBUG set to wemo-client.

$ env DEBUG=wemo-client node examples/index.js

Known Issues

There are some quirks and oddities to be aware of when working with the devices supported by this library.

General

Wemo Link

Contributing

Contributions are very welcome! Please note that by submitting a pull request for this project, you agree to license your contribution under the MIT License to this project.

Credits

Credit goes to Ben Hardill for his research on Belkin Wemo devices.

License

Published under the MIT License.