1.0.9 • Published 3 years ago

esphome-native-api v1.0.9

Weekly downloads
175
License
SEE LICENSE IN LI...
Repository
github
Last release
3 years ago

Publish Test

Esphome native api

This library implements client for Esphome Native APi.

Installation

$ npm i esphome-native-api

Synopsis

Device info and list entities

const { Client } = require('esphome-native-api');
const client = new Client({
    host: '<esp host or ip>',
    port: 6053
});
client.on('deviceInfo', deviceInfo => {
    console.log('Device info:', deviceInfo);
});
client.on('newEntity', entity => {
    console.log('New entity:', entity);

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

Discovery

const { Discovery } = require('esphome-native-api');
Discovery().then(results => {
    console.log(results);
    /*
    [
        {
        mac: '240ac45eebd4',
        host: 'esp32_binary_fan.local',
        version: '1.16.1',
        address: '192.168.0.144',
        family: 'IPv4'
        }
    ]
    */
});
const { Discovery } = require('esphome-native-api');
const discovery = new Discovery();
discovery.on('info', console.log);
/*
{
    mac: '240ac45eebd4',
    host: 'esp32_binary_fan.local',
    version: '1.16.1',
    address: '192.168.0.144',
    family: 'IPv4'
}
*/
discovery.run();

Logging

const { Client } = require('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

const { Discovery } = require('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)

const { Discovery } = require('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('esphome-native-api');
const client = new Client({
    clearSession = false,
    initializeDeviceInfo = true,
    initializeListEntities = true,
    initializeSubscribeStates = true,
    initializeSubscribeLogs = false,
    port = 6053,
    host,
    clientInfo = 'esphomenativeapi',
    password = '',
    reconnect = true,
    reconnectInterval = 30000,
    pingInterval = 15000,
    pingAttempts = 3
});
  • host - (REQUIRED). Host or ip to connect to.
  • port - optional. Default - 6053. Port to connect to.
  • password - passsword. Default - ''. Password used to authorized the client
  • 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.
  • 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
  • error - emitted when any error occurs

Entities

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

  • configattrubute - 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
  • name attribute equal to name of entity

Binary sensor

Only base functionality

Camera

Climate

Cover

Fan

Light

Sensor

Only base functionality

Switch

TestSensor

Only base functionality

Connection

const { Connection } = require('esphome-native-api');
const connection = new Connection({
    port = 6053,
    host,
    clientInfo = 'esphomenativeapi',
    password = '',
    reconnect = true,
    reconnectInterval = 30000,
    pingInterval = 15000,
    pingAttempts = 3
});
  • host - (REQUIRED). Host or ip to connect to.
  • port - optional. Default - 6053. Port to connect to.
  • password - passsword. Default - ''. Password used to authorized the client
  • 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

  • socketConnected - true if socket is connected but no
  • connected - true if client is introduced to esphome device
  • authorized - true if client is logged in esphome device
  • connecting
  • reconnecting
  • disconnecting
  • connect() - do connection try
  • 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
  • async subscribeStatesService() - subsribes to entities state changes
  • async subscribeLogsService(level = 3, dumpConfig = false) - subsribes to logs. Params:
    • level - logs level. 0 - NONE, 1 - ERROR, 2 - WARN, 3 - INFO, 4 - DEBUG, 5 - DEBUG, 6 - VERBOSE, 7 - VERY_VERBOSE
    • dumpConfig
  • async cameraImageService(single = true, stream = false) - requests camera image. Params:
    • single
    • stream
  • async coverCommandService({ key, legacyCommand, position, tilt, stop }) - sends command to cover entity. Params:
    • key - REQUIRED. key/id of entity
    • legacyCommand - optional. 0 - OPEN, 1 - CLOSE, 2 - STOP
    • position - optional. integer
    • tilt - optional. integer
    • stop - optional. boolean
  • async lightCommandService({ key, state, brightness, red, green, blue, white, colorTemperature, transitionLength, flashLength, effect }) - sends command to light entity. Params:
    • key - REQUIRED. key/id of entity
    • state - optional. boolean
    • brightness - optional. integer
    • red - optional. integer 0-255
    • green - optional. integer 0-255
    • blue - optional. integer 0-255
    • white - optional. integer 0-255
    • colorTemperature - optional. integer
    • flashLength - optional. integer
    • effect - optional. effect from effects array in config list
  • async switchCommandService({ key, state }) - sends command to switch entity Params: - key - REQUIRED. key/id of entity - state - optional. boolean
  • async climateCommandService({ key, mode, targetTemperature, targetTemperatureLow, targetTemperatureHigh, away, fanMode, swingMode }) - sends command to climate entity Params: - key - REQUIRED. key/id of entity - mode - optional. 0 - OFF, 1 - AUTO, 2 - COOL, 3 - HEAT, 4 - FAN_ONLY, 5 - DRY. See supported_modes attr in config - targetTemperature- optional. float - targetTemperatureLow- optional. float - targetTemperatureHigh- optional. float - away - optional. Boolean - fanMode - optional. 0 - ON, 1 - OFF, 2 - AUTO, 3 - LOW, 4 - MEDIUM, 5 - HIGH, 6 - MIDDLE, 7 - FOCUS, 8 - DIFFUSE. See supported_fan_modes attr in config - swingMode - optional. 0 - OFF, 1 - BOTH, 2 - VERTICAL, 3 - HORIZONTAL. See supported_swing_modes attr in config

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)
  • message - when valid message from esphome device is received. First arg is type, second is message.
  • socketConnected - emmited when socket is connected
  • socketDisconnected - emmited when socket is disconnected
  • 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

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)
  • message - when valid message from esphome device is received. First arg is type, second is message.
  • socketConnected - emmited when socket is connected
  • socketDisconnected - emmited when socket is disconnected
  • 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
esphomenative-apiesphomeclient
bluebirdeslinteventsgoogle-protobufmulticast-dnsnet
@everything-registry/sub-chunk-1616@infinitebrahmanuniverse/nolb-esp
1.0.9

3 years ago

1.0.8

3 years ago

1.0.7

3 years ago

1.0.6

3 years ago

1.0.5

3 years ago

1.0.4

3 years ago

1.0.2

3 years ago

1.0.1

3 years ago

1.0.3

3 years ago

1.0.0

3 years ago