npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@2colors/esphome-native-api

v1.3.2

Published

esphome native api client

Downloads

858

Readme

Esphome native api

This library implements client for Esphome Native APi.

This library rewrite for node-red-contrib-esphome, original library esphome-native-api by @Nafaya

Installation

$ npm i @2colors/esphome-native-api

Synopsis

Device info and list entities

const { Client } = require('@2colors/esphome-native-api');
const client = new Client({
    host: '<esp host or ip>',
    port: 6053,
    // encryptionKey: '', // Use encryption key
    // password: '', // Insert password if you have any (Deprecated)
});

client.connect();

client.on('deviceInfo', deviceInfo => {
    console.log('Device info:', deviceInfo);
});

client.on('newEntity', entity => {
    console.log('New entity:', entity);

    // enable light
    if (entity.type === 'Light') {
        entity.setState(true);
    }

    // show state
    entity.on('state', (state) => console.log(state));
});

client.on('error', (error) => console.log(error));

Discovery

const { Discovery } = require('@2colors/esphome-native-api');
Discovery().then(results => {
    console.log(results);
    /*
    [
        {
            port: 6053,
            network: 'wifi',
            board: 'esp01_1m',
            platform: 'ESP8266',
            mac: 'c82b965b4153',
            version: '2023.11.4',
            host: 'bathroom-light.local',
            address: '192.168.0.119'
        }
    ]
    */
});
const { Discovery } = require('@2colors/esphome-native-api');
const discovery = new Discovery();
discovery.on('info', console.log);
/*
{
    port: 6053,
    network: 'wifi',
    board: 'esp01_1m',
    platform: 'ESP8266',
    mac: 'c82b965b4153',
    version: '2023.11.4',
    host: 'bathroom-light.local',
    address: '192.168.0.119'
}
*/
discovery.run();

Logging

const { Client } = require('@2colors/esphome-native-api');
const client = new Client({
    host: '<esp host or ip>',
    port: 6053,
    initializeSubscribeLogs: true
});
client.on('logs', ({ message }) => {
    console.log(message);
});

Documantation

Discovery

!!! Importan, if you want use on Windows must disable/uninstall Bonjour (Apple) !!!

const { Discovery } = require('@2colors/esphome-native-api');
const discovery = new Discovery(options);
  • options - optional
  • multicast - optional. Default - true. Use udp multicasting
  • interface - optional. Explicitly specify a network interface. defaults to all
  • port - optional. Default - 5353. Set the udp port
  • ip - optional. Default - 224.0.0.251. Set the udp ip
  • ttl - optional. Default - 255. Set the multicast ttl
  • loopback - optional. Default - true. Receive your own packets
  • reuseAddr - optional. Default - true. Set the reuseAddr option when creating the socket (requires node >=0.11.13)
  • bind - optional. for work interface read more
const { Discovery } = require('@2colors/esphome-native-api');
Discovery(options).then(console.log)
  • options - optional
  • timeout - optional. Default - 5. Time in seconds how long to wait for responses
  • * - all options above

Client

More frienly layer over the Connection

const { Client } = require('@2colors/esphome-native-api');
const client = new Client({
    clearSession = false,
    initializeDeviceInfo = true,
    initializeListEntities = true,
    initializeSubscribeStates = true,
    initializeSubscribeLogs = false,
    initializeSubscribeBLEAdvertisements = false,
    port = 6053,
    host,
    clientInfo = 'esphomenativeapi',
    encryptionKey = '',
    password = '', // Deprecated
    reconnect = true,
    reconnectInterval = 30000,
    pingInterval = 15000,
    pingAttempts = 3
});
  • host - (REQUIRED). Host or ip to connect to
  • port - optional. Default - 6053. Port to connect to
  • encryptionKey - encryption Key. Default - ''. The pre-shared key for the encryption. This is a 32-byte base64 encoded string
  • password - passsword (Deprecated). Default - ''. Password used to authorized the client, It is recommended to use the encryptionKey
  • reconnect - optional. Default - true. indicates wheter reconnect automatically or not
  • reconnectInterval - optional. Default - 30000. Number. Amount of miliseconds to wait before new try
  • clearSession - optional. Default - true. Set true to forget any information after reconnection
  • initializeDeviceInfo - optional. Default - true. Set true to retrieve device info after connection is established
  • initializeListEntities - optional. Default - true. Set true to retrieve list of device's entities after connection is established
  • initializeSubscribeStates - optional. Default - true
  • initializeSubscribeLogs - optional. Default - false
  • initializeSubscribeBLEAdvertisements - optional. Default - false
  • clientInfo - string, name of client to be sent to esphome device. (Not necessary to send but nice for debugging issues)
  • clientInfo - string, name of client to be sent to esphome device. Usually needed only for tracking connection on esphome device. See Connection
  • pingInterval - optional. Default - 15000. Ping interval. Amount of miliseconds. See Connection
  • pingAttempts - optional. Default - 3. Number of failed ping attempts after witch connection is considered to be corrupted. See Connection

