npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

homewizard-energy-api

v1.5.0

Published

Typesafe Node implementation of the HomeWizard Energy API

Downloads

60

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

jvandenaardwegjvandenaardweg

Keywords

homewizardhomewizard-energyhomewizard energyhomewizard-energy-sockethomewizard energy sockethomewizard-apihomewizard apihomewizard-energy-apihomewizard energy api

Readme

Full type-safe implementation of the HomeWizard Energy API in Node. Use the Local API of your HomeWizard devices with ease.

Features

  • Complete type-safety on all API methods, responses, and errors
  • Supports all HomeWizard Wi-Fi devices that have a Local API
  • Exposes a discovery method to discover devices on your local network using Multicast DNS
  • Provides a simple polling interface to request near real-time data from your devices
  • Transforms the P1 telegram text from the P1 meter into a readable detailed object
  • Includes inline documentation on each method, type and property
  • Follows the guidelines provided in the official HomeWizard Energy API documentation

Installation

This library requires Node 14 or higher. Typescript is only required for type-safety, the library will also work without Typescript.

npm install homewizard-energy-api

or

yarn add homewizard-energy-api

Supported devices

This library supports all devices from HomeWizard that expose an API. This includes:

Make sure to enable the Local API setting for each device you want to use with this library. You can do this in the Energy app.

P1 Meter

Get the power consumption or gas usage in your home from the Wi-Fi P1 Meter:

import { P1MeterApi } from 'homewizard-energy-api';

const p1Meter = new P1MeterApi('http://192.168.1.11');

// Get the active power and gas usage
const data = await p1Meter.getData();

| Method | API | Function | Description | | ------ | ---------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | /api | getBasic() | Get basic information from the device. More info in the official docs. | | GET | /api/v1/data | getData() | Returns the most recent measurement from the device. More info in the official docs. | | GET | /api/v1/telegram | getTelegram() | Returns the most recent, valid telegram in text format that was given by the P1 meter, therefore this endpoint is only available for the HWE-P1. More info in the official docs. | | GET | /api/v1/telegram | getParsedTelegram() | Returns the telegram as a detailed JSON response. This is a feature of this library, and not of the API itself. See telegram docs for more info about the telegram endpoint | | PUT | /api/v1/identify | identify() | Identify the device. The status light will blink for a few seconds after calling this endpoint. More info in the official docs. | | GET | /api/v1/system | getSystem() | Returns the actual system settings. More info in the official docs. | | PUT | /api/v1/system | updateSystem() | Configure system settings. Currently the only available option it to turn on and off all cloud communication. More info in the official docs. |

Data polling

A simple polling interface for the P1 Meter (and all other devices) is exposed via api.polling.getData, api.polling.getTelegram and api.polling.getParsedTelegram. See the examples for more information.

import { P1MeterApi } from 'homewizard-energy-api';

const p1Meter = new P1MeterApi('http://192.168.1.35', {
  polling: {
    interval: 1000, // Poll the endpoints each second. Defaults to 1000
    stopOnError: true, // Will stop polling when an error occurs. Defaults to false
  },
});

p1Meter.polling.getData.start();

p1Meter.polling.getData.on('response', response => {
  // Receive the latest data of this P1 Meter from the /api/v1/data endpoint each second:
  // {
  //   smr_version: 50,
  //   meter_model: 'ISKRA 2M550T-1012',
  //   wifi_ssid: 'SOME_WIFI_SSID',
  //   wifi_strength: 100,
  //   total_power_import_t1_kwh: 19055.287,
  //   total_power_import_t2_kwh: 19505.815,
  //   total_power_export_t1_kwh: 0.002,
  //   total_power_export_t2_kwh: 0.007,
  //   active_power_w: 997,
  //   active_power_l1_w: 66,
  //   active_power_l2_w: 88,
  //   active_power_l3_w: 852,
  //   total_gas_m3: 6789.488,
  //   gas_timestamp: 221217223003
  // }
});

p1Meter.polling.getData.on('error', error => {
  // handle an error
});

Energy Socket

Control your Wi-Fi Energy Socket:

import { EnergySocketApi } from 'homewizard-energy-api';

const energySocket = new EnergySocketApi('http://192.168.1.10');

// Turn the Energy Socket ON
const updatedState = await energySocket.updateState({ power_on: true });

| Method | API | Function | Description | | ------ | ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | /api | getBasic() | Get basic information from the device. More info in the official docs. | | GET | /api/v1/state | getState() | Returns the actual state of the Energy Socket. More info in the official docs. | | PUT | /api/v1/state | updateState() | Control the state of the Energy Socket. More info in the official docs. | | GET | /api/v1/data | getData() | Returns the most recent measurement from the device. More info in the official docs. | | PUT | /api/v1/identify | identify() | Identify the device. The status light will blink for a few seconds after calling this endpoint. More info in the official docs. | | GET | /api/v1/system | getSystem() | Returns the actual system settings. More info in the official docs. | | PUT | /api/v1/system | updateSystem() | Configure system settings. Currently the only available option it to turn on and off all cloud communication. More info in the official docs. |

