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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> * 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 <[email protected]> Co-authored-by: Mick <[email protected]>
homewizard · Nov 12, 2024 · 033bff9 · 033bff9
1 parent f5bf2a2
commit 033bff9
Show file tree

Hide file tree

Showing 38 changed files with 7,648 additions and 4,910 deletions.
diff --git a/.cspell.yml b/.cspell.yml
@@ -8,6 +8,7 @@ words:
     - montly # Known typo
     - hwenergy
     - energysocket
+    - energymeter
     - watermeter
     - kwhmeter
     - Zeroconf # Name
@@ -18,3 +19,8 @@ words:
     - AABBCCDDEEFF # Example
     - DDEEFF # Example
     - YYMMDDhhmmss # Example
+    - DDTHH # Chunk of YYYY-MM-DDTHH:mm:ss which is rejected by cspell
+    - rssi # Known acronym
+    - aiohttp # Known library
+    - asyncio # Known library
+    - cafile # Known term in python
diff --git a/.github/ISSUE_TEMPLATE/issue_report.yaml b/.github/ISSUE_TEMPLATE/issue_report.yaml
@@ -6,7 +6,7 @@ body:
           value: |
               This issue form is for reporting documentation issues only!
 
-              If you have a feature or enhancement request, please contact us direclty via our [Helpdesk](https://helpdesk.homewizard.com/en/).
+              If you have a feature or enhancement request, please contact us directly via our [helpdesk](https://helpdesk.homewizard.com/en/).
 
     - type: textarea
       validations:

diff --git a/README.md b/README.md
@@ -34,6 +34,6 @@ $ npm run build
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Submit changes
+### Submit Changes
 
 You are always free to open issues and/or pull requests to improve this documentation.
diff --git a/docs/changelog.mdx b/docs/changelog.mdx
@@ -7,7 +7,7 @@ The API Changelog is available on GitHub. For every important change in the API
 {/* prettier-ignore */}
 <Link className='button button--primary' to='https://github.com/homewizard/api-documentation/releases'>Open Changelog</Link>
 
-## Subscribe to updates
+## Subscribe to Updates
 
 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".
 

diff --git a/docs/discovery.mdx b/docs/discovery.mdx
@@ -1,21 +1,82 @@
 ---
-sidebar_position: 5
+sidebar_position: 3
 ---
 
 import Link from '@docusaurus/Link'
+import Badge from '@site/src/components/Badge.js'
+import PreliminaryWarning from '@site/src/components/PreliminaryWarning.js'
 
 # Discovery
 
-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.
+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.
 
-## Example scan
+## Services
 
-The device can be found on the `_hwenergy._tcp` domain.
+Devices can broadcast one or two services on the network, depending on the available API version(s) of this device:
+
+-   `_hwenergy._tcp` - to discover devices that are using API v1 over HTTP
+-   `_homewizard._tcp` - to discover devices that are using API v2 and later over HTTPS
+
+## `_hwenergy._tcp`
+
+{/* prettier-ignore */}
+<Badge color='hw-green' icon="mdi:check" subtext="Supported">P1 Meter</Badge>
+<Badge color='hw-green' icon="mdi:check" subtext="Supported">Energy Socket</Badge>
+<Badge color='hw-grey' icon="mdi:close" subtext="Not supported">Energy Display</Badge>
+<Badge color='hw-green' icon="mdi:check" subtext="Supported">kWh Meter</Badge>
+<Badge color='hw-green' icon="mdi:check" subtext="Supported">Watermeter</Badge>
+<Badge color='hw-grey' icon="mdi:close" subtext="Not supported">Plug-In Battery</Badge>
+
+---
+
+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.
+
+### TXT Records
+
+A discovery response contains additional data to enhance the setup in your application.
+
+| Data         | Description                                                                                                                                                            |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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). |
+| path         | Set to `/api/v1`. Can be used to verify that your application supports this device and API version.                                                                    |
+| serial       | Device serial number, also used as the MAC address. This unique value per device consists of 12 hexadecimal characters.                                                |
+| product_name | A user-friendly name that may change at any time.                                                                                                                      |
+| product_type | The product type; refer to [supported devices](/docs/introduction#devices). Your application should support additional values for future products.                     |
+
+## `_homewizard._tcp`
+
+{/* prettier-ignore */}
+<Badge color='hw-green' icon="mdi:check" subtext="Supported">P1 Meter</Badge>
+<Badge color='hw-purple'  icon="mdi:wrench" subtext="In development">Energy Socket</Badge>
+<Badge color='hw-purple' icon="mdi:wrench" subtext="In development">Energy Display</Badge>
+<Badge color='hw-purple'  icon="mdi:wrench" subtext="In development">kWh Meter</Badge>
+<Badge color='hw-purple'  icon="mdi:wrench" subtext="In development">Watermeter</Badge>
+<Badge color='hw-purple' icon="mdi:wrench" subtext="In development">Plug-In Battery</Badge>
+
+---
+
+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.
+
+### TXT Records
+
+A discovery response includes additional data to enhance the setup in your application.
+
+| Data         | Description                                                                                                                                        |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| api_version  | The latest [API version](/docs/versioning).                                                                                                        |
+| id           | Device identifier used during [validation of the SSL certificate](/docs/v2/authorization#https), formatted as `appliance/<product_type>/<serial>`. |
+| serial       | Device serial number, also used as the MAC address. This value is unique per device and consist of 12 hexadecimal characters.                      |
+| product_name | A user-friendly name that may change at any time.                                                                                                  |
+| product_type | The product type; refer to [supported devices](/docs/introduction#devices). Your application should support additional values for future products. |
+
+## Example
+
+Run the following command to discover devices on your network: `dns-sd -B _hwenergy._tcp .`
 
 ```
    $ dns-sd -B _hwenergy._tcp .
    Browsing for _hwenergy._tcp
-   DATE: ---Wed 13 Oct 2021---
+   DATE: ---Tue 29 Oct 2024---
    14:51:03.565  ...STARTING...
    Timestamp     A/R  Flags  if Domain  Service Type     Instance Name
    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.
    14:51:03.566  Add      3   7 local.  _hwenergy._tcp.  kwhmeter-667788
    14:51:03.566  Add      3   7 local.  _hwenergy._tcp.  watermeter-ABCDEF
 ```
-
-The hostname is formatted as `<product-name>-<last 6 characters of serial>`, so devices with serial `AABBCCDDEEFF` the hostname is as following:
-
-| Device                   | Example hostname    |
-| ------------------------ | ------------------- |
-| P1 meter                 | p1meter-DDEEFF      |
-| Energy Socket            | energysocket-DDEEFF |
-| Watermeter               | watermeter-DDEEFF   |
-| kWh meter (single phase) | kwhmeter-DDEEFF     |
-| kWh meter (three phase)  | kwhmeter-DDEEFF     |
-
-## TXT records
-
-A discovery response contains some extra data that can be used to improve the setup in your application.
-
-| Data         | Description                                                                                                                                                |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| api_enabled  | '0' or '1', reflects if the API is enabled (1 means enabled)                                                                                               |
-| path         | Fixed to '/api/v1'. Can be used to validate that your application supports this device and API version                                                     |
-| serial       | Serial, also the MAC address. Consists of 12 hexadecimal values                                                                                            |
-| product_name | A fixed, user-friendly name. This name is not the same that is set by the user in the app.                                                                 |
-| product_type | The product type, see [Supported devices](/docs/getting-started#supported-devices). Make sure your application can handle other values for future products |
diff --git a/docs/endpoints/_category_.json b/docs/endpoints/_category_.json
diff --git a/docs/endpoints/api-v1-identify.mdx b/docs/endpoints/api-v1-identify.mdx
diff --git a/docs/endpoints/api-v1-state.mdx b/docs/endpoints/api-v1-state.mdx
diff --git a/docs/endpoints/api-v1-telegram.mdx b/docs/endpoints/api-v1-telegram.mdx