Merge pull request #136 from elad-bar/v2-new-api

V2 new api
elad-bar · Jun 6, 2024 · 23f6a91 · 23f6a91
2 parents 1ef086f + 786a37b
commit 23f6a91
Show file tree

Hide file tree

Showing 50 changed files with 4,131 additions and 2,752 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,57 @@
 # Changelog
 
+## 2.0.0
+
+- Fix "detected blocking call to open inside the event loop by custom integration" error
+
+## 2.0.0b10
+
+- Add support for mapping of multicolor consumable (CyanMagentaYellow)
+- Change the matching of consumable to its details by marker color instead of station
+
+## 2.0.0b9
+
+- Add fallback mechanism for consumables, if station is not available, will use color mapping
+- Fix hassfest failure caused by invalid enums values for translation
+
+## 2.0.0b8
+
+- Fix async dispatcher send
+- Change all sensors with date device class to timestamp [#127](https://github.com/elad-bar/ha-hpprinter/issues/127)
+- Add fallback mechanism for consumables, if station is not available, will use color mapping
+
+## 2.0.0b7
+
+- Safe code blocks (try / catch / log) for generating entities
+- Fix logic of constructing device name if cartridge type is not available
+
+## 2.0.0b6
+
+- When constructing device name, avoid null parts of it [#113](https://github.com/elad-bar/ha-hpprinter/issues/113)
+- Changed the logic of errors from not found endpoints [#120](https://github.com/elad-bar/ha-hpprinter/issues/120)
+  - On initial load / setting up integration - one of the endpoints must return valid response, otherwise the integration will fail to load.
+  - After the integration loaded, it will update data periodically,
+  - If one of the endpoints will return 404 (not found) - the data related to it will get reset, DEBUG message will be logged (instead of ERROR)
+  - If printer goes offline, all data will be set as Unknown.
+
+## 2.0.0b5
+
+- Support no prefetch mode
+- Fix all translations
+
+## v2.0.0b3
+
+- Fix entity translations
+- Fix main device manufacture date
+
+## v2.0.0b2
+
+- Fix wrong library usage for slugify, causing wrong translation key to get picked up
+
+## v2.0.0b1
+
+- Refactor to full HP Printer EWS support
+
 ## v1.0.12
 
 - Fix missing references [Issue #103](https://github.com/elad-bar/ha-hpprinter/issues/103)

diff --git a/README.md b/README.md
@@ -6,104 +6,199 @@ Configuration support multiple HP Printer devices through Configuration -> Integ
 
 [Changelog](https://github.com/elad-bar/ha-hpprinter/blob/master/CHANGELOG.md)
 
-### How to set it up:
+## How to
 
-Look for "HP Printers Integration" and install
+### Requirements
 
-#### Requirements
+- HP Printer with EWS (Embedded Web Server) support
 
-- HP Printer supporting XML API
-  to check printer's compatibility to the component try to get to the printer's XML API (replace placeholder with real IP / Hostname):
-  `http://{IP}/DevMgmt/ProductStatusDyn.xml`
+### Installations via HACS [![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)
 
-#### Basic configuration
+- In HACS, look for "HP Printer" and install and restart
+- If integration was not found, please add custom repository `elad-bar/hpprinter` as integration
+- In Settings --> Devices & Services - (Lower Right) "Add Integration"
 
-- Configuration should be done via Configuration -> Integrations.
-- In case you are already using that integration with YAML Configuration - please remove it
-- Integration supports **multiple** devices
-- In the setup form, the following details are mandatory:
-  - Name - Unique
-  - Host (or IP)
-- Upon submitting the form of creating an integration, a request to the printer will take place and will cause failure in case:
-  - Unsupported API
-  - Invalid server details - when cannot reach host
+### Setup
 
-#### Settings for Monitoring interfaces, devices, tracked devices and update interval
+To add integration use Configuration -> Integrations -> Add `HP Printer`
+Integration supports **multiple** accounts and devices
 
-_Configuration -> Integrations -> {Integration} -> Options_ <br />
+| Fields name | Type    | Required | Default | Description                                  |
+| ----------- | ------- | -------- | ------- | -------------------------------------------- |
+| Host        | Textbox | +        | -       | Defines hostname or IP of the HP Printer EWS |
+| Port        | Textbox | +        | 80      | Defines port of the HP Printer EWS           |
+| Is SSL      | Boolean | +        | False   | Defines which protocol to use HTTP/S         |
 
-```
-Name - Unique
-Host (or IP)
-Update Interval: Textbox, number of seconds to update entities, default=60
-Log level: Drop-down list, change component's log level (more details below), default=Default
-Should store responses?: Check-box, saves XML and JSON files for debugging purpose, default=False
-```
+It is also possible to change configuration after setting up using integration configuration.
 
-###### Log Level's drop-down
+#### Validation errors
 
-New feature to set the log level for the component without need to set log_level in `customization:` and restart or call manually `logger.set_level` and loose it after restart.
+| Errors                                                 |
+| ------------------------------------------------------ |
+| Invalid parameters provided                            |
+| HP Printer Embedded Web Server (EWS) not was not found |
 
-Upon startup or integration's option update, based on the value chosen, the component will make a service call to `logger.set_level` for that component with the desired value,
+## Devices
 
-In case `Default` option is chosen, flow will skip calling the service, after changing from any other option to `Default`, it will not take place automatically, only after restart
+Will extract data of the relevant devices, devices that are not available will be ignored.
 
-###### Store responses
+### Main device
 
-Stores the XML and JSON of each request and final JSON to files, Path in CONFIG_PATH/\*,
-Files that will be generated (Prefix to the file is name of the integration):
+Device that holds entities related to the integration and relations to other sub devices as described below.
 
-- ProductUsageDyn.XML - Raw XML from HP Printer of Usage Details
-- ProductUsageDyn.json - JSON based on the Raw XML of Usage Details after transformed by the component
-- ConsumableConfigDyn.XML - Raw XML from HP Printer of consumable details
-- ConsumableConfigDyn.json - JSON based on the Raw XML of consumable details after transformed by the component
-- ProductConfigDyn.XML - Raw XML from HP Printer of Config Details
-- ProductConfigDyn.json - JSON based on the Raw XML of Config Details after transformed by the component
-- Final.json - JSON based on the 2 JSONs above, merged into simpler data structure for the HA to create sensor based on
+_Binary Sensor_
 
-## Components:
+- ePrint Registered
+- ePrint Status
 
-#### Device status - Binary Sensor
+_Sensor_
 
-```
-State: connected?
-```
+- Manufacture Date
 
-#### Printer details - Sensor
+### Printer
 
-```
-State: # of pages printed
-Attributes:
-    Color - # of printed documents using color cartridges
-    Monochrome - # of printed documents using black cartridges
-    Jams - # of print jobs jammed
-    Cancelled - # of print jobs that were cancelled
-```
+Device holds entities of sensors related to number of pages printed and relation to sub devices of consumables
 
-#### Scanner details - Sensor (For AIO only)
+_Sensor_
 
+- Total pages printed
+- Total black-and-white pages printed
+- Total color pages printed
+- Total single-sided pages printed
+- Total double-sided pages printed
+- Total jams
+- Total miss picks
+
+### Scanner
+
+Device holds entities of sensors related to number of pages scanned
+
+_Sensor_
+
+- Total scanned pages
+- Total scanned pages from ADF
+- Total double-sided pages scanned
+- Total pages from scanner glass
+- Total jams
+- Total miss picks
+
+### Copy
+
+Device holds entities of sensors related to number of pages copied
+
+_Sensor_
+
+- Total copies
+- Total copies from ADF
+- Total pages from scanner glass
+- Total black-and-white copies
+- Total color copies
+
+### Fax
+
+Device holds entities of sensors related to number of pages faxed
+
+_Sensor_
+
+- Total faxed
+
+### Consumable
+
+Devices (device per consumable) holds entities related to consumable (Ink, Toner, Printhead) of a printer device
+
+_Binary Sensor_
+
+- Status
+
+_Sensor_
+
+- Station
+- Type
+- Installation Date
+- Level (will not be available for Printhead)
+- Expiration Date (will not be available for Printhead)
+- Remaining (will not be available for Printhead)
+- Counterfeit Refilled
+- Genuine Refilled
+- Manufacture Date
+
+## Troubleshooting
+
+Before opening an issue, please provide logs and diagnostic file data related to the issue.
+
+### Logs
+
+For debug log level, please add the following to your config.yaml
+
+```yaml
+logger:
+  default: warning
+  logs:
+    custom_components.hpprinter: debug
 ```
-State: # of pages scanned
-Attributes:
-    ADF - # of scanned documents from the ADF
-    Duplex - # of scanned documents from the ADF using duplex mode
-    Flatbed - # of scanned documents from the flatbed
-    Jams - # of scanned jammed
-    Mispick - # of scanned documents failed to take the document from the feeder
-```
 
-#### Cartridges details - Sensor (Per cartridge)
+Or use the HA capability in device page:
+
+1. Settings
+2. Devices & Services
+3. HP Printer
+4. 3 dots menu
+5. Enable debug logging
+
+When done and would like to extract the log, repeat steps, in step #5 - Disable debug logging
+
+### Diagnostic details
 
+Please attach also diagnostic details of the integration, available in:
+
+1. Settings
+2. Devices & Services
+3. HP Printer
+4. 3 dots menu
+5. Download diagnostics
+
+Diagnostic file contains 3 section related to data extracted from the device:
+
+- data.debug.rawData - Raw data extracted from all endpoints of the device, from that source you can extract ideas for additional entities to suggest
+- data.debug.devicesConfig - Configuration of mapping to convert data from HP Printer EWS to HA devices and entities, that will be the section that new entities will be added
+- data.debug.devicesData - Data extracted for HA entities, just relevant data points, according to mapped objects available in section `data.debug.devicesConfig`
+
+## Translations
+
+Integration translated from English to:
+
+- German
+- Danish
+- Spanish
+- French
+- Dutch
+- Norwegian
+- Polish
+- Portuguese
+
+Translation is being auto-generated from Google Translate using `utils/generate_translations.py` script,
+
+```json
+{
+  "en": "en",
+  "de": "de",
+  "dk": "da",
+  "es": "es",
+  "fr": "fr",
+  "nb": "no",
+  "nl": "nl",
+  "pl": "pl",
+  "pt-BR": "pt"
+}
 ```
-State: Remaining level %
-Attributes:
-    Color
-    Type - Ink / Toner / Print head
-    Station - Position of the cartridge
-    Product Number
-    Serial Number
-    Manufactured By
-    Manufactured At
-    Warranty Expiration Date
-    Installed At
+
+If you would like to add new translation language, please add to the `DESTINATION_LANGUAGES` constant the relevant language,
+format is:
+
+```json
+{
+  "HA language": "Google Translate language"
+}
 ```
+
+Script is translating only, new missing values, it will not override translated values.