Client methods and attributes

  • connect() - starts client
  • disconnect() - srops client
  • connected - indicates if client is connected to esphome and autorized
  • initialized - indicates if client is connected and autorized and all initialization step are done
  • entities - array of discovered entities
  • connection - connection instance

Client events

  • connected - emmited if client is connected to esphome and autorized
  • disconnected - emmited when connection is corrupted
  • initialized - emmited if client is connected and autorized and all initialization step are done
  • deviceInfo - emmited when deviceInfo is retrieved or updated. Activated with initializeDeviceInfo options passed to Client's constructor.
  • newEntity - emmited when new entity is discovered. Activated with initializeListEntities options passed to Client's constructor. First argument is instance of one of entities class
  • logs - emmited when esphome send any logs. Activated with initializeSubscribeLogs options passed to Client's constructor. First argument is object with level, tag, message, send_failed
  • ble - emmited when esphome send any BLE Advertisements. Activated with initializeSubscribeBLEAdvertisements options passed to Client's constructor. First argument is object with address, name, rssi, serviceUuidsList, serviceDataList, manufacturerDataList, addressType
  • error - emitted when any error occurs

Entities

Each entity class defines individual interaction with esphome components. All entities have

  • config attrubute - entity configuration receved from esphome
  • state event when new state is received
  • state attribute
  • destroyed event which is called when corresponfing client is no longer connection to this entity(See clearSession option) and
  • type attribute equal to component type
  • name attribute equal to name of entity

Binary sensor

Only base functionality

Button

  • static commandService(connection, { key })
    • key - REQUIRED. key/id of entity

Camera

Climate

  • static commandService(connection, { key, mode, targetTemperature, targetTemperatureLow, targetTemperatureHigh, away, fanMode, swingMode }) - sends command to climate entity
    • key - REQUIRED. key/id of entity
    • mode - optional. 0 - OFF, 1 - AUTO, 2 - COOL, 3 - HEAT, 4 - FAN_ONLY, 5 - DRY. See supportedModesList attr in config
    • targetTemperature- optional. float
    • targetTemperatureLow- optional. float
    • targetTemperatureHigh- optional. float
    • legacyAway - optional. Boolean. Deprecated: use preset with AWAY
    • fanMode - optional. 0 - ON, 1 - OFF, 2 - AUTO, 3 - LOW, 4 - MEDIUM, 5 - HIGH, 6 - MIDDLE, 7 - FOCUS, 8 - DIFFUSE, 9 - QUIET. See supportedFanModesList attr in config
    • swingMode - optional. 0 - OFF, 1 - BOTH, 2 - VERTICAL, 3 - HORIZONTAL. See supportedSwingModesList attr in config
    • customFanMode - optional. string. See supportedCustomFanModesList attr in config
    • preset - optional. 0 - NONE, 1 - HOME, 2 - AWAY, 3 - BOOST, 4 - COMFORT, 5 - ECO, 6 - SLEEP, 7 - ACTIVITY. See supportedPresetsList attr in config
    • customPreset - optional. string. See supportedCustomPresetsList attr in config

