New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

homewizard-energy-api

Package Overview
Dependencies
Maintainers
1
Versions
13
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

homewizard-energy-api

Typesafe Node implementation of the HomeWizard Energy API

  • 1.5.0
  • latest
  • Source
  • npm
  • Socket score
Version published
Weekly downloads
37
decreased by-58.89%
Maintainers
1
Weekly downloads
 
Created
Source

HomeWizard Energy API

npm   github   github sponsor   mit license

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();
MethodAPIFunctionDescription
GET/apigetBasic()Get basic information from the device. More info in the official docs.
GET/api/v1/datagetData()Returns the most recent measurement from the device. More info in the official docs.
GET/api/v1/telegramgetTelegram()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/telegramgetParsedTelegram()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/identifyidentify()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/systemgetSystem()Returns the actual system settings. More info in the official docs.
PUT/api/v1/systemupdateSystem()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 });
MethodAPIFunctionDescription
GET/apigetBasic()Get basic information from the device. More info in the official docs.
GET/api/v1/stategetState()Returns the actual state of the Energy Socket. More info in the official docs.
PUT/api/v1/stateupdateState()Control the state of the Energy Socket. More info in the official docs.
GET/api/v1/datagetData()Returns the most recent measurement from the device. More info in the official docs.
PUT/api/v1/identifyidentify()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/systemgetSystem()Returns the actual system settings. More info in the official docs.
PUT/api/v1/systemupdateSystem()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();
MethodAPIFunctionDescription
GET/apigetBasic()Get basic information from the device. More info in the official docs.
GET/api/v1/datagetData()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();
MethodAPIFunctionDescription
GET/apigetBasic()Get basic information from the device. More info in the official docs.
GET/api/v1/datagetData()Returns the most recent measurement from the device. More info in the official docs.
GET/api/v1/systemgetSystem()Returns the actual system settings. More info in the official docs.
PUT/api/v1/systemupdateSystem()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();
MethodAPIFunctionDescription
GET/apigetBasic()Get basic information from the device. More info in the official docs.
GET/api/v1/datagetData()Returns the most recent measurement from the device. More info in the official docs.
GET/api/v1/systemgetSystem()Returns the actual system settings. More info in the official docs.
PUT/api/v1/systemupdateSystem()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.

Keywords

FAQs

Package last updated on 02 Sep 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

Oracle Drags Its Feet in the JavaScript Trademark Dispute

Security News

Oracle Drags Its Feet in the JavaScript Trademark Dispute

Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.

By Sarah Gooding  -  Feb 07, 2025
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc