1.3.1 • Published 2 months ago

@2colors/esphome-native-api v1.3.1

Weekly downloads
-
License
MIT
Repository
github
Last release
2 months ago

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
esphomenative-apiclient
@richardhopton/noise-c.wasmgoogle-protobufmulticast-dns
@everything-registry/sub-chunk-16homebridge-esphome-aciobroker.esphomenode-red-contrib-esphome@sam-hunt/homebridge-esphome-ts
1.3.1

2 months ago

1.3.0

5 months ago

1.2.9

5 months ago

1.2.8

5 months ago

1.2.7

6 months ago

1.2.6

6 months ago

1.2.5

7 months ago

1.2.4

9 months ago

1.2.0

1 year ago

1.1.1

1 year ago

1.2.3

1 year ago

1.2.2

1 year ago

1.2.1

1 year ago

1.1.0

1 year ago

1.0.9

1 year ago

1.0.8

1 year ago

1.0.7

1 year ago

1.0.6

1 year ago