Data polling

A simple polling interface for the Energy Sockets is exposed via api.polling.getData and api.polling.getState. See the examples for more information.

Watermeter

Get the water consumption in your home from the Wi-Fi Watermeter:

import { WaterMeterApi } from 'homewizard-energy-api';

const waterMeter = new WaterMeterApi('http://192.168.1.12');

// Get the active water usage
const data = await waterMeter.getData();

| Method | API | Function | Description | | ------ | ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | /api | getBasic() | Get basic information from the device. More info in the official docs. | | GET | /api/v1/data | getData() | Returns the most recent measurement from the device. More info in the official docs. |

Data polling

A simple polling interface for the Watermeter is exposed via api.polling.getData. See the examples for more information.

kWh Meter 1-phase

Get the power consumption from the Wi-Fi kWh meter 1-phase MID:

import { KwhMeter1PhaseApi } from 'homewizard-energy-api';

const kwhMeter1Phase = new KwhMeter1PhaseApi('http://192.168.1.13');

// Get the power usage from your Wi-Fi kWh meter 1-phase MID
const data = await kwhMeter1Phase.getData();

| Method | API | Function | Description | | ------ | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | /api | getBasic() | Get basic information from the device. More info in the official docs. | | GET | /api/v1/data | getData() | Returns the most recent measurement from the device. More info in the official docs. | | GET | /api/v1/system | getSystem() | Returns the actual system settings. More info in the official docs. | | PUT | /api/v1/system | updateSystem() | Configure system settings. Currently the only available option it to turn on and off all cloud communication. More info in the official docs. |

Data polling

A simple polling interface for the kWh Meter 1-phase is exposed via api.polling.getData. See the examples for more information.

kWh Meter 3-phase

Get the power consumption from the Wi-Fi kWh meter 3-phase MID:

import { KwhMeter3PhaseApi } from 'homewizard-energy-api';

const kwhMeter3Phase = new KwhMeter3PhaseApi('http://192.168.1.14');

// Get the power usage from your Wi-Fi kWh meter 3-phase MID
const data = await kwhMeter3Phase.getData();

| Method | API | Function | Description | | ------ | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | /api | getBasic() | Get basic information from the device. More info in the official docs. | | GET | /api/v1/data | getData() | Returns the most recent measurement from the device. More info in the official docs. | | GET | /api/v1/system | getSystem() | Returns the actual system settings. More info in the official docs. | | PUT | /api/v1/system | updateSystem() | Configure system settings. Currently the only available option it to turn on and off all cloud communication. More info in the official docs. |

Data polling

A simple polling interface for the kWh Meter 3-phase is exposed via api.polling.getData. See the examples for more information.

Discover HomeWizard devices in your network

This library exposes a discovery method to discover HomeWizard Energy devices in your local network. Each HomeWizard device broadcasts itself on your local network using Multicast DNS. This allows you to use all the devices in your network without knowing the actual IP address of the device. You can find more details about this in the official docs.

Discovery example

import { HomeWizardEnergyDiscovery } from 'homewizard-energy-api';

const discovery = new HomeWizardEnergyDiscovery();

discovery.start();

discovery.on('response', response => {
  // You'll get a response for each device that is found
  // Example response:
  // {
  //   ip: '192.168.1.34',
  //   hostname: 'energysocket-25FF1A.local',
  //   fqdn: 'energysocket-25FF1A._hwenergy._tcp.local',
  //   txt: {
  //     api_enabled: '1',
  //     path: '/api/v1',
  //     serial: '3c39e725ff1a',
  //     product_name: 'Energy Socket',
  //     product_type: 'HWE-SKT'
  //   }
  // }
});

About this library

Hi there! I created this library to provide type-safety when using the HomeWizard Energy API's in my own projects. I made it open source so that you can easily control your HomeWizard devices and have the same level of type-safety while developing your projects.

I'm not affiliated with HomeWizard. I create open source projects in my free time. If you find this project helpful, please consider supporting me on my GitHub Sponsor page. Your support will help me continue to create high-quality, open source projects and cover the costs of maintaining them.

Thank you for your support!

Note that logos, products, and trademarks are the property of HomeWizard.

About HomeWizard Energy

With the HomeWizard Energy platform, you can get insights in your energy usage. Use the HomeWizard Wi-Fi P1 meter to access real-time data directly from your smart meter, the HomeWizard Wi-Fi Energy Socket to get energy insights from all your devices, the HomeWizard Wi-Fi kWh meter to measure devices such as solar panels and the HomeWizard Wi-Fi Watermeter to get insight in your water usage. With the open API you can integrate the data directly into your system of choice.

API Introduction

The HomeWizard Wi-Fi P1 meter, Wi-Fi Energy Socket, Wi-Fi kWh meter and Wi-Fi Watermeter (‘device’) have a local API to retrieve the most recent measurements or control the device. You can access this API as long as you are connected to the same (Wi-Fi) network as the device and the API is enabled in the HomeWizard Energy app. This API is intended to connect your device to your own automation, home automation or graphing system. It is not possible to retrieve data history with the local API, as this is not stored on the device itself.