Wemo-Shim

A stable, local-network-only control layer for Belkin Wemo smart plugs and switches.

Overview

Wemo-Shim provides a robust and dynamic abstraction layer for managing Wemo devices on your local network. It interfaces directly with the low-level wemo-client library to offer a simple, reliable, and high-level API for custom applications and real-time device management.

Features

• Simple API: Get state, turn on/off, and toggle Wemo devices with easy-to-use methods
• State Management: Maintains an accurate in-memory representation of all known devices
• Automatic Synchronization: Detects manual state changes through periodic polling
• Graceful Handling: Manages devices becoming temporarily unresponsive
• Dynamic Discovery: Discover new devices on the network
• Device Management: Rename and permanently delete device configurations
• External Configuration: All settings stored in JSON files that can be modified and reloaded

Installation

npm install jw-wemo-shim

Quick Start

const WemoShim = require('jw-wemo-shim');

const wemo = new WemoShim('./config');

wemo.on('ready', () => {
  console.log('Ready!');
});

await wemo.start();

API

Initialization

const wemo = new WemoShim(configDir);
await wemo.start();

State and Control Methods

• wemo.get(name) - Returns the state object for the named device
• wemo.getState() - Returns the entire master state object
• await wemo.set(name, state) - Sets a device's state to 'on' or 'off'
• await wemo.toggle(name) - Toggles a device's state

Device Management

• await wemo.discoverNewDevices() - Scans the network for new devices
• await wemo.editDeviceName(udn, newName) - Updates a device's name
• await wemo.deleteDevice(udn) - Removes a device from the configuration

Configuration Management

• await wemo.reloadConfig() - Reloads configuration from JSON files

Events

• ready - Emitted when the shim is ready to use
• stateChange - Emitted when a device's state changes
• deviceLost - Emitted when a device becomes unresponsive
• deviceFound - Emitted when a previously lost device is found
• deviceAdded - Emitted when a new device is added
• deviceRemoved - Emitted when a device is removed
• deviceRenamed - Emitted when a device is renamed

Configuration Files

The shim uses two JSON configuration files in the config directory. If they don't exist, they are created on first run with defaults.

If you want a starting point, see the example files in config/.

settings.json

{
  "pollingInterval": 300000
}

• pollingInterval: Time in milliseconds between state polls (default: 300000 = 5 minutes)

devices.json

[
  {
    "name": "livingRoomLamp",
    "udn": "uuid:Socket-1_0-SERIALNUMBER1"
  },
  {
    "name": "UNKNOWN",
    "udn": "uuid:Lightswitch-1_0-SERIALNUMBER2"
  }
]

Each device has:

• name: A friendly name for the device
• udn: The unique device identifier (UDN)

Newly discovered devices are added with the name "UNKNOWN" and should be renamed after identification.

Usage Example

See example.js for a complete usage example.

const WemoShim = require('jw-wemo-shim');

async function main() {
  const wemo = new WemoShim('./config');

  wemo.on('ready', async () => {
    console.log('Wemo shim is ready!');

    // Turn on a device
    await wemo.set('livingRoomLamp', 'on');

    // Get device state
    const state = wemo.get('livingRoomLamp');
    console.log(state);
  });

  await wemo.start();
}

main();

Device Lifecycle

1. First Run: The shim creates empty/default configuration files
2. Discovery: Call discoverNewDevices() to find devices on the network
3. Identification: Interact with "UNKNOWN" devices to identify them physically
4. Configuration: Use editDeviceName() to assign meaningful names
5. Decommission: Use deleteDevice() to remove devices permanently

License

ISC