Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# HomeWizard Energy - Local API Documentation
# HomeWizard - Local API Documentation

The HomeWizard Energy devices are equipped with a local API. This API can be used to read out the data from the device and to control the device. This documentation describes the API and how to use it.
The HomeWizard devices are equipped with a local API. This API can be used to read out the data from the device and to control the device. This documentation describes the API and how to use it.

> [!TIP]
> Visit [api-documentation.homewizard.com](https://api-documentation.homewizard.com) to learn everything about the HomeWizard Energy API.
> Visit [api-documentation.homewizard.com](https://api-documentation.homewizard.com) to learn everything about the HomeWizard API.

## Contributing

Expand Down
2 changes: 1 addition & 1 deletion docs/changelog.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Feature development of the v1 API has been stopped. No new features will be adde

#### 2.0.1 - 30-01-2025

- An issue has been resolved where `energy_import_kwh` and `energy_export_kwh` values in the Plug-In Battery [Measurement API](/docs/v2/measurement#plug-in-battery-hwe-bat) were returning invalid values. The values are now the same as those in the HomeWizard Energy app.
- An issue has been resolved where `energy_import_kwh` and `energy_export_kwh` values in the Plug-In Battery [Measurement API](/docs/v2/measurement#plug-in-battery-hwe-bat) were returning invalid values. The values are now the same as those in the HomeWizard app.

#### 2.1.0 - 01-05-2025

Expand Down
10 changes: 5 additions & 5 deletions docs/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,23 @@ import Link from '@docusaurus/Link'

# Getting Started.

This guide will help you get started with the HomeWizard Energy API.
This guide will help you get started with the HomeWizard API.

## Choosing the Right API Version.

The HomeWizard Energy API has two versions: v1 and v2. The v1 API is available as long as feasible, but will be phased out. The v2 API is the stable version and is recommended to be used. Skip to [getting started with v2](#getting-started-with-v2) if you want to use the v2 API.
The HomeWizard API has two versions: v1 and v2. The v1 API is available as long as feasible, but will be phased out. The v2 API is the stable version and is recommended to be used. Skip to [getting started with v2](#getting-started-with-v2) if you want to use the v2 API.

[Review the device compatibility table](/docs/introduction#devices) to check which API versions are supported for your specific hardware before choosing your version.

## Getting Started with v1.

### 1. Connect your Device to Wi-Fi

Connect your Device to Wi-Fi with the <Link href="https://www.homewizard.nl/energy">HomeWizard Energy App</Link>. Make sure to connect your device with the same network as the device that makes use of the API.
Connect your Device to Wi-Fi with the <Link href="https://www.homewizard.com/">HomeWizard app</Link>. Make sure to connect your device with the same network as the device that makes use of the API.

### 2. Enable the API

To access the data from an Energy device, you have to enable the API. You can do this in the <Link href="https://www.homewizard.nl/energy">HomeWizard Energy app</Link>. Go to Settings → Meters → _Your meter_, and turn on _Local API_.
To access the data from an Energy device, you have to enable the API. You can do this in the <Link href="https://www.homewizard.com/">HomeWizard app</Link>. Go to Settings → Meters → _Your meter_, and turn on _Local API_.

### 3. Get a Measurement

Expand All @@ -43,7 +43,7 @@ The following example will show you can use the API to get basic information.

### 1. Connect your Device to Wi-Fi

Connect your device to Wi-Fi with the <Link href="https://www.homewizard.nl/energy">HomeWizard Energy app</Link>. Make sure to connect your device with the same network as the device that makes use of the API.
Connect your device to Wi-Fi with the <Link href="https://www.homewizard.com/">HomeWizard app</Link>. Make sure to connect your device with the same network as the device that makes use of the API.

### 2. Get a Token

Expand Down
14 changes: 7 additions & 7 deletions docs/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,21 @@ import Badge from '@site/src/components/Badge.js'

# Introduction.

With the HomeWizard Energy platform, you can gain insights into your energy usage. Use the HomeWizard <Link to="https://www.homewizard.com/p1-meter/">P1 Meter</Link> to access real-time data directly from your smart meter, the HomeWizard <Link to="https://www.homewizard.com/energy-socket">Energy Socket</Link> to get energy insights from all your devices, the HomeWizard <Link to="https://www.homewizard.com/kwh-meter">kWh Meter</Link> to measure devices such as solar panels, and the HomeWizard <Link to="https://www.homewizard.com/watermeter">Water Meter</Link> to gain insights into your water usage. With the open API, you can integrate the data directly into your system of choice.
With the HomeWizard platform, you can gain insights into your energy usage. Use the HomeWizard <Link to="https://www.homewizard.com/p1-meter/">P1 Meter</Link> to access real-time data directly from your smart meter, the HomeWizard <Link to="https://www.homewizard.com/energy-socket">Energy Socket</Link> to get energy insights from all your devices, the HomeWizard <Link to="https://www.homewizard.com/kwh-meter">kWh Meter</Link> to measure devices such as solar panels, and the HomeWizard <Link to="https://www.homewizard.com/watermeter">Watermeter</Link> to gain insights into your water usage. With the open API, you can integrate the data directly into your system of choice.

## HomeWizard Energy API.
## HomeWizard API.

The HomeWizard P1 Meter, Energy Socket, kWh Meter, Watermeter, and Plug-In Battery (referred to as "device") each have a local API that allows you to retrieve the latest 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 designed for integrating your device with personal automation, home automation, or data graphing systems. It is not possible to retrieve historical data through the local API, as this data is not stored on the device itself.
The HomeWizard P1 Meter, Energy Socket, kWh Meter, Watermeter, and Plug-In Battery (referred to as "device") each have a local API that allows you to retrieve the latest 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 app. This API is designed for integrating your device with personal automation, home automation, or data graphing systems. It is not possible to retrieve historical data through the local API, as this data is not stored on the device itself.

## Terms and Conditions.

- **License** - The HomeWizard Energy API is licensed, not sold. HomeWizard grants the user a non-exclusive license (with no right to sub-license) to the HomeWizard Energy API for personal, non-commercial use.
- **Usage** - The user may not directly or indirectly use the HomeWizard Energy API to sell, lease, loan or generate a revenue from a product, system or software using the API
- **Support** - The usage of the HomeWizard Energy API is officially supported by HomeWizard, however HomeWizard can not supply customer service regarding the implementation of the API in your own or third party applications.
- **License** - The HomeWizard API is licensed, not sold. HomeWizard grants the user a non-exclusive license (with no right to sub-license) to the HomeWizard API for personal, non-commercial use.
- **Usage** - The user may not directly or indirectly use the HomeWizard API to sell, lease, loan or generate a revenue from a product, system or software using the API
- **Support** - The usage of the HomeWizard API is officially supported by HomeWizard, however HomeWizard can not supply customer service regarding the implementation of the API in your own or third party applications.

## API v2.

The HomeWizard Energy API is moving to v2, which is a more secure and feature-rich version of the API. In v2 of the API, we have added the following features:
The HomeWizard API is moving to v2, which is a more secure and feature-rich version of the API. In v2 of the API, we have added the following features:

- **HTTPS** - Your data is securely transmitted.
- **Always available** - No need to turn on the API in the app.
Expand Down
2 changes: 1 addition & 1 deletion docs/v1/system.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The `/api/v1/system` endpoint can be used to configure system settings. Currentl

## Enable Cloud.

The HomeWizard Energy devices are designed to work with the HomeWizard Energy app and require communication with the HomeWizard cloud to make them function with the app.
The HomeWizard devices are designed to work with the HomeWizard app and require communication with the HomeWizard cloud to make them function with the app.

The `Enable cloud` configuration feature can be used to turn off all communication with the HomeWizard cloud, making the device fully local. The device cannot communicate with the app, and the device won't receive any future firmware updates.

Expand Down
6 changes: 3 additions & 3 deletions docs/v2/authorization.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Authorization
sidebar_position: 1
description: Get a token to authenticate requests to the HomeWizard Energy API.
description: Get a token to authenticate requests to the HomeWizard API.
---

import Badge from '@site/src/components/Badge.js'
Expand All @@ -20,7 +20,7 @@ import Badge from '@site/src/components/Badge.js'

---

The HomeWizard Energy API requires a Bearer token to authorize requests. This token should be included in the `Authorization` header of each request. To get a token you must create a user on the device.
The HomeWizard API requires a Bearer token to authorize requests. This token should be included in the `Authorization` header of each request. To get a token you must create a user on the device.

## Create User and get Token.

Expand Down Expand Up @@ -206,7 +206,7 @@ Content-Length: 0

## Local and Cloud Users.

The local API is used by HomeWizard to enable direct communication between HomeWizard devices on a local network. To simplify setup for non-technical users, tokens can also be generated via the HomeWizard Energy app or background process using the cloud.
The local API is used by HomeWizard to enable direct communication between HomeWizard devices on a local network. To simplify setup for non-technical users, tokens can also be generated via the HomeWizard app or background process using the cloud.

- Cloud-generated users are prefixed with `cloud/`, local users are prefixed with `local/`.
- These tokens are for local device communication only and do not provide access to the cloud nor can be used by the cloud itself.
Expand Down
2 changes: 1 addition & 1 deletion docs/v2/batteries.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import Badge from '@site/src/components/Badge.js'
<Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Socket</Badge>
<Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Display</Badge>
<Badge colorName='hw-green' icon='mdi:check' subtext='Supported'>kWh Meter</Badge>
<Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Water Meter</Badge>
<Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Watermeter</Badge>
<Badge colorName='hw-grey' icon='mdi:close' subtext='Not supported'>Plug-In Battery</Badge>
<br />
<sub>_See [Supported Devices](/docs/introduction#devices) for more information._</sub>
Expand Down
2 changes: 1 addition & 1 deletion docs/v2/error-handling.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Error Handling
sidebar_position: 7
description: Learn how to handle errors when using the HomeWizard Energy API.
description: Learn how to handle errors when using the HomeWizard API.
---

import Badge from '@site/src/components/Badge.js'
Expand Down
4 changes: 2 additions & 2 deletions docs/v2/system.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ The battery is fully controlled locally by the P1 Meter, ensuring fast operation

## Cloud Communication.

HomeWizard Energy devices are designed to work with the HomeWizard Energy app and rely on communication with the HomeWizard cloud for full functionality.
HomeWizard devices are designed to work with the HomeWizard app and rely on communication with the HomeWizard cloud for full functionality.

Users can choose to disable cloud communication, making the device operate entirely locally. However, this will prevent the app from interacting with the device, and the device will no longer receive firmware updates.

Expand Down Expand Up @@ -180,7 +180,7 @@ Content-Type: application/json
}
```

_The v1 API is now disabled, as if it was disabled via the HomeWizard Energy app. The v1 API will respond with an [API disabled error](/docs/v1/error-handling#api-was-disabled) when trying to use it._
_The v1 API is now disabled, as if it was disabled via the HomeWizard app. The v1 API will respond with an [API disabled error](/docs/v1/error-handling#api-was-disabled) when trying to use it._

## Identify.

Expand Down
2 changes: 1 addition & 1 deletion docs/v2/websocket.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import Badge from '@site/src/components/Badge.js'

---

The HomeWizard Energy WebSocket API allows you to receive real-time updates from the device. The WebSocket lets you subscribe to specific topics and receive updates when data changes.
The HomeWizard WebSocket API allows you to receive real-time updates from the device. The WebSocket lets you subscribe to specific topics and receive updates when data changes.

## Structure.

Expand Down
4 changes: 2 additions & 2 deletions docs/versioning.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ import Link from '@docusaurus/Link'

## Version Scheme.

The HomeWizard Energy API follows [semantic versioning](https://semver.org/), with the version number structured as `MAJOR.MINOR.PATCH`. The v1 API only uses the `MAJOR` version, while the v2 API uses both `MAJOR` and `MINOR`.
The HomeWizard API follows [semantic versioning](https://semver.org/), with the version number structured as `MAJOR.MINOR.PATCH`. The v1 API only uses the `MAJOR` version, while the v2 API uses both `MAJOR` and `MINOR`.

- `MAJOR` version updates signal incompatible changes in the API.
- `MINOR` version updates add backward-compatible features or enhancements.
- `PATCH` version updates provide backward-compatible bug fixes.

### Backward Compatibility

The HomeWizard Energy API is designed for backward compatibility, aiming to avoid breaking changes. When a breaking change is necessary, the `MAJOR` version number will increase, while the original API remains accessible. See [Requesting a Specific API Version](#requesting-a-specific-api-version) for more information.
The HomeWizard API is designed for backward compatibility, aiming to avoid breaking changes. When a breaking change is necessary, the `MAJOR` version number will increase, while the original API remains accessible. See [Requesting a Specific API Version](#requesting-a-specific-api-version) for more information.

An older version remain available as long as feasible, but may be removed at any time. To stay informed, [subscribe to updates](/docs/changelog#subscribe-to-updates).

Expand Down
4 changes: 2 additions & 2 deletions docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { themes as prismThemes } from 'prism-react-renderer'

/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'HomeWizard Energy API Documentation',
title: 'HomeWizard API Documentation',
favicon: 'img/favicon.ico',

// Set the production url of your site here
Expand Down Expand Up @@ -54,7 +54,7 @@ const config = {
navbar: {
title: 'API Documentation',
logo: {
alt: 'HomeWizard Energy Logo',
alt: 'HomeWizard Logo',
src: 'img/logo.svg'
},
items: [
Expand Down
2 changes: 1 addition & 1 deletion src/components/HomepageFeatures/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ const FeatureList = [
title: 'Local.',
description: (
<>
The HomeWizard Energy API is available on your local network. This means that you can use it without an internet connection. You can even turn off the connection with the <Link to='/docs/v1/system'>cloud</Link>.
The HomeWizard API is available on your local network. This means that you can use it without an internet connection. You can even turn off the connection with the <Link to='/docs/v1/system'>cloud</Link>.
</>
)
},
Expand Down
4 changes: 2 additions & 2 deletions src/pages/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ function HomepageHeader() {
<Heading as='h1' className={styles.headerTitle}>
Local API Documentation
</Heading>
<p className={styles.headerSubtitle}>Control your HomeWizard Energy devices with the Local API.</p>
<p className={styles.headerSubtitle}>Control your HomeWizard devices with the Local API.</p>
<div className={styles.headerButton}>
<Link className='button button--primary button--lg' to='/docs/introduction'>
Get started
Expand All @@ -26,7 +26,7 @@ function HomepageHeader() {

export default function Home() {
return (
<Layout title={`HomeWizard Energy API Documentation`} description='Learn how to use the HomeWizard Energy Local API.'>
<Layout title={`HomeWizard API Documentation`} description='Learn how to use the HomeWizard Local API.'>
<HomepageHeader />
<main>
<HomepageFeatures />
Expand Down