Skip to content

Commit 033bff9

Browse files
DCSBLJ-D-HWNotMick
authored
Add local API v2 documentation (#120)
* Very initial V2 documentation * More adjustments * More adjustments * More adjustments * Fix pre-commit issues * Add some todo's and resolve ISO8601 todo * Remove mark about old datapoints * Fix invalid name for monthy power peak * Fix timestamp examples * Fix details about absolute current values * Adjust Badge and add BadgeDetail to allow adding a nicer 'V1' sub-batch * Identify and reboot is implemented, remove TODO * Removed already completed TODO * Adjust some warnings * Add basic information about versioning in V2 * Add extra information about authentication process * Add labels * Add info about cloud generated users * Add details about GET and DELETE request in authorization * Improve flow description in authentication * Set telegram to v2 * Tell result can be 200 and 204 * Set correct error example * Adjust device list and mention API versions * Fix device->devices * Adjust 'capacity rate' explainer * Adjust cloud communication description * Adjust led brightness description * Adjust reboot description * Remove TODO in changelog, as they now live in GH issues * Remove TODO from category.json files * Remove last todo's * Remove incomplete information about semver * Adjust mDNS documentation with V2 * Fix issues in v2/system * Streamline v1 doc with new style from v2 (#29) * Add getting started guide for v2 (#30) * Add how-to-validate HTTPS (#31) * Remove references to 'purple blinking' (#32) * Add how to get the hostname (#33) * Add WebSocket documentation (#34) * Initial version of WebSocket documentation * Add Error handling and how to set parameter doc * Do not mix and match authorization and authentication (#35) * Add optional marker for api_v1_enabled (#36) * Add optional marker for v1_api_enabled * Fix formatting * Sytem responds with latest state (#38) * Remove 'v2' in URL's and examples (#40) * Set mDNS name for v2+ API to '_homewizard' (#41) * Improve button press time window behaviour (#42) * Correct order of device response (#43) * Set correct error code in example (#44) * Explain all errros (#45) * Remove Content-Length header from descriptions (#46) * Update mDNS documentation (#49) * Bumb docusaurus to 3.6.0 (#51) * Add firebase redirects (#55) * Spellcheck and typofixes (#50) * Correctly name P1 meter * Correctly name battery * Correctly name watermeter * Correctly name Wi-Fi and kWh Meter * Correctly name API * Yeah we are not talking Dutch over here * Correctly name LinkedIn * Apply suggestions from code review --------- Co-authored-by: Duco Sebel <74970928+DCSBL@users.noreply.github.com> * Update versioning doc (#47) * Make all 'V1' and 'V2' lowercase (#56) * Renamed badge.js to be compatible with capital sensitive OS (#57) * Streamlined v2 authorization (#59) * Streamlined v2 device information (#60) * Use correct error code in error handling example (#61) * Use correct error code in error handling example * Update docs/V2/error-handling.mdx --------- Co-authored-by: Duco Sebel <74970928+DCSBL@users.noreply.github.com> * Use correct api version in X-Api-Version (#62) * Streamlined v2 system (#63) * Use correct error body for response examples (#64) * Use correct error body for response examples * Update docs/V2/error-handling.mdx * Undo change --------- Co-authored-by: Duco Sebel <74970928+DCSBL@users.noreply.github.com> * Use correct error in websocket error example (#65) * Use correct error in websocket error example * Update docs/V2/websocket.mdx --------- Co-authored-by: Duco Sebel <74970928+DCSBL@users.noreply.github.com> * Get telegram expects Accept header (#68) * Improving documentation v2 (#66) * Renamed Us to About us * Fixed battery spelling * Fixed warning * Correctly name page * Added information about spelling mistake * Fixed mistake * Fixed Belgium (is that possible?) * Renamed v1/v2 * Backport renaming * Cleanup in tables * Fixed capital letters for Energy * Fixed capital letters * Made description a bit more clear * Fixed spelling mistake * Renamed data to device information and typofix * Fixed title names * Streamlined capital letters * Improved spelling * Fixed IP address and version naming * Removed not really needed links * Improved layout * Improved sentence * Renamed state * Fixed formatting * Streamlined v's * Fixed DSMR naming * Yeah we are not that lazy * Revert Git being a bitch * Fixed capital letter * Update docs/V1/recent_measurement.mdx * Feedback * Feedback --------- Co-authored-by: Duco Sebel <74970928+DCSBL@users.noreply.github.com> * Fix hyperlinks for documenation references (#69) * Clean up version supported batches (#70) * Clean up version supported batches * Extend badges to contain more info * Extend badges to contain more info * Fix formatting * Adjust badges in introduction * Final touches * Adjust supported batches (#71) * Clean up version supported batches * Extend badges to contain more info * Extend badges to contain more info * Fix formatting * Adjust badges in introduction * Final touches * Adjust formatting * Bumb docusaurus to 3.6.1 * Fix broken link * Rename 'V1' folder to 'v1' and 'V2' folder to 'v2' * Fix redirects * Fix redirects, again * Adjust deprecation policy documentation --------- Co-authored-by: Jochem <100682380+J-D-HW@users.noreply.github.com> Co-authored-by: Mick <91672051+NotMick@users.noreply.github.com>
1 parent f5bf2a2 commit 033bff9

38 files changed

+7648
-4910
lines changed

‎.cspell.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ words:
88
- montly # Known typo
99
- hwenergy
1010
- energysocket
11+
- energymeter
1112
- watermeter
1213
- kwhmeter
1314
- Zeroconf # Name
@@ -18,3 +19,8 @@ words:
1819
- AABBCCDDEEFF # Example
1920
- DDEEFF # Example
2021
- YYMMDDhhmmss # Example
22+
- DDTHH # Chunk of YYYY-MM-DDTHH:mm:ss which is rejected by cspell
23+
- rssi # Known acronym
24+
- aiohttp # Known library
25+
- asyncio # Known library
26+
- cafile # Known term in python

‎.github/ISSUE_TEMPLATE/issue_report.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ body:
66
value: |
77
This issue form is for reporting documentation issues only!
88
9-
If you have a feature or enhancement request, please contact us direclty via our [Helpdesk](https://helpdesk.homewizard.com/en/).
9+
If you have a feature or enhancement request, please contact us directly via our [helpdesk](https://helpdesk.homewizard.com/en/).
1010
1111
- type: textarea
1212
validations:

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,6 @@ $ npm run build
3434

3535
This command generates static content into the `build` directory and can be served using any static contents hosting service.
3636

37-
### Submit changes
37+
### Submit Changes
3838

3939
You are always free to open issues and/or pull requests to improve this documentation.

‎docs/changelog.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ The API Changelog is available on GitHub. For every important change in the API
77
{/* prettier-ignore */}
88
<Link className='button button--primary' to='https://github.com/homewizard/api-documentation/releases'>Open Changelog</Link>
99

10-
## Subscribe to updates
10+
## Subscribe to Updates
1111

1212
Get notified for changes in the API and its documentation when something has changed. Subscribe to changes at GitHub. Click the "Watch" button in the top-right to select your notifications type. We recommend you to select "Watch → "Custom" → "Releases".
1313

‎docs/discovery.mdx‎

Lines changed: 66 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,82 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 3
33
---
44

55
import Link from '@docusaurus/Link'
6+
import Badge from '@site/src/components/Badge.js'
7+
import PreliminaryWarning from '@site/src/components/PreliminaryWarning.js'
68

79
# Discovery
810

9-
The energy devices can be automatically discovered on your network, the method used for this is <Link to="https://www.ionos.com/digitalguide/server/know-how/multicast-dns/">Multicast DNS</Link> (also called `mDNS`, `Zeroconf` or `Bonjour`). Your application can use this technology to discover the device(s) without the user having to enter the IP address.
11+
Energy devices can be automatically discovered on your network using <Link to="https://datatracker.ietf.org/doc/html/rfc6762">Multicast DNS</Link> (also known as `mDNS`, `Zeroconf`, or `Bonjour`). This technology enables your application to discover devices without requiring the user to know the IP address.
1012

11-
## Example scan
13+
## Services
1214

13-
The device can be found on the `_hwenergy._tcp` domain.
15+
Devices can broadcast one or two services on the network, depending on the available API version(s) of this device:
16+
17+
- `_hwenergy._tcp` - to discover devices that are using API v1 over HTTP
18+
- `_homewizard._tcp` - to discover devices that are using API v2 and later over HTTPS
19+
20+
## `_hwenergy._tcp`
21+
22+
{/* prettier-ignore */}
23+
<Badge color='hw-green' icon="mdi:check" subtext="Supported">P1 Meter</Badge>
24+
<Badge color='hw-green' icon="mdi:check" subtext="Supported">Energy Socket</Badge>
25+
<Badge color='hw-grey' icon="mdi:close" subtext="Not supported">Energy Display</Badge>
26+
<Badge color='hw-green' icon="mdi:check" subtext="Supported">kWh Meter</Badge>
27+
<Badge color='hw-green' icon="mdi:check" subtext="Supported">Watermeter</Badge>
28+
<Badge color='hw-grey' icon="mdi:close" subtext="Not supported">Plug-In Battery</Badge>
29+
30+
---
31+
32+
This service is used to discover devices that are using **API v1**, which uses HTTP (port 80). Devices with API v1 are available on the `_hwenergy._tcp` service.
33+
34+
### TXT Records
35+
36+
A discovery response contains additional data to enhance the setup in your application.
37+
38+
| Data | Description |
39+
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40+
| api_enabled | Indicates if the API is enabled. The API is disabled when set to `0` and enabled when set to `1`. See [how to enable the API](/docs/getting-started#2-enable-the-api). |
41+
| path | Set to `/api/v1`. Can be used to verify that your application supports this device and API version. |
42+
| serial | Device serial number, also used as the MAC address. This unique value per device consists of 12 hexadecimal characters. |
43+
| product_name | A user-friendly name that may change at any time. |
44+
| product_type | The product type; refer to [supported devices](/docs/introduction#devices). Your application should support additional values for future products. |
45+
46+
## `_homewizard._tcp`
47+
48+
{/* prettier-ignore */}
49+
<Badge color='hw-green' icon="mdi:check" subtext="Supported">P1 Meter</Badge>
50+
<Badge color='hw-purple' icon="mdi:wrench" subtext="In development">Energy Socket</Badge>
51+
<Badge color='hw-purple' icon="mdi:wrench" subtext="In development">Energy Display</Badge>
52+
<Badge color='hw-purple' icon="mdi:wrench" subtext="In development">kWh Meter</Badge>
53+
<Badge color='hw-purple' icon="mdi:wrench" subtext="In development">Watermeter</Badge>
54+
<Badge color='hw-purple' icon="mdi:wrench" subtext="In development">Plug-In Battery</Badge>
55+
56+
---
57+
58+
This service is used to discover devices that are using **API v2 and later**, which uses HTTPS (port 443). Devices with this API version are available on the `_homewizard._tcp` service.
59+
60+
### TXT Records
61+
62+
A discovery response includes additional data to enhance the setup in your application.
63+
64+
| Data | Description |
65+
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
66+
| api_version | The latest [API version](/docs/versioning). |
67+
| id | Device identifier used during [validation of the SSL certificate](/docs/v2/authorization#https), formatted as `appliance/<product_type>/<serial>`. |
68+
| serial | Device serial number, also used as the MAC address. This value is unique per device and consist of 12 hexadecimal characters. |
69+
| product_name | A user-friendly name that may change at any time. |
70+
| product_type | The product type; refer to [supported devices](/docs/introduction#devices). Your application should support additional values for future products. |
71+
72+
## Example
73+
74+
Run the following command to discover devices on your network: `dns-sd -B _hwenergy._tcp .`
1475

1576
```
1677
$ dns-sd -B _hwenergy._tcp .
1778
Browsing for _hwenergy._tcp
18-
DATE: ---Wed 13 Oct 2021---
79+
DATE: ---Tue 29 Oct 2024---
1980
14:51:03.565 ...STARTING...
2081
Timestamp A/R Flags if Domain Service Type Instance Name
2182
14:51:03.566 Add 3 7 local. _hwenergy._tcp. energysocket-AABBCC
@@ -25,25 +86,3 @@ The device can be found on the `_hwenergy._tcp` domain.
2586
14:51:03.566 Add 3 7 local. _hwenergy._tcp. kwhmeter-667788
2687
14:51:03.566 Add 3 7 local. _hwenergy._tcp. watermeter-ABCDEF
2788
```
28-
29-
The hostname is formatted as `<product-name>-<last 6 characters of serial>`, so devices with serial `AABBCCDDEEFF` the hostname is as following:
30-
31-
| Device | Example hostname |
32-
| ------------------------ | ------------------- |
33-
| P1 meter | p1meter-DDEEFF |
34-
| Energy Socket | energysocket-DDEEFF |
35-
| Watermeter | watermeter-DDEEFF |
36-
| kWh meter (single phase) | kwhmeter-DDEEFF |
37-
| kWh meter (three phase) | kwhmeter-DDEEFF |
38-
39-
## TXT records
40-
41-
A discovery response contains some extra data that can be used to improve the setup in your application.
42-
43-
| Data | Description |
44-
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
45-
| api_enabled | '0' or '1', reflects if the API is enabled (1 means enabled) |
46-
| path | Fixed to '/api/v1'. Can be used to validate that your application supports this device and API version |
47-
| serial | Serial, also the MAC address. Consists of 12 hexadecimal values |
48-
| product_name | A fixed, user-friendly name. This name is not the same that is set by the user in the app. |
49-
| product_type | The product type, see [Supported devices](/docs/getting-started#supported-devices). Make sure your application can handle other values for future products |

‎docs/endpoints/_category_.json‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎docs/endpoints/api-v1-identify.mdx‎

Lines changed: 0 additions & 30 deletions
This file was deleted.

‎docs/endpoints/api-v1-state.mdx‎

Lines changed: 0 additions & 121 deletions
This file was deleted.

‎docs/endpoints/api-v1-telegram.mdx‎

Lines changed: 0 additions & 62 deletions
This file was deleted.

0 commit comments

Comments
 (0)