This library implements client for Esphome Native APi.
This library rewrite for node-red-contrib-esphome, original library esphome-native-api by @Nafaya
$ npm i @2colors/esphome-native-api
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));
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();
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);
});
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 workinterface
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
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
. Settrue
to forget any information after reconnection -
initializeDeviceInfo
- optional. Default -true
. Settrue
to retrieve device info after connection is established -
initializeListEntities
- optional. Default -true
. Settrue
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
-
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
-
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 withinitializeDeviceInfo
options passed toClient
's constructor. -
newEntity
- emmited when new entity is discovered. Activated withinitializeListEntities
options passed toClient
's constructor. First argument is instance of one of entities class -
logs
- emmited when esphome send any logs. Activated withinitializeSubscribeLogs
options passed toClient
's constructor. First argument is object withlevel
,tag
,message
,send_failed
-
ble
- emmited when esphome send any BLE Advertisements. Activated withinitializeSubscribeBLEAdvertisements
options passed toClient
's constructor. First argument is object withaddress
,name
,rssi
,serviceUuidsList
,serviceDataList
,manufacturerDataList
,addressType
-
error
- emitted when any error occurs
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(SeeclearSession
option) and -
type
attribute equal to component type -
name
attribute equal to name of entity
Only base functionality
-
static commandService(connection, { key })
-
key
- REQUIRED. key/id of entity
-
-
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. SeesupportedModesList
attr in config -
targetTemperature
- optional. float -
targetTemperatureLow
- optional. float -
targetTemperatureHigh
- optional. float -
legacyAway
- optional. Boolean. Deprecated: usepreset
with AWAY -
fanMode
- optional. 0 - ON, 1 - OFF, 2 - AUTO, 3 - LOW, 4 - MEDIUM, 5 - HIGH, 6 - MIDDLE, 7 - FOCUS, 8 - DIFFUSE, 9 - QUIET. SeesupportedFanModesList
attr in config -
swingMode
- optional. 0 - OFF, 1 - BOTH, 2 - VERTICAL, 3 - HORIZONTAL. SeesupportedSwingModesList
attr in config -
customFanMode
- optional. string. SeesupportedCustomFanModesList
attr in config -
preset
- optional. 0 - NONE, 1 - HOME, 2 - AWAY, 3 - BOOST, 4 - COMFORT, 5 - ECO, 6 - SLEEP, 7 - ACTIVITY. SeesupportedPresetsList
attr in config -
customPreset
- optional. string. SeesupportedCustomPresetsList
attr in config
-
-
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: useposition
-
position
- optional. float. 0.0 - CLOSED, 1.0 - OPEN. SeesupportsPosition
attr in config -
tilt
- optional. float. 0.0 - CLOSED, 1.0 - OPEN. SeesupportsTilt
attr in config -
stop
- optional. boolean
-
-
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. SeesupportedSpeedLevels
attr in config
-
-
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. SeesupportedColorModesList
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
-
-
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. SeerequiresCode
attr in config
-
-
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
-
-
static commandService(connection, { key, state })
- sends command to number entity.-
key
- REQUIRED. key/id of entity -
state
- REQUIRED. float. SeeminValue
,maxValue
, andstep
attrs in config
-
-
static commandService(connection, { key, state })
- sends command to select entity.-
key
- REQUIRED. key/id of entity -
state
- REQUIRED. string. SeeoptionsList
attr in config
-
Only base functionality
-
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. SeetonesList
attr in config -
duration
- optional. integer. SeesupportsDuration
attr in config -
volume
- optional. integer. SeesupportsVolume
attr in config
-
-
static commandService(connection, { key, state })
- sends command to switch entity.-
key
- REQUIRED. key/id of entity -
state
- REQUIRED. boolean
-
Only base functionality
-
static commandService(connection, { key, state })
- sends command to text entity.-
key
- REQUIRED. key/id of entity -
state
- REQUIRED. string. SeeminLength
,maxLength
attrs in config
-
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.
-
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. Seestatic commandService
in the Entity classesbuttonCommandService(data)
climateCommandService(data)
coverCommandService(data)
fanCommandService(data)
lightCommandService(data)
lockCommandService(data)
numberCommandService(data)
selectCommandService(data)
sirenCommandService(data)
switchCommandService(data)
mediaplayerCommandService(data)
-
message.<type>
- when valid message from esphome device is received. First arg is message. The event is called beforemessage
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