Home Assistant Node.js library
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
.eslintrc
.gitignore
LICENSE
README.md
package.json
yarn.lock

README.md

node-homeassistant

Home Assistant API Node.js library. It wraps the Home Assistant RESTful API in easy-to-use, Promise-based functions.

NPM Badge

Install

npm install homeassistant

Usage

const HomeAssistant = require('homeassistant');
const hass = new HomeAssistant({
  // Your Home Assistant host
  // Optional, defaults to http://locahost
  host: 'http://example.com',

  // Your Home Assistant port number
  // Optional, defaults to 8123
  port: 8123,

  // Your Home Assistant API password
  // Optional
  password: 'api_password',

  // Ignores SSL certificate errors, use with caution
  // Optional, defaults to false
  ignoreCert: false
});

hass.services.call('toggle', 'switch', 'lights_3_0')
  .then(res => console.log('Toggled lights', res))
  .catch(err => console.error(err));

Interface

All functions return Promises.

Configuration

// Returns if the API is up and running
hass.status();

// Returns the current configuration
hass.config();

// Returns basic information about the Home Assistant instance
hass.discoveryInfo();

// Returns all data needed to bootstrap Home Assistant
hass.bootstrap();

Camera

// Returns the image from the specified camera entity
hass.camera.image('entityId');

Events

// Returns an array of event objects
hass.events.list();

// Fires an event
// Requires the event name and an event data JSON object
hass.events.fire('call_service', {
  domain: 'switch',
  service: 'toggle',
  service_data: {
    entity_id: 'switch.lights_3_0'
  }
});

History

// Returns an array of state changes in the past
// Requires a datetime in YYYY-MM-DDTHH:MM:SSZ format
// An optional entityId can be provided to filter the results
hass.history.state('2017-05-01T12:00:00-04:00', 'sensor.temperature');

Logs

// Returns all errors logged during the current session of Home Assistant
hass.logs.errors();

Services

// Returns an array of all service objects
hass.services.list();

// Calls a service
// Requires the service, the domain, and the entity
// Alternatively, you can provide a service data JSON object as the third parameter
hass.services.call('toggle', 'switch', 'lights_3_0');
hass.services.call('toggle', 'switch', {
  entity_id: 'switch.lights_3_0'
});

States

// Returns an array of all state objects
hass.states.list();

// Returns a state object for a specified entity
// Requires the domain and entity
hass.states.get('sensor', 'temperature');

// Updates or creates the current state of an entity
// Requires the domain, entity, and a JSON object with a `state` attribute
hass.states.update('sensor', 'temperature', {
  state: 80,
  attributes: {
    unit_of_measurement: '°F'
  }
});

Templates

// Renders a Home Assistant template: https://home-assistant.io/topics/templating/
hass.templates.render('Mike is at {{ states("device_tracker.mike") }}.');

License

MIT