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)
  • textCommandService(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