Cover

  • static commandService(connection, { key, legacyCommand, position, tilt, stop }) - sends command to cover entity.
    • key - REQUIRED. key/id of entity
    • legacyCommand - optional. 0 - OPEN, 1 - CLOSE, 2 - STOP. Deprecated: use position
    • position - optional. float. 0.0 - CLOSED, 1.0 - OPEN. See supportsPosition attr in config
    • tilt - optional. float. 0.0 - CLOSED, 1.0 - OPEN. See supportsTilt attr in config
    • stop - optional. boolean

Fan

  • static commandService(connection, { key, state, speed, oscillating, direction, speedLevel }) - sends command to fan entity.
    • key - REQUIRED. key/id of entity
    • state - optional. boolean
    • speed - optional. 0 - LOW, 1 - MEDIUM, 2 - HIGH
    • oscillating - optional. boolean
    • direction - optional. 0 - FORWARD, 1 - REVERSE
    • speedLevel - optional. integer. See supportedSpeedLevels attr in config

Light

  • static commandService(connection, { key, state, brightness, red, green, blue, colorMode, colorBrightness, white, colorTemperature, coldWhite, warmWhite, transitionLength, flashLength, effect }) - sends command to light entity.
    • key - REQUIRED. key/id of entity
    • state - optional. boolean
    • brightness - optional. float
    • red - optional. integer 0-255
    • green - optional. integer 0-255
    • blue - optional. integer 0-255
    • colorMode - optional. integer. See supportedColorModesList attr in config
    • colorBrightness - optional. float
    • white - optional. integer 0-255
    • colorTemperature - optional. integer
    • coldWhite - optional. float
    • warmWhite - optional. float
    • flashLength - optional. integer
    • effect - optional. string. effect from effects array in config list

