Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/filp/homeassistant-ws
Minimalist client library for Homeassistant's Websocket API
https://github.com/filp/homeassistant-ws
api homeassistant node npm websocket
Last synced: about 15 hours ago
JSON representation
Minimalist client library for Homeassistant's Websocket API
- Host: GitHub
- URL: https://github.com/filp/homeassistant-ws
- Owner: filp
- License: mit
- Created: 2020-04-26T22:06:08.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-08-24T11:26:47.000Z (about 1 month ago)
- Last Synced: 2024-09-20T13:36:25.077Z (5 days ago)
- Topics: api, homeassistant, node, npm, websocket
- Language: TypeScript
- Size: 128 KB
- Stars: 15
- Watchers: 6
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# homeassistant-ws
[](https://www.npmjs.com/package/homeassistant-ws)
[](https://github.com/filp/homeassistant-ws/blob/master/LICENSE.md)
Minimalist client library for [Homeassistant's Websocket API](https://developers.home-assistant.io/docs/external_api_websocket). Works in node, and also in the browser.
---
## Installation:
Using `npm`:
```shell
$ npm i --save homeassistant-ws
```
Import it in your project:
```js
import hass from 'homeassistant-ws';
async function main() {
// Assuming hass running in `localhost`, under the default `8321` port:
const client = await hass({
token: 'my-secret-token',
});
}
```
Tokens are available from your profile page under the Homeassistant UI. For documentation on the authentication API, see [the official HA documentation](https://developers.home-assistant.io/docs/auth_api/).
## Configuration options
The following properties (shown with their defaults) can be passed to the constructor. All are **optional**.
```js
hass({
protocol: 'ws',
host: 'localhost',
port: 8123,
path: '/api/websocket',
// Must be set if HA expects authentication:
token: null,
// Used to serialize outgoing messages:
messageSerializer: (outgoingMessage) => JSON.stringify(outgoingMessage),
// Used to parse incoming messages. Receives the entire Websocket message object:
messageParser: (incomingMessage) => JSON.parse(incomingMessage.data),
// Should return a WebSocket instance
ws: (opts) => {
return new WebSocket(
`${opts.protocol}://${opts.host}:${opts.port}${opts.path}`
);
},
});
```
## Example
The following example includes all available methods. For more details on available Homeassistant event types, states, etc. see the [official Websocket API](https://developers.home-assistant.io/docs/external_api_websocket)
```js
import hass from 'hass';
async function main() {
// Establishes a connection, and authenticates if necessary:
const client = await hass({ token: 'my-token' });
// Get a list of all available states, panels or services:
await client.getStates();
await client.getServices();
await client.getPanels();
// Get hass configuration:
await client.getConfig();
// Get a Buffer containing the current thumbnail for the given media player
await client.getMediaPlayerThumbnail('media_player.my_player');
// { content_type: 'image/jpeg', content: Buffer<...>}
// Get a Buffer containing a thumbnail for the given camera
await client.getCameraThumbnail('camera.front_yard');
// { content_type: 'image/jpeg', content: Buffer<...>}
// Call a service, by its domain and name. The third argument is optional.
await client.callService('lights', 'turn_on', {
entity_id: 'light.my_light',
});
// Listen for all HASS events - the 'message' event is a homeassistant-ws event triggered for
// all messages received through the websocket connection with HASS:
//
// See https://developers.home-assistant.io/docs/api/websocket/ for details on HASS events:
client.on('message', (rawMessageData) => {
console.log(rawMessageData);
});
// Listen only for state changes:
client.on('state_changed', (stateChangedEvent) => {
console.log(stateChangedEvent.data.new_state.state);
});
}
```