Sonoff Switch SDK

A Node.js SDK for controlling Sonoff switches via local API.

Installation

As a Library

npm install sonoff-switch-sdk

As a Global CLI

npm install -g sonoff-switch-sdk

Usage

As a Library

const SonoffSwitch = require('sonoff-switch-sdk');

const mySwitch = new SonoffSwitch({
    deviceId: '10025a82b3',
    apiKey: 'your-api-key',
    host: '192.168.1.12',
    port: 8081 // optional, defaults to 8081
});

// Turn on
await mySwitch.turnOn();

// Turn off
await mySwitch.turnOff();

// Ping device
const info = await mySwitch.ping();
console.log(info);

As a CLI

Using Command-line Options

sonoff-switch -d 10025a82b3 -a your-api-key -h 192.168.1.12 on
sonoff-switch -d 10025a82b3 -a your-api-key -h 192.168.1.12 off
sonoff-switch -d 10025a82b3 -h 192.168.1.12 ping

Using Environment Variables

export SONOFF_DEVICE_ID=10025a82b3
export SONOFF_API_KEY=your-api-key
export SONOFF_HOST=192.168.1.12
export SONOFF_PORT=8081

sonoff-switch on
sonoff-switch off
sonoff-switch ping

CLI Options

Usage: sonoff-switch [options] <command>

Commands:
  on          Turn the switch on
  off         Turn the switch off
  ping        Get device info

Options:
  -d, --device-id <id>     Device ID
  -a, --api-key <key>      API key
  -h, --host <host>        Device IP address
  -p, --port <port>        Port number (default: 8081)
  --help                   Show help message

Configuration

The SDK requires the following configuration:

• deviceId: Your Sonoff device ID
• apiKey: Your device API key (also called selfApikey) - required for on/off commands
• host: IP address of your Sonoff device
• port: Port number (optional, defaults to 8081)

API Reference

new SonoffSwitch(config)

Creates a new SonoffSwitch instance.

Parameters:

• config.deviceId (string): Device ID
• config.apiKey (string): API key
• config.host (string): Device IP address
• config.port (number): Port number (optional, defaults to 8081)

turnOn()

Turns the switch on. Returns a Promise with the device response.

turnOff()

Turns the switch off. Returns a Promise with the device response.

ping()

Pings the device to get device information. Returns a Promise with the device info.

setSwitch(state)

Sets the switch to a specific state.

Parameters:

• state (string): Either 'on' or 'off'

Returns a Promise with the device response.

Finding Your Device Information

To use this SDK, you'll need your device ID, API key, and local IP address. You can find these by:

1. Setting your eWeLink app to LAN mode
2. Using network tools to discover your device's IP address
3. Extracting the device ID and API key from the eWeLink app or API

License

MIT