Lock

  • static commandService(connection, { key, command, code } - sends command to lock entity.
    • key - REQUIRED. key/id of entity
    • command - REQUIRED. 0 - UNLOCK, 1 - LOCK, 2 - OPEN
    • code - optional. string. See requiresCode attr in config

MediaPlayer

  • static commandService(connection, { key, command, volume, mediaUrl } - sends command to mediaplayer entity.
    • key - REQUIRED. key/id of entity
    • command - REQUIRED. 0 - MEDIA_PLAYER_COMMAND_PLAY, 1 - MEDIA_PLAYER_COMMAND_PAUSE, 2 - MEDIA_PLAYER_COMMAND_STOP, 3 - MEDIA_PLAYER_COMMAND_MUTE, 4 - MEDIA_PLAYER_COMMAND_UNMUTE
    • volume - optional. float
    • mediaUrl - optional. string

Number

  • static commandService(connection, { key, state }) - sends command to number entity.
    • key - REQUIRED. key/id of entity
    • state - REQUIRED. float. See minValue, maxValue, and step attrs in config

Select

  • static commandService(connection, { key, state }) - sends command to select entity.
    • key - REQUIRED. key/id of entity
    • state - REQUIRED. string. See optionsList attr in config

Sensor

Only base functionality

Siren

  • static commandService(connection, { key, state, tone, duration, volume }) - sends command to siren entity.
    • key - REQUIRED. key/id of entity
    • state - REQUIRED. boolean
    • tone - optional. string. See tonesList attr in config
    • duration - optional. integer. See supportsDuration attr in config
    • volume - optional. integer. See supportsVolume attr in config

Switch

  • static commandService(connection, { key, state }) - sends command to switch entity.
    • key - REQUIRED. key/id of entity
    • state - REQUIRED. boolean

TextSensor

Only base functionality

Text

  • static commandService(connection, { key, state }) - sends command to text entity.
    • key - REQUIRED. key/id of entity
    • state - REQUIRED. string. See minLength, maxLength attrs in config

Connection

const { Connection } = require('@2colors/esphome-native-api');
const connection = new Connection({
    port = 6053,
    host,
    clientInfo = 'esphomenativeapi',
    encryptionKey = '',
    password = '', // Deprecated
    reconnect = true,
    reconnectInterval = 30000,
    pingInterval = 15000,
    pingAttempts = 3
});
  • host - (REQUIRED). Host or ip to connect to.
  • port - optional. Default - 6053. Port to connect to.
  • encryptionKey - encryption Key. Default - ''. The pre-shared key for the encryption. This is a 32-byte base64 encoded string
  • password - passsword (Deprecated). Default - ''. Password used to authorized the client, It is recommended to use the encryptionKey
  • reconnect - optional. Default - true. indicates wheter reconnect automatically or not
  • reconnectInterval - optional. Default - 30000. Number. Amount of miliseconds to wait before new try
  • clientInfo - string, name of client to be sent to esphome device. (Not necessary to send but nice for debugging issues)
  • clientInfo - string, name of client to be sent to esphome device. Usually needed only for tracking connection on esphome device.
  • pingInterval - optional. Default - 15000. Ping interval. Amount of miliseconds.
  • pingAttempts - optional. Default - 3. Number of failed ping attempts after witch connection is considered to be corrupted.

Methods and attributes

  • connected - true if client is introduced to esphome device
  • authorized - true if client is logged in esphome device
  • connect() - do connection try
  • disconnect() - close connection
  • async deviceInfoService() - subsribes to entities state changes. Returns device info object
  • async getTimeService() - subsribes to entities state changes. Returns time object
  • async listEntitiesService() - subsribes to entities state changes. Returns entities list
  • subscribeStatesService() - subsribes to entities state changes
  • subscribeLogsService(level = 5, dumpConfig = false) - subsribes to logs.
    • level - logs level. 0 - NONE, 1 - ERROR, 2 - WARN, 3 - INFO, 4 - DEBUG, 5 - DEBUG, 6 - VERBOSE, 7 - VERY_VERBOSE
    • dumpConfig
  • cameraImageService(single = true, stream = false) - requests camera image.
    • single
    • stream
  • subscribeBluetoothAdvertisementService() - subsribes to bluetooth advertisement state changes
  • unsubscribeBluetoothAdvertisementService() - unsubsribes to bluetooth advertisement state changes
  • async connectBluetoothDeviceService(address = int) - connect to connectable BLE device
  • async disconnectBluetoothDeviceService(address = int) - disconnect to connectable BLE device
  • async listBluetoothGATTServicesService(address = int) - MUST be connected to BLE device, BLE list GATT services
  • async readBluetoothGATTCharacteristicService(address = int, handle) - MUST be connected to BLE device, BLE list GATT Characteristic services
  • async writeBluetoothGATTCharacteristicService(address = int, handle, someUint8Array, response = false) - MUST be connected to BLE device, BLE write GATT Characteristic more pull/10
  • async notifyBluetoothGATTCharacteristicService(address = int, handle) - MUST be connected to BLE device, BLE notify GATT Characteristic
  • async readBluetoothGATTDescriptorService(address = int, handle) - MUST be connected to BLE device, BLE list GATT Descriptor
  • async writeBluetoothGATTDescriptorService(address = int, handle, someUint8Array) - MUST be connected to BLE device, BLE write GATT Descriptor
  • <entityType>CommandService(data) - sends command to the specified entity. See static commandService in the Entity classes
    • buttonCommandService(data)
    • climateCommandService(data)
    • coverCommandService(data)
    • fanCommandService(data)
    • lightCommandService(data)
    • lockCommandService(data)
    • numberCommandService(data)
    • selectCommandService(data)
    • sirenCommandService(data)
    • switchCommandService(data)
    • mediaplayerCommandService(data)

Connection events

  • message.<type> - when valid message from esphome device is received. First arg is message. The event is called before message event(more genetal analogue)
  • reconnect - emmited if client is reconnect to esphome device
  • message - when valid message from esphome device is received. First arg is type, second is message.
  • connected - emmited if client is introduced to esphome device
  • disconnected - emmited if session is corruptred
  • authorized - emmited if client is logged in esphome device
  • unauthorized - emmited if session is corruptred
  • data - when any data is received
  • error - when any error is occured
  • unhandledData - when data is received, but an error occured and we have unprocessed data